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 33 33 20 32 30 30 37 2f in,v 1.233 2007/
05f0: 30 38 2f 32 31 20 31 36 3a 31 35 3a 35 36 20 64 08/21 16:15:56 d
0600: 72 68 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66 6e rh Exp $.*/.#ifn
0610: 64 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a def _SQLITE3_H_.
0620: 23 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 #define _SQLITE3
0630: 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 _H_.#include <st
0640: 64 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e darg.h> /* N
0650: 65 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65 eeded for the de
0660: 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c finition of va_l
0670: 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 ist */../*.** Ma
0680: 6b 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63 ke sure we can c
0690: 61 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66 all this stuff f
06a0: 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 rom C++..*/.#ifd
06b0: 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 ef __cplusplus.e
06c0: 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 xtern "C" {.#end
06d0: 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 if.../*.** Add t
06e0: 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 he ability to ov
06f0: 65 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a erride 'extern'.
0700: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 */.#ifndef SQLIT
0710: 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e E_EXTERN.# defin
0720: 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 e SQLITE_EXTERN
0730: 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 2f extern.#endif../
0740: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 74 *.** Make sure t
0750: 68 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 68 65 hese symbols whe
0760: 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 re not defined b
0770: 79 20 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 y some previous
0780: 68 65 61 64 65 72 0a 2a 2a 20 66 69 6c 65 2e 0a header.** file..
0790: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 */.#ifdef SQLITE
07a0: 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66 _VERSION.# undef
07b0: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a SQLITE_VERSION.
07c0: 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51 #endif.#ifdef SQ
07d0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d LITE_VERSION_NUM
07e0: 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 BER.# undef SQLI
07f0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 TE_VERSION_NUMBE
0800: 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 R.#endif../*.**
0810: 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c CAPI3REF: Compil
0820: 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 e-Time Library V
0830: 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a ersion Numbers.*
0840: 2a 0a 2a 2a 20 54 68 65 20 76 65 72 73 69 6f 6e *.** The version
0850: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c of the SQLite l
0860: 69 62 72 61 72 79 20 69 73 20 63 6f 6e 74 61 69 ibrary is contai
0870: 6e 65 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 ned in the sqlit
0880: 65 33 2e 68 0a 2a 2a 20 68 65 61 64 65 72 20 66 e3.h.** header f
0890: 69 6c 65 20 69 6e 20 61 20 23 64 65 66 69 6e 65 ile in a #define
08a0: 20 6e 61 6d 65 64 20 53 51 4c 49 54 45 5f 56 45 named SQLITE_VE
08b0: 52 53 49 4f 4e 2e 20 20 54 68 65 20 53 51 4c 49 RSION. The SQLI
08c0: 54 45 5f 56 45 52 53 49 4f 4e 0a 2a 2a 20 6d 61 TE_VERSION.** ma
08d0: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20 cro resolves to
08e0: 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e a string constan
08f0: 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 72 t..**.** The for
0900: 6d 61 74 20 6f 66 20 74 68 65 20 76 65 72 73 69 mat of the versi
0910: 6f 6e 20 73 74 72 69 6e 67 20 69 73 20 22 58 2e on string is "X.
0920: 59 2e 5a 22 2c 20 77 68 65 72 65 0a 2a 2a 20 58 Y.Z", where.** X
0930: 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 is the major ve
0940: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 2c 20 59 20 rsion number, Y
0950: 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 is the minor ver
0960: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 sion number and
0970: 5a 0a 2a 2a 20 69 73 20 74 68 65 20 72 65 6c 65 Z.** is the rele
0980: 61 73 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 ase number. The
0990: 20 58 2e 59 2e 5a 20 6d 69 67 68 74 20 62 65 20 X.Y.Z might be
09a0: 66 6f 6c 6c 6f 77 65 64 20 62 79 20 22 61 6c 70 followed by "alp
09b0: 68 61 22 20 6f 72 20 22 62 65 74 61 22 2e 0a 2a ha" or "beta"..*
09c0: 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 20 22 33 * For example "3
09d0: 2e 31 2e 31 62 65 74 61 22 2e 0a 2a 2a 0a 2a 2a .1.1beta"..**.**
09e0: 20 54 68 65 20 58 20 76 61 6c 75 65 20 69 73 20 The X value is
09f0: 61 6c 77 61 79 73 20 33 20 69 6e 20 53 51 4c 69 always 3 in SQLi
0a00: 74 65 2e 20 20 54 68 65 20 58 20 76 61 6c 75 65 te. The X value
0a10: 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77 68 only changes wh
0a20: 65 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 en.** backwards
0a30: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 69 73 compatibility is
0a40: 20 62 72 6f 6b 65 6e 20 61 6e 64 20 77 65 20 69 broken and we i
0a50: 6e 74 65 6e 64 20 74 6f 20 6e 65 76 65 72 20 62 ntend to never b
0a60: 72 65 61 6b 0a 2a 2a 20 62 61 63 6b 77 61 72 64 reak.** backward
0a70: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e s compatibility.
0a80: 20 20 54 68 65 20 59 20 76 61 6c 75 65 20 6f 6e The Y value on
0a90: 6c 79 20 63 68 61 6e 67 65 73 20 77 68 65 6e 0a ly changes when.
0aa0: 2a 2a 20 74 68 65 72 65 20 61 72 65 20 6d 61 6a ** there are maj
0ab0: 6f 72 20 66 65 61 74 75 72 65 20 65 6e 68 61 6e or feature enhan
0ac0: 63 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 cements that are
0ad0: 20 66 6f 72 77 61 72 64 73 20 63 6f 6d 70 61 74 forwards compat
0ae0: 69 62 6c 65 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 ible.** but not
0af0: 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 backwards compat
0b00: 69 62 6c 65 2e 20 20 54 68 65 20 5a 20 76 61 6c ible. The Z val
0b10: 75 65 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 ue is incremente
0b20: 64 20 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72 d with.** each r
0b30: 65 6c 65 61 73 65 20 62 75 74 20 72 65 73 65 74 elease but reset
0b40: 73 20 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e s back to 0 when
0b50: 20 59 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 Y is incremente
0b60: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c d..**.** The SQL
0b70: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 ITE_VERSION_NUMB
0b80: 45 52 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ER is an integer
0b90: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20 with the value
0ba0: 0a 2a 2a 20 28 58 2a 31 30 30 30 30 30 30 20 2b .** (X*1000000 +
0bb0: 20 59 2a 31 30 30 30 20 2b 20 5a 29 2e 20 46 6f Y*1000 + Z). Fo
0bc0: 72 20 65 78 61 6d 70 6c 65 2c 20 66 6f 72 20 76 r example, for v
0bd0: 65 72 73 69 6f 6e 20 22 33 2e 31 2e 31 62 65 74 ersion "3.1.1bet
0be0: 61 22 2c 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 56 a", .** SQLITE_V
0bf0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 69 73 ERSION_NUMBER is
0c00: 20 73 65 74 20 74 6f 20 33 30 30 31 30 30 31 2e set to 3001001.
0c10: 20 54 6f 20 64 65 74 65 63 74 20 69 66 20 74 68 To detect if th
0c20: 65 79 20 61 72 65 20 75 73 69 6e 67 20 0a 2a 2a ey are using .**
0c30: 20 76 65 72 73 69 6f 6e 20 33 2e 31 2e 31 20 6f version 3.1.1 o
0c40: 72 20 67 72 65 61 74 65 72 20 61 74 20 63 6f 6d r greater at com
0c50: 70 69 6c 65 20 74 69 6d 65 2c 20 70 72 6f 67 72 pile time, progr
0c60: 61 6d 73 20 6d 61 79 20 75 73 65 20 74 68 65 20 ams may use the
0c70: 74 65 73 74 20 0a 2a 2a 20 28 53 51 4c 49 54 45 test .** (SQLITE
0c80: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 3e _VERSION_NUMBER>
0c90: 3d 33 30 30 31 30 30 31 29 2e 0a 2a 2a 0a 2a 2a =3001001)..**.**
0ca0: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
0cb0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 te3_libversion()
0cc0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6c ] and [sqlite3_l
0cd0: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 ibversion_number
0ce0: 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ()]..*/.#define
0cf0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 SQLITE_VERSION
0d00: 20 20 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d "--VERS--
0d10: 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ".#define SQLITE
0d20: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 _VERSION_NUMBER
0d30: 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 --VERSION-NUMBER
0d40: 2d 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 --../*.** CAPI3R
0d50: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 EF: Run-Time Lib
0d60: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d rary Version Num
0d70: 62 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 bers.**.** These
0d80: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
0d90: 20 76 61 6c 75 65 73 20 65 71 75 69 76 61 6c 65 values equivale
0da0: 6e 74 20 74 6f 20 74 68 65 20 68 65 61 64 65 72 nt to the header
0db0: 20 63 6f 6e 73 74 61 6e 74 73 0a 2a 2a 20 5b 53 constants.** [S
0dc0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 61 QLITE_VERSION] a
0dd0: 6e 64 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 nd [SQLITE_VERSI
0de0: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 54 68 65 ON_NUMBER]. The
0df0: 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 values returned
0e00: 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 .** by this rout
0e10: 69 6e 65 73 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 ines should only
0e20: 20 62 65 20 64 69 66 66 65 72 65 6e 74 20 66 72 be different fr
0e30: 6f 6d 20 74 68 65 20 68 65 61 64 65 72 20 76 61 om the header va
0e40: 6c 75 65 73 0a 2a 2a 20 69 66 20 79 6f 75 20 63 lues.** if you c
0e50: 6f 6d 70 69 6c 65 20 79 6f 75 72 20 70 72 6f 67 ompile your prog
0e60: 72 61 6d 20 75 73 69 6e 67 20 61 6e 20 73 71 6c ram using an sql
0e70: 69 74 65 33 2e 68 20 68 65 61 64 65 72 20 66 72 ite3.h header fr
0e80: 6f 6d 20 61 0a 2a 2a 20 64 69 66 66 65 72 65 6e om a.** differen
0e90: 74 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c t version of SQL
0ea0: 69 74 65 20 74 68 61 74 20 74 68 65 20 76 65 72 ite that the ver
0eb0: 73 69 6f 6e 20 6f 66 20 74 68 65 20 6c 69 62 72 sion of the libr
0ec0: 61 72 79 20 79 6f 75 0a 2a 2a 20 6c 69 6e 6b 20 ary you.** link
0ed0: 61 67 61 69 6e 73 74 2e 0a 2a 2a 0a 2a 2a 20 54 against..**.** T
0ee0: 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 he sqlite3_versi
0ef0: 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 on[] string cons
0f00: 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 tant contains th
0f10: 65 20 74 65 78 74 20 6f 66 20 74 68 65 0a 2a 2a e text of the.**
0f20: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e [SQLITE_VERSION
0f30: 5d 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 73 ] string. The s
0f40: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
0f50: 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 n() function ret
0f60: 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 65 72 urns.** a poiner
0f70: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
0f80: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 version[] string
0f90: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 constant. The
0fa0: 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 73 20 70 function.** is p
0fb0: 72 6f 76 69 64 65 64 20 66 6f 72 20 44 4c 4c 20 rovided for DLL
0fc0: 75 73 65 72 73 20 77 68 6f 20 63 61 6e 20 6f 6e users who can on
0fd0: 6c 79 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 ly access functi
0fe0: 6f 6e 73 20 61 6e 64 20 6e 6f 74 0a 2a 2a 20 63 ons and not.** c
0ff0: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 onstants within
1000: 74 68 65 20 44 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 the DLL..*/.SQLI
1010: 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 TE_EXTERN const
1020: 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 char sqlite3_ver
1030: 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 sion[];.const ch
1040: 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 ar *sqlite3_libv
1050: 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 69 6e ersion(void);.in
1060: 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 t sqlite3_libver
1070: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 sion_number(void
1080: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1090: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e EF: Database Con
10a0: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a nection Handle.*
10b0: 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 *.** Each open S
10c0: 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 QLite database i
10d0: 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 s represented by
10e0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
10f0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 0a 2a nstance of the.*
1100: 2a 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 * opaque structu
1110: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 re named "sqlite
1120: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 3". It is usefu
1130: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e l to think of an
1140: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e sqlite3.** poin
1150: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 ter as an object
1160: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f . The [sqlite3_
1170: 6f 70 65 6e 5d 2c 20 5b 73 71 6c 69 74 65 33 5f open], [sqlite3_
1180: 6f 70 65 6e 31 36 5d 2c 20 61 6e 64 0a 2a 2a 20 open16], and.**
1190: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
11a0: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 ] interfaces are
11b0: 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 its constructor
11c0: 73 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 s.** and [sqlite
11d0: 33 5f 63 6c 6f 73 65 5d 20 69 73 20 69 74 73 20 3_close] is its
11e0: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 destructor. The
11f0: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 re are many othe
1200: 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 r interfaces.**
1210: 28 73 75 63 68 20 61 73 20 5b 73 71 6c 69 74 65 (such as [sqlite
1220: 33 5f 70 72 65 70 61 72 65 5f 76 32 5d 2c 20 5b 3_prepare_v2], [
1230: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
1240: 75 6e 63 74 69 6f 6e 5d 2c 20 61 6e 64 0a 2a 2a unction], and.**
1250: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 [sqlite3_busy_t
1260: 69 6d 65 6f 75 74 5d 20 74 6f 20 6e 61 6d 65 20 imeout] to name
1270: 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20 but three) that
1280: 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 74 are methods on t
1290: 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 2e 0a 2a his.** object..*
12a0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
12b0: 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 sqlite3 sqlite3
12c0: 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 ;.../*.** CAPI3R
12d0: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 EF: 64-Bit Integ
12e0: 65 72 20 54 79 70 65 73 0a 2a 2a 0a 2a 2a 20 53 er Types.**.** S
12f0: 6f 6d 65 20 63 6f 6d 70 69 6c 65 72 73 20 64 6f ome compilers do
1300: 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 74 68 65 not support the
1310: 20 22 6c 6f 6e 67 20 6c 6f 6e 67 22 20 64 61 74 "long long" dat
1320: 61 74 79 70 65 2e 20 20 53 6f 20 77 65 20 68 61 atype. So we ha
1330: 76 65 0a 2a 2a 20 74 6f 20 64 6f 20 63 6f 6d 70 ve.** to do comp
1340: 69 6c 65 72 2d 73 70 65 63 69 66 69 63 20 74 79 iler-specific ty
1350: 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 pedefs for 64-bi
1360: 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 t signed and uns
1370: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a igned integers..
1380: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 **.** Many SQLit
1390: 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 e interface func
13a0: 74 69 6f 6e 73 20 72 65 71 75 69 72 65 20 61 20 tions require a
13b0: 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 61 64-bit integer a
13c0: 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 6f rguments..** Tho
13d0: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 se interfaces ar
13e0: 65 20 64 65 63 6c 61 72 65 64 20 75 73 69 6e 67 e declared using
13f0: 20 74 68 69 73 20 74 79 70 65 64 65 66 2e 0a 2a this typedef..*
1400: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f /.#ifdef SQLITE_
1410: 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 INT64_TYPE. typ
1420: 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 edef SQLITE_INT6
1430: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 4_TYPE sqlite_in
1440: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 t64;. typedef u
1450: 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 nsigned SQLITE_I
1460: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 NT64_TYPE sqlite
1470: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 _uint64;.#elif d
1480: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 efined(_MSC_VER)
1490: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f || defined(__BO
14a0: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 RLANDC__). type
14b0: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 def __int64 sqli
14c0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 te_int64;. type
14d0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 def unsigned __i
14e0: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 nt64 sqlite_uint
14f0: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64;.#else. type
1500: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e def long long in
1510: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a t sqlite_int64;.
1520: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e typedef unsign
1530: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 ed long long int
1540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a sqlite_uint64;.
1550: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73 #endif.typedef s
1560: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 qlite_int64 sqli
1570: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 te3_int64;.typed
1580: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 ef sqlite_uint64
1590: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b sqlite3_uint64;
15a0: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 ../*.** If compi
15b0: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65 ling for a proce
15c0: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20 ssor that lacks
15d0: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 floating point s
15e0: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 upport,.** subst
15f0: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f itute integer fo
1600: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 r floating-point
1610: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 .*/.#ifdef SQLIT
1620: 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f E_OMIT_FLOATING_
1630: 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 POINT.# define d
1640: 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e ouble sqlite3_in
1650: 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a t64.#endif../*.*
1660: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 * CAPI3REF: Clos
1670: 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20 43 ing A Database C
1680: 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 onnection.**.**
1690: 43 61 6c 6c 20 74 68 69 73 20 66 75 6e 63 74 69 Call this functi
16a0: 6f 6e 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 on with a pointe
16b0: 72 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 r to a structure
16c0: 20 74 68 61 74 20 77 61 73 20 70 72 65 76 69 6f that was previo
16d0: 75 73 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 usly.** returned
16e0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f from [sqlite3_o
16f0: 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 pen()], [sqlite3
1700: 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a _open16()], or.*
1710: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f * [sqlite3_open_
1720: 76 32 28 29 5d 20 61 6e 64 20 74 68 65 20 63 6f v2()] and the co
1730: 72 72 65 73 70 6f 6e 64 69 6e 67 20 64 61 74 61 rresponding data
1740: 62 61 73 65 20 77 69 6c 6c 20 62 79 0a 2a 2a 20 base will by.**
1750: 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6c closed..**.** Al
1760: 6c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 l SQL statements
1770: 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 prepared using
1780: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1790: 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 _v2()] or.** [sq
17a0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
17b0: 76 32 28 29 5d 20 6d 75 73 74 20 62 65 20 64 65 v2()] must be de
17c0: 73 74 72 6f 79 65 64 20 75 73 69 6e 67 20 5b 73 stroyed using [s
17d0: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
17e0: 29 5d 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 )].** before thi
17f0: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c s routine is cal
1800: 6c 65 64 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 led. Otherwise,
1810: 53 51 4c 49 54 45 5f 42 55 53 59 20 69 73 20 72 SQLITE_BUSY is r
1820: 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65 0a eturned and the.
1830: 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ** database conn
1840: 65 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 6f ection remains o
1850: 70 65 6e 2e 0a 2a 2a 0a 2a 2a 20 50 61 73 73 69 pen..**.** Passi
1860: 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 ng this routine
1870: 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 a database conne
1880: 63 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 61 ction that has a
1890: 6c 72 65 61 64 79 20 62 65 65 6e 0a 2a 2a 20 63 lready been.** c
18a0: 6c 6f 73 65 64 20 72 65 73 75 6c 74 73 20 69 6e losed results in
18b0: 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 undefined behav
18c0: 69 6f 72 2e 20 20 49 66 20 6f 74 68 65 72 20 69 ior. If other i
18d0: 6e 74 65 72 66 61 63 65 73 20 74 68 61 74 0a 2a nterfaces that.*
18e0: 2a 20 72 65 66 65 72 65 6e 63 65 20 74 68 65 20 * reference the
18f0: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f same database co
1900: 6e 6e 65 63 74 69 6f 6e 20 61 72 65 20 70 65 6e nnection are pen
1910: 64 69 6e 67 20 28 65 69 74 68 65 72 20 69 6e 20 ding (either in
1920: 74 68 65 0a 2a 2a 20 73 61 6d 65 20 74 68 72 65 the.** same thre
1930: 61 64 20 6f 72 20 69 6e 20 64 69 66 66 65 72 65 ad or in differe
1940: 6e 74 20 74 68 72 65 61 64 73 29 20 77 68 65 6e nt threads) when
1950: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 this routine is
1960: 20 63 61 6c 6c 65 64 2c 0a 2a 2a 20 74 68 65 6e called,.** then
1970: 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
1980: 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 69 undefined and i
1990: 73 20 61 6c 6d 6f 73 74 20 63 65 72 74 61 69 6e s almost certain
19a0: 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a ly undesirable..
19b0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 */.int sqlite3_c
19c0: 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a 29 3b lose(sqlite3 *);
19d0: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 ../*.** The type
19e0: 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 for a callback
19f0: 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 function..** Thi
1a00: 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 s is legacy and
1a10: 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 deprecated. It
1a20: 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 is included for
1a30: 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f historical.** co
1a40: 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 mpatibility and
1a50: 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 is not documente
1a60: 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e d..*/.typedef in
1a70: 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c t (*sqlite3_call
1a80: 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c back)(void*,int,
1a90: 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b char**, char**);
1aa0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1ab0: 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 : One-Step Query
1ac0: 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 Execution Inter
1ad0: 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 face.**.** This
1ae0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 interface is use
1af0: 64 20 74 6f 20 64 6f 20 61 20 6f 6e 65 2d 74 69 d to do a one-ti
1b00: 6d 65 20 65 76 61 6c 75 61 74 61 74 69 6f 6e 20 me evaluatation
1b10: 6f 66 20 7a 65 72 6f 0a 2a 2a 20 6f 72 20 6d 6f of zero.** or mo
1b20: 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 re SQL statement
1b30: 73 2e 20 20 55 54 46 2d 38 20 74 65 78 74 20 6f s. UTF-8 text o
1b40: 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d f the SQL statem
1b50: 65 6e 74 73 20 74 6f 0a 2a 2a 20 62 65 20 65 76 ents to.** be ev
1b60: 61 6c 75 74 65 64 20 69 73 20 70 61 73 73 65 64 aluted is passed
1b70: 20 69 6e 20 61 73 20 74 68 65 20 73 65 63 6f 6e in as the secon
1b80: 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 d parameter. Th
1b90: 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 e statements.**
1ba0: 61 72 65 20 70 72 65 70 61 72 65 64 20 6f 6e 65 are prepared one
1bb0: 20 62 79 20 6f 6e 65 20 75 73 69 6e 67 20 5b 73 by one using [s
1bc0: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
1bd0: 5d 2c 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 ], evaluated.**
1be0: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 using [sqlite3_s
1bf0: 74 65 70 28 29 5d 2c 20 74 68 65 6e 20 64 65 73 tep()], then des
1c00: 74 72 6f 79 65 64 20 75 73 69 6e 67 20 5b 73 71 troyed using [sq
1c10: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
1c20: 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 6f 6e 65 20 ]..**.** If one
1c30: 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 53 or more of the S
1c40: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 QL statements ar
1c50: 65 20 71 75 65 72 69 65 73 2c 20 74 68 65 6e 0a e queries, then.
1c60: 2a 2a 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 ** the callback
1c70: 66 75 6e 63 74 69 6f 6e 20 73 70 65 63 69 66 69 function specifi
1c80: 65 64 20 62 79 20 74 68 65 20 33 72 64 20 70 61 ed by the 3rd pa
1c90: 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 69 6e rameter is.** in
1ca0: 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 voked once for e
1cb0: 61 63 68 20 72 6f 77 20 6f 66 20 74 68 65 20 71 ach row of the q
1cc0: 75 65 72 79 20 72 65 73 75 6c 74 2e 20 20 54 68 uery result. Th
1cd0: 69 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 73 is callback.** s
1ce0: 68 6f 75 6c 64 20 6e 6f 72 6d 61 6c 6c 79 20 72 hould normally r
1cf0: 65 74 75 72 6e 20 30 2e 20 20 49 66 20 74 68 65 eturn 0. If the
1d00: 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
1d10: 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 s a non-zero.**
1d20: 76 61 6c 75 65 20 74 68 65 6e 20 74 68 65 20 71 value then the q
1d30: 75 65 72 79 20 69 73 20 61 62 6f 72 74 65 64 2c uery is aborted,
1d40: 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 all subsequent
1d50: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a SQL statements.*
1d60: 2a 20 61 72 65 20 73 6b 69 70 70 65 64 20 61 6e * are skipped an
1d70: 64 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 d the sqlite3_ex
1d80: 65 63 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 ec() function re
1d90: 74 75 72 6e 73 20 74 68 65 20 53 51 4c 49 54 45 turns the SQLITE
1da0: 5f 41 42 4f 52 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 _ABORT..**.** Th
1db0: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 4th parameter
1dc0: 74 6f 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 to this interfac
1dd0: 65 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 e is an arbitrar
1de0: 79 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 y pointer that i
1df0: 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f s.** passed thro
1e00: 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 ugh to the callb
1e10: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 ack function as
1e20: 69 74 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 its first parame
1e30: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 32 ter..**.** The 2
1e40: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 nd parameter to
1e50: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e the callback fun
1e60: 63 74 69 6f 6e 20 69 73 20 74 68 65 20 6e 75 6d ction is the num
1e70: 62 65 72 20 6f 66 0a 2a 2a 20 63 6f 6c 75 6d 6e ber of.** column
1e80: 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 72 s in the query r
1e90: 65 73 75 6c 74 2e 20 20 54 68 65 20 33 72 64 20 esult. The 3rd
1ea0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
1eb0: 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 callback.** is
1ec0: 61 6e 20 61 72 72 61 79 20 6f 66 20 73 74 72 69 an array of stri
1ed0: 6e 67 73 20 68 6f 6c 64 69 6e 67 20 74 68 65 20 ngs holding the
1ee0: 76 61 6c 75 65 73 20 66 6f 72 20 65 61 63 68 20 values for each
1ef0: 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 73 20 65 78 74 column.** as ext
1f00: 72 61 63 74 65 64 20 75 73 69 6e 67 20 5b 73 71 racted using [sq
1f10: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
1f20: 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 34 74 68 t()]..** The 4th
1f30: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
1f40: 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e e callback is an
1f50: 20 61 72 72 61 79 20 6f 66 20 73 74 72 69 6e 67 array of string
1f60: 73 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 75 73 s.** obtained us
1f70: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c ing [sqlite3_col
1f80: 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 umn_name()] and
1f90: 68 6f 6c 64 69 6e 67 0a 2a 2a 20 74 68 65 20 6e holding.** the n
1fa0: 61 6d 65 73 20 6f 66 20 65 61 63 68 20 63 6f 6c ames of each col
1fb0: 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 umn..**.** The c
1fc0: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
1fd0: 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2c 20 65 76 may be NULL, ev
1fe0: 65 6e 20 66 6f 72 20 71 75 65 72 69 65 73 2e 20 en for queries.
1ff0: 20 41 20 4e 55 4c 4c 0a 2a 2a 20 63 61 6c 6c 62 A NULL.** callb
2000: 61 63 6b 20 69 73 20 6e 6f 74 20 61 6e 20 65 72 ack is not an er
2010: 72 6f 72 2e 20 20 49 74 20 6a 75 73 74 20 6d 65 ror. It just me
2020: 61 6e 73 20 74 68 61 74 20 6e 6f 20 63 61 6c 6c ans that no call
2030: 62 61 63 6b 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 back.** will be
2040: 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 invoked..**.** I
2050: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 f an error occur
2060: 73 20 77 68 69 6c 65 20 70 61 72 73 69 6e 67 20 s while parsing
2070: 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 or evaluating th
2080: 65 20 53 51 4c 20 28 62 75 74 0a 2a 2a 20 6e 6f e SQL (but.** no
2090: 74 20 77 68 69 6c 65 20 65 78 65 63 75 74 69 6e t while executin
20a0: 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 29 20 g the callback)
20b0: 74 68 65 6e 20 61 6e 20 61 70 70 72 6f 70 72 69 then an appropri
20c0: 61 74 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 ate error.** mes
20d0: 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 sage is written
20e0: 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 into memory obta
20f0: 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 ined from [sqlit
2100: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 e3_malloc()] and
2110: 0a 2a 2a 20 2a 65 72 72 6d 73 67 20 69 73 20 6d .** *errmsg is m
2120: 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 ade to point to
2130: 74 68 61 74 20 6d 65 73 73 61 67 65 2e 20 20 54 that message. T
2140: 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 he calling funct
2150: 69 6f 6e 0a 2a 2a 20 69 73 20 72 65 73 70 6f 6e ion.** is respon
2160: 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e sible for freein
2170: 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 g the memory tha
2180: 74 20 68 6f 6c 64 73 20 74 68 65 20 65 72 72 6f t holds the erro
2190: 72 0a 2a 2a 20 6d 65 73 73 61 67 65 2e 20 20 20 r.** message.
21a0: 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 Use [sqlite3_fre
21b0: 65 28 29 5d 20 66 6f 72 20 74 68 69 73 2e 20 20 e()] for this.
21c0: 49 66 20 65 72 72 6d 73 67 3d 3d 4e 55 4c 4c 2c If errmsg==NULL,
21d0: 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20 65 72 72 6f .** then no erro
21e0: 72 20 6d 65 73 73 61 67 65 20 69 73 20 65 76 65 r message is eve
21f0: 72 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a r written..**.**
2200: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 The return valu
2210: 65 20 69 73 20 69 73 20 53 51 4c 49 54 45 5f 4f e is is SQLITE_O
2220: 4b 20 69 66 20 74 68 65 72 65 20 61 72 65 20 6e K if there are n
2230: 6f 20 65 72 72 6f 72 73 20 61 6e 64 0a 2a 2a 20 o errors and.**
2240: 73 6f 6d 65 20 6f 74 68 65 72 20 5b 53 51 4c 49 some other [SQLI
2250: 54 45 5f 4f 4b 20 7c 20 72 65 74 75 72 6e 20 63 TE_OK | return c
2260: 6f 64 65 5d 20 69 66 20 74 68 65 72 65 20 69 73 ode] if there is
2270: 20 61 6e 20 65 72 72 6f 72 2e 20 20 0a 2a 2a 20 an error. .**
2280: 54 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 72 The particular r
2290: 65 74 75 72 6e 20 76 61 6c 75 65 20 64 65 70 65 eturn value depe
22a0: 6e 64 73 20 6f 6e 20 74 68 65 20 74 79 70 65 20 nds on the type
22b0: 6f 66 20 65 72 72 6f 72 2e 20 0a 2a 2a 0a 2a 2f of error. .**.*/
22c0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 .int sqlite3_exe
22d0: 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 c(. sqlite3*,
22e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
22f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2300: 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 /* An open datab
2310: 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 ase */. const c
2320: 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 har *sql,
2330: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2340: 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 /* SQL to be
2350: 20 65 76 61 6c 75 74 65 64 20 2a 2f 0a 20 20 69 evaluted */. i
2360: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 nt (*callback)(v
2370: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c oid*,int,char**,
2380: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c char**), /* Cal
2390: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a lback function *
23a0: 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 /. void *,
23b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
23c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
23d0: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 * 1st argument t
23e0: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 o callback */.
23f0: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 char **errmsg
2400: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2410: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 /* Er
2420: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 ror msg written
2430: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a here */.);../*.*
2440: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 * CAPI3REF: Resu
2450: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 lt Codes.** KEYW
2460: 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 0a ORDS: SQLITE_OK.
2470: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 **.** Many SQLit
2480: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 e functions retu
2490: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65 rn an integer re
24a0: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 sult code from t
24b0: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 he set shown.**
24c0: 61 62 6f 76 65 20 69 6e 20 6f 72 64 65 72 20 74 above in order t
24d0: 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 o indicates succ
24e0: 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a ess or failure..
24f0: 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 73 75 6c 74 **.** The result
2500: 20 63 6f 64 65 73 20 61 62 6f 76 65 20 61 72 65 codes above are
2510: 20 74 68 65 20 6f 6e 6c 79 20 6f 6e 65 73 20 72 the only ones r
2520: 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 eturned by SQLit
2530: 65 20 69 6e 20 69 74 73 0a 2a 2a 20 64 65 66 61 e in its.** defa
2540: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ult configuratio
2550: 6e 2e 20 20 48 6f 77 65 76 65 72 2c 20 74 68 65 n. However, the
2560: 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 [sqlite3_extend
2570: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 ed_result_codes(
2580: 29 5d 0a 2a 2a 20 41 50 49 20 63 61 6e 20 62 65 )].** API can be
2590: 20 75 73 65 64 20 74 6f 20 73 65 74 20 61 20 64 used to set a d
25a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 6f atabase connecto
25b0: 69 6e 20 74 6f 20 72 65 74 75 72 6e 20 6d 6f 72 in to return mor
25c0: 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 72 65 e detailed.** re
25d0: 73 75 6c 74 20 63 6f 64 65 73 2e 0a 2a 2a 0a 2a sult codes..**.*
25e0: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c * See also: [SQL
25f0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c ITE_IOERR_READ |
2600: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 extended result
2610: 20 63 6f 64 65 73 5d 0a 2a 2a 0a 2a 2f 0a 23 64 codes].**.*/.#d
2620: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 efine SQLITE_OK
2630: 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 0 /*
2640: 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 Successful resu
2650: 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 lt */./* beginni
2660: 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 ng-of-error-code
2670: 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c s */.#define SQL
2680: 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 ITE_ERROR
2690: 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 1 /* SQL erro
26a0: 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 r or missing dat
26b0: 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 abase */.#define
26c0: 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c SQLITE_INTERNAL
26d0: 20 20 20 20 20 32 20 20 20 2f 2a 20 4e 4f 54 20 2 /* NOT
26e0: 55 53 45 44 2e 20 49 6e 74 65 72 6e 61 6c 20 6c USED. Internal l
26f0: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 ogic error in SQ
2700: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 Lite */.#define
2710: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 SQLITE_PERM
2720: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 3 /* Acces
2730: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e s permission den
2740: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ied */.#define S
2750: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 QLITE_ABORT
2760: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 4 /* Callba
2770: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 ck routine reque
2780: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f sted an abort */
2790: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
27a0: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20 BUSY 5
27b0: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 /* The database
27c0: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 file is locked
27d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
27e0: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 E_LOCKED 6
27f0: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e /* A table in
2800: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 the database is
2810: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 locked */.#defi
2820: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 ne SQLITE_NOMEM
2830: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 7 /* A
2840: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 malloc() failed
2850: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
2860: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 E_READONLY 8
2870: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f /* Attempt to
2880: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c write a readonl
2890: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 y database */.#d
28a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 efine SQLITE_INT
28b0: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a ERRUPT 9 /*
28c0: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 Operation termi
28d0: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 nated by sqlite3
28e0: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 _interrupt()*/.#
28f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
2900: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f ERR 10 /
2910: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 * Some kind of d
2920: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 isk I/O error oc
2930: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e curred */.#defin
2940: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 e SQLITE_CORRUPT
2950: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 11 /* The
2960: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 database disk i
2970: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 mage is malforme
2980: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
2990: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 ITE_NOTFOUND
29a0: 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 12 /* NOT USED
29b0: 2e 20 54 61 62 6c 65 20 6f 72 20 72 65 63 6f 72 . Table or recor
29c0: 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a 23 d not found */.#
29d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 define SQLITE_FU
29e0: 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f LL 13 /
29f0: 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c * Insertion fail
2a00: 65 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 ed because datab
2a10: 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 ase is full */.#
2a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 define SQLITE_CA
2a30: 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f NTOPEN 14 /
2a40: 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e * Unable to open
2a50: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
2a60: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 le */.#define SQ
2a70: 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 LITE_PROTOCOL
2a80: 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 15 /* NOT USE
2a90: 44 2e 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b D. Database lock
2aa0: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 protocol error
2ab0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
2ac0: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 E_EMPTY 16
2ad0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 /* Database i
2ae0: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 s empty */.#defi
2af0: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 ne SQLITE_SCHEMA
2b00: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 17 /* Th
2b10: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d e database schem
2b20: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 a changed */.#de
2b30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 fine SQLITE_TOOB
2b40: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 IG 18 /*
2b50: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 String or BLOB e
2b60: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 xceeds size limi
2b70: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
2b80: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 ITE_CONSTRAINT
2b90: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 19 /* Abort du
2ba0: 65 20 74 6f 20 63 6f 6e 74 72 61 69 6e 74 20 76 e to contraint v
2bb0: 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 iolation */.#def
2bc0: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 ine SQLITE_MISMA
2bd0: 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 TCH 20 /* D
2be0: 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 ata type mismatc
2bf0: 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c h */.#define SQL
2c00: 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 ITE_MISUSE
2c10: 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 21 /* Library
2c20: 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 used incorrectly
2c30: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
2c40: 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 TE_NOLFS 2
2c50: 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 2 /* Uses OS f
2c60: 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 eatures not supp
2c70: 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f orted on host */
2c80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2c90: 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20 AUTH 23
2ca0: 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f /* Authorizatio
2cb0: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 n denied */.#def
2cc0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 ine SQLITE_FORMA
2cd0: 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 T 24 /* A
2ce0: 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 uxiliary databas
2cf0: 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a e format error *
2d00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
2d10: 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 _RANGE 25
2d20: 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 /* 2nd paramet
2d30: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 er to sqlite3_bi
2d40: 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 nd out of range
2d50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
2d60: 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 E_NOTADB 26
2d70: 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 /* File opene
2d80: 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 d that is not a
2d90: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f database file */
2da0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2db0: 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 ROW 100
2dc0: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 /* sqlite3_step
2dd0: 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 () has another r
2de0: 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 ow ready */.#def
2df0: 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 ine SQLITE_DONE
2e00: 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 101 /* s
2e10: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 qlite3_step() ha
2e20: 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 s finished execu
2e30: 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f ting */./* end-o
2e40: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f f-error-codes */
2e50: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2e60: 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c : Extended Resul
2e70: 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 49 6e t Codes.**.** In
2e80: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e its default con
2e90: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 figuration, SQLi
2ea0: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 te API routines
2eb0: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 return one of 26
2ec0: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 72 65 73 75 integer.** resu
2ed0: 6c 74 20 63 6f 64 65 73 20 64 65 73 63 72 69 62 lt codes describ
2ee0: 65 64 20 61 74 20 72 65 73 75 6c 74 2d 63 6f 64 ed at result-cod
2ef0: 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 es. However, ex
2f00: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f perience has sho
2f10: 77 6e 20 74 68 61 74 0a 2a 2a 20 6d 61 6e 79 20 wn that.** many
2f20: 6f 66 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 of these result
2f30: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f codes are too co
2f40: 75 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 urse-grained. T
2f50: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 hey do not provi
2f60: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e de as.** much in
2f70: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 formation about
2f80: 70 72 6f 62 6c 65 6d 73 20 61 73 20 75 73 65 72 problems as user
2f90: 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 s might like. I
2fa0: 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a n an effort to.*
2fb0: 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 * address this,
2fc0: 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f newer versions o
2fd0: 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f f SQLite (versio
2fe0: 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 n 3.3.8 and late
2ff0: 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 r) include.** su
3000: 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 pport for additi
3010: 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 onal result code
3020: 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d s that provide m
3030: 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 ore detailed inf
3040: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 ormation.** abou
3050: 74 20 65 72 72 6f 72 73 2e 20 20 54 68 65 20 65 t errors. The e
3060: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
3070: 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 odes are enabled
3080: 20 28 6f 72 20 64 69 73 61 62 6c 65 64 29 20 66 (or disabled) f
3090: 6f 72 20 0a 2a 2a 20 65 61 63 68 20 64 61 74 61 or .** each data
30a0: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 base.** connecti
30b0: 6f 6e 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 on using the [sq
30c0: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 lite3_extended_r
30d0: 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 esult_codes()] A
30e0: 50 49 2e 0a 2a 2a 20 0a 2a 2a 20 53 6f 6d 65 20 PI..** .** Some
30f0: 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 of the available
3100: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 extended result
3110: 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65 codes are liste
3120: 64 20 61 62 6f 76 65 2e 0a 2a 2a 20 57 65 20 65 d above..** We e
3130: 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 xpect the number
3140: 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 of extended res
3150: 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 ult codes will b
3160: 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 e expand.** over
3170: 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 time. Software
3180: 20 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e that uses exten
3190: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
31a0: 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a should expect.*
31b0: 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 * to see new res
31c0: 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 ult codes in fut
31d0: 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 ure releases of
31e0: 53 51 4c 69 74 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 SQLite..** .** T
31f0: 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 he symbolic name
3200: 20 66 6f 72 20 61 6e 20 65 78 74 65 6e 64 65 64 for an extended
3210: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61 6c 77 result code alw
3220: 61 79 73 20 63 6f 6e 74 61 69 6e 73 20 61 20 72 ays contains a r
3230: 65 6c 61 74 65 64 0a 2a 2a 20 70 72 69 6d 61 72 elated.** primar
3240: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61 73 y result code as
3250: 20 61 20 70 72 65 66 69 78 2e 20 20 50 72 69 6d a prefix. Prim
3260: 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ary result codes
3270: 20 63 6f 6e 74 61 69 6e 20 61 20 73 69 6e 67 6c contain a singl
3280: 65 0a 2a 2a 20 22 5f 22 20 63 68 61 72 61 63 74 e.** "_" charact
3290: 65 72 2e 20 20 45 78 74 65 6e 64 65 64 20 72 65 er. Extended re
32a0: 73 75 6c 74 20 63 6f 64 65 73 20 63 6f 6e 74 61 sult codes conta
32b0: 69 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 22 in two or more "
32c0: 5f 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a _" characters..*
32d0: 2a 20 54 68 65 20 6e 75 6d 65 72 69 63 20 76 61 * The numeric va
32e0: 6c 75 65 20 6f 66 20 61 6e 20 65 78 74 65 6e 64 lue of an extend
32f0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 63 ed result code c
3300: 61 6e 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 an be converted
3310: 74 6f 20 69 74 73 0a 2a 2a 20 63 6f 72 72 65 73 to its.** corres
3320: 70 6f 6e 64 69 6e 67 20 70 72 69 6d 61 72 79 20 ponding primary
3330: 72 65 73 75 6c 74 20 63 6f 64 65 20 62 79 20 6d result code by m
3340: 61 73 6b 69 6e 67 20 6f 66 66 20 74 68 65 20 6c asking off the l
3350: 6f 77 65 72 20 38 20 62 79 74 65 73 2e 0a 2a 2a ower 8 bytes..**
3360: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f .** The SQLITE_O
3370: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69 K result code wi
3380: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65 ll never be exte
3390: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 nded. It will a
33a0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 lways.** be exac
33b0: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 tly zero..*/.#de
33c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
33d0: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 R_READ
33e0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
33f0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (1<<8)).#define
3400: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f SQLITE_IOERR_SHO
3410: 52 54 5f 52 45 41 44 20 20 20 20 28 53 51 4c 49 RT_READ (SQLI
3420: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 TE_IOERR | (2<<8
3430: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
3440: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 E_IOERR_WRITE
3450: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
3460: 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 ERR | (3<<8)).#d
3470: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
3480: 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 RR_FSYNC
3490: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
34a0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (4<<8)).#define
34b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 SQLITE_IOERR_DI
34c0: 52 5f 46 53 59 4e 43 20 20 20 20 20 28 53 51 4c R_FSYNC (SQL
34d0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c ITE_IOERR | (5<<
34e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
34f0: 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 TE_IOERR_TRUNCAT
3500: 45 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 E (SQLITE_I
3510: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 OERR | (6<<8)).#
3520: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
3530: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 ERR_FSTAT
3540: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
3550: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (7<<8)).#defin
3560: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 e SQLITE_IOERR_U
3570: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 28 53 51 NLOCK (SQ
3580: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c LITE_IOERR | (8<
3590: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
35a0: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b ITE_IOERR_RDLOCK
35b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
35c0: 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a IOERR | (9<<8)).
35d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
35e0: 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 OERR_DELETE
35f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
3600: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 | (10<<8)).#def
3610: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
3620: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 28 _BLOCKED (
3630: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
3640: 31 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 11<<8))../*.** C
3650: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 API3REF: Flags F
3660: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 or File Open Ope
3670: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 43 6f rations.**.** Co
3680: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 74 68 65 mbination of the
3690: 20 66 6f 6c 6c 6f 77 69 6e 67 20 62 69 74 20 76 following bit v
36a0: 61 6c 75 65 73 20 61 72 65 20 75 73 65 64 20 61 alues are used a
36b0: 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 s the.** third a
36c0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b rgument to the [
36d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
36e0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 )] interface and
36f0: 0a 2a 2a 20 61 73 20 66 6f 75 72 74 68 20 61 72 .** as fourth ar
3700: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 78 4f gument to the xO
3710: 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 pen method of th
3720: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 e.** [sqlite3_vf
3730: 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2f s] object..**.*/
3740: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3750: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 OPEN_READONLY
3760: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0x00000001
3770: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3780: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 OPEN_READWRITE
3790: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0x00000002
37a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
37b0: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 OPEN_CREATE
37c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0x00000004
37d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
37e0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f OPEN_DELETEONCLO
37f0: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 SE 0x00000008
3800: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3810: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 OPEN_EXCLUSIVE
3820: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0x00000010
3830: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3840: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 OPEN_MAIN_DB
3850: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0x00000100
3860: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3870: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 OPEN_TEMP_DB
3880: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0x00000200
3890: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
38a0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 OPEN_MAIN_JOURNA
38b0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 33 30 30 L 0x00000300
38c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
38d0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 OPEN_TEMP_JOURNA
38e0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 L 0x00000400
38f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3900: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 OPEN_SUBJOURNAL
3910: 20 20 20 20 20 20 30 78 30 30 30 30 30 35 30 30 0x00000500
3920: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3930: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 OPEN_MASTER_JOUR
3940: 4e 41 4c 20 20 20 30 78 30 30 30 30 30 36 30 30 NAL 0x00000600
3950: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
3960: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74 : Device Charact
3970: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 eristics.**.** T
3980: 68 65 20 78 44 65 76 69 63 65 43 61 70 61 62 69 he xDeviceCapabi
3990: 6c 69 74 69 65 73 20 6d 65 74 68 6f 64 20 6f 66 lities method of
39a0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f the [sqlite3_io
39b0: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a _methods].** obj
39c0: 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 ect returns an i
39d0: 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 nteger which is
39e0: 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20 a vector of the
39f0: 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 62 69 74 following.** bit
3a00: 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 values expressi
3a10: 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 ng I/O character
3a20: 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 istics of the ma
3a30: 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 ss storage.** de
3a40: 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 vice that holds
3a50: 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 the file that th
3a60: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 e [sqlite3_io_me
3a70: 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 thods].** refers
3a80: 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 to..**.** The S
3a90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
3aa0: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e IC property mean
3ab0: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 s that all write
3ac0: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 s of.** any size
3ad0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 are atomic. Th
3ae0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
3af0: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a TOMICnnn values.
3b00: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 ** mean that wri
3b10: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 tes of blocks th
3b20: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 at are nnn bytes
3b30: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 in size and.**
3b40: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 are aligned to a
3b50: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 n address which
3b60: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 is an integer mu
3b70: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e ltiple of.** nnn
3b80: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 are atomic. Th
3b90: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 e SQLITE_IOCAP_S
3ba0: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 AFE_APPEND value
3bb0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 means.** that w
3bc0: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 hen data is appe
3bd0: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 nded to a file,
3be0: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 the data is appe
3bf0: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 nded.** first th
3c00: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 en the size of t
3c10: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e he file is exten
3c20: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f ded, never the o
3c30: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 ther.** way arou
3c40: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f nd. The SQLITE_
3c50: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c IOCAP_SEQUENTIAL
3c60: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 property means
3c70: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 that.** informat
3c80: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 ion is written t
3c90: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 o disk in the sa
3ca0: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c me order as call
3cb0: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 s.** to xWrite()
3cc0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
3cd0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
3ce0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
3cf0: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 0001.#define SQL
3d00: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
3d10: 35 31 32 20 20 20 20 20 20 20 30 78 30 30 30 30 512 0x0000
3d20: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 0002.#define SQL
3d30: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
3d40: 31 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 1K 0x0000
3d50: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 0004.#define SQL
3d60: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
3d70: 32 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 2K 0x0000
3d80: 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 0008.#define SQL
3d90: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
3da0: 34 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 4K 0x0000
3db0: 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0010.#define SQL
3dc0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
3dd0: 38 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 8K 0x0000
3de0: 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0020.#define SQL
3df0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
3e00: 31 36 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 16K 0x0000
3e10: 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0040.#define SQL
3e20: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
3e30: 33 32 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 32K 0x0000
3e40: 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0080.#define SQL
3e50: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
3e60: 36 34 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 64K 0x0000
3e70: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0100.#define SQL
3e80: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 ITE_IOCAP_SAFE_A
3e90: 50 50 45 4e 44 20 20 20 20 20 30 78 30 30 30 30 PPEND 0x0000
3ea0: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0200.#define SQL
3eb0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e ITE_IOCAP_SEQUEN
3ec0: 54 49 41 4c 20 20 20 20 20 20 30 78 30 30 30 30 TIAL 0x0000
3ed0: 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 0400../*.** CAPI
3ee0: 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 3REF: File Locki
3ef0: 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 ng Levels.**.**
3f00: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 SQLite uses one
3f10: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 of the following
3f20: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 integer values
3f30: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a as the second.**
3f40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c argument to cal
3f50: 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 ls it makes to t
3f60: 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 he xLock() and x
3f70: 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 Unlock() methods
3f80: 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 .** of an [sqlit
3f90: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f e3_io_methods] o
3fa0: 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e bject..*/.#defin
3fb0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f e SQLITE_LOCK_NO
3fc0: 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 NE 0.#d
3fd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 efine SQLITE_LOC
3fe0: 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20 K_SHARED
3ff0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
4000: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 _LOCK_RESERVED
4010: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 2.#define SQ
4020: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e LITE_LOCK_PENDIN
4030: 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e G 3.#defin
4040: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 e SQLITE_LOCK_EX
4050: 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f CLUSIVE 4../
4060: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
4070: 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 ynchronization T
4080: 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 ype Flags.**.**
4090: 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f When SQLite invo
40a0: 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 kes the xSync()
40b0: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 method of an [sq
40c0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
40d0: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 74 20 75 ].** object it u
40e0: 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f ses a combinatio
40f0: 6e 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 n of the followi
4100: 6e 67 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 ng integer value
4110: 73 20 61 73 0a 2a 2a 20 74 68 65 20 73 65 63 6f s as.** the seco
4120: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a nd argument..**.
4130: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 ** When the SQLI
4140: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 TE_SYNC_DATAONLY
4150: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 flag is used, i
4160: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 t means that the
4170: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 .** sync operati
4180: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f on only needs to
4190: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d flush data to m
41a0: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e ass storage. In
41b0: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 ode.** informati
41c0: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 on need not be f
41d0: 6c 75 73 68 65 64 2e 20 20 54 68 65 20 53 51 4c lushed. The SQL
41e0: 49 54 45 5f 53 59 4e 43 5f 42 41 52 52 49 45 52 ITE_SYNC_BARRIER
41f0: 20 66 6c 61 67 0a 2a 2a 20 6d 65 61 6e 73 20 74 flag.** means t
4200: 68 61 74 20 74 68 65 20 6e 6f 74 68 69 6e 67 20 hat the nothing
4210: 61 63 74 75 61 6c 6c 79 20 6e 65 65 64 73 20 74 actually needs t
4220: 6f 20 62 65 20 73 79 6e 63 68 65 64 20 74 6f 20 o be synched to
4230: 6d 61 73 73 20 73 74 6f 72 61 67 65 2c 0a 2a 2a mass storage,.**
4240: 20 62 75 74 20 61 6c 6c 20 77 72 69 74 65 20 6f but all write o
4250: 70 65 72 61 74 69 6f 6e 73 20 74 68 61 74 20 6f perations that o
4260: 63 63 75 72 20 62 65 66 6f 72 65 20 74 68 65 20 ccur before the
4270: 62 61 72 72 69 65 72 20 6d 75 73 74 20 63 6f 6d barrier must com
4280: 70 6c 65 74 65 0a 2a 2a 20 62 65 66 6f 72 65 20 plete.** before
4290: 61 6e 79 20 77 72 69 74 65 20 6f 70 65 72 61 74 any write operat
42a0: 69 6f 6e 73 20 74 68 61 74 20 6f 63 63 75 72 20 ions that occur
42b0: 61 66 74 65 72 20 74 68 65 20 62 61 72 72 69 65 after the barrie
42c0: 72 20 62 65 67 69 6e 2e 0a 2a 2a 20 54 68 65 20 r begin..** The
42d0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d SQLITE_SYNC_NORM
42e0: 41 4c 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 AL means to use
42f0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 normal fsync() s
4300: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 54 68 65 emantics..** The
4310: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c SQLITE_SYNC_FUL
4320: 4c 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 6f 20 L flag means to
4330: 75 73 65 20 4d 61 63 20 4f 53 2d 58 20 73 74 79 use Mac OS-X sty
4340: 6c 65 20 66 75 6c 6c 73 79 6e 63 0a 2a 2a 20 69 le fullsync.** i
4350: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 nstead of fsync(
4360: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 )..*/.#define SQ
4370: 4c 49 54 45 5f 53 59 4e 43 5f 42 41 52 52 49 45 LITE_SYNC_BARRIE
4380: 52 20 20 20 20 20 20 20 30 78 30 30 30 30 31 0a R 0x00001.
4390: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
43a0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 YNC_NORMAL
43b0: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 0x00002.#defin
43c0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 e SQLITE_SYNC_FU
43d0: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 LL 0x00
43e0: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 003.#define SQLI
43f0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 TE_SYNC_DATAONLY
4400: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 0a 0x00010...
4410: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
4420: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 OS Interface Ope
4430: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a n File Handle.**
4440: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f .** An [sqlite3_
4450: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 file] object rep
4460: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 resents an open
4470: 66 69 6c 65 20 69 6e 20 74 68 65 20 4f 53 0a 2a file in the OS.*
4480: 2a 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 * interface laye
4490: 72 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f r. Individual O
44a0: 53 20 69 6e 74 65 72 66 61 63 65 20 69 6d 70 6c S interface impl
44b0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c ementations will
44c0: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 .** want to subc
44d0: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 lass this object
44e0: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 by appending ad
44f0: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a ditional fields.
4500: 2a 2a 20 6f 66 20 74 68 65 69 72 20 6f 77 6e 20 ** of their own
4510: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f use. The pMetho
4520: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f ds entry is a po
4530: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b inter to an.** [
4540: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
4550: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 ds] object that
4560: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 defines methods
4570: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a for performing.*
4580: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 * I/O operations
4590: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c on the open fil
45a0: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 e..*/.typedef st
45b0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c ruct sqlite3_fil
45c0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a e sqlite3_file;.
45d0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 struct sqlite3_f
45e0: 69 6c 65 20 7b 0a 20 20 73 74 72 75 63 74 20 73 ile {. struct s
45f0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
4600: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a s *pMethods; /*
4610: 20 4d 65 74 68 6f 64 73 20 61 67 61 69 6e 73 74 Methods against
4620: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 2a the open file *
4630: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.};../*.** CAPI
4640: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 3REF: OS Interfa
4650: 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 ce File Virtual
4660: 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a Methods Object.*
4670: 2a 0a 2a 2a 20 45 76 65 72 79 20 6f 70 65 6e 20 *.** Every open
4680: 66 69 6c 65 20 69 6e 20 74 68 65 20 5b 73 71 6c file in the [sql
4690: 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 ite3_vfs] xOpen
46a0: 6d 65 74 68 6f 64 20 63 6f 6e 74 61 69 6e 73 20 method contains
46b0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 a pointer to.**
46c0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 an instance of t
46d0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 6f 62 6a he following obj
46e0: 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 ect. This objec
46f0: 74 20 64 65 66 69 6e 65 73 20 74 68 65 0a 2a 2a t defines the.**
4700: 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f methods used to
4710: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 perform various
4720: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 67 61 69 operations agai
4730: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c nst the open fil
4740: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 e..**.** The fla
4750: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 gs argument to x
4760: 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 Sync may be one
4770: 6f 66 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 42 of SQLITE_SYNC_B
4780: 41 52 52 49 45 52 2c 0a 2a 2a 20 53 51 4c 49 54 ARRIER,.** SQLIT
4790: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 53 E_SYNC_NORMAL, S
47a0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2e QLITE_SYNC_FULL.
47b0: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 The first choi
47c0: 63 65 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a ce means that.**
47d0: 20 64 61 74 61 20 69 73 20 6e 6f 74 20 6e 65 63 data is not nec
47e0: 65 73 73 61 72 69 6c 79 20 73 79 6e 63 65 64 20 essarily synced
47f0: 74 6f 20 64 69 73 6b 20 63 6f 6d 70 6c 65 74 65 to disk complete
4800: 6c 79 2c 20 6f 6e 6c 79 20 74 68 61 74 0a 2a 2a ly, only that.**
4810: 20 61 6c 6c 20 77 72 69 74 65 73 20 74 68 61 74 all writes that
4820: 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20 74 68 occur before th
4830: 65 20 73 79 6e 63 20 63 6f 6d 70 6c 65 74 65 20 e sync complete
4840: 62 65 66 6f 72 65 20 61 6e 79 0a 2a 2a 20 77 72 before any.** wr
4850: 69 74 65 73 20 74 68 61 74 20 6f 63 63 75 72 20 ites that occur
4860: 61 66 74 65 72 20 74 68 65 20 73 79 6e 63 2e 20 after the sync.
4870: 20 54 68 65 20 73 65 63 6f 6e 64 20 66 6c 61 67 The second flag
4880: 20 69 73 20 74 68 65 0a 2a 2a 20 6e 6f 72 6d 61 is the.** norma
4890: 6c 20 66 73 79 6e 63 28 29 2e 20 20 54 68 65 20 l fsync(). The
48a0: 74 68 69 72 64 20 66 6c 61 67 20 69 73 20 61 20 third flag is a
48b0: 4f 53 2d 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 OS-X style fulls
48c0: 79 6e 63 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 ync..** The SQLI
48d0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 20 66 6c 61 TE_SYNC_DATA fla
48e0: 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e g may be ORed in
48f0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 to indicate tha
4900: 74 20 6f 6e 6c 79 0a 2a 2a 20 74 68 65 20 64 61 t only.** the da
4910: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 20 61 ta of the file a
4920: 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 nd not its inode
4930: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e needs to be syn
4940: 63 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 ced..** .** The
4950: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 integer values t
4960: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 o xLock() and xU
4970: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 nlock() are one
4980: 6f 66 0a 2a 2a 20 53 51 4c 49 54 45 5f 4c 4f 43 of.** SQLITE_LOC
4990: 4b 5f 4e 4f 4e 45 2c 20 53 51 4c 49 54 45 5f 4c K_NONE, SQLITE_L
49a0: 4f 43 4b 5f 52 45 41 44 2c 20 53 51 4c 49 54 45 OCK_READ, SQLITE
49b0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 2c 0a _LOCK_RESERVED,.
49c0: 2a 2a 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 ** SQLITE_LOCK_P
49d0: 45 4e 44 49 4e 47 2c 20 6f 72 20 53 51 4c 49 54 ENDING, or SQLIT
49e0: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 E_LOCK_EXCLUSIVE
49f0: 2e 20 20 78 4c 6f 63 6b 28 29 0a 2a 2a 20 69 6e . xLock().** in
4a00: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b creases the lock
4a10: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 . xUnlock() decr
4a20: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 eases the lock.
4a30: 20 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 .** The xCheckR
4a40: 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 eservedLock() me
4a50: 74 68 6f 64 20 6c 6f 6f 6b 73 0a 2a 2a 20 74 6f thod looks.** to
4a60: 20 73 65 65 20 69 66 20 61 6e 79 20 64 61 74 61 see if any data
4a70: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c base connection,
4a80: 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 0a either in this.
4a90: 2a 2a 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e ** process or in
4aa0: 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 some other proc
4ab0: 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 ess, is holding
4ac0: 61 6e 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 an RESERVED,.**
4ad0: 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c PENDING, or EXCL
4ae0: 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 USIVE lock on th
4af0: 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 e file. It retu
4b00: 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 rns true.** if s
4b10: 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 uch a lock exist
4b20: 73 20 61 6e 64 20 66 61 6c 73 65 20 69 66 20 6e s and false if n
4b30: 6f 74 2e 0a 2a 2a 20 0a 2a 2a 20 78 42 72 65 61 ot..** .** xBrea
4b40: 6b 4c 6f 63 6b 28 29 20 61 74 74 65 6d 70 74 73 kLock() attempts
4b50: 20 74 6f 20 62 72 65 61 6b 20 61 20 6c 6f 63 6b to break a lock
4b60: 20 68 65 6c 64 20 62 79 20 61 6e 6f 74 68 65 72 held by another
4b70: 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69 process..** Thi
4b80: 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f s can be used to
4b90: 20 72 65 6d 6f 76 65 20 61 20 73 74 61 6c 65 20 remove a stale
4ba0: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 2c 20 66 dot-file lock, f
4bb0: 6f 72 20 65 78 61 6d 70 6c 65 2e 0a 2a 2a 20 49 or example..** I
4bc0: 74 20 72 65 74 75 72 6e 73 20 30 20 6f 6e 20 73 t returns 0 on s
4bd0: 75 63 63 65 73 73 20 61 6e 64 20 6e 6f 6e 2d 7a uccess and non-z
4be0: 65 72 6f 20 66 6f 72 20 61 20 66 61 69 6c 75 72 ero for a failur
4bf0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 e..**.** The xSe
4c00: 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f ctorSize() metho
4c10: 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 d returns the se
4c20: 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 ctor size of the
4c30: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 .** device that
4c40: 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 underlies the fi
4c50: 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 le. The sector
4c60: 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d size is the.** m
4c70: 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 inimum write tha
4c80: 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d t can be perform
4c90: 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 ed without distu
4ca0: 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 rbing.** other b
4cb0: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 ytes in the file
4cc0: 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 . The xDeviceCh
4cd0: 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a aracteristics().
4ce0: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e ** method return
4cf0: 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 s a bit vector d
4d00: 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 escribing behavi
4d10: 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e ors of the.** un
4d20: 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a derlying device:
4d30: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
4d40: 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 li> SQLITE_IOCAP
4d50: 5f 41 54 4f 4d 49 43 0a 2a 2a 20 3c 6c 69 3e 20 _ATOMIC.** <li>
4d60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
4d70: 4d 49 43 35 31 32 0a 2a 2a 20 3c 6c 69 3e 20 53 MIC512.** <li> S
4d80: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
4d90: 49 43 31 4b 0a 2a 2a 20 3c 6c 69 3e 20 53 51 4c IC1K.** <li> SQL
4da0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
4db0: 32 4b 0a 2a 2a 20 3c 6c 69 3e 20 53 51 4c 49 54 2K.** <li> SQLIT
4dc0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b E_IOCAP_ATOMIC4K
4dd0: 0a 2a 2a 20 3c 6c 69 3e 20 53 51 4c 49 54 45 5f .** <li> SQLITE_
4de0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 0a 2a IOCAP_ATOMIC8K.*
4df0: 2a 20 3c 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f * <li> SQLITE_IO
4e00: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 0a 2a 2a CAP_ATOMIC16K.**
4e10: 20 3c 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f 43 <li> SQLITE_IOC
4e20: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 0a 2a 2a 20 AP_ATOMIC32K.**
4e30: 3c 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f 43 41 <li> SQLITE_IOCA
4e40: 50 5f 41 54 4f 4d 49 43 36 34 4b 0a 2a 2a 20 3c P_ATOMIC64K.** <
4e50: 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 li> SQLITE_IOCAP
4e60: 5f 53 41 46 45 5f 41 50 50 45 4e 44 0a 2a 2a 20 _SAFE_APPEND.**
4e70: 3c 6c 69 3e 20 53 51 4c 49 54 45 5f 49 4f 43 41 <li> SQLITE_IOCA
4e80: 50 5f 53 45 51 55 45 4e 54 49 41 4c 0a 2a 2a 20 P_SEQUENTIAL.**
4e90: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 </ul>.**.** The
4ea0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
4eb0: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 MIC property mea
4ec0: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 ns that all writ
4ed0: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a es of.** any siz
4ee0: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 e are atomic. T
4ef0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
4f00: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 ATOMICnnn values
4f10: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 .** mean that wr
4f20: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 ites of blocks t
4f30: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 hat are nnn byte
4f40: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a s in size and.**
4f50: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 are aligned to
4f60: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 an address which
4f70: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d is an integer m
4f80: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e ultiple of.** nn
4f90: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 n are atomic. T
4fa0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
4fb0: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 SAFE_APPEND valu
4fc0: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 e means.** that
4fd0: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 when data is app
4fe0: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c ended to a file,
4ff0: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 the data is app
5000: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 ended.** first t
5010: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 hen the size of
5020: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 the file is exte
5030: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 nded, never the
5040: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f other.** way aro
5050: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 und. The SQLITE
5060: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 _IOCAP_SEQUENTIA
5070: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 L property means
5080: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 that.** informa
5090: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 tion is written
50a0: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 to disk in the s
50b0: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c ame order as cal
50c0: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 ls.** to xWrite(
50d0: 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 )..*/.typedef st
50e0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f ruct sqlite3_io_
50f0: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f methods sqlite3_
5100: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 io_methods;.stru
5110: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 ct sqlite3_io_me
5120: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 thods {. int iV
5130: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a ersion;. int (*
5140: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f xClose)(sqlite3_
5150: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a file*);. int (*
5160: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 xRead)(sqlite3_f
5170: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 ile*, void*, int
5180: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 5f 69 6e iAmt, sqlite_in
5190: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e t64 iOfst);. in
51a0: 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 t (*xWrite)(sqli
51b0: 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 te3_file*, const
51c0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 void*, int iAmt
51d0: 2c 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 69 , sqlite_int64 i
51e0: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 Ofst);. int (*x
51f0: 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 Truncate)(sqlite
5200: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 5f 3_file*, sqlite_
5210: 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 int64 size);. i
5220: 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 nt (*xSync)(sqli
5230: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 te3_file*, int f
5240: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 lags);. int (*x
5250: 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 FileSize)(sqlite
5260: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 5f 3_file*, sqlite_
5270: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 int64 *pSize);.
5280: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 int (*xLock)(sq
5290: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 lite3_file*, int
52a0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f );. int (*xUnlo
52b0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ck)(sqlite3_file
52c0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 *, int);. int (
52d0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c *xCheckReservedL
52e0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ock)(sqlite3_fil
52f0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 72 e*);. int (*xBr
5300: 65 61 6b 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 eakLock)(sqlite3
5310: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 _file*);. int (
5320: 2a 78 4c 6f 63 6b 53 74 61 74 65 29 28 73 71 6c *xLockState)(sql
5330: 69 74 65 33 5f 66 69 6c 65 20 2a 29 3b 0a 20 20 ite3_file *);.
5340: 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a int (*xSectorSiz
5350: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a e)(sqlite3_file*
5360: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 );. int (*xDevi
5370: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 ceCharacteristic
5380: 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a s)(sqlite3_file*
5390: 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e );. /* Addition
53a0: 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 al methods may b
53b0: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
53c0: 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b e releases */.};
53d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
53e0: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a : Mutex Handle.*
53f0: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d *.** The mutex m
5400: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c odule within SQL
5410: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c ite defines [sql
5420: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 ite3_mutex] to b
5430: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 e an.** abstract
5440: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 type for a mute
5450: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 x object. The S
5460: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 QLite core never
5470: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 looks.** at the
5480: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 internal repres
5490: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b entation of an [
54a0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 sqlite3_mutex].
54b0: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c It only.** deal
54c0: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 s with pointers
54d0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
54e0: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a mutex] object..*
54f0: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 *.** Mutexes are
5500: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b created using [
5510: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c sqlite3_mutex_al
5520: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 loc()]..*/.typed
5530: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
5540: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 3_mutex sqlite3_
5550: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 mutex;../*.** CA
5560: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 PI3REF: OS Inter
5570: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a face Object.**.*
5580: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 * An instance of
5590: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 this object def
55a0: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 ines the interfa
55b0: 63 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a ce between the.*
55c0: 2a 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e * SQLite core an
55d0: 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 d the underlying
55e0: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 operating syste
55f0: 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a m. The "vfs".**
5600: 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 in the name of
5610: 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 the object stand
5620: 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 s for "virtual f
5630: 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a ile system"..**.
5640: 2a 2a 20 54 68 65 20 69 56 65 72 73 69 6f 6e 20 ** The iVersion
5650: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c field is initial
5660: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 ly 1 but may be
5670: 6c 61 72 67 65 72 20 66 6f 72 20 66 75 74 75 72 larger for futur
5680: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 e.** versions of
5690: 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 SQLite. Additi
56a0: 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 onal fields may
56b0: 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 be appended to t
56c0: 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 his.** object wh
56d0: 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 en the iVersion
56e0: 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 value is increas
56f0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a ed..**.** The sz
5700: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 OsFile field is
5710: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
5720: 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 subclassed sqlit
5730: 65 33 5f 66 69 6c 65 0a 2a 2a 20 73 74 72 75 63 e3_file.** struc
5740: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 ture used by thi
5750: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 s VFS. mxPathna
5760: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 me is the maximu
5770: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 m length of.** a
5780: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 pathname in thi
5790: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 s VFS..**.** The
57a0: 20 6e 52 65 66 20 66 69 65 6c 64 20 69 73 20 69 nRef field is i
57b0: 6e 63 72 65 6d 65 6e 74 65 64 20 61 6e 64 20 64 ncremented and d
57c0: 65 63 72 65 6d 65 6e 74 65 64 20 62 79 20 53 51 ecremented by SQ
57d0: 4c 69 74 65 20 74 6f 20 6b 65 65 70 0a 2a 2a 20 Lite to keep.**
57e0: 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d count of the num
57f0: 62 65 72 20 6f 66 20 75 73 65 72 73 20 6f 66 20 ber of users of
5800: 74 68 65 20 56 46 53 2e 20 20 54 68 69 73 20 66 the VFS. This f
5810: 69 65 6c 64 20 61 6e 64 0a 2a 2a 20 76 66 73 4d ield and.** vfsM
5820: 75 74 65 78 2c 20 70 4e 65 78 74 2c 20 61 6e 64 utex, pNext, and
5830: 20 70 50 72 65 76 20 61 72 65 20 74 68 65 20 6f pPrev are the o
5840: 6e 6c 79 20 66 69 65 6c 64 73 20 69 6e 20 74 68 nly fields in th
5850: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 0a 2a e sqlite3_vfs .*
5860: 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 * structure that
5870: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 SQLite will eve
5880: 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 r modify. SQLit
5890: 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 e will only acce
58a0: 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 ss.** or modify
58b0: 74 68 65 73 65 20 66 69 65 6c 64 73 20 77 68 69 these fields whi
58c0: 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 le holding a par
58d0: 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d ticular static m
58e0: 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 utex..** The app
58f0: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 lication should
5900: 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 never modify any
5910: 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20 73 fields of the s
5920: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 qlite3_vfs.** ob
5930: 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 ject once the ob
5940: 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 ject has been re
5950: 67 69 73 74 65 72 65 64 2e 0a 2a 2a 20 0a 2a 2a gistered..** .**
5960: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 The sqlite3_vfs
5970: 2e 76 66 73 4d 75 74 65 78 20 69 73 20 61 20 6d .vfsMutex is a m
5980: 75 74 65 78 20 75 73 65 64 20 62 79 20 74 68 65 utex used by the
5990: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a OS interface..*
59a0: 2a 20 49 74 20 73 68 6f 75 6c 64 20 69 6e 69 74 * It should init
59b0: 69 61 6c 6c 79 20 62 65 20 4e 55 4c 4c 2e 20 20 ially be NULL.
59c0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 69 74 SQLite will init
59d0: 69 61 6c 69 7a 65 20 74 68 69 73 20 66 69 65 6c ialize this fiel
59e0: 64 0a 2a 2a 20 75 73 69 6e 67 20 73 71 6c 69 74 d.** using sqlit
59f0: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 e3_mutex_alloc()
5a00: 20 75 70 6f 6e 20 66 69 72 73 74 20 75 73 65 20 upon first use
5a10: 6f 66 20 74 68 65 20 61 64 61 70 74 6f 72 0a 2a of the adaptor.*
5a20: 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6f 70 65 * by sqlite3_ope
5a30: 6e 5f 76 32 28 29 20 61 6e 64 20 77 69 6c 6c 20 n_v2() and will
5a40: 64 65 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 6d deallocate the m
5a50: 75 74 65 78 20 77 68 65 6e 20 74 68 65 0a 2a 2a utex when the.**
5a60: 20 6c 61 73 74 20 75 73 65 72 20 63 6c 6f 73 65 last user close
5a70: 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 s. In other wor
5a80: 64 73 2c 20 76 66 73 4d 75 74 65 78 20 77 69 6c ds, vfsMutex wil
5a90: 6c 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 0a 2a l be allocated.*
5aa0: 2a 20 77 68 65 6e 20 6e 52 65 66 20 74 72 61 6e * when nRef tran
5ab0: 73 69 74 69 6f 6e 73 20 66 72 6f 6d 20 30 20 74 sitions from 0 t
5ac0: 6f 20 31 20 61 6e 64 20 77 69 6c 6c 20 62 65 20 o 1 and will be
5ad0: 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e deallocated when
5ae0: 0a 2a 2a 20 6e 52 65 66 20 74 72 61 6e 73 69 74 .** nRef transit
5af0: 69 6f 6e 73 20 66 72 6f 6d 20 31 20 74 6f 20 30 ions from 1 to 0
5b00: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 ..**.** Register
5b10: 65 64 20 76 66 73 20 6d 6f 64 75 6c 65 73 20 61 ed vfs modules a
5b20: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e re kept on a lin
5b30: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 ked list formed
5b40: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 by.** the pNext
5b50: 61 6e 64 20 70 50 72 65 76 20 70 6f 69 6e 74 65 and pPrev pointe
5b60: 72 73 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 rs. The [sqlite
5b70: 33 5f 72 65 67 69 73 74 65 72 5f 76 66 73 28 29 3_register_vfs()
5b80: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 ].** and [sqlite
5b90: 33 5f 75 6e 72 65 67 69 73 74 65 72 5f 76 66 73 3_unregister_vfs
5ba0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d ()] interfaces m
5bb0: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a anage this list.
5bc0: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 ** in a thread-s
5bd0: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 afe way. The [s
5be0: 71 6c 69 74 65 33 5f 61 63 71 75 69 72 65 5f 76 qlite3_acquire_v
5bf0: 66 73 28 29 5d 20 73 65 61 72 63 68 65 73 20 74 fs()] searches t
5c00: 68 65 0a 2a 2a 20 6c 69 73 74 2e 0a 2a 2a 0a 2a he.** list..**.*
5c10: 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c * The zName fiel
5c20: 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 d holds the name
5c30: 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 of the VFS modu
5c40: 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 le. The name mu
5c50: 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 st.** be unique
5c60: 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d across all VFS m
5c70: 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 51 odules..**.** SQ
5c80: 4c 69 74 65 20 77 69 6c 6c 20 67 75 61 72 61 6e Lite will guaran
5c90: 74 65 65 20 74 68 61 74 20 74 68 65 20 7a 46 69 tee that the zFi
5ca0: 6c 65 6e 61 6d 65 20 73 74 72 69 6e 67 20 70 61 lename string pa
5cb0: 73 73 65 64 20 74 6f 0a 2a 2a 20 78 4f 70 65 6e ssed to.** xOpen
5cc0: 28 29 20 69 73 20 61 20 66 75 6c 6c 20 70 61 74 () is a full pat
5cd0: 68 6e 61 6d 65 20 61 73 20 67 65 6e 65 72 61 74 hname as generat
5ce0: 65 64 20 62 79 20 78 46 75 6c 6c 50 61 74 68 6e ed by xFullPathn
5cf0: 61 6d 65 28 29 20 61 6e 64 0a 2a 2a 20 74 68 61 ame() and.** tha
5d00: 74 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c t the string wil
5d10: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 l be valid and u
5d20: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 nchanged until x
5d30: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 Close() is.** ca
5d40: 6c 6c 65 64 2e 20 20 53 6f 20 74 68 65 20 73 71 lled. So the sq
5d50: 6c 69 74 65 33 5f 66 69 6c 65 20 63 61 6e 20 73 lite3_file can s
5d60: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 tore a pointer t
5d70: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d o the.** filenam
5d80: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f e if it needs to
5d90: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 remember the fi
5da0: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 lename for some
5db0: 72 65 61 73 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 reason..**.** Th
5dc0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 e flags argument
5dd0: 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 73 20 61 to xOpen() is a
5de0: 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6c 61 copy of the fla
5df0: 67 73 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 gs argument.** t
5e00: 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 o sqlite3_open_v
5e10: 32 28 29 2e 20 20 49 66 20 73 71 6c 69 74 65 33 2(). If sqlite3
5e20: 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 _open() or sqlit
5e30: 65 33 5f 6f 70 65 6e 31 36 28 29 0a 2a 2a 20 69 e3_open16().** i
5e40: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 s used, then fla
5e50: 67 73 20 69 73 20 53 51 4c 49 54 45 5f 4f 50 45 gs is SQLITE_OPE
5e60: 4e 5f 52 45 41 44 57 52 49 54 45 20 7c 20 53 51 N_READWRITE | SQ
5e70: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
5e80: 2e 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 ..** If xOpen()
5e90: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 opens a file rea
5ea0: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 d-only then it s
5eb0: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 ets *pOutFlags t
5ec0: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 53 51 4c o.** include SQL
5ed0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c ITE_OPEN_READONL
5ee0: 59 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 Y. Other bits i
5ef0: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 n *pOutFlags may
5f00: 20 62 65 0a 2a 2a 20 73 65 74 2e 0a 2a 2a 20 0a be.** set..** .
5f10: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 ** SQLite will a
5f20: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 lso add one of t
5f30: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 he following fla
5f40: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 gs to the xOpen(
5f50: 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e ).** call, depen
5f60: 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 ding on the obje
5f70: 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a ct being opened:
5f80: 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 .** .** <ul>.**
5f90: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
5fa0: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c EN_MAIN_DB].** <
5fb0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
5fc0: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a N_MAIN_JOURNAL].
5fd0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
5fe0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a _OPEN_TEMP_DB].*
5ff0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
6000: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 OPEN_TEMP_JOURNA
6010: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c L].** <li> [SQL
6020: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 ITE_OPEN_SUBJOUR
6030: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 NAL].** <li> [S
6040: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 QLITE_OPEN_MASTE
6050: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f R_JOURNAL].** </
6060: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 ul>.**.** The fi
6070: 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 le I/O implement
6080: 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 ation can use th
6090: 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c e object type fl
60a0: 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 ags to.** change
60b0: 73 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 s the way it dea
60c0: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 ls with files.
60d0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 For example, an
60e0: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 application.** t
60f0: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 hat does not car
6100: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 e about crash re
6110: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 covery or rollba
6120: 63 6b 2c 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a ck, might make.*
6130: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 * the open of a
6140: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e journal file a n
6150: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f o-op. Writes to
6160: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 61 72 this journal ar
6170: 65 0a 2a 2a 20 61 6c 73 6f 20 61 20 6e 6f 2d 6f e.** also a no-o
6180: 70 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 74 20 p. Any attempt
6190: 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 to read the jour
61a0: 6e 61 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 nal return SQLIT
61b0: 45 5f 49 4f 45 52 52 2e 0a 2a 2a 20 4f 72 20 74 E_IOERR..** Or t
61c0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
61d0: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a n might recogniz
61e0: 65 20 74 68 65 20 61 20 64 61 74 61 62 61 73 65 e the a database
61f0: 20 66 69 6c 65 20 77 69 6c 6c 0a 2a 2a 20 62 65 file will.** be
6200: 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 doing page-alig
6210: 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 ned sector reads
6220: 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 and writes in a
6230: 20 72 61 6e 64 6f 6d 20 6f 72 64 65 72 0a 2a 2a random order.**
6240: 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 and set up its
6250: 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 I/O subsystem ac
6260: 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 20 0a 2a cordingly..** .*
6270: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 * SQLite might a
6280: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 lso add one of t
6290: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 he following fla
62a0: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a gs to the xOpen.
62b0: 2a 2a 20 6d 65 74 68 6f 64 3a 0a 2a 2a 20 0a 2a ** method:.** .*
62c0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b * <ul>.** <li> [
62d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 SQLITE_OPEN_DELE
62e0: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c TEONCLOSE].** <l
62f0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f i> [SQLITE_OPEN_
6300: 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f EXCLUSIVE].** </
6310: 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 5b ul>.** .** The [
6320: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 SQLITE_OPEN_DELE
6330: 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 TEONCLOSE] flag
6340: 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 means the file s
6350: 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 hould be.** dele
6360: 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 ted when it is c
6370: 6c 6f 73 65 64 2e 20 20 54 68 69 73 20 77 69 6c losed. This wil
6380: 6c 20 61 6c 77 61 79 73 20 62 65 20 73 65 74 20 l always be set
6390: 66 6f 72 20 54 45 4d 50 20 0a 2a 2a 20 64 61 74 for TEMP .** dat
63a0: 61 62 61 73 65 73 20 61 6e 64 20 6a 6f 75 72 6e abases and journ
63b0: 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a als and for subj
63c0: 6f 75 72 6e 61 6c 73 2e 20 20 54 68 65 20 0a 2a ournals. The .*
63d0: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 * [SQLITE_OPEN_E
63e0: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 6d XCLUSIVE] flag m
63f0: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 eans the file sh
6400: 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 0a 2a ould be opened.*
6410: 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 * for exclusive
6420: 61 63 63 65 73 73 2e 20 20 54 68 69 73 20 66 6c access. This fl
6430: 61 67 20 69 73 20 73 65 74 20 66 6f 72 20 61 6c ag is set for al
6440: 6c 20 66 69 6c 65 73 20 65 78 63 65 70 74 0a 2a l files except.*
6450: 2a 20 66 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 * for the main d
6460: 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a atabase file..**
6470: 20 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 .** The sqlite3
6480: 5f 66 69 6c 65 20 73 74 72 75 63 74 75 72 65 20 _file structure
6490: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 passed as the th
64a0: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a ird argument to.
64b0: 2a 2a 20 78 4f 70 65 6e 20 69 73 20 61 6c 6c 6f ** xOpen is allo
64c0: 63 61 74 65 64 20 62 79 20 74 68 65 20 63 61 6c cated by the cal
64d0: 6c 65 72 2e 20 20 78 4f 70 65 6e 20 6a 75 73 74 ler. xOpen just
64e0: 20 66 69 6c 6c 73 20 69 74 20 69 6e 2e 20 20 54 fills it in. T
64f0: 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 20 61 6c 6c he.** caller all
6500: 6f 63 61 74 65 73 20 61 20 6d 69 6e 69 6d 75 6d ocates a minimum
6510: 20 6f 66 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 of szOsFile byt
6520: 65 73 20 66 6f 72 20 74 68 65 20 73 71 6c 69 74 es for the sqlit
6530: 65 33 5f 66 69 6c 65 0a 2a 2a 20 73 74 72 75 63 e3_file.** struc
6540: 74 75 72 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 ture..** .** The
6550: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 flags argument
6560: 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 to xAccess() may
6570: 20 62 65 20 30 20 28 74 6f 20 74 65 73 74 20 66 be 0 (to test f
6580: 6f 72 20 74 68 65 0a 2a 2a 20 65 78 69 73 74 61 or the.** exista
6590: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 29 20 6f nce of a file) o
65a0: 72 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f r SQLITE_ACCESS_
65b0: 52 45 41 44 57 52 49 54 45 20 74 6f 20 74 65 73 READWRITE to tes
65c0: 74 20 74 6f 20 73 65 65 0a 2a 2a 20 69 66 20 61 t to see.** if a
65d0: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c file is readabl
65e0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 e and writable,
65f0: 6f 72 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 or SQLITE_ACCESS
6600: 5f 52 45 41 44 4f 4e 4c 59 0a 2a 2a 20 74 6f 20 _READONLY.** to
6610: 74 65 73 74 20 74 6f 20 73 65 65 20 69 66 20 61 test to see if a
6620: 20 66 69 6c 65 20 69 73 20 72 65 61 64 2d 6f 6e file is read-on
6630: 6c 79 2e 20 20 54 68 65 20 66 69 6c 65 20 63 61 ly. The file ca
6640: 6e 20 62 65 20 61 20 0a 2a 2a 20 64 69 72 65 63 n be a .** direc
6650: 74 6f 72 79 2e 0a 2a 2a 20 0a 2a 2a 20 53 51 4c tory..** .** SQL
6660: 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 ite will always
6670: 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 allocate at leas
6680: 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 t mxPathname+1 b
6690: 79 74 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6f yte for.** the o
66a0: 75 74 70 75 74 20 62 75 66 66 65 72 73 20 66 6f utput buffers fo
66b0: 72 20 78 47 65 74 54 65 6d 70 4e 61 6d 65 20 61 r xGetTempName a
66c0: 6e 64 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 nd xFullPathname
66d0: 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 78 52 61 ..** .** The xRa
66e0: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 ndomness(), xSle
66f0: 65 70 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 ep(), and xCurre
6700: 6e 74 54 69 6d 65 28 29 20 69 6e 74 65 72 66 61 ntTime() interfa
6710: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73 ces.** are not s
6720: 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f trictly a part o
6730: 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d f the filesystem
6740: 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a , but they are.*
6750: 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 * included in th
6760: 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 e VFS structure
6770: 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 for completeness
6780: 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d ..** The xRandom
6790: 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 ness() function
67a0: 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 attempts to retu
67b0: 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a rn nBytes bytes.
67c0: 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 ** of good-quali
67d0: 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e ty randomness in
67e0: 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 to zOut. The re
67f0: 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a turn value is.**
6800: 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 the actual numb
6810: 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 er of bytes of r
6820: 61 6e 64 6f 6d 6e 65 73 73 20 67 65 6e 65 72 61 andomness genera
6830: 74 65 64 2e 20 20 54 68 65 0a 2a 2a 20 78 53 6c ted. The.** xSl
6840: 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 eep() method cau
6850: 73 65 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 se the calling t
6860: 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 hread to sleep f
6870: 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 or at.** least t
6880: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 he number of mic
6890: 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e roseconds given.
68a0: 20 20 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 The xCurrentTi
68b0: 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 me().** method r
68c0: 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 eturns a Julian
68d0: 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 Day Number for t
68e0: 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 he current date
68f0: 61 6e 64 0a 2a 2a 20 74 69 6d 65 2e 0a 2a 2f 0a and.** time..*/.
6900: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
6910: 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 qlite3_vfs sqlit
6920: 65 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 73 e3_vfs;.struct s
6930: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 qlite3_vfs {. i
6940: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 nt iVersion;
6950: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 /* Struc
6960: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d ture version num
6970: 62 65 72 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f ber */. int szO
6980: 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 sFile;
6990: 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 /* Size of sub
69a0: 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f classed sqlite3_
69b0: 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 file */. int mx
69c0: 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 Pathname;
69d0: 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 /* Maximum fi
69e0: 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 le pathname leng
69f0: 74 68 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 th */. int nRef
6a00: 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ;
6a10: 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 /* Number of re
6a20: 66 65 72 65 6e 63 65 73 20 74 6f 20 74 68 69 73 ferences to this
6a30: 20 73 74 72 75 63 74 75 72 65 20 2a 2f 0a 20 20 structure */.
6a40: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 76 sqlite3_mutex *v
6a50: 66 73 4d 75 74 65 78 3b 20 2f 2a 20 41 20 6d 75 fsMutex; /* A mu
6a60: 74 65 78 20 66 6f 72 20 74 68 69 73 20 56 46 53 tex for this VFS
6a70: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 */. sqlite3_vf
6a80: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f s *pNext; /
6a90: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 * Next registere
6aa0: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 d VFS */. const
6ab0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 char *zName;
6ac0: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 /* Name of t
6ad0: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 his virtual file
6ae0: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 system */. voi
6af0: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 d *pAppData;
6b00: 20 20 20 20 20 20 2f 2a 20 41 70 70 6c 69 63 61 /* Applica
6b10: 74 69 6f 6e 20 63 6f 6e 74 65 78 74 20 2a 2f 0a tion context */.
6b20: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 76 int (*xOpen)(v
6b30: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 2c 20 63 oid *pAppData, c
6b40: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
6b50: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c , sqlite3_file*,
6b60: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 .
6b70: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a int flags, int *
6b80: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e pOutFlags);. in
6b90: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 76 6f 69 t (*xDelete)(voi
6ba0: 64 20 2a 70 41 70 70 44 61 74 61 2c 20 63 6f 6e d *pAppData, con
6bb0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
6bc0: 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 int syncDir);.
6bd0: 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 76 int (*xAccess)(v
6be0: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 2c 20 63 oid *pAppData, c
6bf0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
6c00: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 , int flags);.
6c10: 69 6e 74 20 28 2a 78 47 65 74 54 65 6d 70 4e 61 int (*xGetTempNa
6c20: 6d 65 29 28 76 6f 69 64 20 2a 70 41 70 70 44 61 me)(void *pAppDa
6c30: 74 61 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b ta, char *zOut);
6c40: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 . int (*xFullPa
6c50: 74 68 6e 61 6d 65 29 28 76 6f 69 64 20 2a 70 41 thname)(void *pA
6c60: 70 70 44 61 74 61 2c 20 63 6f 6e 73 74 20 63 68 ppData, const ch
6c70: 61 72 20 2a 7a 4e 61 6d 65 2c 20 63 68 61 72 20 ar *zName, char
6c80: 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a *zOut);. void *
6c90: 28 2a 78 44 6c 4f 70 65 6e 29 28 76 6f 69 64 20 (*xDlOpen)(void
6ca0: 2a 70 41 70 70 44 61 74 61 2c 20 63 6f 6e 73 74 *pAppData, const
6cb0: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 char *zFilename
6cc0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 );. void (*xDlE
6cd0: 72 72 6f 72 29 28 76 6f 69 64 20 2a 70 41 70 70 rror)(void *pApp
6ce0: 44 61 74 61 2c 20 69 6e 74 20 6e 42 79 74 65 2c Data, int nByte,
6cf0: 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b char *zErrMsg);
6d00: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 53 79 . void *(*xDlSy
6d10: 6d 29 28 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 m)(void*, const
6d20: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 3b 0a char *zSymbol);.
6d30: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 void (*xDlClos
6d40: 65 29 28 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 e)(void*);. int
6d50: 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 (*xRandomness)(
6d60: 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 2c 20 void *pAppData,
6d70: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 int nByte, char
6d80: 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a *zOut);. int (*
6d90: 78 53 6c 65 65 70 29 28 76 6f 69 64 20 2a 70 41 xSleep)(void *pA
6da0: 70 70 44 61 74 61 2c 20 69 6e 74 20 6d 69 63 72 ppData, int micr
6db0: 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 oseconds);. int
6dc0: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 (*xCurrentTime)
6dd0: 28 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 2c (void *pAppData,
6de0: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 2f 2a 20 double*);. /*
6df0: 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 New fields may b
6e00: 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 e appended in fi
6e10: 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 gure versions.
6e20: 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a The iVersion. *
6e30: 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 * value will inc
6e40: 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 rement whenever
6e50: 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f this happens. */
6e60: 0a 7d 3b 0a 0a 23 64 65 66 69 6e 65 20 53 51 4c .};..#define SQL
6e70: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 ITE_ACCESS_EXIST
6e80: 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 S 0.#define S
6e90: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
6ea0: 44 57 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65 DWRITE 1.#define
6eb0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 SQLITE_ACCESS_R
6ec0: 45 41 44 4f 4e 4c 59 20 20 32 0a 0a 2f 2a 0a 2a EADONLY 2../*.*
6ed0: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 * CAPI3REF: Enab
6ee0: 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 le Or Disable Ex
6ef0: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f tended Result Co
6f00: 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 des.**.** This r
6f10: 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f outine enables o
6f20: 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a r disables the.*
6f30: 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f * [SQLITE_IOERR_
6f40: 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 READ | extended
6f50: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 result codes] fe
6f60: 61 74 75 72 65 2e 0a 2a 2a 20 42 79 20 64 65 66 ature..** By def
6f70: 61 75 6c 74 2c 20 53 51 4c 69 74 65 20 41 50 49 ault, SQLite API
6f80: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
6f90: 20 6f 6e 65 20 6f 66 20 6f 6e 6c 79 20 32 36 20 one of only 26
6fa0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 integer.** [SQLI
6fb0: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 TE_OK | result c
6fc0: 6f 64 65 73 5d 2e 20 20 57 68 65 6e 20 65 78 74 odes]. When ext
6fd0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
6fe0: 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 es.** are enable
6ff0: 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e d by this routin
7000: 65 2c 20 74 68 65 20 72 65 70 65 74 6f 69 72 65 e, the repetoire
7010: 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 64 65 73 of result codes
7020: 20 63 61 6e 20 62 65 0a 2a 2a 20 6d 75 63 68 20 can be.** much
7030: 6c 61 72 67 65 72 20 61 6e 64 20 63 61 6e 20 28 larger and can (
7040: 68 6f 70 65 66 75 6c 6c 79 29 20 70 72 6f 76 69 hopefully) provi
7050: 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 de more detailed
7060: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 information.**
7070: 61 62 6f 75 74 20 74 68 65 20 63 61 75 73 65 20 about the cause
7080: 6f 66 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a of an error..**.
7090: 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 ** The second ar
70a0: 67 75 6d 65 6e 74 20 69 73 20 61 20 62 6f 6f 6c gument is a bool
70b0: 65 61 6e 20 76 61 6c 75 65 20 74 68 61 74 20 74 ean value that t
70c0: 75 72 6e 73 20 65 78 74 65 6e 64 65 64 20 72 65 urns extended re
70d0: 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 6f 6e sult.** codes on
70e0: 20 61 6e 64 20 6f 66 66 2e 20 20 45 78 74 65 6e and off. Exten
70f0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
7100: 20 61 72 65 20 6f 66 66 20 62 79 20 64 65 66 61 are off by defa
7110: 75 6c 74 20 66 6f 72 0a 2a 2a 20 62 61 63 6b 77 ult for.** backw
7120: 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 ards compatibili
7130: 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 76 65 ty with older ve
7140: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
7150: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
7160: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 _extended_result
7170: 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c _codes(sqlite3*,
7180: 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a int onoff);../*
7190: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 .** CAPI3REF: La
71a0: 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a st Insert Rowid.
71b0: 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72 79 **.** Each entry
71c0: 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 in an SQLite ta
71d0: 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 ble has a unique
71e0: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 64-bit signed i
71f0: 6e 74 65 67 65 72 20 6b 65 79 0a 2a 2a 20 63 61 nteger key.** ca
7200: 6c 6c 65 64 20 74 68 65 20 22 72 6f 77 69 64 22 lled the "rowid"
7210: 2e 20 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 . The rowid is a
7220: 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 20 lways available
7230: 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 as an undeclared
7240: 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 .** column named
7250: 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 ROWID, OID, or
7260: 5f 52 4f 57 49 44 5f 2e 20 20 49 66 20 74 68 65 _ROWID_. If the
7270: 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c table has a col
7280: 75 6d 6e 20 6f 66 0a 2a 2a 20 74 79 70 65 20 49 umn of.** type I
7290: 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b NTEGER PRIMARY K
72a0: 45 59 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c EY then that col
72b0: 75 6d 6e 20 69 73 20 61 6e 6f 74 68 65 72 20 61 umn is another a
72c0: 6e 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 0a n alias for the.
72d0: 2a 2a 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 ** rowid..**.**
72e0: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 This routine ret
72f0: 75 72 6e 73 20 74 68 65 20 72 6f 77 69 64 20 6f urns the rowid o
7300: 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e f the most recen
7310: 74 20 49 4e 53 45 52 54 20 69 6e 74 6f 0a 2a 2a t INSERT into.**
7320: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72 the database fr
7330: 6f 6d 20 74 68 65 20 64 61 74 61 62 61 73 65 20 om the database
7340: 63 6f 6e 6e 65 63 74 69 6f 6e 20 67 69 76 65 6e connection given
7350: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 0a 2a in the first .*
7360: 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 * argument. If
7370: 6e 6f 20 69 6e 73 65 72 74 73 20 68 61 76 65 20 no inserts have
7380: 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e ever occurred on
7390: 20 74 68 69 73 20 64 61 74 61 62 61 73 65 0a 2a this database.*
73a0: 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 * connection, ze
73b0: 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a ro is returned..
73c0: 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 49 4e 53 45 **.** If an INSE
73d0: 52 54 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e RT occurs within
73e0: 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e a trigger, then
73f0: 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 the rowid of th
7400: 65 0a 2a 2a 20 69 6e 73 65 72 74 65 64 20 72 6f e.** inserted ro
7410: 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 w is returned by
7420: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73 this routine as
7430: 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 long as the tri
7440: 67 67 65 72 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 gger.** is runni
7450: 6e 67 2e 20 20 42 75 74 20 6f 6e 63 65 20 74 68 ng. But once th
7460: 65 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e e trigger termin
7470: 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 ates, the value
7480: 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 74 returned.** by t
7490: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 his routine reve
74a0: 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 rts to the last
74b0: 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 value inserted b
74c0: 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 74 72 69 efore the.** tri
74d0: 67 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a gger fired..**.*
74e0: 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 * If another thr
74f0: 65 61 64 20 64 6f 65 73 20 61 20 6e 65 77 20 69 ead does a new i
7500: 6e 73 65 72 74 20 6f 6e 20 74 68 65 20 73 61 6d nsert on the sam
7510: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
7520: 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 74 ction.** while t
7530: 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 his routine is r
7540: 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 unning and thus
7550: 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 changes the last
7560: 20 69 6e 73 65 72 74 20 72 6f 77 69 64 2c 0a 2a insert rowid,.*
7570: 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 * then the retur
7580: 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 n value of this
7590: 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 routine is undef
75a0: 69 6e 65 64 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 ined..*/.sqlite3
75b0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c _int64 sqlite3_l
75c0: 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 ast_insert_rowid
75d0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
75e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 ** CAPI3REF: Cou
75f0: 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 nt The Number Of
7600: 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a Rows Modified.*
7610: 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 *.** This functi
7620: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e on returns the n
7630: 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 umber of databas
7640: 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 e rows that were
7650: 20 63 68 61 6e 67 65 64 0a 2a 2a 20 28 6f 72 20 changed.** (or
7660: 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 inserted or dele
7670: 74 65 64 29 20 62 79 20 74 68 65 20 6d 6f 73 74 ted) by the most
7680: 20 72 65 63 65 6e 74 20 53 51 4c 20 73 74 61 74 recent SQL stat
7690: 65 6d 65 6e 74 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 ement. Only.**
76a0: 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 changes that are
76b0: 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 directly specif
76c0: 69 65 64 20 62 79 20 74 68 65 20 49 4e 53 45 52 ied by the INSER
76d0: 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 0a 2a 2a T, UPDATE, or.**
76e0: 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e DELETE statemen
76f0: 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 t are counted.
7700: 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 Auxiliary change
7710: 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 s caused by.** t
7720: 72 69 67 67 65 72 73 20 61 72 65 20 6e 6f 74 20 riggers are not
7730: 63 6f 75 6e 74 65 64 2e 20 20 55 73 65 20 74 68 counted. Use th
7740: 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c e [sqlite3_total
7750: 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 _changes()] func
7760: 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 tion.** to find
7770: 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 the total number
7780: 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 63 6c of changes incl
7790: 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 uding changes ca
77a0: 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73 used by triggers
77b0: 2e 0a 2a 2a 0a 2a 2a 20 57 69 74 68 69 6e 20 74 ..**.** Within t
77c0: 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 he body of a tri
77d0: 67 67 65 72 2c 20 74 68 65 20 73 71 6c 69 74 65 gger, the sqlite
77e0: 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 3_changes() inte
77f0: 72 66 61 63 65 20 63 61 6e 20 62 65 0a 2a 2a 20 rface can be.**
7800: 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 called to find t
7810: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 he number of.**
7820: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d changes in the m
7830: 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d ost recently com
7840: 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 pleted INSERT, U
7850: 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 PDATE, or DELETE
7860: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 .** statement wi
7870: 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 thin the body of
7880: 20 74 68 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a the trigger..**
7890: 0a 2a 2a 20 41 6c 6c 20 63 68 61 6e 67 65 73 20 .** All changes
78a0: 61 72 65 20 63 6f 75 6e 74 65 64 2c 20 65 76 65 are counted, eve
78b0: 6e 20 69 66 20 74 68 65 79 20 77 65 72 65 20 6c n if they were l
78c0: 61 74 65 72 20 75 6e 64 6f 6e 65 20 62 79 20 61 ater undone by a
78d0: 0a 2a 2a 20 52 4f 4c 4c 42 41 43 4b 20 6f 72 20 .** ROLLBACK or
78e0: 41 42 4f 52 54 2e 20 20 45 78 63 65 70 74 2c 20 ABORT. Except,
78f0: 63 68 61 6e 67 65 73 20 61 73 73 6f 63 69 61 74 changes associat
7900: 65 64 20 77 69 74 68 20 63 72 65 61 74 69 6e 67 ed with creating
7910: 20 61 6e 64 0a 2a 2a 20 64 72 6f 70 70 69 6e 67 and.** dropping
7920: 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 tables are not
7930: 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 counted..**.** I
7940: 66 20 61 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 f a callback inv
7950: 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 okes [sqlite3_ex
7960: 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 ec()] or [sqlite
7970: 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 3_step()] recurs
7980: 69 76 65 6c 79 2c 0a 2a 2a 20 74 68 65 6e 20 74 ively,.** then t
7990: 68 65 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 he changes in th
79a0: 65 20 69 6e 6e 65 72 2c 20 72 65 63 75 72 73 69 e inner, recursi
79b0: 76 65 20 63 61 6c 6c 20 61 72 65 20 63 6f 75 6e ve call are coun
79c0: 74 65 64 20 74 6f 67 65 74 68 65 72 0a 2a 2a 20 ted together.**
79d0: 77 69 74 68 20 74 68 65 20 63 68 61 6e 67 65 73 with the changes
79e0: 20 69 6e 20 74 68 65 20 6f 75 74 65 72 20 63 61 in the outer ca
79f0: 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 ll..**.** SQLite
7a00: 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 implements the
7a10: 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 command "DELETE
7a20: 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68 FROM table" with
7a30: 6f 75 74 20 61 20 57 48 45 52 45 20 63 6c 61 75 out a WHERE clau
7a40: 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e se.** by droppin
7a50: 67 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67 g and recreating
7a60: 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54 68 the table. (Th
7a70: 69 73 20 69 73 20 6d 75 63 68 20 66 61 73 74 65 is is much faste
7a80: 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 r than going.**
7a90: 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 through and dele
7aa0: 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20 ting individual
7ab0: 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 elements from th
7ac0: 65 20 74 61 62 6c 65 2e 29 20 20 42 65 63 61 75 e table.) Becau
7ad0: 73 65 20 6f 66 0a 2a 2a 20 74 68 69 73 20 6f 70 se of.** this op
7ae0: 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 timization, the
7af0: 63 68 61 6e 67 65 20 63 6f 75 6e 74 20 66 6f 72 change count for
7b00: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 "DELETE FROM ta
7b10: 62 6c 65 22 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 ble" will be.**
7b20: 7a 65 72 6f 20 72 65 67 61 72 64 6c 65 73 73 20 zero regardless
7b30: 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 of the number of
7b40: 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 77 elements that w
7b50: 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69 ere originally i
7b60: 6e 20 74 68 65 0a 2a 2a 20 74 61 62 6c 65 2e 20 n the.** table.
7b70: 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72 61 To get an accura
7b80: 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 te count of the
7b90: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64 number of rows d
7ba0: 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 eleted, use.** "
7bb0: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c DELETE FROM tabl
7bc0: 65 20 57 48 45 52 45 20 31 22 20 69 6e 73 74 65 e WHERE 1" inste
7bd0: 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f ad..**.** If ano
7be0: 74 68 65 72 20 74 68 72 65 61 64 20 6d 61 6b 65 ther thread make
7bf0: 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 s changes on the
7c00: 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 same database c
7c10: 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 onnection.** whi
7c20: 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 le this routine
7c30: 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 is running then
7c40: 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
7c50: 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 of this routine
7c60: 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 .** is undefined
7c70: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
7c80: 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 _changes(sqlite3
7c90: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
7ca0: 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 REF: Total Numbe
7cb0: 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 r Of Rows Modifi
7cc0: 65 64 0a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 ed.***.** This f
7cd0: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
7ce0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 the number of da
7cf0: 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 tabase rows that
7d00: 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 6d 6f have been.** mo
7d10: 64 69 66 69 65 64 20 62 79 20 49 4e 53 45 52 54 dified by INSERT
7d20: 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 , UPDATE or DELE
7d30: 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 TE statements si
7d40: 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73 65 nce the database
7d50: 20 68 61 6e 64 6c 65 0a 2a 2a 20 77 61 73 20 6f handle.** was o
7d60: 70 65 6e 65 64 2e 20 54 68 69 73 20 69 6e 63 6c pened. This incl
7d70: 75 64 65 73 20 55 50 44 41 54 45 2c 20 49 4e 53 udes UPDATE, INS
7d80: 45 52 54 20 61 6e 64 20 44 45 4c 45 54 45 20 73 ERT and DELETE s
7d90: 74 61 74 65 6d 65 6e 74 73 20 65 78 65 63 75 74 tatements execut
7da0: 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 ed.** as part of
7db0: 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d trigger program
7dc0: 73 2e 20 41 6c 6c 20 63 68 61 6e 67 65 73 20 61 s. All changes a
7dd0: 72 65 20 63 6f 75 6e 74 65 64 20 61 73 20 73 6f re counted as so
7de0: 6f 6e 20 61 73 20 74 68 65 0a 2a 2a 20 73 74 61 on as the.** sta
7df0: 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 tement that make
7e00: 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 s them is comple
7e10: 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 ted (when the st
7e20: 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 69 atement handle i
7e30: 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f 20 5b s.** passed to [
7e40: 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
7e50: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e or [sqlite3_fin
7e60: 61 6c 69 73 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a alise()])..**.**
7e70: 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 See also the [s
7e80: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 28 29 5d qlite3_change()]
7e90: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a interface..**.*
7ea0: 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 * SQLite impleme
7eb0: 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 nts the command
7ec0: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 "DELETE FROM tab
7ed0: 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20 57 48 le" without a WH
7ee0: 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79 ERE clause.** by
7ef0: 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 dropping and re
7f00: 63 72 65 61 74 69 6e 67 20 74 68 65 20 74 61 62 creating the tab
7f10: 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75 le. (This is mu
7f20: 63 68 20 66 61 73 74 65 72 20 74 68 61 6e 20 67 ch faster than g
7f30: 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 oing.** through
7f40: 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 and deleting ind
7f50: 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 ividual elements
7f60: 20 66 6f 72 6d 20 74 68 65 20 74 61 62 6c 65 2e form the table.
7f70: 29 20 20 42 65 63 61 75 73 65 20 6f 66 0a 2a 2a ) Because of.**
7f80: 20 74 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 69 this optimizati
7f90: 6f 6e 2c 20 74 68 65 20 63 68 61 6e 67 65 20 63 on, the change c
7fa0: 6f 75 6e 74 20 66 6f 72 20 22 44 45 4c 45 54 45 ount for "DELETE
7fb0: 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 6c FROM table" wil
7fc0: 6c 20 62 65 0a 2a 2a 20 7a 65 72 6f 20 72 65 67 l be.** zero reg
7fd0: 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e ardless of the n
7fe0: 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 umber of element
7ff0: 73 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 67 s that were orig
8000: 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65 0a 2a 2a inally in the.**
8010: 20 74 61 62 6c 65 2e 20 54 6f 20 67 65 74 20 61 table. To get a
8020: 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 n accurate count
8030: 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f of the number o
8040: 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 f rows deleted,
8050: 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 use.** "DELETE F
8060: 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 ROM table WHERE
8070: 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 1" instead..**.*
8080: 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 * If another thr
8090: 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 ead makes change
80a0: 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 s on the same da
80b0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
80c0: 6e 0a 2a 2a 20 77 68 69 6c 65 20 74 68 69 73 20 n.** while this
80d0: 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 routine is runni
80e0: 6e 67 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 ng then the retu
80f0: 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 rn value of this
8100: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 69 73 20 75 routine.** is u
8110: 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 ndefined..*/.int
8120: 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 sqlite3_total_c
8130: 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 hanges(sqlite3*)
8140: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
8150: 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c F: Interrupt A L
8160: 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 ong-Running Quer
8170: 79 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e y.**.** This fun
8180: 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 ction causes any
8190: 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 pending databas
81a0: 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 e operation to a
81b0: 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 bort and.** retu
81c0: 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 rn at its earlie
81d0: 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 st opportunity.
81e0: 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 This routine is
81f0: 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 typically.** ca
8200: 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 lled in response
8210: 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f to a user actio
8220: 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69 n such as pressi
8230: 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f ng "Cancel".** o
8240: 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 r Ctrl-C where t
8250: 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 he user wants a
8260: 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 long query opera
8270: 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 tion to halt.**
8280: 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a immediately..**.
8290: 2a 2a 20 49 74 20 69 73 20 73 61 66 65 20 74 6f ** It is safe to
82a0: 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 call this routi
82b0: 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 ne from a thread
82c0: 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 different from
82d0: 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 the.** thread th
82e0: 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 at is currently
82f0: 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 running the data
8300: 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 base operation.
8310: 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f But it.** is no
8320: 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 t safe to call t
8330: 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 his routine with
8340: 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a database conn
8350: 65 63 74 69 6f 6e 20 74 68 61 74 0a 2a 2a 20 69 ection that.** i
8360: 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 s closed or migh
8370: 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 t close before s
8380: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
8390: 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a () returns..**.*
83a0: 2a 20 54 68 65 20 53 51 4c 20 6f 70 65 72 61 74 * The SQL operat
83b0: 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 ion that is inte
83c0: 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 rrupted will ret
83d0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 urn [SQLITE_INTE
83e0: 52 52 55 50 54 5d 2e 0a 2a 2a 20 49 66 20 61 6e RRUPT]..** If an
83f0: 20 69 6e 74 65 72 72 75 70 74 65 64 20 6f 70 65 interrupted ope
8400: 72 61 74 69 6f 6e 20 77 61 73 20 61 6e 20 75 70 ration was an up
8410: 64 61 74 65 20 74 68 61 74 20 69 73 20 69 6e 73 date that is ins
8420: 69 64 65 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 ide an.** explic
8430: 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 it transaction,
8440: 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 then the entire
8450: 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 69 6c 6c transaction will
8460: 20 62 65 20 72 6f 6c 6c 65 64 0a 2a 2a 20 62 61 be rolled.** ba
8470: 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ck automatically
8480: 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 ..*/.void sqlite
8490: 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 3_interrupt(sqli
84a0: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
84b0: 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e PI3REF: Determin
84c0: 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 e If An SQL Stat
84d0: 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 ement Is Complet
84e0: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 e.**.** These fu
84f0: 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 74 nctions return t
8500: 72 75 65 20 69 66 20 74 68 65 20 67 69 76 65 6e rue if the given
8510: 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 63 6f input string co
8520: 6d 70 72 69 73 65 73 0a 2a 2a 20 6f 6e 65 20 6f mprises.** one o
8530: 72 20 6d 6f 72 65 20 63 6f 6d 70 6c 65 74 65 20 r more complete
8540: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 SQL statements.
8550: 46 6f 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f For the sqlite3_
8560: 63 6f 6d 70 6c 65 74 65 28 29 20 63 61 6c 6c 2c complete() call,
8570: 0a 2a 2a 20 74 68 65 20 70 61 72 61 6d 65 74 65 .** the paramete
8580: 72 20 6d 75 73 74 20 62 65 20 61 20 6e 75 6c 2d r must be a nul-
8590: 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 terminated UTF-8
85a0: 20 73 74 72 69 6e 67 2e 20 46 6f 72 0a 2a 2a 20 string. For.**
85b0: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 sqlite3_complete
85c0: 31 36 28 29 2c 20 61 20 6e 75 6c 2d 74 65 72 6d 16(), a nul-term
85d0: 69 6e 61 74 65 64 20 6d 61 63 68 69 6e 65 20 62 inated machine b
85e0: 79 74 65 20 6f 72 64 65 72 20 55 54 46 2d 31 36 yte order UTF-16
85f0: 20 73 74 72 69 6e 67 0a 2a 2a 20 69 73 20 72 65 string.** is re
8600: 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 quired..**.** Th
8610: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
8620: 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6d 6d useful for comm
8630: 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 and-line input t
8640: 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 o determine if t
8650: 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 he.** currently
8660: 65 6e 74 65 72 65 64 20 74 65 78 74 20 66 6f 72 entered text for
8670: 6d 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 ms one or more c
8680: 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 omplete SQL stat
8690: 65 6d 65 6e 74 73 20 6f 72 0a 2a 2a 20 69 66 20 ements or.** if
86a0: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 additional input
86b0: 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 is needed befor
86c0: 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 73 74 e sending the st
86d0: 61 74 65 6d 65 6e 74 73 20 69 6e 74 6f 0a 2a 2a atements into.**
86e0: 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 SQLite for pars
86f0: 69 6e 67 2e 20 54 68 65 20 61 6c 67 6f 72 69 74 ing. The algorit
8700: 68 6d 20 69 73 20 73 69 6d 70 6c 65 2e 20 20 49 hm is simple. I
8710: 66 20 74 68 65 20 0a 2a 2a 20 6c 61 73 74 20 74 f the .** last t
8720: 6f 6b 65 6e 20 6f 74 68 65 72 20 74 68 61 6e 20 oken other than
8730: 73 70 61 63 65 73 20 61 6e 64 20 63 6f 6d 6d 65 spaces and comme
8740: 6e 74 73 20 69 73 20 61 20 73 65 6d 69 63 6f 6c nts is a semicol
8750: 6f 6e 2c 20 74 68 65 6e 20 72 65 74 75 72 6e 20 on, then return
8760: 0a 2a 2a 20 74 72 75 65 2e 20 20 41 63 74 75 61 .** true. Actua
8770: 6c 6c 79 2c 20 74 68 65 20 61 6c 67 6f 72 69 74 lly, the algorit
8780: 68 6d 20 69 73 20 61 20 6c 69 74 74 6c 65 20 6d hm is a little m
8790: 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 20 ore complicated
87a0: 74 68 61 6e 20 74 68 61 74 0a 2a 2a 20 69 6e 20 than that.** in
87b0: 6f 72 64 65 72 20 74 6f 20 64 65 61 6c 20 77 69 order to deal wi
87c0: 74 68 20 74 72 69 67 67 65 72 73 2c 20 62 75 74 th triggers, but
87d0: 20 74 68 65 20 62 61 73 69 63 20 69 64 65 61 20 the basic idea
87e0: 69 73 20 74 68 65 20 73 61 6d 65 3a 20 20 74 68 is the same: th
87f0: 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 e.** statement i
8800: 73 20 6e 6f 74 20 63 6f 6d 70 6c 65 74 65 20 75 s not complete u
8810: 6e 6c 65 73 73 20 69 74 20 65 6e 64 73 20 69 6e nless it ends in
8820: 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 2e 0a 2a 2f a semicolon..*/
8830: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d .int sqlite3_com
8840: 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 plete(const char
8850: 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 *sql);.int sqli
8860: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 te3_complete16(c
8870: 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b onst void *sql);
8880: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
8890: 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c : Register A Cal
88a0: 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 lback To Handle
88b0: 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f SQLITE_BUSY Erro
88c0: 72 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f rs.**.** This ro
88d0: 75 74 69 6e 65 20 69 64 65 6e 74 69 66 69 65 73 utine identifies
88e0: 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 a callback func
88f0: 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 tion that might
8900: 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 be invoked.** wh
8910: 65 6e 65 76 65 72 20 61 6e 20 61 74 74 65 6d 70 enever an attemp
8920: 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 t is made to ope
8930: 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 n a database tab
8940: 6c 65 20 0a 2a 2a 20 74 68 61 74 20 61 6e 6f 74 le .** that anot
8950: 68 65 72 20 74 68 72 65 61 64 20 6f 72 20 70 72 her thread or pr
8960: 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 ocess has locked
8970: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79 ..** If the busy
8980: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c callback is NUL
8990: 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f L, then [SQLITE_
89a0: 42 55 53 59 5d 0a 2a 2a 20 28 6f 72 20 73 6f 6d BUSY].** (or som
89b0: 65 74 69 6d 65 73 20 5b 53 51 4c 49 54 45 5f 49 etimes [SQLITE_I
89c0: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 29 0a 2a OERR_BLOCKED]).*
89d0: 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d * is returned im
89e0: 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 mediately upon e
89f0: 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 ncountering the
8a00: 6c 6f 63 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 lock..** If the
8a10: 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 busy callback is
8a20: 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 not NULL, then
8a30: 74 68 65 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 the.** callback
8a40: 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 will be invoked
8a50: 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e with two argumen
8a60: 74 73 2e 20 20 54 68 65 0a 2a 2a 20 66 69 72 73 ts. The.** firs
8a70: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 t argument to th
8a80: 65 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 e handler is a c
8a90: 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a opy of the void*
8aa0: 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a pointer which.*
8ab0: 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 * is the third a
8ac0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 rgument to this
8ad0: 72 6f 75 74 69 6e 65 2e 20 20 54 68 65 20 73 65 routine. The se
8ae0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
8af0: 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 .** the handler
8b00: 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 is the number of
8b10: 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 times that the
8b20: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 busy handler has
8b30: 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 .** been invoked
8b40: 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e for this lockin
8b50: 67 20 65 76 65 6e 74 2e 20 49 66 20 74 68 65 0a g event. If the.
8b60: 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b ** busy callback
8b70: 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e returns 0, then
8b80: 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 no additional a
8b90: 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 ttempts are made
8ba0: 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 to.** access th
8bb0: 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b e database and [
8bc0: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 SQLITE_BUSY] or
8bd0: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c [SQLITE_IOERR_BL
8be0: 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e OCKED] is return
8bf0: 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 ed..** If the ca
8c00: 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e llback returns n
8c10: 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e on-zero, then an
8c20: 6f 74 68 65 72 20 61 74 74 65 6d 70 74 20 69 73 other attempt is
8c30: 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 made to open th
8c40: 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 6f e.** database fo
8c50: 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 r reading and th
8c60: 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e e cycle repeats.
8c70: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 .**.** The prese
8c80: 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 nce of a busy ha
8c90: 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 ndler does not g
8ca0: 75 61 72 61 6e 74 65 65 20 74 68 61 74 0a 2a 2a uarantee that.**
8cb0: 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f it will be invo
8cc0: 6b 65 64 20 77 68 65 6e 20 74 68 65 72 65 20 69 ked when there i
8cd0: 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f s lock contentio
8ce0: 6e 2e 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65 20 n..** If SQLite
8cf0: 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 determines that
8d00: 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 invoking the bus
8d10: 79 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 y handler could
8d20: 72 65 73 75 6c 74 20 69 6e 0a 2a 2a 20 61 20 64 result in.** a d
8d30: 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c eadlock, it will
8d40: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
8d50: 42 55 53 59 5d 20 69 6e 73 74 65 61 64 2e 0a 2a BUSY] instead..*
8d60: 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 * Consider a sce
8d70: 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 nario where one
8d80: 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 process is holdi
8d90: 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 ng a read lock t
8da0: 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 hat.** it is try
8db0: 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 ing to promote t
8dc0: 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 o a reserved loc
8dd0: 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e k and.** a secon
8de0: 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c d process is hol
8df0: 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 ding a reserved
8e00: 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 lock that it is
8e10: 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f trying.** to pro
8e20: 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 mote to an exclu
8e30: 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 sive lock. The
8e40: 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 first process ca
8e50: 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 nnot proceed.**
8e60: 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c because it is bl
8e70: 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 ocked by the sec
8e80: 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f ond and the seco
8e90: 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f nd process canno
8ea0: 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 t.** proceed bec
8eb0: 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b ause it is block
8ec0: 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e ed by the first.
8ed0: 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 If both proces
8ee0: 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 ses.** invoke th
8ef0: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c e busy handlers,
8f00: 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 neither will ma
8f10: 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e ke any progress.
8f20: 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 Therefore,.**
8f30: 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b SQLite returns [
8f40: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 SQLITE_BUSY] for
8f50: 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 the first proce
8f60: 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 ss, hoping that
8f70: 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 this.** will ind
8f80: 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 uce the first pr
8f90: 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 ocess to release
8fa0: 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 its read lock a
8fb0: 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 nd allow.** the
8fc0: 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 second process t
8fd0: 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a o proceed..**.**
8fe0: 20 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 The default bus
8ff0: 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 y callback is NU
9000: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 LL..**.** The [S
9010: 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f QLITE_BUSY] erro
9020: 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 r is converted t
9030: 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f o [SQLITE_IOERR_
9040: 42 4c 4f 43 4b 45 44 5d 20 77 68 65 6e 0a 2a 2a BLOCKED] when.**
9050: 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 SQLite is in th
9060: 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 e middle of a la
9070: 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 rge transaction
9080: 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a where all the.**
9090: 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f changes will no
90a0: 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 t fit into the i
90b0: 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 n-memory cache.
90c0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 SQLite will.**
90d0: 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 already hold a R
90e0: 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 ESERVED lock on
90f0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
9100: 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a e, but it needs.
9110: 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 ** to promote th
9120: 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 is lock to EXCLU
9130: 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 SIVE so that it
9140: 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a can spill cache.
9150: 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 ** pages into th
9160: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
9170: 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 without harm to
9180: 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 concurrent.** re
9190: 61 64 65 72 73 2e 20 20 49 66 20 69 74 20 69 73 aders. If it is
91a0: 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f unable to promo
91b0: 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 te the lock, the
91c0: 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a n the in-memory.
91d0: 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 ** cache will be
91e0: 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f left in an inco
91f0: 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 nsistent state a
9200: 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a nd so the error.
9210: 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f ** code is promo
9220: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c ted from the rel
9230: 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b atively benign [
9240: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a SQLITE_BUSY] to.
9250: 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 ** the more seve
9260: 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 re [SQLITE_IOERR
9270: 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69 73 _BLOCKED]. This
9280: 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d error code prom
9290: 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 otion.** forces
92a0: 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c an automatic rol
92b0: 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 lback of the cha
92c0: 6e 67 65 73 2e 20 53 65 65 20 74 68 65 0a 2a 2a nges. See the.**
92d0: 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a 2f <a href="http:/
92e0: 2f 77 77 77 2e 73 71 6c 69 74 65 2e 6f 72 67 2f /www.sqlite.org/
92f0: 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 cvstrac/wiki?p=C
9300: 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 orruptionFollowi
9310: 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a ngBusyError">.**
9320: 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f CorruptionFollo
9330: 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 wingBusyError</a
9340: 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 > wiki page for
9350: 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 a discussion of
9360: 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 why.** this is i
9370: 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 09 0a 2a 2a mportant..**..**
9380: 20 53 71 6c 69 74 65 20 69 73 20 72 65 2d 65 6e Sqlite is re-en
9390: 74 72 61 6e 74 2c 20 73 6f 20 74 68 65 20 62 75 trant, so the bu
93a0: 73 79 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 73 sy handler may s
93b0: 74 61 72 74 20 61 20 6e 65 77 20 71 75 65 72 79 tart a new query
93c0: 2e 20 0a 2a 2a 20 28 49 74 20 69 73 20 6e 6f 74 . .** (It is not
93d0: 20 63 6c 65 61 72 20 77 68 79 20 61 6e 79 6f 6e clear why anyon
93e0: 65 20 77 6f 75 6c 64 20 65 76 65 72 79 20 77 61 e would every wa
93f0: 6e 74 20 74 6f 20 64 6f 20 74 68 69 73 2c 20 62 nt to do this, b
9400: 75 74 20 69 74 0a 2a 2a 20 69 73 20 61 6c 6c 6f ut it.** is allo
9410: 77 65 64 2c 20 69 6e 20 74 68 65 6f 72 79 2e 29 wed, in theory.)
9420: 20 20 42 75 74 20 74 68 65 20 62 75 73 79 20 68 But the busy h
9430: 61 6e 64 6c 65 72 20 6d 61 79 20 6e 6f 74 20 63 andler may not c
9440: 6c 6f 73 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 lose the.** data
9450: 62 61 73 65 2e 20 20 43 6c 6f 73 69 6e 67 20 74 base. Closing t
9460: 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d he database from
9470: 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 a busy handler
9480: 77 69 6c 6c 20 64 65 6c 65 74 65 20 0a 2a 2a 20 will delete .**
9490: 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 data structures
94a0: 6f 75 74 20 66 72 6f 6d 20 75 6e 64 65 72 20 74 out from under t
94b0: 68 65 20 65 78 65 63 75 74 69 6e 67 20 71 75 65 he executing que
94c0: 72 79 20 61 6e 64 20 77 69 6c 6c 20 0a 2a 2a 20 ry and will .**
94d0: 70 72 6f 62 61 62 6c 79 20 72 65 73 75 6c 74 20 probably result
94e0: 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f in a segmentatio
94f0: 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 n fault or other
9500: 20 72 75 6e 74 69 6d 65 20 65 72 72 6f 72 2e 0a runtime error..
9510: 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 **.** There can
9520: 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 only be a single
9530: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 busy handler de
9540: 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 20 64 fined for each d
9550: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 atabase.** conne
9560: 63 74 69 6f 6e 2e 20 20 53 65 74 74 69 6e 67 20 ction. Setting
9570: 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c a new busy handl
9580: 65 72 20 63 6c 65 61 72 73 20 61 6e 79 20 70 72 er clears any pr
9590: 65 76 69 6f 75 73 20 6f 6e 65 2e 0a 2a 2a 20 4e evious one..** N
95a0: 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 ote that calling
95b0: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 [sqlite3_busy_t
95c0: 69 6d 65 6f 75 74 28 29 5d 20 77 69 6c 6c 20 61 imeout()] will a
95d0: 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 lso set or clear
95e0: 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e .** the busy han
95f0: 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e dler..**.** When
9600: 20 6f 70 65 72 61 74 69 6e 67 20 69 6e 20 5b 73 operating in [s
9610: 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 qlite3_enable_sh
9620: 61 72 65 64 5f 63 61 63 68 65 20 7c 20 73 68 61 ared_cache | sha
9630: 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c red cache mode],
9640: 0a 2a 2a 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c .** only a singl
9650: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 e busy handler c
9660: 61 6e 20 62 65 20 64 65 66 69 6e 65 64 20 66 6f an be defined fo
9670: 72 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 r each database
9680: 66 69 6c 65 2e 0a 2a 2a 20 53 6f 20 69 66 20 74 file..** So if t
9690: 77 6f 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e wo database conn
96a0: 65 63 74 69 6f 6e 73 20 73 68 61 72 65 20 61 20 ections share a
96b0: 73 69 6e 67 6c 65 20 63 61 63 68 65 2c 20 74 68 single cache, th
96c0: 65 6e 20 63 68 61 6e 67 69 6e 67 0a 2a 2a 20 74 en changing.** t
96d0: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 he busy handler
96e0: 6f 6e 20 6f 6e 65 20 63 6f 6e 6e 65 63 74 69 6f on one connectio
96f0: 6e 20 77 69 6c 6c 20 61 6c 73 6f 20 63 68 61 6e n will also chan
9700: 67 65 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 ge the busy.** h
9710: 61 6e 64 6c 65 72 20 69 6e 20 74 68 65 20 6f 74 andler in the ot
9720: 68 65 72 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 her connection.
9730: 20 54 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 The busy handle
9740: 72 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 r is invoked.**
9750: 69 6e 20 74 68 65 20 74 68 72 65 61 64 20 74 68 in the thread th
9760: 61 74 20 77 61 73 20 72 75 6e 6e 69 6e 67 20 77 at was running w
9770: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 42 hen the SQLITE_B
9780: 55 53 59 20 77 61 73 20 68 69 74 2e 0a 2a 2f 0a USY was hit..*/.
9790: 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 int sqlite3_busy
97a0: 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 _handler(sqlite3
97b0: 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c *, int(*)(void*,
97c0: 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f int), void*);../
97d0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
97e0: 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 et A Busy Timeou
97f0: 74 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 t.**.** This rou
9800: 74 69 6e 65 20 73 65 74 73 20 61 20 62 75 73 79 tine sets a busy
9810: 20 68 61 6e 64 6c 65 72 20 74 68 61 74 20 73 6c handler that sl
9820: 65 65 70 73 20 66 6f 72 20 61 20 77 68 69 6c 65 eeps for a while
9830: 20 77 68 65 6e 20 61 0a 2a 2a 20 74 61 62 6c 65 when a.** table
9840: 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65 is locked. The
9850: 20 68 61 6e 64 6c 65 72 20 77 69 6c 6c 20 73 6c handler will sl
9860: 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d eep multiple tim
9870: 65 73 20 75 6e 74 69 6c 20 0a 2a 2a 20 61 74 20 es until .** at
9880: 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 least "ms" milli
9890: 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 seconds of sleep
98a0: 69 6e 67 20 68 61 76 65 20 62 65 65 6e 20 64 6f ing have been do
98b0: 6e 65 2e 20 20 41 66 74 65 72 0a 2a 2a 20 22 6d ne. After.** "m
98c0: 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 s" milliseconds
98d0: 6f 66 20 73 6c 65 65 70 69 6e 67 2c 20 74 68 65 of sleeping, the
98e0: 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 handler returns
98f0: 20 30 20 77 68 69 63 68 0a 2a 2a 20 63 61 75 73 0 which.** caus
9900: 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 es [sqlite3_step
9910: 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 20 5b 53 ()] to return [S
9920: 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b QLITE_BUSY] or [
9930: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f SQLITE_IOERR_BLO
9940: 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c CKED]..**.** Cal
9950: 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e ling this routin
9960: 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 e with an argume
9970: 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 nt less than or
9980: 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a equal to zero.**
9990: 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 turns off all b
99a0: 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a usy handlers..**
99b0: 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e .** There can on
99c0: 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 ly be a single b
99d0: 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 usy handler for
99e0: 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 a particular dat
99f0: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 abase.** connect
9a00: 69 6f 6e 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 ion. If another
9a10: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 77 61 busy handler wa
9a20: 73 20 64 65 66 69 6e 65 64 20 20 0a 2a 2a 20 28 s defined .** (
9a30: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 using [sqlite3_b
9a40: 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 usy_handler()])
9a50: 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 prior to calling
9a60: 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 .** this routine
9a70: 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 , that other bus
9a80: 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 y handler is cle
9a90: 61 72 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c ared..*/.int sql
9aa0: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 ite3_busy_timeou
9ab0: 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 t(sqlite3*, int
9ac0: 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ms);../*.** CAPI
9ad0: 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 3REF: Convenienc
9ae0: 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 e Routines For R
9af0: 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a unning Queries.*
9b00: 2a 0a 2a 2a 20 54 68 69 73 20 6e 65 78 74 20 72 *.** This next r
9b10: 6f 75 74 69 6e 65 20 69 73 20 61 20 63 6f 6e 76 outine is a conv
9b20: 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 enience wrapper
9b30: 61 72 6f 75 6e 64 20 5b 73 71 6c 69 74 65 33 5f around [sqlite3_
9b40: 65 78 65 63 28 29 5d 2e 0a 2a 2a 20 49 6e 73 74 exec()]..** Inst
9b50: 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 ead of invoking
9b60: 61 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 20 a user-supplied
9b70: 63 61 6c 6c 62 61 63 6b 20 66 6f 72 20 65 61 63 callback for eac
9b80: 68 20 72 6f 77 20 6f 66 20 74 68 65 0a 2a 2a 20 h row of the.**
9b90: 72 65 73 75 6c 74 2c 20 74 68 69 73 20 72 6f 75 result, this rou
9ba0: 74 69 6e 65 20 72 65 6d 65 6d 62 65 72 73 20 65 tine remembers e
9bb0: 61 63 68 20 72 6f 77 20 6f 66 20 74 68 65 20 72 ach row of the r
9bc0: 65 73 75 6c 74 20 69 6e 20 6d 65 6d 6f 72 79 0a esult in memory.
9bd0: 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ** obtained from
9be0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
9bf0: 28 29 5d 2c 20 74 68 65 6e 20 72 65 74 75 72 6e ()], then return
9c00: 73 20 61 6c 6c 20 6f 66 20 74 68 65 20 72 65 73 s all of the res
9c10: 75 6c 74 20 61 66 74 65 72 20 74 68 65 0a 2a 2a ult after the.**
9c20: 20 71 75 65 72 79 20 68 61 73 20 66 69 6e 69 73 query has finis
9c30: 68 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 41 73 20 61 hed. .**.** As a
9c40: 6e 20 65 78 61 6d 70 6c 65 2c 20 73 75 70 70 6f n example, suppo
9c50: 73 65 20 74 68 65 20 71 75 65 72 79 20 72 65 73 se the query res
9c60: 75 6c 74 20 77 68 65 72 65 20 74 68 69 73 20 74 ult where this t
9c70: 61 62 6c 65 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 able:.**.** <pre
9c80: 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 >.** Name
9c90: 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a | Age.**
9ca0: 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d --------
9cb0: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a ---------------.
9cc0: 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 ** Alice
9cd0: 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 | 43.**
9ce0: 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 Bob
9cf0: 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 | 28.**
9d00: 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 Cindy | 21
9d10: 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a .** </pre>.**.**
9d20: 20 49 66 20 74 68 65 20 33 72 64 20 61 72 67 75 If the 3rd argu
9d30: 6d 65 6e 74 20 77 65 72 65 20 26 61 7a 52 65 73 ment were &azRes
9d40: 75 6c 74 20 74 68 65 6e 20 61 66 74 65 72 20 74 ult then after t
9d50: 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 he function retu
9d60: 72 6e 73 0a 2a 2a 20 61 7a 52 65 73 75 6c 74 20 rns.** azResult
9d70: 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 74 68 65 will contain the
9d80: 20 66 6f 6c 6c 6f 77 69 6e 67 20 64 61 74 61 3a following data:
9d90: 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 .**.** <pre>.**
9da0: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 5b azResult[
9db0: 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 0] = "Name";.**
9dc0: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 5b azResult[
9dd0: 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 1] = "Age";.**
9de0: 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 5b 32 azResult[2
9df0: 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 ] = "Alice";.**
9e00: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 5b azResult[
9e10: 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 3] = "43";.**
9e20: 20 20 20 20 20 61 7a 52 65 73 75 6c 74 5b 34 5d azResult[4]
9e30: 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 = "Bob";.**
9e40: 20 20 20 20 61 7a 52 65 73 75 6c 74 5b 35 5d 20 azResult[5]
9e50: 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 = "28";.**
9e60: 20 20 61 7a 52 65 73 75 6c 74 5b 36 5d 20 3d 20 azResult[6] =
9e70: 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 "Cindy";.**
9e80: 20 20 20 61 7a 52 65 73 75 6c 74 5b 37 5d 20 3d azResult[7] =
9e90: 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e "21";.** </pre>
9ea0: 0a 2a 2a 0a 2a 2a 20 4e 6f 74 69 63 65 20 74 68 .**.** Notice th
9eb0: 61 74 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 at there is an e
9ec0: 78 74 72 61 20 72 6f 77 20 6f 66 20 64 61 74 61 xtra row of data
9ed0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 containing the
9ee0: 63 6f 6c 75 6d 6e 0a 2a 2a 20 68 65 61 64 65 72 column.** header
9ef0: 73 2e 20 20 42 75 74 20 74 68 65 20 2a 6e 72 6f s. But the *nro
9f00: 77 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 w return value i
9f10: 73 20 73 74 69 6c 6c 20 33 2e 20 20 2a 6e 63 6f s still 3. *nco
9f20: 6c 75 6d 6e 20 69 73 0a 2a 2a 20 73 65 74 20 74 lumn is.** set t
9f30: 6f 20 32 2e 20 20 49 6e 20 67 65 6e 65 72 61 6c o 2. In general
9f40: 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 , the number of
9f50: 76 61 6c 75 65 73 20 69 6e 73 65 72 74 65 64 20 values inserted
9f60: 69 6e 74 6f 20 61 7a 52 65 73 75 6c 74 0a 2a 2a into azResult.**
9f70: 20 77 69 6c 6c 20 62 65 20 28 28 2a 6e 72 6f 77 will be ((*nrow
9f80: 29 20 2b 20 31 29 2a 28 2a 6e 63 6f 6c 75 6d 6e ) + 1)*(*ncolumn
9f90: 29 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 )..**.** After t
9fa0: 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 he calling funct
9fb0: 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 ion has finished
9fc0: 20 75 73 69 6e 67 20 74 68 65 20 72 65 73 75 6c using the resul
9fd0: 74 2c 20 69 74 20 73 68 6f 75 6c 64 20 0a 2a 2a t, it should .**
9fe0: 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 pass the result
9ff0: 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 6f data pointer to
a000: 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 sqlite3_free_ta
a010: 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 ble() in order t
a020: 6f 20 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 o .** release th
a030: 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 e memory that wa
a040: 73 20 6d 61 6c 6c 6f 63 2d 65 64 2e 20 20 42 65 s malloc-ed. Be
a050: 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 cause of the way
a060: 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 the .** [sqlite
a070: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 3_malloc()] happ
a080: 65 6e 73 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 ens, the calling
a090: 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e function must n
a0a0: 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 0a ot try to call .
a0b0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ** [sqlite3_free
a0c0: 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f ()] directly. O
a0d0: 6e 6c 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 nly [sqlite3_fre
a0e0: 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 e_table()] is ab
a0f0: 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 0a 2a le to release .*
a100: 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f * the memory pro
a110: 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 perly and safely
a120: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 ..**.** The retu
a130: 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 rn value of this
a140: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20 routine is the
a150: 73 61 6d 65 20 61 73 20 66 72 6f 6d 20 5b 73 71 same as from [sq
a160: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 0a 2a lite3_exec()]..*
a170: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 /.int sqlite3_ge
a180: 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 t_table(. sqlit
a190: 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 e3*,
a1a0: 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 /* An open dat
a1b0: 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 abase */. const
a1c0: 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 char *sql,
a1d0: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 /* SQL to be e
a1e0: 78 65 63 75 74 65 64 20 2a 2f 0a 20 20 63 68 61 xecuted */. cha
a1f0: 72 20 2a 2a 2a 72 65 73 75 6c 74 70 2c 20 20 20 r ***resultp,
a200: 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 20 77 72 /* Result wr
a210: 69 74 74 65 6e 20 74 6f 20 61 20 63 68 61 72 20 itten to a char
a220: 2a 5b 5d 20 20 74 68 61 74 20 74 68 69 73 20 70 *[] that this p
a230: 6f 69 6e 74 73 20 74 6f 20 2a 2f 0a 20 20 69 6e oints to */. in
a240: 74 20 2a 6e 72 6f 77 2c 20 20 20 20 20 20 20 20 t *nrow,
a250: 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f /* Number o
a260: 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 f result rows wr
a270: 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 itten here */.
a280: 69 6e 74 20 2a 6e 63 6f 6c 75 6d 6e 2c 20 20 20 int *ncolumn,
a290: 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 /* Number
a2a0: 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d of result colum
a2b0: 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 ns written here
a2c0: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d */. char **errm
a2d0: 73 67 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 sg /* E
a2e0: 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e rror msg written
a2f0: 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 here */.);.void
a300: 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 sqlite3_free_ta
a310: 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c ble(char **resul
a320: 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
a330: 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 REF: Formatted S
a340: 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 tring Printing F
a350: 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 unctions.**.** T
a360: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
a370: 65 20 77 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 20 e workalikes of
a380: 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 the "printf()" f
a390: 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f amily of functio
a3a0: 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 ns.** from the s
a3b0: 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 tandard C librar
a3c0: 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c y..**.** The sql
a3d0: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 ite3_mprintf() a
a3e0: 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 nd sqlite3_vmpri
a3f0: 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 ntf() routines w
a400: 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 rite their.** re
a410: 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 sults into memor
a420: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
a430: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
a440: 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e )]..** The strin
a450: 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 gs returned by t
a460: 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 hese two routine
a470: 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 s should be.** r
a480: 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 eleased by [sqli
a490: 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 42 6f te3_free()]. Bo
a4a0: 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 th routines retu
a4b0: 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 rn a.** NULL poi
a4c0: 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 nter if [sqlite3
a4d0: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e _malloc()] is un
a4e0: 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 able to allocate
a4f0: 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 enough.** memor
a500: 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 y to hold the re
a510: 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a sulting string..
a520: 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33 **.** In sqlite3
a530: 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 _snprintf() rout
a540: 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 ine is similar t
a550: 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 o "snprintf()" f
a560: 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 rom.** the stand
a570: 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 ard C library.
a580: 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 The result is wr
a590: 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a itten into the.*
a5a0: 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 * buffer supplie
a5b0: 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 d as the second
a5c0: 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 parameter whose
a5d0: 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 size is given by
a5e0: 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 .** the first pa
a5f0: 72 61 6d 65 74 65 72 2e 20 20 4e 6f 74 65 20 74 rameter. Note t
a600: 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 hat the order of
a610: 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 the.** first tw
a620: 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 o parameters is
a630: 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e reversed from sn
a640: 70 72 69 6e 74 66 28 29 2e 20 20 54 68 69 73 20 printf(). This
a650: 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 is an.** histori
a660: 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 cal accident tha
a670: 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 t cannot be fixe
a680: 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 d without breaki
a690: 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 ng.** backwards
a6a0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 compatibility.
a6b0: 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 Note also that s
a6c0: 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
a6d0: 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 ).** returns a p
a6e0: 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 ointer to its bu
a6f0: 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 ffer instead of
a700: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a the number of.**
a710: 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 characters actu
a720: 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 ally written int
a730: 6f 20 74 68 65 20 62 75 66 66 65 72 2e 20 20 57 o the buffer. W
a740: 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 e admit that.**
a750: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 the number of ch
a760: 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e aracters written
a770: 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 would be a more
a780: 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a useful return.*
a790: 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 * value but we c
a7a0: 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 annot change the
a7b0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
a7c0: 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 of sqlite3_snpri
a7d0: 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 ntf().** now wit
a7e0: 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f hout breaking co
a7f0: 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a mpatibility..**.
a800: 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 ** As long as th
a810: 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 e buffer size is
a820: 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 greater than ze
a830: 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 ro, sqlite3_snpr
a840: 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e intf().** guaran
a850: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 tees that the bu
a860: 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a ffer is always z
a870: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 ero-terminated.
a880: 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 The first.** pa
a890: 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 rameter "n" is t
a8a0: 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 he total size of
a8b0: 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 the buffer, inc
a8c0: 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 luding space for
a8d0: 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 .** the zero ter
a8e0: 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 minator. So the
a8f0: 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 longest string
a900: 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 that can be comp
a910: 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 letely.** writte
a920: 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 n will be n-1 ch
a930: 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 aracters..**.**
a940: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
a950: 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d ll implement som
a960: 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 e additional for
a970: 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f matting.** optio
a980: 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66 ns that are usef
a990: 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 ul for construct
a9a0: 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ing SQL statemen
a9b0: 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 ts..** All of th
a9c0: 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 20 66 e usual printf f
a9d0: 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e ormatting option
a9e0: 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 s apply. In add
a9f0: 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 ition, there.**
aa00: 69 73 20 61 72 65 20 22 25 71 22 20 61 6e 64 20 is are "%q" and
aa10: 22 25 51 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a "%Q" options..**
aa20: 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70 74 69 6f .** The %q optio
aa30: 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 n works like %s
aa40: 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74 in that it subst
aa50: 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 itutes a null-te
aa60: 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 rminated.** stri
aa70: 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 ng from the argu
aa80: 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 ment list. But
aa90: 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 %q also doubles
aaa0: 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 every '\'' chara
aab0: 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 cter..** %q is d
aac0: 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 esigned for use
aad0: 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 inside a string
aae0: 6c 69 74 65 72 61 6c 2e 20 20 42 79 20 64 6f 75 literal. By dou
aaf0: 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a bling each '\''.
ab00: 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20 ** character it
ab10: 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61 escapes that cha
ab20: 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 racter and allow
ab30: 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 s it to be inser
ab40: 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 ted into.** the
ab50: 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f string..**.** Fo
ab60: 72 20 65 78 61 6d 70 6c 65 2c 20 73 6f 20 73 6f r example, so so
ab70: 6d 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 me string variab
ab80: 6c 65 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 le contains text
ab90: 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
aba0: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
abb0: 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a pre>.** char *z
abc0: 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 Text = "It's a h
abd0: 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c appy day!";.** <
abe0: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
abf0: 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e e>.**.** One can
ac00: 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 use this text i
ac10: 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 n an SQL stateme
ac20: 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a nt as follows:.*
ac30: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
ac40: 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 ><pre>.** char
ac50: 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f *zSQL = sqlite3_
ac60: 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 mprintf("INSERT
ac70: 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 INTO table VALUE
ac80: 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 S('%q')", zText)
ac90: 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 ;.** sqlite3_ex
aca0: 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 ec(db, zSQL, 0,
acb0: 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 0, 0);.** sqlit
acc0: 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a e3_free(zSQL);.*
acd0: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
ace0: 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 uote>.**.** Beca
acf0: 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 use the %q forma
ad00: 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 t string is used
ad10: 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 , the '\'' chara
ad20: 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a cter in zText.**
ad30: 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 is escaped and
ad40: 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 the SQL generate
ad50: 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a d is as follows:
ad60: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
ad70: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 te><pre>.** INS
ad80: 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 ERT INTO table1
ad90: 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 VALUES('It''s a
ada0: 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 happy day!').**
adb0: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
adc0: 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 te>.**.** This i
add0: 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 s correct. Had
ade0: 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 we used %s inste
adf0: 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 ad of %q, the ge
ae00: 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 nerated SQL.** w
ae10: 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 ould have looked
ae20: 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a like this:.**.*
ae30: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
ae40: 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 re>.** INSERT I
ae50: 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 NTO table1 VALUE
ae60: 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 S('It's a happy
ae70: 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 day!');.** </pre
ae80: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
ae90: 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 *.** This second
aea0: 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 example is an S
aeb0: 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e QL syntax error.
aec0: 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 As a general r
aed0: 75 6c 65 20 79 6f 75 0a 2a 2a 20 73 68 6f 75 6c ule you.** shoul
aee0: 64 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 d always use %q
aef0: 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 instead of %s wh
af00: 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 en inserting tex
af10: 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 t into a string
af20: 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a .** literal..**.
af30: 2a 2a 20 54 68 65 20 25 51 20 6f 70 74 69 6f 6e ** The %Q option
af40: 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 works like %q e
af50: 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 xcept it also ad
af60: 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 ds single quotes
af70: 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f around.** the o
af80: 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f utside of the to
af90: 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 4f 72 20 tal string. Or
afa0: 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 if the parameter
afb0: 20 69 6e 20 74 68 65 20 61 72 67 75 6d 65 6e 74 in the argument
afc0: 0a 2a 2a 20 6c 69 73 74 20 69 73 20 61 20 4e 55 .** list is a NU
afd0: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 LL pointer, %Q s
afe0: 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74 ubstitutes the t
aff0: 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 ext "NULL" (with
b000: 6f 75 74 20 73 69 6e 67 6c 65 0a 2a 2a 20 71 75 out single.** qu
b010: 6f 74 65 73 29 20 69 6e 20 70 6c 61 63 65 20 6f otes) in place o
b020: 66 20 74 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e f the %Q option.
b030: 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c So, for exampl
b040: 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 e, one could say
b050: 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
b060: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 ote><pre>.** ch
b070: 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 ar *zSQL = sqlit
b080: 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 e3_mprintf("INSE
b090: 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 RT INTO table VA
b0a0: 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 LUES(%Q)", zText
b0b0: 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 );.** sqlite3_e
b0c0: 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c xec(db, zSQL, 0,
b0d0: 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 0, 0);.** sqli
b0e0: 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a te3_free(zSQL);.
b0f0: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
b100: 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 quote>.**.** The
b110: 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c code above will
b120: 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 render a correc
b130: 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 t SQL statement
b140: 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 in the zSQL.** v
b150: 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 ariable even if
b160: 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 the zText variab
b170: 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 le is a NULL poi
b180: 6e 74 65 72 2e 0a 2a 2f 0a 63 68 61 72 20 2a 73 nter..*/.char *s
b190: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 qlite3_mprintf(c
b1a0: 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b onst char*,...);
b1b0: 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 .char *sqlite3_v
b1c0: 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 mprintf(const ch
b1d0: 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 ar*, va_list);.c
b1e0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 har *sqlite3_snp
b1f0: 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c rintf(int,char*,
b200: 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e const char*, ...
b210: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
b220: 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 EF: Memory Alloc
b230: 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a ation Subsystem.
b240: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 **.** The SQLite
b250: 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 core uses these
b260: 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 three routines
b270: 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f for all of its o
b280: 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d wn.** internal m
b290: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
b2a0: 20 6e 65 65 64 73 2e 20 20 54 68 65 20 64 65 66 needs. The def
b2b0: 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ault implementat
b2c0: 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 65 ion.** of the me
b2d0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
b2e0: 73 75 62 73 79 73 74 65 6d 20 75 73 65 73 20 74 subsystem uses t
b2f0: 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 he malloc(), rea
b300: 6c 6c 6f 63 28 29 0a 2a 2a 20 61 6e 64 20 66 72 lloc().** and fr
b310: 65 65 28 29 20 70 72 6f 76 69 64 65 64 20 62 79 ee() provided by
b320: 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 the standard C
b330: 6c 69 62 72 61 72 79 2e 20 20 48 6f 77 65 76 65 library. Howeve
b340: 72 2c 20 69 66 20 0a 2a 2a 20 53 51 4c 69 74 65 r, if .** SQLite
b350: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
b360: 68 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 h the following
b370: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d C preprocessor m
b380: 61 63 72 6f 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 acro.**.** <bloc
b390: 6b 71 75 6f 74 65 3e 20 53 51 4c 49 54 45 5f 4f kquote> SQLITE_O
b3a0: 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 MIT_MEMORY_ALLOC
b3b0: 41 54 49 4f 4e 20 3c 2f 62 6c 6f 63 6b 71 75 6f ATION </blockquo
b3c0: 74 65 3e 0a 2a 2a 0a 2a 2a 20 74 68 65 6e 20 6e te>.**.** then n
b3d0: 6f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e o implementation
b3e0: 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 is provided for
b3f0: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
b400: 62 79 0a 2a 2a 20 53 51 4c 69 74 65 2e 20 20 54 by.** SQLite. T
b410: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 he application t
b420: 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 hat links agains
b430: 74 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 65 t SQLite is.** e
b440: 78 70 65 63 74 65 64 20 74 6f 20 70 72 6f 76 69 xpected to provi
b450: 64 65 20 69 74 73 20 6f 77 6e 20 69 6d 70 6c 65 de its own imple
b460: 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2f 0a 76 6f mentation..*/.vo
b470: 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c id *sqlite3_mall
b480: 6f 63 28 75 6e 73 69 67 6e 65 64 20 69 6e 74 29 oc(unsigned int)
b490: 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f ;.void *sqlite3_
b4a0: 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 75 realloc(void*, u
b4b0: 6e 73 69 67 6e 65 64 20 69 6e 74 29 3b 0a 76 6f nsigned int);.vo
b4c0: 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 id sqlite3_free(
b4d0: 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 void*);../*.** C
b4e0: 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 API3REF: Memory
b4f0: 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 Allocator Statis
b500: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 49 6e 20 61 64 tics.**.** In ad
b510: 64 69 74 69 6f 6e 20 74 6f 20 74 68 65 20 62 61 dition to the ba
b520: 73 69 63 20 74 68 72 65 65 20 61 6c 6c 6f 63 61 sic three alloca
b530: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 0a 2a tion routines .*
b540: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f * [sqlite3_mallo
b550: 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 c()], [sqlite3_f
b560: 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c ree()], and [sql
b570: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c ite3_realloc()],
b580: 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 .** the memory a
b590: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 llocation subsys
b5a0: 74 65 6d 20 69 6e 63 6c 75 64 65 64 20 77 69 74 tem included wit
b5b0: 68 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 h the SQLite.**
b5c0: 73 6f 75 72 63 65 73 20 70 72 6f 76 69 64 65 73 sources provides
b5d0: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 the interfaces
b5e0: 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 0a shown below..**.
b5f0: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 6f 66 20 ** The first of
b600: 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e these two routin
b610: 65 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 es returns the a
b620: 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 20 mount of memory
b630: 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 .** currently ou
b640: 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f tstanding (mallo
b650: 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 ced but not free
b660: 64 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 0a d). The second.
b670: 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c ** returns the l
b680: 61 72 67 65 73 74 20 69 6e 73 74 61 6e 74 61 6e argest instantan
b690: 65 6f 75 73 20 61 6d 6f 75 6e 74 20 6f 66 20 6f eous amount of o
b6a0: 75 74 73 74 61 6e 64 69 6e 67 0a 2a 2a 20 6d 65 utstanding.** me
b6b0: 6d 6f 72 79 2e 20 20 54 68 65 20 68 69 67 68 77 mory. The highw
b6c0: 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 ater mark is res
b6d0: 65 74 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 et if the argume
b6e0: 6e 74 20 69 73 0a 2a 2a 20 74 72 75 65 2e 20 20 nt is.** true.
b6f0: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 The SQLite core
b700: 64 6f 65 73 20 6e 6f 74 20 75 73 65 20 65 69 74 does not use eit
b710: 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 her of these rou
b720: 74 69 6e 65 73 0a 2a 2a 20 61 6e 64 20 73 6f 20 tines.** and so
b730: 74 68 65 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 they do not have
b740: 20 74 6f 20 62 65 20 69 6d 70 6c 65 6d 65 6e 74 to be implement
b750: 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 ed by the applic
b760: 61 74 69 6f 6e 0a 2a 2a 20 69 66 20 53 51 4c 49 ation.** if SQLI
b770: 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 TE_OMIT_MEMORY_A
b780: 4c 4c 4f 43 41 54 49 4f 4e 20 69 73 20 64 65 66 LLOCATION is def
b790: 69 6e 65 64 2e 20 20 54 68 65 73 65 20 72 6f 75 ined. These rou
b7a0: 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 72 6f tines.** are pro
b7b0: 76 69 64 65 64 20 62 79 20 74 68 65 20 64 65 66 vided by the def
b7c0: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 73 75 62 73 ault memory subs
b7d0: 79 73 74 65 6d 20 66 6f 72 20 64 69 61 67 6e 6f ystem for diagno
b7e0: 73 74 69 63 0a 2a 2a 20 70 75 72 70 6f 73 65 73 stic.** purposes
b7f0: 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 75 69 6e ..*/.sqlite3_uin
b800: 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f t64 sqlite3_memo
b810: 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 ry_used(void);.s
b820: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 73 71 qlite3_uint64 sq
b830: 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
b840: 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 hwater(int reset
b850: 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Flag);../*.** CA
b860: 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 PI3REF: Memory A
b870: 6c 6c 6f 63 61 74 69 6f 6e 20 41 6c 61 72 6d 73 llocation Alarms
b880: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 .**.** The [sqli
b890: 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d te3_memory_alarm
b8a0: 5d 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 65 ] routine is use
b8b0: 64 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a d to register.**
b8c0: 20 61 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 6d a callback on m
b8d0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
b8e0: 20 65 76 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 events..**.** T
b8f0: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 his routine regi
b900: 73 74 65 72 73 20 6f 72 20 63 6c 65 61 72 73 20 sters or clears
b910: 61 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 a callbacks that
b920: 20 66 69 72 65 73 20 77 68 65 6e 0a 2a 2a 20 74 fires when.** t
b930: 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d he amount of mem
b940: 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 65 78 ory allocated ex
b950: 63 65 65 64 73 20 69 54 68 72 65 73 68 6f 6c 64 ceeds iThreshold
b960: 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 61 20 73 69 6e . Only.** a sin
b970: 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e gle callback can
b980: 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 61 be registered a
b990: 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 t a time. Each
b9a0: 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 call.** to [sqli
b9b0: 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d te3_memory_alarm
b9c0: 28 29 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74 ()] overwrites t
b9d0: 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c he previous call
b9e0: 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 63 61 6c back..** The cal
b9f0: 6c 62 61 63 6b 20 69 73 20 64 69 73 61 62 6c 65 lback is disable
ba00: 64 20 62 79 20 73 65 74 74 69 6e 67 20 78 43 61 d by setting xCa
ba10: 6c 6c 62 61 63 6b 20 74 6f 20 61 20 4e 55 4c 4c llback to a NULL
ba20: 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 .** pointer..**
ba30: 0a 2a 2a 20 54 68 65 20 70 61 72 61 6d 65 74 65 .** The paramete
ba40: 72 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 rs to the callba
ba50: 63 6b 20 61 72 65 20 74 68 65 20 70 41 72 67 20 ck are the pArg
ba60: 76 61 6c 75 65 2c 20 74 68 65 20 0a 2a 2a 20 61 value, the .** a
ba70: 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 20 mount of memory
ba80: 63 75 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 currently in use
ba90: 2c 20 61 6e 64 20 74 68 65 20 73 69 7a 65 20 6f , and the size o
baa0: 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 f the.** allocat
bab0: 69 6f 6e 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 ion that provoke
bac0: 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 d the callback.
bad0: 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 69 The callback wi
bae0: 6c 6c 0a 2a 2a 20 70 72 65 73 75 6d 61 62 6c 79 ll.** presumably
baf0: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 invoke [sqlite3
bb00: 5f 66 72 65 65 28 29 5d 20 74 6f 20 66 72 65 65 _free()] to free
bb10: 20 75 70 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 up memory space
bb20: 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 ..** The callbac
bb30: 6b 20 6d 61 79 20 69 6e 76 6f 6b 65 20 5b 73 71 k may invoke [sq
bb40: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
bb50: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c or [sqlite3_real
bb60: 6c 6f 63 28 29 5d 0a 2a 2a 20 62 75 74 20 69 66 loc()].** but if
bb70: 20 69 74 20 64 6f 65 73 2c 20 6e 6f 20 61 64 64 it does, no add
bb80: 69 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b itional callback
bb90: 73 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 s will be invoke
bba0: 64 20 62 79 0a 2a 2a 20 74 68 65 20 72 65 63 75 d by.** the recu
bbb0: 72 73 69 76 65 20 63 61 6c 6c 73 2e 0a 2a 2a 0a rsive calls..**.
bbc0: 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f ** The [sqlite3_
bbd0: 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 soft_heap_limit(
bbe0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 )] interface wor
bbf0: 6b 73 20 62 79 20 72 65 67 69 73 74 65 72 69 6e ks by registerin
bc00: 67 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c g.** a memory al
bc10: 61 72 6d 20 61 74 20 74 68 65 20 73 6f 66 74 20 arm at the soft
bc20: 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 20 69 heap limit and i
bc30: 6e 76 6f 6b 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c nvoking .** [sql
bc40: 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d ite3_release_mem
bc50: 6f 72 79 28 29 5d 20 69 6e 20 74 68 65 20 61 6c ory()] in the al
bc60: 61 72 6d 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 arm callback. A
bc70: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 pplication.** pr
bc80: 6f 67 72 61 6d 73 20 73 68 6f 75 6c 64 20 6e 6f ograms should no
bc90: 74 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 t attempt to use
bca0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 the [sqlite3_me
bcb0: 6d 6f 72 79 5f 61 6c 61 72 6d 28 29 5d 0a 2a 2a mory_alarm()].**
bcc0: 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 61 75 interface becau
bcd0: 73 65 20 64 6f 69 6e 67 20 73 6f 20 77 69 6c 6c se doing so will
bce0: 20 69 6e 74 65 72 66 65 72 65 20 77 69 74 68 20 interfere with
bcf0: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
bd00: 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 soft_heap_limit(
bd10: 29 5d 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a 69 6e )] module..*/.in
bd20: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 t sqlite3_memory
bd30: 5f 61 6c 61 72 6d 28 0a 20 20 76 6f 69 64 28 2a _alarm(. void(*
bd40: 78 43 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 20 xCallback)(void
bd50: 2a 70 41 72 67 2c 20 73 71 6c 69 74 65 33 5f 75 *pArg, sqlite3_u
bd60: 69 6e 74 36 34 20 75 73 65 64 2c 20 75 6e 73 69 int64 used, unsi
bd70: 67 6e 65 64 20 69 6e 74 20 4e 29 2c 0a 20 20 76 gned int N),. v
bd80: 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 73 71 6c oid *pArg,. sql
bd90: 69 74 65 33 5f 75 69 6e 74 36 34 20 69 54 68 72 ite3_uint64 iThr
bda0: 65 73 68 6f 6c 64 0a 29 3b 0a 0a 0a 2f 2a 0a 2a eshold.);.../*.*
bdb0: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 * CAPI3REF: Comp
bdc0: 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 ile-Time Authori
bdd0: 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 zation Callbacks
bde0: 0a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 .***.** This rou
bdf0: 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 tine registers a
be00: 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
be10: 62 61 63 6b 20 77 69 74 68 20 74 68 65 20 53 51 back with the SQ
be20: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 0a Lite library. .
be30: 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 ** The authorize
be40: 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e r callback is in
be50: 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 voked as SQL sta
be60: 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e tements are bein
be70: 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 g compiled.** by
be80: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
be90: 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 e()] or its vari
bea0: 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 ants [sqlite3_pr
beb0: 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 epare_v2()],.**
bec0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
bed0: 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 16()] and [sqlit
bee0: 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
bef0: 29 5d 2e 20 20 41 74 20 76 61 72 69 6f 75 73 0a )]. At various.
bf00: 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 ** points during
bf10: 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e the compilation
bf20: 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 process, as log
bf30: 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 ic is being crea
bf40: 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 ted.** to perfor
bf50: 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e m various action
bf60: 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 s, the authorize
bf70: 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e r callback is in
bf80: 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 voked to.** see
bf90: 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 if those actions
bfa0: 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54 are allowed. T
bfb0: 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
bfc0: 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a llback should.**
bfd0: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f return SQLITE_O
bfe0: 4b 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 K to allow the a
bff0: 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 ction, [SQLITE_I
c000: 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c GNORE] to disall
c010: 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 ow the.** specif
c020: 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c ic action but al
c030: 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 low the SQL stat
c040: 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 ement to continu
c050: 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 e to be.** compi
c060: 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f led, or [SQLITE_
c070: 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 DENY] to cause t
c080: 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 he entire SQL st
c090: 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a atement to be.**
c0a0: 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 rejected with a
c0b0: 6e 20 65 72 72 6f 72 2e 20 20 0a 2a 2a 0a 2a 2a n error. .**.**
c0c0: 20 44 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 Depending on th
c0d0: 65 20 61 63 74 69 6f 6e 2c 20 74 68 65 20 5b 53 e action, the [S
c0e0: 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 61 6e QLITE_IGNORE] an
c0f0: 64 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 d [SQLITE_DENY]
c100: 72 65 74 75 72 6e 0a 2a 2a 20 63 6f 64 65 73 20 return.** codes
c110: 6d 69 67 68 74 20 6d 65 61 6e 20 73 6f 6d 65 74 might mean somet
c120: 68 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 6f hing different o
c130: 72 20 74 68 65 79 20 6d 69 67 68 74 20 6d 65 61 r they might mea
c140: 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 68 n the same.** th
c150: 69 6e 67 2e 20 20 49 66 20 74 68 65 20 61 63 74 ing. If the act
c160: 69 6f 6e 20 69 73 2c 20 66 6f 72 20 65 78 61 6d ion is, for exam
c170: 70 6c 65 2c 20 74 6f 20 70 65 72 66 6f 72 6d 20 ple, to perform
c180: 61 20 64 65 6c 65 74 65 20 6f 70 65 72 74 69 6f a delete opertio
c190: 6e 2c 0a 2a 2a 20 74 68 65 6e 20 5b 53 51 4c 49 n,.** then [SQLI
c1a0: 54 45 5f 49 47 4e 4f 52 45 5d 20 61 6e 64 20 5b TE_IGNORE] and [
c1b0: 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 62 6f 74 SQLITE_DENY] bot
c1c0: 68 20 63 61 75 73 65 20 74 68 65 20 73 74 61 74 h cause the stat
c1d0: 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 61 74 69 6f ement compilatio
c1e0: 6e 0a 2a 2a 20 74 6f 20 66 61 69 6c 20 77 69 74 n.** to fail wit
c1f0: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 42 75 74 h an error. But
c200: 20 69 66 20 74 68 65 20 61 63 74 69 6f 6e 20 69 if the action i
c210: 73 20 74 6f 20 72 65 61 64 20 61 20 73 70 65 63 s to read a spec
c220: 69 66 69 63 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 66 ific column.** f
c230: 72 6f 6d 20 61 20 73 70 65 63 69 66 69 63 20 74 rom a specific t
c240: 61 62 6c 65 2c 20 74 68 65 6e 20 5b 53 51 4c 49 able, then [SQLI
c250: 54 45 5f 44 45 4e 59 5d 20 77 69 6c 6c 20 63 61 TE_DENY] will ca
c260: 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 0a 2a use the entire.*
c270: 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 66 * statement to f
c280: 61 69 6c 20 62 75 74 20 5b 53 51 4c 49 54 45 5f ail but [SQLITE_
c290: 49 47 4e 4f 52 45 5d 20 77 69 6c 6c 20 63 61 75 IGNORE] will cau
c2a0: 73 65 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 se a NULL value
c2b0: 74 6f 20 62 65 0a 2a 2a 20 72 65 61 64 20 69 6e to be.** read in
c2c0: 73 74 65 61 64 20 6f 66 20 74 68 65 20 61 63 74 stead of the act
c2d0: 75 61 6c 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 ual column value
c2e0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 ..**.** The firs
c2f0: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 t parameter to t
c300: 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
c310: 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 llback is a copy
c320: 20 6f 66 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 of.** the third
c330: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
c340: 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 e sqlite3_set_au
c350: 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 thorizer() inter
c360: 66 61 63 65 2e 0a 2a 2a 20 54 68 65 20 73 65 63 face..** The sec
c370: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ond parameter to
c380: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 the callback is
c390: 20 61 6e 20 69 6e 74 65 67 65 72 20 0a 2a 2a 20 an integer .**
c3a0: 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 [SQLITE_COPY | a
c3b0: 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 ction code] that
c3c0: 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 70 specifies the p
c3d0: 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e articular action
c3e0: 0a 2a 2a 20 74 6f 20 62 65 20 61 75 74 68 6f 72 .** to be author
c3f0: 69 7a 65 64 2e 20 20 54 68 65 20 61 76 61 69 6c ized. The avail
c400: 61 62 6c 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 able action code
c410: 73 20 61 72 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 s are.** [SQLITE
c420: 5f 43 4f 50 59 20 7c 20 64 6f 63 75 6d 65 6e 74 _COPY | document
c430: 65 64 20 73 65 70 61 72 61 74 65 6c 79 5d 2e 20 ed separately].
c440: 20 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 The third throu
c450: 67 68 20 73 69 78 74 68 0a 2a 2a 20 70 61 72 61 gh sixth.** para
c460: 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 63 61 meters to the ca
c470: 6c 6c 62 61 63 6b 20 61 72 65 20 73 74 72 69 6e llback are strin
c480: 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 gs that contain
c490: 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 additional.** de
c4a0: 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 tails about the
c4b0: 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 action to be aut
c4c0: 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 horized..**.** A
c4d0: 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 n authorizer is
c4e0: 75 73 65 64 20 77 68 65 6e 20 70 72 65 70 61 72 used when prepar
c4f0: 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ing SQL statemen
c500: 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 ts from an untru
c510: 73 74 65 64 0a 2a 2a 20 73 6f 75 72 63 65 2c 20 sted.** source,
c520: 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 to ensure that t
c530: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
c540: 73 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 s do not try to
c550: 61 63 63 65 73 73 20 64 61 74 61 0a 2a 2a 20 74 access data.** t
c560: 68 61 74 20 74 68 65 79 20 61 72 65 20 6e 6f 74 hat they are not
c570: 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c allowed to see,
c580: 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f or that they do
c590: 20 6e 6f 74 20 74 72 79 20 74 6f 0a 2a 2a 20 65 not try to.** e
c5a0: 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 xecute malicious
c5b0: 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 statements that
c5c0: 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 damage the data
c5d0: 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 base. For.** ex
c5e0: 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 ample, an applic
c5f0: 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 ation may allow
c600: 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 a user to enter
c610: 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c arbitrary.** SQL
c620: 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 queries for eva
c630: 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 luation by a dat
c640: 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 abase. But the
c650: 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 application does
c660: 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 .** not want the
c670: 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 user to be able
c680: 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 to make arbitra
c690: 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 ry changes to th
c6a0: 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 e.** database.
c6b0: 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f An authorizer co
c6c0: 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 uld then be put
c6d0: 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 in place while t
c6e0: 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 he.** user-enter
c6f0: 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 ed SQL is being
c700: 70 72 65 70 61 72 65 64 20 74 68 61 74 20 64 69 prepared that di
c710: 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 sallows everythi
c720: 6e 67 0a 2a 2a 20 65 78 63 65 70 74 20 53 45 4c ng.** except SEL
c730: 45 43 54 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 ECT statements.
c740: 20 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 .**.** Only a s
c750: 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 ingle authorizer
c760: 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 can be in place
c770: 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 on a database c
c780: 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 onnection.** at
c790: 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 a time. Each ca
c7a0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 ll to sqlite3_se
c7b0: 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 t_authorizer ove
c7c0: 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 rrides the.** pr
c7d0: 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20 20 41 20 evious call. A
c7e0: 4e 55 4c 4c 20 61 75 74 68 6f 72 69 7a 65 72 20 NULL authorizer
c7f0: 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f 20 61 75 means that no au
c800: 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 thorization.** c
c810: 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
c820: 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 ed. The default
c830: 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 4e authorizer is N
c840: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 ULL..**.** Note
c850: 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 that the authori
c860: 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 zer callback is
c870: 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 invoked only dur
c880: 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ing .** [sqlite3
c890: 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 _prepare()] or i
c8a0: 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 ts variants. Au
c8b0: 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e thorization is n
c8c0: 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 ot.** performed
c8d0: 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 during statement
c8e0: 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b evaluation in [
c8f0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e sqlite3_step()].
c900: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
c910: 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a set_authorizer(.
c920: 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e sqlite3*,. in
c930: 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a t (*xAuth)(void*
c940: 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a ,int,const char*
c950: 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e ,const char*,con
c960: 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 st char*,const c
c970: 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 har*),. void *p
c980: 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a UserData.);../*.
c990: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 ** CAPI3REF: Aut
c9a0: 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 horizer Return C
c9b0: 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b odes.**.** The [
c9c0: 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
c9d0: 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 orizer | authori
c9e0: 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e zer callback fun
c9f0: 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 ction] must.** r
ca00: 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 eturn either [SQ
ca10: 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 LITE_OK] or one
ca20: 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e of these two con
ca30: 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a stants in order.
ca40: 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c ** to signal SQL
ca50: 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e ite whether or n
ca60: 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 ot the action is
ca70: 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 permitted. See
ca80: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
ca90: 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 _set_authorizer
caa0: 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 | authorizer doc
cab0: 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 umentation] for
cac0: 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e additional.** in
cad0: 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 formation..*/.#d
cae0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e efine SQLITE_DEN
caf0: 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 Y 1 /* Abort
cb00: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
cb10: 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 nt with an error
cb20: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
cb30: 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a TE_IGNORE 2 /*
cb40: 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 Don't allow acc
cb50: 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 ess, but don't g
cb60: 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 enerate an error
cb70: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
cb80: 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 REF: Authorizer
cb90: 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a Action Codes.**.
cba0: 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f ** The [sqlite3_
cbb0: 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 set_authorizer()
cbc0: 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 ] interface regi
cbd0: 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b sters a callback
cbe0: 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 function.** tha
cbf0: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 t is invoked to
cc00: 61 75 74 68 6f 72 69 7a 65 72 20 63 65 72 74 61 authorizer certa
cc10: 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 in SQL statement
cc20: 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a actions. The.*
cc30: 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 * second paramet
cc40: 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 er to the callba
cc50: 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ck is an integer
cc60: 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 code that speci
cc70: 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 fies.** what act
cc80: 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 ion is being aut
cc90: 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 horized. These
cca0: 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 are the integer
ccb0: 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 action codes tha
ccc0: 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 t.** the authori
ccd0: 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 zer callback may
cce0: 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a be passed..**.*
ccf0: 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 * These action c
cd00: 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 ode values signi
cd10: 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 fy what kind of
cd20: 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 operation is to
cd30: 62 65 20 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 be .** authorize
cd40: 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 d. The 3rd and
cd50: 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 4th parameters t
cd60: 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 o the authorizat
cd70: 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 ion callback.**
cd80: 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 function will be
cd90: 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e parameters or N
cda0: 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e ULL depending on
cdb0: 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a which of these.
cdc0: 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 ** codes is used
cdd0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 as the second p
cde0: 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 35 arameter. The 5
cdf0: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
ce00: 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 the.** authorize
ce10: 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 r callback is th
ce20: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 e name of the da
ce30: 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 tabase ("main",
ce40: 22 74 65 6d 70 22 2c 20 0a 2a 2a 20 65 74 63 2e "temp", .** etc.
ce50: 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e ) if applicable.
ce60: 20 20 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 The 6th parame
ce70: 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f ter to the autho
ce80: 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a rizer callback.*
ce90: 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 * is the name of
cea0: 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 the inner-most
ceb0: 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 trigger or view
cec0: 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 that is responsi
ced0: 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 ble for.** the a
cee0: 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 ccess attempt or
cef0: 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 NULL if this ac
cf00: 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 cess attempt is
cf10: 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 20 0a 2a directly from .*
cf20: 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 * top-level SQL
cf30: 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a code..*/./******
cf40: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
cf50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
cf60: 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a ***** 3rd ******
cf70: 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a ****** 4th *****
cf80: 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 ******/.#define
cf90: 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e SQLITE_CREATE_IN
cfa0: 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 DEX 1
cfb0: 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 /* Index Name
cfc0: 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
cfd0: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
cfe0: 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 QLITE_CREATE_TAB
cff0: 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 LE 2
d000: 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
d010: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
d020: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
d030: 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 LITE_CREATE_TEMP
d040: 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f _INDEX 3 /
d050: 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 * Index Name
d060: 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
d070: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
d080: 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f ITE_CREATE_TEMP_
d090: 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a TABLE 4 /*
d0a0: 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
d0b0: 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
d0c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
d0d0: 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 TE_CREATE_TEMP_T
d0e0: 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 RIGGER 5 /*
d0f0: 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 Trigger Name
d100: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
d110: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
d120: 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 E_CREATE_TEMP_VI
d130: 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 EW 6 /* V
d140: 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e iew Name N
d150: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
d160: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
d170: 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 _CREATE_TRIGGER
d180: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 7 /* Tr
d190: 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 igger Name Ta
d1a0: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
d1b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d1c0: 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 CREATE_VIEW
d1d0: 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 8 /* Vie
d1e0: 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c w Name NUL
d1f0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
d200: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
d210: 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 ELETE
d220: 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 9 /* Tabl
d230: 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
d240: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
d250: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
d260: 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 OP_INDEX
d270: 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 10 /* Index
d280: 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 Name Table
d290: 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
d2a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
d2b0: 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 P_TABLE
d2c0: 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 11 /* Table
d2d0: 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
d2e0: 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
d2f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
d300: 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 _TEMP_INDEX
d310: 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 12 /* Index N
d320: 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e ame Table N
d330: 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
d340: 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
d350: 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 TEMP_TABLE
d360: 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 13 /* Table Na
d370: 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
d380: 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
d390: 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
d3a0: 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 EMP_TRIGGER 1
d3b0: 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 4 /* Trigger N
d3c0: 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d ame Table Nam
d3d0: 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
d3e0: 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 e SQLITE_DROP_TE
d3f0: 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 MP_VIEW 15
d400: 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 /* View Name
d410: 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
d420: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
d430: 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 SQLITE_DROP_TRI
d440: 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 GGER 16
d450: 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d /* Trigger Nam
d460: 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 e Table Name
d470: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
d480: 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 SQLITE_DROP_VIEW
d490: 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 17
d4a0: 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 /* View Name
d4b0: 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
d4c0: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
d4d0: 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 QLITE_INSERT
d4e0: 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 18
d4f0: 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
d500: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
d510: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
d520: 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 LITE_PRAGMA
d530: 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 19 /
d540: 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 * Pragma Name
d550: 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 1st arg or NUL
d560: 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c L */.#define SQL
d570: 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 ITE_READ
d580: 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 /*
d590: 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
d5a0: 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 Column Name
d5b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
d5c0: 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 TE_SELECT
d5d0: 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 21 /*
d5e0: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
d5f0: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
d600: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
d610: 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 E_TRANSACTION
d620: 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4e 22 /* N
d630: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e ULL N
d640: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
d650: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
d660: 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 _UPDATE
d670: 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 23 /* Ta
d680: 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f ble Name Co
d690: 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f lumn Name */
d6a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d6b0: 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 ATTACH
d6c0: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 24 /* Fil
d6d0: 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c ename NUL
d6e0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
d6f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
d700: 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 ETACH
d710: 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 25 /* Data
d720: 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c base Name NULL
d730: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
d740: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c define SQLITE_AL
d750: 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 TER_TABLE
d760: 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 26 /* Datab
d770: 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 ase Name Table
d780: 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
d790: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 efine SQLITE_REI
d7a0: 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 NDEX
d7b0: 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 27 /* Index
d7c0: 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
d7d0: 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
d7e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c fine SQLITE_ANAL
d7f0: 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 YZE
d800: 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 28 /* Table N
d810: 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
d820: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
d830: 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
d840: 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 E_VTABLE
d850: 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 29 /* Table Na
d860: 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e me Module N
d870: 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 ame */.#defi
d880: 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 ne SQLITE_DROP_V
d890: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 TABLE 3
d8a0: 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 0 /* Table Nam
d8b0: 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 e Module Na
d8c0: 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e me */.#defin
d8d0: 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f e SQLITE_FUNCTIO
d8e0: 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 N 31
d8f0: 20 20 20 2f 2a 20 46 75 6e 63 74 69 6f 6e 20 4e /* Function N
d900: 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 ame NULL
d910: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
d920: 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 SQLITE_COPY
d930: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 0
d940: 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 /* No longer u
d950: 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 sed */../*.** CA
d960: 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 PI3REF: Tracing
d970: 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 And Profiling Fu
d980: 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 nctions.**.** Th
d990: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 ese routines reg
d9a0: 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 ister callback f
d9b0: 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 unctions that ca
d9c0: 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a n be used for.**
d9d0: 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f tracing and pro
d9e0: 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 filing the execu
d9f0: 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 tion of SQL stat
da00: 65 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 63 ements..** The c
da10: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
da20: 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 registered by s
da30: 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 qlite3_trace() i
da40: 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 74 20 s invoked.** at
da50: 74 68 65 20 66 69 72 73 74 20 5b 73 71 6c 69 74 the first [sqlit
da60: 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 74 e3_step()] for t
da70: 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 he evaluation of
da80: 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e an SQL statemen
da90: 74 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 t..** The callba
daa0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 ck function regi
dab0: 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 stered by sqlite
dac0: 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 3_profile() is i
dad0: 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 nvoked.** as eac
dae0: 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 h SQL statement
daf0: 66 69 6e 69 73 68 65 73 20 61 6e 64 20 69 6e 63 finishes and inc
db00: 6c 75 64 65 73 0a 2a 2a 20 69 6e 66 6f 72 6d 61 ludes.** informa
db10: 74 69 6f 6e 20 6f 6e 20 68 6f 77 20 6c 6f 6e 67 tion on how long
db20: 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 that statement
db30: 72 61 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ran..**.** The s
db40: 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 qlite3_profile()
db50: 20 41 50 49 20 69 73 20 63 75 72 72 65 6e 74 6c API is currentl
db60: 79 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 y considered exp
db70: 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 0a 2a 2a erimental and.**
db80: 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 is subject to c
db90: 68 61 6e 67 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a hange..*/.void *
dba0: 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 sqlite3_trace(sq
dbb0: 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 lite3*, void(*xT
dbc0: 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 race)(void*,cons
dbd0: 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 t char*), void*)
dbe0: 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f ;.void *sqlite3_
dbf0: 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a profile(sqlite3*
dc00: 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 ,. void(*xProf
dc10: 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 ile)(void*,const
dc20: 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 char*,sqlite3_u
dc30: 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a int64), void*);.
dc40: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
dc50: 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 Query Progress
dc60: 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 Callbacks.**.**
dc70: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e This routine con
dc80: 66 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62 61 figures a callba
dc90: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 ck function - th
dca0: 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 e progress callb
dcb0: 61 63 6b 20 2d 20 74 68 61 74 0a 2a 2a 20 69 73 ack - that.** is
dcc0: 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 invoked periodi
dcd0: 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e cally during lon
dce0: 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 g running calls
dcf0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 to [sqlite3_exec
dd00: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
dd10: 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 _step()] and [sq
dd20: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
dd30: 29 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 )]. An example
dd40: 75 73 65 20 66 6f 72 20 74 68 69 73 20 0a 2a 2a use for this .**
dd50: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f interface is to
dd60: 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 keep a GUI upda
dd70: 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 ted during a lar
dd80: 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 ge query..**.**
dd90: 54 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c The progress cal
dda0: 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
ddb0: 20 6f 6e 63 65 20 66 6f 72 20 65 76 65 72 79 20 once for every
ddc0: 4e 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e N virtual machin
ddd0: 65 20 6f 70 63 6f 64 65 73 2c 0a 2a 2a 20 77 68 e opcodes,.** wh
dde0: 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 ere N is the sec
ddf0: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ond argument to
de00: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 this function. T
de10: 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c he progress call
de20: 62 61 63 6b 0a 2a 2a 20 69 74 73 65 6c 66 20 69 back.** itself i
de30: 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 s identified by
de40: 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 the third argume
de50: 6e 74 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 nt to this funct
de60: 69 6f 6e 2e 20 54 68 65 20 66 6f 75 72 74 68 0a ion. The fourth.
de70: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 ** argument to t
de80: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 his function is
de90: 61 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 70 a void pointer p
dea0: 61 73 73 65 64 20 74 6f 20 74 68 65 20 70 72 6f assed to the pro
deb0: 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 0a 2a gress callback.*
dec0: 2a 20 66 75 6e 63 74 69 6f 6e 20 65 61 63 68 20 * function each
ded0: 74 69 6d 65 20 69 74 20 69 73 20 69 6e 76 6f 6b time it is invok
dee0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 ed..**.** If a c
def0: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
df00: 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 exec()], [sqlite
df10: 33 5f 73 74 65 70 28 29 5d 2c 20 6f 72 20 5b 73 3_step()], or [s
df20: 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
df30: 28 29 5d 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 ()].** results i
df40: 6e 20 66 65 77 65 72 20 74 68 61 6e 20 4e 20 6f n fewer than N o
df50: 70 63 6f 64 65 73 20 62 65 69 6e 67 20 65 78 65 pcodes being exe
df60: 63 75 74 65 64 2c 20 74 68 65 6e 20 74 68 65 20 cuted, then the
df70: 70 72 6f 67 72 65 73 73 20 0a 2a 2a 20 63 61 6c progress .** cal
df80: 6c 62 61 63 6b 20 69 73 20 6e 65 76 65 72 20 69 lback is never i
df90: 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 4f nvoked..** .** O
dfa0: 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f nly a single pro
dfb0: 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 66 gress callback f
dfc0: 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 unction may be r
dfd0: 65 67 69 73 74 65 72 65 64 20 66 6f 72 20 65 61 egistered for ea
dfe0: 63 68 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62 ch.** open datab
dff0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 ase connection.
e000: 20 45 76 65 72 79 20 63 61 6c 6c 20 74 6f 20 73 Every call to s
e010: 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f qlite3_progress_
e020: 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 6f 76 65 handler().** ove
e030: 72 77 72 69 74 65 73 20 74 68 65 20 72 65 73 75 rwrites the resu
e040: 6c 74 73 20 6f 66 20 74 68 65 20 70 72 65 76 69 lts of the previ
e050: 6f 75 73 20 63 61 6c 6c 2e 0a 2a 2a 20 54 6f 20 ous call..** To
e060: 72 65 6d 6f 76 65 20 74 68 65 20 70 72 6f 67 72 remove the progr
e070: 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 61 6c 74 ess callback alt
e080: 6f 67 65 74 68 65 72 2c 20 70 61 73 73 20 4e 55 ogether, pass NU
e090: 4c 4c 20 61 73 20 74 68 65 20 74 68 69 72 64 0a LL as the third.
e0a0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 ** argument to t
e0b0: 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a his function..**
e0c0: 0a 2a 2a 20 49 66 20 74 68 65 20 70 72 6f 67 72 .** If the progr
e0d0: 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 ess callback ret
e0e0: 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 6f 74 urns a result ot
e0f0: 68 65 72 20 74 68 61 6e 20 30 2c 20 74 68 65 6e her than 0, then
e100: 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a the current .**
e110: 20 71 75 65 72 79 20 69 73 20 69 6d 6d 65 64 69 query is immedi
e120: 61 74 65 6c 79 20 74 65 72 6d 69 6e 61 74 65 64 ately terminated
e130: 20 61 6e 64 20 61 6e 79 20 64 61 74 61 62 61 73 and any databas
e140: 65 20 63 68 61 6e 67 65 73 20 72 6f 6c 6c 65 64 e changes rolled
e150: 20 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 63 6f back..** The co
e160: 6e 74 61 69 6e 69 6e 67 20 5b 73 71 6c 69 74 65 ntaining [sqlite
e170: 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 3_exec()], [sqli
e180: 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 6f 72 0a te3_step()], or.
e190: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f ** [sqlite3_get_
e1a0: 74 61 62 6c 65 28 29 5d 20 63 61 6c 6c 20 72 65 table()] call re
e1b0: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4e 54 turns SQLITE_INT
e1c0: 45 52 52 55 50 54 2e 20 20 20 54 68 69 73 20 66 ERRUPT. This f
e1d0: 65 61 74 75 72 65 0a 2a 2a 20 63 61 6e 20 62 65 eature.** can be
e1e0: 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 used, for examp
e1f0: 6c 65 2c 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 le, to implement
e200: 20 74 68 65 20 22 43 61 6e 63 65 6c 22 20 62 75 the "Cancel" bu
e210: 74 74 6f 6e 20 6f 6e 20 61 0a 2a 2a 20 70 72 6f tton on a.** pro
e220: 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 gress dialog box
e230: 20 69 6e 20 61 20 47 55 49 2e 0a 2a 2f 0a 76 6f in a GUI..*/.vo
e240: 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 id sqlite3_progr
e250: 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 ess_handler(sqli
e260: 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a te3*, int, int(*
e270: 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 )(void*), void*)
e280: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
e290: 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 F: Opening A New
e2a0: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 Database Connec
e2b0: 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 4f 70 65 6e 20 tion.**.** Open
e2c0: 74 68 65 20 73 71 6c 69 74 65 20 64 61 74 61 62 the sqlite datab
e2d0: 61 73 65 20 66 69 6c 65 20 22 66 69 6c 65 6e 61 ase file "filena
e2e0: 6d 65 22 2e 20 20 54 68 65 20 22 66 69 6c 65 6e me". The "filen
e2f0: 61 6d 65 22 20 69 73 20 55 54 46 2d 38 0a 2a 2a ame" is UTF-8.**
e300: 20 65 6e 63 6f 64 65 64 20 66 6f 72 20 73 71 6c encoded for sql
e310: 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 ite3_open() and
e320: 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 69 UTF-16 encoded i
e330: 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 n the native byt
e340: 65 20 6f 72 64 65 72 0a 2a 2a 20 66 6f 72 20 73 e order.** for s
e350: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e qlite3_open16().
e360: 20 20 41 6e 20 5b 73 71 6c 69 74 65 33 2a 5d 20 An [sqlite3*]
e370: 68 61 6e 64 6c 65 20 69 73 20 72 65 74 75 72 6e handle is return
e380: 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 ed in *ppDb, eve
e390: 6e 0a 2a 2a 20 69 66 20 61 6e 20 65 72 72 6f 72 n.** if an error
e3a0: 20 6f 63 63 75 72 73 2e 20 49 66 20 74 68 65 20 occurs. If the
e3b0: 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
e3c0: 65 64 20 28 6f 72 20 63 72 65 61 74 65 64 29 20 ed (or created)
e3d0: 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 0a 2a 2a successfully,.**
e3e0: 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b then [SQLITE_OK
e3f0: 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 4f ] is returned. O
e400: 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f therwise an erro
e410: 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e r code is return
e420: 65 64 2e 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 ed. The.** [sqli
e430: 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 te3_errmsg()] or
e440: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
e450: 31 36 28 29 5d 20 20 72 6f 75 74 69 6e 65 73 20 16()] routines
e460: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f can be used to o
e470: 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c btain.** an Engl
e480: 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 ish language des
e490: 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 cription of the
e4a0: 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 error..**.** If
e4b0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
e4c0: 65 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 e does not exist
e4d0: 2c 20 74 68 65 6e 20 61 20 6e 65 77 20 64 61 74 , then a new dat
e4e0: 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 abase will be cr
e4f0: 65 61 74 65 64 0a 2a 2a 20 61 73 20 6e 65 65 64 eated.** as need
e500: 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 ed. The default
e510: 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 encoding for th
e520: 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 e database will
e530: 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 be UTF-8 if.** s
e540: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 69 73 qlite3_open() is
e550: 20 63 61 6c 6c 65 64 20 61 6e 64 20 55 54 46 2d called and UTF-
e560: 31 36 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 16 if sqlite3_op
e570: 65 6e 31 36 20 69 73 20 75 73 65 64 2e 0a 2a 2a en16 is used..**
e580: 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e .** Whether or n
e590: 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 ot an error occu
e5a0: 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 rs when it is op
e5b0: 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 20 ened, resources
e5c0: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 associated.** wi
e5d0: 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a th the [sqlite3*
e5e0: 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 ] handle should
e5f0: 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 20 70 be released by p
e600: 61 73 73 69 6e 67 20 69 74 20 74 6f 0a 2a 2a 20 assing it to.**
e610: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 [sqlite3_close()
e620: 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 ] when it is no
e630: 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e longer required.
e640: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
e650: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 e3_open_v2() int
e660: 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b erface works lik
e670: 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 e sqlite3_open()
e680: 20 65 78 63 65 70 74 20 74 68 61 74 0a 2a 2a 20 except that.**
e690: 70 72 6f 76 69 64 65 73 20 74 77 6f 20 61 64 64 provides two add
e6a0: 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 itional paramete
e6b0: 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 rs for additiona
e6c0: 6c 20 63 6f 6e 74 72 6f 6c 20 6f 76 65 72 20 74 l control over t
e6d0: 68 65 0a 2a 2a 20 6e 65 77 20 64 61 74 61 62 61 he.** new databa
e6e0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 se connection.
e6f0: 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 The flags parame
e700: 74 65 72 20 63 61 6e 20 62 65 20 6f 6e 65 20 6f ter can be one o
e710: 66 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a f:.**.** <ol>.**
e720: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
e730: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 0a 2a 2a PEN_READONLY].**
e740: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
e750: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 0a 2a PEN_READWRITE].*
e760: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
e770: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 OPEN_READWRITE]
e780: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 | [SQLITE_OPEN_C
e790: 52 45 41 54 45 5d 0a 2a 2a 20 3c 2f 6f 6c 3e 0a REATE].** </ol>.
e7a0: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
e7b0: 76 61 6c 75 65 20 6f 70 65 6e 73 20 74 68 65 20 value opens the
e7c0: 64 61 74 61 62 61 73 65 20 72 65 61 64 2d 6f 6e database read-on
e7d0: 6c 79 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 ly. If the data
e7e0: 62 61 73 65 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 base does.** not
e7f0: 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73 previously exis
e800: 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 t, an error is r
e810: 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 73 65 eturned. The se
e820: 63 6f 6e 64 20 6f 70 74 69 6f 6e 20 6f 70 65 6e cond option open
e830: 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 s.** the databas
e840: 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e e for reading an
e850: 64 20 77 72 69 74 69 6e 67 20 62 75 74 20 74 68 d writing but th
e860: 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 e database must
e870: 61 6c 72 65 61 64 79 0a 2a 2a 20 65 78 69 73 74 already.** exist
e880: 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 69 73 20 or an error is
e890: 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 74 returned. The t
e8a0: 68 69 72 64 20 6f 70 74 69 6f 6e 20 6f 70 65 6e hird option open
e8b0: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a s the database.*
e8c0: 2a 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e * for reading an
e8d0: 64 20 77 72 69 74 69 6e 67 20 61 6e 64 20 63 72 d writing and cr
e8e0: 65 61 74 65 73 20 69 74 20 69 66 20 69 74 20 64 eates it if it d
e8f0: 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 oes not already
e900: 65 78 69 73 74 2e 0a 2a 2a 20 54 68 65 20 74 68 exist..** The th
e910: 69 72 64 20 6f 70 74 69 6f 6e 73 20 69 73 20 62 ird options is b
e920: 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 ehavior that is
e930: 75 73 65 64 20 61 6c 77 61 79 73 20 66 6f 72 20 used always for
e940: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a sqlite3_open().*
e950: 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 * and sqlite3_op
e960: 65 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 en16()..**.** Th
e970: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
e980: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 er to sqlite3_op
e990: 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e en_v2() is the n
e9a0: 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 ame of the.** [s
e9b0: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
e9c0: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 ct that defines
e9d0: 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 the operating sy
e9e0: 73 74 65 6d 20 0a 2a 2a 20 69 6e 74 65 72 66 61 stem .** interfa
e9f0: 63 65 20 74 68 61 74 20 74 68 65 20 6e 65 77 20 ce that the new
ea00: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
ea10: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 ion should use.
ea20: 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 If the.** fourt
ea30: 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 h parameter is a
ea40: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 NULL pointer th
ea50: 65 6e 20 61 20 64 65 66 61 75 6c 74 20 73 75 69 en a default sui
ea60: 74 61 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 table for.** the
ea70: 20 68 6f 73 74 20 65 6e 76 69 72 6f 6e 6d 65 6e host environmen
ea80: 74 20 69 73 20 73 75 62 73 74 69 74 75 74 65 64 t is substituted
ea90: 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 6f 20 ..**.** Note to
eaa0: 77 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 20 20 windows users:
eab0: 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 The encoding use
eac0: 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 d for the filena
ead0: 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f me argument.** o
eae0: 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 f sqlite3_open()
eaf0: 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 must be UTF-8,
eb00: 6e 6f 74 20 77 68 61 74 65 76 65 72 20 63 6f 64 not whatever cod
eb10: 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 epage is current
eb20: 6c 79 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20 20 ly.** defined.
eb30: 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 Filenames contai
eb40: 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e ning internation
eb50: 61 6c 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 al characters mu
eb60: 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a st be converted.
eb70: 2a 2a 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f ** to UTF-8 prio
eb80: 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 r to passing the
eb90: 6d 20 69 6e 74 6f 20 73 71 6c 69 74 65 33 5f 6f m into sqlite3_o
eba0: 70 65 6e 28 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 pen()..*/.int sq
ebb0: 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f lite3_open(. co
ebc0: 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 nst char *filena
ebd0: 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 me, /* Databas
ebe0: 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d e filename (UTF-
ebf0: 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 8) */. sqlite3
ec00: 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 **ppDb
ec10: 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 /* OUT: SQLite d
ec20: 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 b handle */.);.i
ec30: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 nt sqlite3_open1
ec40: 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 6(. const void
ec50: 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 *filename, /*
ec60: 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d Database filenam
ec70: 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 e (UTF-16) */.
ec80: 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 sqlite3 **ppDb
ec90: 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 /* OUT:
eca0: 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 SQLite db handle
ecb0: 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 */.);.int sqlit
ecc0: 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f e3_open_v2(. co
ecd0: 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 nst void *filena
ece0: 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 me, /* Databas
ecf0: 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d e filename (UTF-
ed00: 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 8) */. sqlite3
ed10: 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 **ppDb,
ed20: 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 /* OUT: SQLite d
ed30: 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e b handle */. in
ed40: 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 t flags,
ed50: 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a /* Flags *
ed60: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
ed70: 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e zVfs /* N
ed80: 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c ame of VFS modul
ed90: 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a e to use */.);..
eda0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
edb0: 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 Error Codes And
edc0: 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 54 Messages.**.** T
edd0: 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f he sqlite3_errco
ede0: 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 de() interface r
edf0: 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 eturns the numer
ee00: 69 63 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b ic.** [SQLITE_OK
ee10: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 | result code]
ee20: 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 or [SQLITE_IOERR
ee30: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 _READ | extended
ee40: 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a result code].**
ee50: 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 for the most re
ee60: 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 cent failed sqli
ee70: 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 te3_* API call a
ee80: 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 ssociated.** wit
ee90: 68 20 5b 73 71 6c 69 74 65 33 5d 20 68 61 6e 64 h [sqlite3] hand
eea0: 6c 65 20 27 64 62 27 2e 20 20 49 66 20 61 20 70 le 'db'. If a p
eeb0: 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 rior API call fa
eec0: 69 6c 65 64 20 62 75 74 20 74 68 65 0a 2a 2a 20 iled but the.**
eed0: 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 most recent API
eee0: 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 call succeeded,
eef0: 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
ef00: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 from sqlite3_er
ef10: 72 63 6f 64 65 28 29 0a 2a 2a 20 69 73 20 75 6e rcode().** is un
ef20: 64 65 66 69 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 defined. .**.**
ef30: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d The sqlite3_errm
ef40: 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 sg() and sqlite3
ef50: 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 _errmsg16() retu
ef60: 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 61 rn English-langa
ef70: 75 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 uge.** text that
ef80: 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 describes the e
ef90: 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 rror, as either
efa0: 55 54 46 38 20 6f 72 20 55 54 46 31 36 20 72 65 UTF8 or UTF16 re
efb0: 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d spectively..** M
efc0: 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 emory to hold th
efd0: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 e error message
efe0: 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 string is manage
eff0: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 20 20 54 d internally. T
f000: 68 65 20 0a 2a 2a 20 73 74 72 69 6e 67 20 6d 61 he .** string ma
f010: 79 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e y be overwritten
f020: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 or deallocated
f030: 62 79 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 by subsequent ca
f040: 6c 6c 73 20 74 6f 20 53 51 4c 69 74 65 0a 2a 2a lls to SQLite.**
f050: 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 interface funct
f060: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c ions..**.** Call
f070: 73 20 74 6f 20 6d 61 6e 79 20 73 71 6c 69 74 65 s to many sqlite
f080: 33 5f 2a 20 66 75 6e 63 74 69 6f 6e 73 20 73 65 3_* functions se
f090: 74 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 t the error code
f0a0: 20 61 6e 64 20 73 74 72 69 6e 67 20 72 65 74 75 and string retu
f0b0: 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 rned.** by [sqli
f0c0: 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 te3_errcode()],
f0d0: 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 [sqlite3_errmsg(
f0e0: 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 )], and [sqlite3
f0f0: 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 _errmsg16()].**
f100: 28 6f 76 65 72 77 72 69 74 69 6e 67 20 74 68 65 (overwriting the
f110: 20 70 72 65 76 69 6f 75 73 20 76 61 6c 75 65 73 previous values
f120: 29 2e 20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c ). Note that cal
f130: 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 ls to [sqlite3_e
f140: 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 5b 73 rrcode()],.** [s
f150: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d qlite3_errmsg()]
f160: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 , and [sqlite3_e
f170: 72 72 6d 73 67 31 36 28 29 5d 20 74 68 65 6d 73 rrmsg16()] thems
f180: 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 66 66 elves do not aff
f190: 65 63 74 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c ect the.** resul
f1a0: 74 73 20 6f 66 20 66 75 74 75 72 65 20 69 6e 76 ts of future inv
f1b0: 6f 63 61 74 69 6f 6e 73 2e 20 20 43 61 6c 6c 73 ocations. Calls
f1c0: 20 74 6f 20 41 50 49 20 72 6f 75 74 69 6e 65 73 to API routines
f1d0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 72 65 74 that do not ret
f1e0: 75 72 6e 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 urn.** an error
f1f0: 63 6f 64 65 20 28 65 78 61 6d 70 6c 65 73 3a 20 code (examples:
f200: 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f [sqlite3_data_co
f210: 75 6e 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 unt()] or [sqlit
f220: 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 29 20 64 e3_mprintf()]) d
f230: 6f 0a 2a 2a 20 6e 6f 74 20 63 68 61 6e 67 65 20 o.** not change
f240: 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 72 the error code r
f250: 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 eturned by this
f260: 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 41 routine..**.** A
f270: 73 73 75 6d 69 6e 67 20 6e 6f 20 6f 74 68 65 72 ssuming no other
f280: 20 69 6e 74 65 72 76 65 6e 69 6e 67 20 73 71 6c intervening sql
f290: 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 73 ite3_* API calls
f2a0: 20 61 72 65 20 6d 61 64 65 2c 20 74 68 65 20 65 are made, the e
f2b0: 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 72 65 74 rror.** code ret
f2c0: 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 urned by this fu
f2d0: 6e 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 69 nction is associ
f2e0: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 73 61 ated with the sa
f2f0: 6d 65 20 65 72 72 6f 72 20 61 73 0a 2a 2a 20 74 me error as.** t
f300: 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 he strings retur
f310: 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ned by [sqlite3_
f320: 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 5b 73 errmsg()] and [s
f330: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 qlite3_errmsg16(
f340: 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 )]..*/.int sqlit
f350: 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 e3_errcode(sqlit
f360: 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 e3 *db);.const c
f370: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 har *sqlite3_err
f380: 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 msg(sqlite3*);.c
f390: 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
f3a0: 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 e3_errmsg16(sqli
f3b0: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
f3c0: 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 PI3REF: SQL Stat
f3d0: 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a ement Object.**.
f3e0: 2a 2a 20 49 6e 73 74 61 6e 63 65 20 6f 66 20 74 ** Instance of t
f3f0: 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 his object repre
f400: 73 65 6e 74 20 73 69 6e 67 6c 65 20 53 51 4c 20 sent single SQL
f410: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 54 68 69 statements. Thi
f420: 73 0a 2a 2a 20 69 73 20 76 61 72 69 6f 75 73 6c s.** is variousl
f430: 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 y known as a "pr
f440: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
f450: 22 20 6f 72 20 61 20 0a 2a 2a 20 22 63 6f 6d 70 " or a .** "comp
f460: 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 iled SQL stateme
f470: 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 nt" or simply as
f480: 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a a "statement"..
f490: 2a 2a 20 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 ** .** The life
f4a0: 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f of a statement o
f4b0: 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 bject goes somet
f4c0: 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a hing like this:.
f4d0: 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c **.** <ol>.** <l
f4e0: 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 i> Create the ob
f4f0: 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 ject using [sqli
f500: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
f510: 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a ] or a related.*
f520: 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e * function.
f530: 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 .** <li> Bind va
f540: 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 lues to host par
f550: 61 6d 65 74 65 72 73 20 75 73 69 6e 67 0a 2a 2a ameters using.**
f560: 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 [sqlite3_b
f570: 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 ind_blob | sqlit
f580: 65 33 5f 62 69 6e 64 5f 2a 20 69 6e 74 65 72 66 e3_bind_* interf
f590: 61 63 65 73 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 aces]..** <li> R
f5a0: 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 un the SQL by ca
f5b0: 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 lling [sqlite3_s
f5c0: 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f tep()] one or mo
f5d0: 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 re times..** <li
f5e0: 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74 > Reset the stat
f5f0: 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c ement using [sql
f600: 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 ite3_reset()] th
f610: 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 en go back.**
f620: 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 to step 2. D
f630: 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d o this zero or m
f640: 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c ore times..** <l
f650: 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f i> Destroy the o
f660: 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c bject using [sql
f670: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
f680: 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a ..** </ol>.**.**
f690: 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 Refer to docume
f6a0: 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 ntation on indiv
f6b0: 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 idual methods ab
f6c0: 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e ove for addition
f6d0: 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f al.** informatio
f6e0: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 n..*/.typedef st
f6f0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d ruct sqlite3_stm
f700: 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a t sqlite3_stmt;.
f710: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
f720: 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 Compiling An SQ
f730: 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a L Statement.**.*
f740: 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 * To execute an
f750: 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 SQL query, it mu
f760: 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 st first be comp
f770: 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 iled into a byte
f780: 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d -code.** program
f790: 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 using one of th
f7a0: 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 20 0a 2a ese routines. .*
f7b0: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 *.** The first a
f7c0: 72 67 75 6d 65 6e 74 20 22 64 62 22 20 69 73 20 rgument "db" is
f7d0: 61 6e 20 5b 73 71 6c 69 74 65 33 20 7c 20 53 51 an [sqlite3 | SQ
f7e0: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 68 61 Lite database ha
f7f0: 6e 64 6c 65 5d 20 0a 2a 2a 20 6f 62 74 61 69 6e ndle] .** obtain
f800: 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 20 ed from a prior
f810: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
f820: 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c _open()] or [sql
f830: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a ite3_open16()]..
f840: 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 ** The second ar
f850: 67 75 6d 65 6e 74 20 22 7a 53 71 6c 22 20 69 73 gument "zSql" is
f860: 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 the statement t
f870: 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 o be compiled, e
f880: 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 ncoded.** as eit
f890: 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 her UTF-8 or UTF
f8a0: 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 -16. The sqlite
f8b0: 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 3_prepare() and
f8c0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
f8d0: 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 v2().** interfac
f8e0: 65 73 20 75 73 65 73 20 55 54 46 2d 38 20 61 6e es uses UTF-8 an
f8f0: 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 d sqlite3_prepar
f900: 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 e16() and sqlite
f910: 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
f920: 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a .** use UTF-16..
f930: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79 **.** If the nBy
f940: 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c te argument is l
f950: 65 73 73 0a 2a 2a 20 74 68 61 6e 20 7a 65 72 6f ess.** than zero
f960: 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 , then zSql is r
f970: 65 61 64 20 75 70 20 74 6f 20 74 68 65 20 66 69 ead up to the fi
f980: 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 rst zero termina
f990: 74 6f 72 2e 20 20 49 66 0a 2a 2a 20 6e 42 79 74 tor. If.** nByt
f9a0: 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 e is non-negativ
f9b0: 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 e, then it is th
f9c0: 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
f9d0: 20 6f 66 20 0a 2a 2a 20 62 79 74 65 73 20 72 65 of .** bytes re
f9e0: 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 ad from zSql. W
f9f0: 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e hen nByte is non
fa00: 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a -negative, the.*
fa10: 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e * zSql string en
fa20: 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 ds at either the
fa30: 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 63 68 first '\000' ch
fa40: 61 72 61 63 74 65 72 20 6f 72 20 0a 2a 2a 20 75 aracter or .** u
fa50: 6e 74 69 6c 20 74 68 65 20 6e 42 79 74 65 2d 74 ntil the nByte-t
fa60: 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 h byte, whicheve
fa70: 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a r comes first..*
fa80: 2a 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20 69 73 20 *.** *pzTail is
fa90: 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f made to point to
faa0: 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 20 the first byte
fab0: 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 past the end of
fac0: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 53 51 4c the first.** SQL
fad0: 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 statement in zS
fae0: 71 6c 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e ql. This routin
faf0: 65 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c 65 73 20 e only compiles
fb00: 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d the first statem
fb10: 65 6e 74 0a 2a 2a 20 69 6e 20 7a 53 71 6c 2c 20 ent.** in zSql,
fb20: 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 so *pzTail is le
fb30: 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 77 ft pointing to w
fb40: 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f hat remains unco
fb50: 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 mpiled..**.** *p
fb60: 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f pStmt is left po
fb70: 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 inting to a comp
fb80: 69 6c 65 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 iled .** [sqlite
fb90: 33 5f 73 74 6d 74 20 7c 20 53 51 4c 20 73 74 61 3_stmt | SQL sta
fba0: 74 65 6d 65 6e 74 20 73 74 72 75 63 74 75 72 65 tement structure
fbb0: 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a ] that can be.**
fbc0: 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 executed using
fbd0: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
fbe0: 2e 20 20 4f 72 20 69 66 20 74 68 65 72 65 20 69 . Or if there i
fbf0: 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 s an error, *ppS
fc00: 74 6d 74 20 6d 61 79 20 62 65 0a 2a 2a 20 73 65 tmt may be.** se
fc10: 74 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74 t to NULL. If t
fc20: 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f he input text co
fc30: 6e 74 61 69 6e 65 64 20 6e 6f 20 53 51 4c 20 28 ntained no SQL (
fc40: 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 if the input is
fc50: 61 6e 64 0a 2a 2a 20 65 6d 70 74 79 20 73 74 72 and.** empty str
fc60: 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 ing or a comment
fc70: 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 ) then *ppStmt i
fc80: 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 20 20 s set to NULL.
fc90: 54 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 70 The calling.** p
fca0: 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 rocedure is resp
fcb0: 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 onsible for dele
fcc0: 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 ting the compile
fcd0: 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a d SQL statement.
fce0: 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ** using [sqlite
fcf0: 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 3_finalize()] af
fd00: 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 ter it has finis
fd10: 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 0a hed with it..**.
fd20: 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b ** On success, [
fd30: 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 SQLITE_OK] is re
fd40: 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 turned. Otherwi
fd50: 73 65 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 se an .** [SQLIT
fd60: 45 5f 45 52 52 4f 52 20 7c 20 65 72 72 6f 72 20 E_ERROR | error
fd70: 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 code] is returne
fd80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c d..**.** The sql
fd90: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
fda0: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 ) and sqlite3_pr
fdb0: 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 epare16_v2() int
fdc0: 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 erfaces are.** r
fdd0: 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 ecommended for a
fde0: 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e ll new programs.
fdf0: 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 The two older i
fe00: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 nterfaces are re
fe10: 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 tained.** for ba
fe20: 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 ckwards compatib
fe30: 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 ility, but their
fe40: 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 use is discoura
fe50: 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22 ged..** In the "
fe60: 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 v2" interfaces,
fe70: 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 the prepared sta
fe80: 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 tement.** that i
fe90: 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 s returned (the
fea0: 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f [sqlite3_stmt] o
feb0: 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 bject) contains
fec0: 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 0a 2a a copy of the .*
fed0: 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 * original SQL t
fee0: 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 ext. This causes
fef0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 the [sqlite3_st
ff00: 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 ep()] interface
ff10: 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 64 to.** behave a d
ff20: 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 77 ifferently in tw
ff30: 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f o ways:.**.** <o
ff40: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 l>.** <li>.** If
ff50: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 the database sc
ff60: 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e hema changes, in
ff70: 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 stead of returni
ff80: 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d ng [SQLITE_SCHEM
ff90: 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 A] as it.** alwa
ffa0: 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b ys used to do, [
ffb0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
ffc0: 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c will automatical
ffd0: 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 ly recompile the
ffe0: 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e SQL.** statemen
fff0: 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e t and try to run
10000 20 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20 74 it again. If t
10010 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 63 68 he schema has ch
10020 61 6e 67 65 64 20 69 6e 20 61 20 77 61 79 0a 2a anged in a way.*
10030 2a 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 * that makes the
10040 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f statement no lo
10050 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c nger valid, [sql
10060 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c ite3_step()] wil
10070 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 l still.** retur
10080 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 n [SQLITE_SCHEMA
10090 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 ]. But unlike t
100a0 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 he legacy behavi
100b0 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 or, [SQLITE_SCHE
100c0 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 MA] is.** now a
100d0 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 fatal error. Ca
100e0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 lling [sqlite3_p
100f0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61 repare_v2()] aga
10100 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 in will not make
10110 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f the.** error go
10120 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 away. Note: us
10130 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 e [sqlite3_errms
10140 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 g()] to find the
10150 20 74 65 78 74 20 6f 66 20 74 68 65 20 70 61 72 text of the par
10160 73 69 6e 67 0a 2a 2a 20 65 72 72 6f 72 20 74 68 sing.** error th
10170 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e at results in an
10180 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d [SQLITE_SCHEMA]
10190 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 return..** </li
101a0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 >.**.** <li>.**
101b0 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 When an error oc
101c0 63 75 72 73 2c 20 0a 2a 2a 20 5b 73 71 6c 69 74 curs, .** [sqlit
101d0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 e3_step()] will
101e0 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 return one of th
101f0 65 20 64 65 74 61 69 6c 65 64 20 0a 2a 2a 20 5b e detailed .** [
10200 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72 SQLITE_ERROR | r
10210 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a esult codes] or.
10220 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 ** [SQLITE_IOERR
10230 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 _READ | extended
10240 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 73 result codes] s
10250 75 63 68 20 61 73 20 64 69 72 65 63 74 6c 79 2e uch as directly.
10260 0a 2a 2a 20 54 68 65 20 6c 65 67 61 63 79 20 62 .** The legacy b
10270 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 ehavior was that
10280 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
10290 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 ] would only ret
102a0 75 72 6e 20 61 20 67 65 6e 65 72 69 63 0a 2a 2a urn a generic.**
102b0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
102c0 72 65 73 75 6c 74 20 63 6f 64 65 20 61 6e 64 20 result code and
102d0 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20 74 you would have t
102e0 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 o make a second
102f0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 call to.** [sqli
10300 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 te3_reset()] in
10310 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 order to find th
10320 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 e underlying cau
10330 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 se of the proble
10340 6d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 22 m..** With the "
10350 76 32 22 20 70 72 65 70 61 72 65 20 69 6e 74 65 v2" prepare inte
10360 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 rfaces, the unde
10370 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f rlying reason fo
10380 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 0a 2a r the error is.*
10390 2a 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 * returned immed
103a0 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e iately..** </li>
103b0 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 .** </ol>.*/.int
103c0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
103d0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
103e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 /* D
103f0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a atabase handle *
10400 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
10410 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 zSql, /* S
10420 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 QL statement, UT
10430 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 F-8 encoded */.
10440 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 int nByte,
10450 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 /* Maxi
10460 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 mum length of zS
10470 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a ql in bytes. */.
10480 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a sqlite3_stmt *
10490 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 *ppStmt, /* OUT
104a0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 : Statement hand
104b0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 le */. const ch
104c0 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 ar **pzTail
104d0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 /* OUT: Pointer
104e0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f to unused portio
104f0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a n of zSql */.);.
10500 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 int sqlite3_prep
10510 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 are_v2(. sqlite
10520 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
10530 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 /* Database ha
10540 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
10550 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 char *zSql,
10560 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 /* SQL stateme
10570 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 nt, UTF-8 encode
10580 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 d */. int nByte
10590 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
105a0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 * Maximum length
105b0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 of zSql in byte
105c0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f s. */. sqlite3_
105d0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 stmt **ppStmt,
105e0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e /* OUT: Statemen
105f0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f t handle */. co
10600 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 nst char **pzTai
10610 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f l /* OUT: Po
10620 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 inter to unused
10630 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 portion of zSql
10640 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 */.);.int sqlite
10650 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 3_prepare16(. s
10660 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
10670 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
10680 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 se handle */. c
10690 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c onst void *zSql,
106a0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 /* SQL st
106b0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 atement, UTF-16
106c0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 encoded */. int
106d0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 nByte,
106e0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 /* Maximum
106f0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 length of zSql i
10700 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 n bytes. */. sq
10710 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 lite3_stmt **ppS
10720 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 tmt, /* OUT: St
10730 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a atement handle *
10740 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a /. const void *
10750 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f *pzTail /* O
10760 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 UT: Pointer to u
10770 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 nused portion of
10780 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 zSql */.);.int
10790 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
107a0 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 6_v2(. sqlite3
107b0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
107c0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 /* Database hand
107d0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f le */. const vo
107e0 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 id *zSql,
107f0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 /* SQL statement
10800 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 , UTF-16 encoded
10810 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c */. int nByte,
10820 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
10830 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 Maximum length
10840 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 of zSql in bytes
10850 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 . */. sqlite3_s
10860 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f tmt **ppStmt, /
10870 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 * OUT: Statement
10880 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
10890 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c st void **pzTail
108a0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 /* OUT: Poi
108b0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 nter to unused p
108c0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a ortion of zSql *
108d0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.);../*.** CAPI
108e0 33 52 45 46 3a 20 20 44 79 6e 61 6d 69 63 61 6c 3REF: Dynamical
108f0 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f ly Typed Value O
10900 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 bject.**.** SQLi
10910 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 te uses dynamic
10920 74 79 70 69 6e 67 20 66 6f 72 20 74 68 65 20 76 typing for the v
10930 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e alues it stores.
10940 20 20 56 61 6c 75 65 73 20 63 61 6e 20 0a 2a 2a Values can .**
10950 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c be integers, fl
10960 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c oating point val
10970 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c ues, strings, BL
10980 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 20 20 57 OBs, or NULL. W
10990 68 65 6e 0a 2a 2a 20 70 61 73 73 69 6e 67 20 61 hen.** passing a
109a0 72 6f 75 6e 64 20 76 61 6c 75 65 73 20 69 6e 74 round values int
109b0 65 72 6e 61 6c 6c 79 2c 20 65 61 63 68 20 76 61 ernally, each va
109c0 6c 75 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 lue is represent
109d0 65 64 20 61 73 0a 2a 2a 20 61 6e 20 69 6e 73 74 ed as.** an inst
109e0 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 ance of the sqli
109f0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
10a00 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
10a10 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f uct Mem sqlite3_
10a20 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 value;../*.** CA
10a30 50 49 33 52 45 46 3a 20 20 53 51 4c 20 46 75 6e PI3REF: SQL Fun
10a40 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 ction Context Ob
10a50 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 ject.**.** The c
10a60 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 ontext in which
10a70 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 an SQL function
10a80 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 executes is stor
10a90 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 ed in an.** sqli
10aa0 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 te3_context obje
10ab0 63 74 2e 20 20 41 20 70 6f 69 6e 74 65 72 20 74 ct. A pointer t
10ac0 6f 20 73 75 63 68 20 61 6e 20 6f 62 6a 65 63 74 o such an object
10ad0 20 69 73 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 is the.** first
10ae0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 75 73 parameter to us
10af0 65 72 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 er-defined SQL f
10b00 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2f 0a 74 79 70 unctions..*/.typ
10b10 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
10b20 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 te3_context sqli
10b30 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a te3_context;../*
10b40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 42 .** CAPI3REF: B
10b50 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f inding Values To
10b60 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d Prepared Statem
10b70 65 6e 74 73 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 ents.**.** In th
10b80 65 20 53 51 4c 20 73 74 72 69 6e 67 73 20 69 6e e SQL strings in
10b90 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f put to [sqlite3_
10ba0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e prepare_v2()] an
10bb0 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a d its variants,.
10bc0 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6c ** one or more l
10bd0 69 74 65 72 61 6c 73 20 63 61 6e 20 62 65 20 72 iterals can be r
10be0 65 70 6c 61 63 65 20 62 79 20 61 20 70 61 72 61 eplace by a para
10bf0 6d 65 74 65 72 20 69 6e 20 6f 6e 65 20 6f 66 20 meter in one of
10c00 74 68 65 73 65 0a 2a 2a 20 66 6f 72 6d 73 3a 0a these.** forms:.
10c10 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
10c20 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f i> ?.** <li> ?
10c30 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 41 41 NNN.** <li> :AA
10c40 41 0a 2a 2a 20 3c 6c 69 3e 20 20 40 41 41 41 0a A.** <li> @AAA.
10c50 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a ** <li> $VVV.**
10c60 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 </ul>.**.** In
10c70 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 66 6f the parameter fo
10c80 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 rms shown above
10c90 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65 NNN is an intege
10ca0 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 41 41 r literal,.** AA
10cb0 41 20 69 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d A is an alphanum
10cc0 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 20 eric identifier
10cd0 61 6e 64 20 56 56 56 20 69 73 20 61 20 76 61 72 and VVV is a var
10ce0 69 61 62 6c 65 20 6e 61 6d 65 20 61 63 63 6f 72 iable name accor
10cf0 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 73 ding.** to the s
10d00 79 6e 74 61 78 20 72 75 6c 65 73 20 6f 66 20 74 yntax rules of t
10d10 68 65 20 54 43 4c 20 70 72 6f 67 72 61 6d 6d 69 he TCL programmi
10d20 6e 67 20 6c 61 6e 67 75 61 67 65 2e 0a 2a 2a 20 ng language..**
10d30 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 The values of th
10d40 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 20 28 ese parameters (
10d50 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 also called "hos
10d60 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 t parameter name
10d70 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 s").** can be se
10d80 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 t using the sqli
10d90 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
10da0 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 tines defined he
10db0 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 re..**.** The fi
10dc0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
10dd0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 the sqlite3_bind
10de0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 6c _*() routines al
10df0 77 61 79 73 20 69 73 20 61 20 70 6f 69 6e 74 65 ways is a pointe
10e00 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c r.** to the [sql
10e10 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 ite3_stmt] objec
10e20 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 t returned from
10e30 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
10e40 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 69 74 73 _v2()] or.** its
10e50 20 76 61 72 69 61 6e 74 73 2e 20 20 54 68 65 20 variants. The
10e60 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 second.** argume
10e70 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 nt is the index
10e80 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 of the parameter
10e90 20 74 6f 20 62 65 20 73 65 74 2e 20 20 54 68 65 to be set. The
10ea0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
10eb0 20 68 61 73 0a 2a 2a 20 61 6e 20 69 6e 64 65 78 has.** an index
10ec0 20 6f 66 20 31 2e 20 57 68 65 6e 20 74 68 65 20 of 1. When the
10ed0 73 61 6d 65 20 6e 61 6d 65 64 20 70 61 72 61 6d same named param
10ee0 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 eter is used mor
10ef0 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 e than once, sec
10f00 6f 6e 64 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 ond.** and subse
10f10 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 quent.** occurre
10f20 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 nces have the sa
10f30 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 me index as the
10f40 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 first occurrence
10f50 2e 20 20 54 68 65 20 69 6e 64 65 78 20 66 6f 72 . The index for
10f60 0a 2a 2a 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 .** named parame
10f70 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b ters can be look
10f80 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a ed up using the.
10f90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
10fa0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 _parameter_name(
10fb0 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 )] API if desire
10fc0 64 2e 20 20 54 68 65 20 69 6e 64 65 78 20 66 6f d. The index fo
10fd0 72 20 22 3f 4e 4e 4e 22 0a 2a 2a 20 70 61 72 61 r "?NNN".** para
10fe0 6d 65 74 65 73 20 69 73 20 74 68 65 20 76 61 6c metes is the val
10ff0 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 ue of NNN..** Th
11000 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 e NNN value must
11010 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e be between 1 an
11020 64 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 d the compile-ti
11030 6d 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 me.** parameter
11040 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49 41 SQLITE_MAX_VARIA
11050 42 4c 45 5f 4e 55 4d 42 45 52 20 28 64 65 66 61 BLE_NUMBER (defa
11060 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e ult value: 999).
11070 0a 2a 2a 20 53 65 65 20 3c 61 20 68 72 65 66 3d .** See <a href=
11080 22 6c 69 6d 69 74 73 2e 68 74 6d 6c 22 3e 6c 69 "limits.html">li
11090 6d 69 74 73 2e 68 74 6d 6c 3c 2f 61 3e 20 66 6f mits.html</a> fo
110a0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 r additional inf
110b0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 ormation..**.**
110c0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 The third argume
110d0 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 nt is the value
110e0 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 to bind to the p
110f0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 arameter..**.**
11100 49 6e 20 74 68 6f 73 65 0a 2a 2a 20 72 6f 75 74 In those.** rout
11110 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 ines that have a
11120 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 fourth argument
11130 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 , its value is t
11140 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
11150 65 73 0a 2a 2a 20 69 6e 20 74 68 65 20 70 61 72 es.** in the par
11160 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 ameter. To be c
11170 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 lear: the value
11180 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 is the number of
11190 20 62 79 74 65 73 20 69 6e 20 74 68 65 0a 2a 2a bytes in the.**
111a0 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 string, not the
111b0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 number of chara
111c0 63 74 65 72 73 2e 20 20 54 68 65 20 6e 75 6d 62 cters. The numb
111d0 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 64 er.** of bytes d
111e0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 oes not include
111f0 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 the zero-termina
11200 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64 20 6f tor at the end o
11210 66 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 49 66 f strings..** If
11220 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
11230 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 meter is negativ
11240 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 e, the length of
11250 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a the string is.*
11260 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 * number of byte
11270 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 s up to the firs
11280 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f t zero terminato
11290 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 r..**.** The fif
112a0 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 th argument to s
112b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
112c0 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 (), sqlite3_bind
112d0 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 _text(), and.**
112e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
112f0 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72 t16() is a destr
11300 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 uctor used to di
11310 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f spose of the BLO
11320 42 20 6f 72 0a 2a 2a 20 74 65 78 74 20 61 66 74 B or.** text aft
11330 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 er SQLite has fi
11340 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 nished with it.
11350 20 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 If the fifth ar
11360 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a gument is the.**
11370 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b special value [
11380 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 SQLITE_STATIC],
11390 74 68 65 6e 20 74 68 65 20 6c 69 62 72 61 72 79 then the library
113a0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 assumes that th
113b0 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a e information.**
113c0 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 is in static, u
113d0 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 nmanaged space a
113e0 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 nd does not need
113f0 20 74 6f 20 62 65 20 66 72 65 65 64 2e 20 20 49 to be freed. I
11400 66 20 74 68 65 0a 2a 2a 20 66 69 66 74 68 20 61 f the.** fifth a
11410 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 rgument has the
11420 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 value [SQLITE_TR
11430 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 20 53 ANSIENT], then S
11440 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 0a QLite makes its.
11450 2a 2a 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 ** own private c
11460 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 opy of the data
11470 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 immediately, bef
11480 6f 72 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f ore the sqlite3_
11490 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 72 6f 75 74 bind_*().** rout
114a0 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a ine returns..**.
114b0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 ** The sqlite3_b
114c0 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 ind_zeroblob() r
114d0 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 outine binds a B
114e0 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 6e 20 LOB of length n
114f0 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 that.** is fille
11500 64 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 d with zeros. A
11510 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 zeroblob uses a
11520 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 fixed amount of
11530 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 memory.** (just
11540 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 an integer to h
11550 6f 6c 64 20 69 74 20 73 69 7a 65 29 20 77 68 69 old it size) whi
11560 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 le it is being p
11570 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 rocessed..** Zer
11580 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e oblobs are inten
11590 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 ded to serve as
115a0 70 6c 61 63 65 2d 68 6f 6c 64 65 72 73 20 66 6f place-holders fo
115b0 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a r BLOBs whose.**
115c0 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 content is late
115d0 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 20 r written using
115e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f .** [sqlite3_blo
115f0 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 b_open | increme
11600 6e 74 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 nt BLOB I/O] rou
11610 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tines..**.** The
11620 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 sqlite3_bind_*(
11630 29 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 ) routines must
11640 62 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 0a be called after.
11650 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
11660 61 72 65 5f 76 32 28 29 5d 20 28 61 6e 64 20 69 are_v2()] (and i
11670 74 73 20 76 61 72 69 61 6e 74 73 29 20 6f 72 20 ts variants) or
11680 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
11690 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20 ] and.** before
116a0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
116b0 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20 61 72 ..** Bindings ar
116c0 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 e not cleared by
116d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 the [sqlite3_re
116e0 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a set()] routine..
116f0 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d ** Unbound param
11700 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 eters are interp
11710 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a reted as NULL..*
11720 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
11730 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 nes return [SQLI
11740 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 TE_OK] on succes
11750 73 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 63 6f s or an error co
11760 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e de if.** anythin
11770 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b g goes wrong. [
11780 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 SQLITE_RANGE] is
11790 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 returned if the
117a0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e parameter.** in
117b0 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 dex is out of ra
117c0 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f nge. [SQLITE_NO
117d0 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 MEM] is returned
117e0 20 69 66 20 6d 61 6c 6c 6f 63 20 66 61 69 6c 73 if malloc fails
117f0 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 ..** [SQLITE_MIS
11800 55 53 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 USE] is returned
11810 20 69 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e if these routin
11820 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 6f 6e es are called on
11830 20 61 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 a virtual.** ma
11840 63 68 69 6e 65 20 74 68 61 74 20 69 73 20 74 68 chine that is th
11850 65 20 77 72 6f 6e 67 20 73 74 61 74 65 20 6f 72 e wrong state or
11860 20 77 68 69 63 68 20 68 61 73 20 61 6c 72 65 61 which has alrea
11870 64 79 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 dy been finalize
11880 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 d..*/.int sqlite
11890 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 3_bind_blob(sqli
118a0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
118b0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
118c0 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 n, void(*)(void
118d0 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 *));.int sqlite3
118e0 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c _bind_double(sql
118f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
11900 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 double);.int sq
11910 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 lite3_bind_int(s
11920 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
11930 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c t, int);.int sql
11940 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 ite3_bind_int64(
11950 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
11960 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 nt, sqlite3_int6
11970 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 4);.int sqlite3_
11980 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 bind_null(sqlite
11990 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 3_stmt*, int);.i
119a0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
119b0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d text(sqlite3_stm
119c0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 t*, int, const c
119d0 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 har*, int n, voi
119e0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e d(*)(void*));.in
119f0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 t sqlite3_bind_t
11a00 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ext16(sqlite3_st
11a10 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 mt*, int, const
11a20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 void*, int, void
11a30 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 (*)(void*));.int
11a40 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 sqlite3_bind_va
11a50 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lue(sqlite3_stmt
11a60 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 *, int, const sq
11a70 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 lite3_value*);.i
11a80 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
11a90 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 zeroblob(sqlite3
11aa0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 _stmt*, int, int
11ab0 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 n);../*.** CAPI
11ac0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 3REF: Number Of
11ad0 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 73 0a Host Parameters.
11ae0 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 **.** Return the
11af0 20 6c 61 72 67 65 73 74 20 68 6f 73 74 20 70 61 largest host pa
11b00 72 61 6d 65 74 65 72 20 69 6e 64 65 78 20 69 6e rameter index in
11b10 20 74 68 65 20 70 72 65 63 6f 6d 70 69 6c 65 64 the precompiled
11b20 20 73 74 61 74 65 6d 65 6e 74 20 67 69 76 65 6e statement given
11b30 0a 2a 2a 20 61 73 20 74 68 65 20 61 72 67 75 6d .** as the argum
11b40 65 6e 74 2e 20 20 57 68 65 6e 20 74 68 65 20 68 ent. When the h
11b50 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 61 ost parameters a
11b60 72 65 20 6f 66 20 74 68 65 20 66 6f 72 6d 73 20 re of the forms
11b70 6c 69 6b 65 20 22 3a 41 41 41 22 0a 2a 2a 20 6f like ":AAA".** o
11b80 72 20 22 3f 22 2c 20 74 68 65 6e 20 74 68 65 79 r "?", then they
11b90 20 61 72 65 20 61 73 73 69 67 6e 65 64 20 73 65 are assigned se
11ba0 71 75 65 6e 74 69 61 6c 20 69 6e 63 72 65 61 73 quential increas
11bb0 69 6e 67 20 6e 75 6d 62 65 72 73 20 62 65 67 69 ing numbers begi
11bc0 6e 6e 69 6e 67 0a 2a 2a 20 77 69 74 68 20 6f 6e nning.** with on
11bd0 65 2c 20 73 6f 20 74 68 65 20 76 61 6c 75 65 20 e, so the value
11be0 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 returned is the
11bf0 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 number of parame
11c00 74 65 72 73 2e 20 20 48 6f 77 65 76 65 72 0a 2a ters. However.*
11c10 2a 20 69 66 20 74 68 65 20 73 61 6d 65 20 68 6f * if the same ho
11c20 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d st parameter nam
11c30 65 20 69 73 20 75 73 65 64 20 6d 75 6c 74 69 70 e is used multip
11c40 6c 65 20 74 69 6d 65 73 2c 20 65 61 63 68 20 6f le times, each o
11c50 63 63 75 72 72 61 6e 63 65 0a 2a 2a 20 69 73 20 ccurrance.** is
11c60 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 6e given the same n
11c70 75 6d 62 65 72 2c 20 73 6f 20 74 68 65 20 76 61 umber, so the va
11c80 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 6e 20 lue returned in
11c90 74 68 61 74 20 63 61 73 65 20 69 73 20 74 68 65 that case is the
11ca0 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 75 6e number.** of un
11cb0 69 71 75 65 20 68 6f 73 74 20 70 61 72 61 6d 65 ique host parame
11cc0 74 65 72 20 6e 61 6d 65 73 2e 20 20 49 66 20 68 ter names. If h
11cd0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 6f ost parameters o
11ce0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e f the form "?NNN
11cf0 22 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 28 77 ".** are used (w
11d00 68 65 72 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69 here NNN is an i
11d10 6e 74 65 67 65 72 29 20 74 68 65 6e 20 74 68 65 nteger) then the
11d20 72 65 20 6d 69 67 68 74 20 62 65 20 67 61 70 73 re might be gaps
11d30 20 69 6e 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 in the.** numbe
11d40 72 69 6e 67 20 61 6e 64 20 74 68 65 20 76 61 6c ring and the val
11d50 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 ue returned by t
11d60 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 his interface is
11d70 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 the index of th
11d80 65 0a 2a 2a 20 68 6f 73 74 20 70 61 72 61 6d 65 e.** host parame
11d90 74 65 72 20 77 69 74 68 20 74 68 65 20 6c 61 72 ter with the lar
11da0 67 65 73 74 20 69 6e 64 65 78 20 76 61 6c 75 65 gest index value
11db0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 70 ..**.** The prep
11dc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6d ared statement m
11dd0 75 73 74 20 6e 6f 74 20 6e 6f 74 20 62 65 20 5b ust not not be [
11de0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
11df0 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 0a 2a 2a | finalized].**
11e00 20 70 72 69 6f 72 20 74 6f 20 74 68 69 73 20 72 prior to this r
11e10 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 6e 69 6e outine returnnin
11e20 67 2e 20 20 4f 74 68 65 72 77 69 73 65 20 74 68 g. Otherwise th
11e30 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e e results are un
11e40 64 65 66 69 6e 65 64 0a 2a 2a 20 61 6e 64 20 70 defined.** and p
11e50 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 robably undesira
11e60 62 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ble..*/.int sqli
11e70 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
11e80 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 er_count(sqlite3
11e90 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 _stmt*);../*.**
11ea0 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f CAPI3REF: Name O
11eb0 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 f A Host Paramet
11ec0 65 72 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f er.**.** This ro
11ed0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 utine returns a
11ee0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e pointer to the n
11ef0 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74 68 20 ame of the n-th
11f00 70 61 72 61 6d 65 74 65 72 20 69 6e 20 61 20 0a parameter in a .
11f10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 ** [sqlite3_stmt
11f20 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 | prepared stat
11f30 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 48 6f 73 74 20 ement]..** Host
11f40 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 parameters of th
11f50 65 20 66 6f 72 6d 20 22 3a 41 41 41 22 20 6f 72 e form ":AAA" or
11f60 20 22 40 41 41 41 22 20 6f 72 20 22 24 56 56 56 "@AAA" or "$VVV
11f70 22 20 68 61 76 65 20 61 20 6e 61 6d 65 0a 2a 2a " have a name.**
11f80 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 which is the st
11f90 72 69 6e 67 20 22 3a 41 41 41 22 20 6f 72 20 22 ring ":AAA" or "
11fa0 40 41 41 41 22 20 6f 72 20 22 24 56 56 56 22 2e @AAA" or "$VVV".
11fb0 20 20 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 .** In other w
11fc0 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 ords, the initia
11fd0 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 l ":" or "$" or
11fe0 22 40 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 "@".** is includ
11ff0 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 ed as part of th
12000 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d e name..** Param
12010 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 eters of the for
12020 6d 20 22 3f 22 20 6f 72 20 22 3f 4e 4e 4e 22 20 m "?" or "?NNN"
12030 68 61 76 65 20 6e 6f 20 6e 61 6d 65 2e 0a 2a 2a have no name..**
12040 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 62 6f .** The first bo
12050 75 6e 64 20 70 61 72 61 6d 65 74 65 72 20 68 61 und parameter ha
12060 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c s an index of 1,
12070 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 not 0..**.** If
12080 20 74 68 65 20 76 61 6c 75 65 20 6e 20 69 73 20 the value n is
12090 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 out of range or
120a0 69 66 20 74 68 65 20 6e 2d 74 68 20 70 61 72 61 if the n-th para
120b0 6d 65 74 65 72 20 69 73 20 6e 61 6d 65 6c 65 73 meter is nameles
120c0 73 2c 0a 2a 2a 20 74 68 65 6e 20 4e 55 4c 4c 20 s,.** then NULL
120d0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 is returned. Th
120e0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e e returned strin
120f0 67 20 69 73 20 61 6c 77 61 79 73 20 69 6e 20 74 g is always in t
12100 68 65 0a 2a 2a 20 55 54 46 2d 38 20 65 6e 63 6f he.** UTF-8 enco
12110 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 ding even if the
12120 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 named parameter
12130 20 77 61 73 20 6f 72 69 67 69 6e 61 6c 6c 79 20 was originally
12140 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 61 73 20 specified.** as
12150 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 UTF-16 in [sqlit
12160 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 e3_prepare16()]
12170 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 or [sqlite3_prep
12180 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a are16_v2()]..*/.
12190 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 const char *sqli
121a0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
121b0 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f er_name(sqlite3_
121c0 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a stmt*, int);../*
121d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e .** CAPI3REF: In
121e0 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 dex Of A Paramet
121f0 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 er With A Given
12200 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 Name.**.** This
12210 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
12220 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 20 68 the index of a h
12230 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 77 69 ost parameter wi
12240 74 68 20 74 68 65 20 67 69 76 65 6e 20 6e 61 6d th the given nam
12250 65 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6d e..** The name m
12260 75 73 74 20 6d 61 74 63 68 20 65 78 61 63 74 6c ust match exactl
12270 79 2e 20 20 49 66 20 6e 6f 20 70 61 72 61 6d 65 y. If no parame
12280 74 65 72 20 77 69 74 68 20 74 68 65 20 67 69 76 ter with the giv
12290 65 6e 20 6e 61 6d 65 20 69 73 20 0a 2a 2a 20 66 en name is .** f
122a0 6f 75 6e 64 2c 20 72 65 74 75 72 6e 20 30 2e 20 ound, return 0.
122b0 20 50 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 Parameter names
122c0 20 6d 75 73 74 20 62 65 20 55 54 46 38 2e 0a 2a must be UTF8..*
122d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 /.int sqlite3_bi
122e0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 nd_parameter_ind
122f0 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ex(sqlite3_stmt*
12300 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
12310 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ame);../*.** CAP
12320 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c I3REF: Reset All
12330 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 Bindings On A P
12340 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e repared Statemen
12350 74 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 t.**.** Contrary
12360 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f to the intuitio
12370 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 n of many, [sqli
12380 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 te3_reset()] doe
12390 73 20 6e 6f 74 0a 2a 2a 20 72 65 73 65 74 20 74 s not.** reset t
123a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 he [sqlite3_bind
123b0 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 _blob | bindings
123c0 5d 20 6f 6e 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 ] on a .** [sqli
123d0 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 te3_stmt | prepa
123e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 red statement].
123f0 20 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e Use this routin
12400 65 20 74 6f 0a 2a 2a 20 72 65 73 65 74 20 61 6c e to.** reset al
12410 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 l host parameter
12420 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e s to NULL..*/.in
12430 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f t sqlite3_clear_
12440 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 bindings(sqlite3
12450 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 _stmt*);../*.**
12460 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 CAPI3REF: Number
12470 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 Of Columns In A
12480 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a Result Set.**.*
12490 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d * Return the num
124a0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 ber of columns i
124b0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 n the result set
124c0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 returned by the
124d0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 .** [sqlite3_st
124e0 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51 mt | compiled SQ
124f0 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68 L statement]. Th
12500 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 is routine retur
12510 6e 73 20 30 0a 2a 2a 20 69 66 20 70 53 74 6d 74 ns 0.** if pStmt
12520 20 69 73 20 61 6e 20 53 51 4c 20 73 74 61 74 65 is an SQL state
12530 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e ment that does n
12540 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 ot return data (
12550 66 6f 72 20 0a 2a 2a 20 65 78 61 6d 70 6c 65 20 for .** example
12560 61 6e 20 55 50 44 41 54 45 29 2e 0a 2a 2f 0a 69 an UPDATE)..*/.i
12570 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nt sqlite3_colum
12580 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f n_count(sqlite3_
12590 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f stmt *pStmt);../
125a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
125b0 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 olumn Names In A
125c0 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a Result Set.**.*
125d0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
125e0 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 return the name
125f0 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 assigned to a p
12600 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e articular column
12610 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c .** in the resul
12620 74 20 73 65 74 20 6f 66 20 61 20 53 45 4c 45 43 t set of a SELEC
12630 54 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 T statement. Th
12640 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
12650 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 _name().** inter
12660 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 face returns a p
12670 6f 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46 38 ointer to a UTF8
12680 20 73 74 72 69 6e 67 20 61 6e 64 20 73 71 6c 69 string and sqli
12690 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 te3_column_name1
126a0 36 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 6().** returns a
126b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 55 54 pointer to a UT
126c0 46 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 F16 string. The
126d0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
126e0 20 69 73 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 is the.** [sqli
126f0 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 te3_stmt | prepa
12700 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 red statement] t
12710 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 hat implements t
12720 68 65 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d he SELECT statem
12730 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f ent..** The seco
12740 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
12750 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 the column numbe
12760 72 2e 20 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73 r. The left-mos
12770 74 20 63 6f 6c 75 6d 6e 20 69 73 0a 2a 2a 20 6e t column is.** n
12780 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 umber 0..**.** T
12790 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 he returned stri
127a0 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 ng pointer is va
127b0 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 lid until either
127c0 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 the .** [sqlite
127d0 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 3_stmt | prepare
127e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 d statement] is
127f0 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 destroyed by [sq
12800 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
12810 5d 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 ].** or until th
12820 65 20 6e 65 78 74 20 63 61 6c 6c 20 73 71 6c 69 e next call sqli
12830 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 te3_column_name(
12840 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c ) or sqlite3_col
12850 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a 2a 20 umn_name16().**
12860 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 on the same colu
12870 6d 6e 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 mn..*/.const cha
12880 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d r *sqlite3_colum
12890 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 n_name(sqlite3_s
128a0 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f tmt*, int N);.co
128b0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
128c0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 3_column_name16(
128d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
128e0 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 nt N);../*.** CA
128f0 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f PI3REF: Source O
12900 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 f Data In A Quer
12910 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 54 y Result.**.** T
12920 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 hese routines pr
12930 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f ovide a means to
12940 20 64 65 74 65 72 6d 69 6e 65 20 77 68 61 74 20 determine what
12950 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a column of what.*
12960 2a 20 74 61 62 6c 65 20 69 6e 20 77 68 69 63 68 * table in which
12970 20 64 61 74 61 62 61 73 65 20 61 20 72 65 73 75 database a resu
12980 6c 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 lt of a SELECT s
12990 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66 tatement comes f
129a0 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 rom..** The name
129b0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
129c0 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c or table or col
129d0 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 umn can be retur
129e0 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 ned as.** either
129f0 20 61 20 55 54 46 38 20 6f 72 20 55 54 46 31 36 a UTF8 or UTF16
12a00 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 string. The _d
12a10 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 atabase_ routine
12a20 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 s return.** the
12a30 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 database name, t
12a40 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 he _table_ routi
12a50 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 nes return the t
12a60 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a able name, and.*
12a70 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f * the origin_ ro
12a80 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 utines return th
12a90 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a e column name..*
12aa0 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 * The returned s
12ab0 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 tring is valid u
12ac0 6e 74 69 6c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c ntil.** the [sql
12ad0 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 ite3_stmt | prep
12ae0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
12af0 69 73 20 64 65 73 74 72 6f 79 65 64 20 75 73 69 is destroyed usi
12b00 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 ng.** [sqlite3_f
12b10 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e inalize()] or un
12b20 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 til the same inf
12b30 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 ormation is requ
12b40 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 ested.** again i
12b50 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e n a different en
12b60 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 coding..**.** Th
12b70 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 e names returned
12b80 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 are the origina
12b90 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d l un-aliased nam
12ba0 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 es of the.** dat
12bb0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e abase, table, an
12bc0 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 d column..**.**
12bd0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
12be0 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 nt to the follow
12bf0 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61 20 0a ing calls is a .
12c00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 ** [sqlite3_stmt
12c10 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 | compiled SQL
12c20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 statement]..** T
12c30 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 hese functions r
12c40 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f eturn informatio
12c50 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 n about the Nth
12c60 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 column returned
12c70 62 79 20 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 by .** the state
12c80 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 ment, where N is
12c90 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 the second func
12ca0 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a tion argument..*
12cb0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74 68 20 *.** If the Nth
12cc0 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 column returned
12cd0 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 by the statement
12ce0 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f is an expressio
12cf0 6e 0a 2a 2a 20 6f 72 20 73 75 62 71 75 65 72 79 n.** or subquery
12d00 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f and is not a co
12d10 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e lumn value, then
12d20 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 all of these fu
12d30 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 nctions.** retur
12d40 6e 20 4e 55 4c 4c 2e 20 4f 74 68 65 72 77 69 73 n NULL. Otherwis
12d50 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 e, they return t
12d60 68 65 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 he .** name of t
12d70 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 he attached data
12d80 62 61 73 65 2c 20 74 61 62 6c 65 20 61 6e 64 20 base, table and
12d90 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 column that quer
12da0 79 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 y result.** colu
12db0 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 mn was extracted
12dc0 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 from..**.** As
12dd0 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 with all other S
12de0 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 QLite APIs, thos
12df0 65 20 70 6f 73 74 66 69 78 65 64 20 77 69 74 68 e postfixed with
12e00 20 22 31 36 22 20 72 65 74 75 72 6e 20 55 54 46 "16" return UTF
12e10 2d 31 36 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 73 -16.** encoded s
12e20 74 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 trings, the othe
12e30 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 r functions retu
12e40 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 rn UTF-8..**.**
12e50 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f These APIs are o
12e60 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 nly available if
12e70 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 the library was
12e80 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 compiled with t
12e90 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e he .** SQLITE_EN
12ea0 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 ABLE_COLUMN_META
12eb0 44 41 54 41 20 70 72 65 70 72 6f 63 65 73 73 6f DATA preprocesso
12ec0 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 r symbol defined
12ed0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 ..*/.const char
12ee0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
12ef0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 database_name(sq
12f00 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
12f10 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 ;.const void *sq
12f20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 lite3_column_dat
12f30 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c abase_name16(sql
12f40 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
12f50 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
12f60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c ite3_column_tabl
12f70 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 e_name(sqlite3_s
12f80 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 tmt*,int);.const
12f90 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 void *sqlite3_c
12fa0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 olumn_table_name
12fb0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
12fc0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 ,int);.const cha
12fd0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d r *sqlite3_colum
12fe0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 n_origin_name(sq
12ff0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
13000 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 ;.const void *sq
13010 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 lite3_column_ori
13020 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 gin_name16(sqlit
13030 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a e3_stmt*,int);..
13040 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
13050 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 Declared Datatyp
13060 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 e Of A Query Res
13070 75 6c 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 ult.**.** The fi
13080 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 rst parameter is
13090 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 a [sqlite3_stmt
130a0 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 | compiled SQL
130b0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 0a 2a 2a 20 statement]. .**
130c0 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e If this statemen
130d0 74 20 69 73 20 61 20 53 45 4c 45 43 54 20 73 74 t is a SELECT st
130e0 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 atement and the
130f0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 Nth column of th
13100 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 e .** returned r
13110 65 73 75 6c 74 20 73 65 74 20 20 6f 66 20 74 68 esult set of th
13120 61 74 20 53 45 4c 45 43 54 20 69 73 20 61 20 74 at SELECT is a t
13130 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 able column (not
13140 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f an.** expressio
13150 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 n or subquery) t
13160 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 hen the declared
13170 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 type of the tab
13180 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 le.** column is
13190 72 65 74 75 72 6e 65 64 2e 20 49 66 20 74 68 65 returned. If the
131a0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 Nth column of t
131b0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 he result set is
131c0 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f an.** expressio
131d0 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 n or subquery, t
131e0 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 hen a NULL point
131f0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a er is returned..
13200 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 ** The returned
13210 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 string is always
13220 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 20 UTF-8 encoded.
13230 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 0a For example, in.
13240 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
13250 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 schema:.**.** CR
13260 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 EATE TABLE t1(c1
13270 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a VARIANT);.**.**
13280 20 41 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 And the followi
13290 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d ng statement com
132a0 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c piled:.**.** SEL
132b0 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 ECT c1 + 1, c1 F
132c0 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 54 68 ROM t1;.**.** Th
132d0 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 en this routine
132e0 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 would return the
132f0 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 string "VARIANT
13300 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 " for the second
13310 0a 2a 2a 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d .** result colum
13320 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 n (i==1), and a
13330 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 NULL pointer for
13340 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c the first resul
13350 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 28 69 3d 3d t column.** (i==
13360 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 0)..**.** SQLite
13370 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 uses dynamic ru
13380 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 n-time typing.
13390 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 So just because
133a0 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 a column.** is d
133b0 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 eclared to conta
133c0 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 in a particular
133d0 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 type does not me
133e0 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 an that the.** d
133f0 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 ata stored in th
13400 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 at column is of
13410 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 the declared typ
13420 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a e. SQLite is.**
13430 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c strongly typed,
13440 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 but the typing
13450 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 is dynamic not s
13460 74 61 74 69 63 2e 20 20 54 79 70 65 0a 2a 2a 20 tatic. Type.**
13470 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 is associated wi
13480 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 th individual va
13490 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 lues, not with t
134a0 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a he containers.**
134b0 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 used to hold th
134c0 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 ose values..*/.c
134d0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
134e0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 e3_column_declty
134f0 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 pe(sqlite3_stmt
13500 2a 2c 20 69 6e 74 20 69 29 3b 0a 63 6f 6e 73 74 *, int i);.const
13510 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 void *sqlite3_c
13520 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 olumn_decltype16
13530 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
13540 6e 74 29 3b 0a 0a 2f 2a 20 0a 2a 2a 20 43 41 50 nt);../* .** CAP
13550 49 33 52 45 46 3a 20 20 45 76 61 6c 75 61 74 65 I3REF: Evaluate
13560 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e An SQL Statemen
13570 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 6e t.**.** After an
13580 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c [sqlite3_stmt |
13590 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 20 SQL statement]
135a0 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 has been prepare
135b0 64 20 77 69 74 68 20 61 20 63 61 6c 6c 0a 2a 2a d with a call.**
135c0 20 74 6f 20 65 69 74 68 65 72 20 5b 73 71 6c 69 to either [sqli
135d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
135e0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 ] or [sqlite3_pr
135f0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 epare16_v2()] or
13600 20 74 6f 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 to one of.** th
13610 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 e legacy interfa
13620 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 ces [sqlite3_pre
13630 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 pare()] or [sqli
13640 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d te3_prepare16()]
13650 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 66 ,.** then this f
13660 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 unction must be
13670 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f called one or mo
13680 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c re times to eval
13690 75 61 74 65 20 74 68 65 20 0a 2a 2a 20 73 74 61 uate the .** sta
136a0 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 tement..**.** Th
136b0 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 e details of the
136c0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 behavior of thi
136d0 73 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 s sqlite3_step()
136e0 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e interface depen
136f0 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 d.** on whether
13700 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 the statement wa
13710 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 s prepared using
13720 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 the newer "v2"
13730 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 interface.** [sq
13740 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
13750 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
13760 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
13770 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 or the older le
13780 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 gacy.** interfac
13790 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 e [sqlite3_prepa
137a0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 re()] and [sqlit
137b0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e e3_prepare16()].
137c0 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 The use of the
137d0 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 .** new "v2" int
137e0 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d erface is recomm
137f0 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 ended for new ap
13800 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 plications but t
13810 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 he legacy.** int
13820 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 erface will cont
13830 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f inue to be suppo
13840 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 rted..**.** In t
13850 68 65 20 6c 61 67 61 63 79 20 69 6e 74 65 72 66 he lagacy interf
13860 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 ace, the return
13870 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 value will be ei
13880 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 ther [SQLITE_BUS
13890 59 5d 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f Y], .** [SQLITE_
138a0 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 DONE], [SQLITE_R
138b0 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 OW], [SQLITE_ERR
138c0 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f OR], or [SQLITE_
138d0 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 MISUSE]..** With
138e0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 the "v2" interf
138f0 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 ace, any of the
13900 6f 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b other [SQLITE_OK
13910 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a | result code].
13920 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f ** or [SQLITE_IO
13930 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e ERR_READ | exten
13940 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d ded result code]
13950 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e might be return
13960 65 64 20 61 73 0a 2a 2a 20 77 65 6c 6c 2e 0a 2a ed as.** well..*
13970 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 *.** [SQLITE_BUS
13980 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 Y] means that th
13990 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e e database engin
139a0 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 e was unable to
139b0 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 acquire the.** d
139c0 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 atabase locks it
139d0 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 needs to do its
139e0 20 6a 6f 62 2e 20 20 49 66 20 74 68 65 20 73 74 job. If the st
139f0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 43 4f 4d atement is a COM
13a00 4d 49 54 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 MIT.** or occurs
13a10 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 outside of an e
13a20 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 xplicit transact
13a30 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 ion, then you ca
13a40 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 n retry the.** s
13a50 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 tatement. If th
13a60 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e e statement is n
13a70 6f 74 20 61 20 43 4f 4d 4d 49 54 20 61 6e 64 20 ot a COMMIT and
13a80 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a occurs within a.
13a90 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e ** explicit tran
13aa0 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 saction then you
13ab0 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b should rollback
13ac0 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e the transaction
13ad0 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 before.** conti
13ae0 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 nuing..**.** [SQ
13af0 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 LITE_DONE] means
13b00 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d that the statem
13b10 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 ent has finished
13b20 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 executing.** su
13b30 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c ccessfully. sql
13b40 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 ite3_step() shou
13b50 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 ld not be called
13b60 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 again on this v
13b70 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e irtual.** machin
13b80 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 e without first
13b90 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 calling [sqlite3
13ba0 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 _reset()] to res
13bb0 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a et the virtual.*
13bc0 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 * machine back t
13bd0 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 o its initial st
13be0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ate..**.** If th
13bf0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
13c00 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 being executed r
13c10 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c eturns any data,
13c20 20 74 68 65 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 then .** [SQLIT
13c30 45 5f 52 4f 57 5d 20 69 73 20 72 65 74 75 72 6e E_ROW] is return
13c40 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e ed each time a n
13c50 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 ew row of data i
13c60 73 20 72 65 61 64 79 0a 2a 2a 20 66 6f 72 20 70 s ready.** for p
13c70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 rocessing by the
13c80 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c caller. The val
13c90 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 ues may be acces
13ca0 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 sed using.** the
13cb0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
13cc0 5f 69 6e 74 20 7c 20 63 6f 6c 75 6d 6e 20 61 63 _int | column ac
13cd0 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e cess functions].
13ce0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 .** sqlite3_step
13cf0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 () is called aga
13d00 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 in to retrieve t
13d10 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 he next row of d
13d20 61 74 61 2e 0a 2a 2a 20 0a 2a 2a 20 5b 53 51 4c ata..** .** [SQL
13d30 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 ITE_ERROR] means
13d40 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 that a run-time
13d50 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 error (such as
13d60 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 a constraint.**
13d70 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f violation) has o
13d80 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 ccurred. sqlite
13d90 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 3_step() should
13da0 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 not be called ag
13db0 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d ain on.** the VM
13dc0 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 . More informati
13dd0 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 on may be found
13de0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 by calling [sqli
13df0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a te3_errmsg()]..*
13e00 2a 20 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 * With the legac
13e10 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d y interface, a m
13e20 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 ore specific err
13e30 6f 72 20 63 6f 64 65 20 28 65 78 61 6d 70 6c 65 or code (example
13e40 3a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 :.** [SQLITE_INT
13e50 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 ERRUPT], [SQLITE
13e60 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 _SCHEMA], [SQLIT
13e70 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 E_CORRUPT], and
13e80 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e so forth).** can
13e90 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 be obtained by
13ea0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 calling [sqlite3
13eb0 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 _reset()] on the
13ec0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d .** [sqlite3_stm
13ed0 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 t | prepared sta
13ee0 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 tement]. In the
13ef0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c "v2" interface,
13f00 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 .** the more spe
13f10 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 cific error code
13f20 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 is returned dir
13f30 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 ectly by sqlite3
13f40 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b _step()..**.** [
13f50 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d SQLITE_MISUSE] m
13f60 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 eans that the th
13f70 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 is routine was c
13f80 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 alled inappropri
13f90 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 ately..** Perhap
13fa0 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 s it was called
13fb0 6f 6e 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 on a [sqlite3_st
13fc0 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 mt | prepared st
13fd0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 atement] that ha
13fe0 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 s.** already bee
13ff0 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c n [sqlite3_final
14000 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d ize | finalized]
14010 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 or on one that
14020 68 61 64 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 had .** previous
14030 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c ly returned [SQL
14040 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 ITE_ERROR] or [S
14050 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 QLITE_DONE]. Or
14060 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 it could.** be
14070 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 the case that th
14080 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 e same database
14090 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 connection is be
140a0 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 ing used by two
140b0 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 or.** more threa
140c0 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d ds at the same m
140d0 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a oment in time..*
140e0 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e *.** <b>Goofy In
140f0 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f terface Alert:</
14100 62 3e 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67 b>.** In the leg
14110 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 0a acy interface, .
14120 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 ** the sqlite3_s
14130 74 65 70 28 29 20 41 50 49 20 61 6c 77 61 79 73 tep() API always
14140 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 returns a gener
14150 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 0a 2a ic error code,.*
14160 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d * [SQLITE_ERROR]
14170 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 , following any
14180 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e error other than
14190 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a [SQLITE_BUSY].*
141a0 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 * and [SQLITE_MI
141b0 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 SUSE]. You must
141c0 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 72 call [sqlite3_r
141d0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 eset()] or.** [s
141e0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
141f0 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 )] in order to f
14200 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 73 ind one of the s
14210 70 65 63 69 66 69 63 0a 2a 2a 20 5b 53 51 4c 49 pecific.** [SQLI
14220 54 45 5f 45 52 52 4f 52 20 7c 20 72 65 73 75 6c TE_ERROR | resul
14230 74 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 t codes] that be
14240 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 tter describes t
14250 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 he error..** We
14260 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 admit that this
14270 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 is a goofy desig
14280 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 n. The problem
14290 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a has been fixed.*
142a0 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 * with the "v2"
142b0 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 interface. If y
142c0 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f ou prepare all o
142d0 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 f your SQL state
142e0 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 ments.** using e
142f0 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 ither [sqlite3_p
14300 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
14310 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
14320 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 16_v2()] instead
14330 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 .** of the legac
14340 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 y [sqlite3_prepa
14350 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 re()] and [sqlit
14360 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c e3_prepare16()],
14370 20 74 68 65 6e 20 74 68 65 20 0a 2a 2a 20 6d 6f then the .** mo
14380 72 65 20 73 70 65 63 69 66 69 63 20 5b 53 51 4c re specific [SQL
14390 49 54 45 5f 45 52 52 4f 52 20 7c 20 72 65 73 75 ITE_ERROR | resu
143a0 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 lt codes] are re
143b0 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a turned directly.
143c0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 ** by sqlite3_st
143d0 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f ep(). The use o
143e0 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 f the "v2" inter
143f0 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e face is recommen
14400 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ded..*/.int sqli
14410 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 te3_step(sqlite3
14420 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 _stmt*);../*.**
14430 43 41 50 49 33 52 45 46 3a 0a 2a 2a 0a 2a 2a 20 CAPI3REF:.**.**
14440 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 Return the numbe
14450 72 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 74 r of values in t
14460 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f he current row o
14470 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 f the result set
14480 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 ..**.** After a
14490 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
144a0 5f 73 74 65 70 28 29 5d 20 74 68 61 74 20 72 65 _step()] that re
144b0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f turns [SQLITE_RO
144c0 57 5d 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 W], this routine
144d0 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 .** will return
144e0 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 61 the same value a
144f0 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 s the [sqlite3_c
14500 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 20 66 olumn_count()] f
14510 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 41 66 74 65 unction..** Afte
14520 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 r [sqlite3_step(
14530 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 )] has returned
14540 61 6e 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d an [SQLITE_DONE]
14550 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c , [SQLITE_BUSY],
14560 20 6f 72 0a 2a 2a 20 61 20 5b 53 51 4c 49 54 45 or.** a [SQLITE
14570 5f 45 52 52 4f 52 20 7c 20 65 72 72 6f 72 20 63 _ERROR | error c
14580 6f 64 65 5d 2c 20 6f 72 20 62 65 66 6f 72 65 20 ode], or before
14590 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
145a0 20 68 61 73 20 62 65 65 6e 20 0a 2a 2a 20 63 61 has been .** ca
145b0 6c 6c 65 64 20 6f 6e 20 74 68 65 20 5b 73 71 6c lled on the [sql
145c0 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 ite3_stmt | prep
145d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
145e0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 74 69 for the first ti
145f0 6d 65 2c 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 me,.** this rout
14600 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f ine returns zero
14610 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
14620 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 _data_count(sqli
14630 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
14640 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
14650 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 F: Fundamental D
14660 61 74 61 74 79 70 65 73 0a 2a 2a 0a 2a 2a 20 45 atatypes.**.** E
14670 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 very value in SQ
14680 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 Lite has one of
14690 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c five fundamental
146a0 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a datatypes:.**.*
146b0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 * <ul>.** <li> 6
146c0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 4-bit signed int
146d0 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d eger.** <li> 64-
146e0 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e bit IEEE floatin
146f0 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a g point number.*
14700 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a * <li> string.**
14710 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c <li> BLOB.** <l
14720 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e i> NULL.** </ul>
14730 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e .**.** These con
14740 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 stants are codes
14750 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f for each of tho
14760 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 se types..**.**
14770 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 Note that the SQ
14780 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 LITE_TEXT consta
14790 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 nt was also used
147a0 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 in SQLite versi
147b0 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f on 2.** for a co
147c0 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 mpletely differe
147d0 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 nt meaning. Sof
147e0 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 tware that links
147f0 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a against both.**
14800 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
14810 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 2 and SQLite ver
14820 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 sion 3 should us
14830 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 6e e SQLITE3_TEXT n
14840 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 ot.** SQLITE_TEX
14850 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 T..*/.#define SQ
14860 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a LITE_INTEGER 1.
14870 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
14880 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e LOAT 2.#defin
14890 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 e SQLITE_BLOB
148a0 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 4.#define SQLI
148b0 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 TE_NULL 5.#i
148c0 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 fdef SQLITE_TEXT
148d0 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f .# undef SQLITE_
148e0 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 TEXT.#else.# def
148f0 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 ine SQLITE_TEXT
14900 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 3.#endif.#de
14910 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 fine SQLITE3_TEX
14920 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 T 3../*.** C
14930 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 73 API3REF: Results
14940 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 Values From A Q
14950 75 65 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 uery.**.** These
14960 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
14970 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f information abo
14980 75 74 20 74 68 65 20 69 6e 66 6f 72 6d 61 74 69 ut the informati
14990 6f 6e 0a 2a 2a 20 69 6e 20 61 20 73 69 6e 67 6c on.** in a singl
149a0 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 e column of the
149b0 63 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20 72 current result r
149c0 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 ow of a query.
149d0 49 6e 20 65 76 65 72 79 0a 2a 2a 20 63 61 73 65 In every.** case
149e0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
149f0 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ent is a pointer
14a00 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c to the .** [sql
14a10 69 74 65 33 5f 73 74 6d 74 20 7c 20 53 51 4c 20 ite3_stmt | SQL
14a20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 statement] that
14a30 69 73 20 62 65 69 6e 67 0a 2a 2a 20 65 76 61 6c is being.** eval
14a40 75 61 74 65 20 28 74 68 65 20 5b 73 71 6c 69 74 uate (the [sqlit
14a50 65 33 5f 73 74 6d 74 2a 5d 20 74 68 61 74 20 77 e3_stmt*] that w
14a60 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d as returned from
14a70 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 .** [sqlite3_pr
14a80 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f epare_v2()] or o
14a90 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e ne of its varian
14aa0 74 73 29 20 61 6e 64 0a 2a 2a 20 74 68 65 20 73 ts) and.** the s
14ab0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 econd argument i
14ac0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 s the index of t
14ad0 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 he column for wh
14ae0 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 ich information
14af0 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 .** should be re
14b00 74 75 72 6e 65 64 2e 20 20 54 68 65 20 6c 65 66 turned. The lef
14b10 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 68 61 t-most column ha
14b20 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 30 2e s an index of 0.
14b30 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 .**.** If the SQ
14b40 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e L statement is n
14b50 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 ot currently poi
14b60 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f nt to a valid ro
14b70 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 w, or if the.**
14b80 74 68 65 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 the column index
14b90 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 is out of range
14ba0 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 , the result is
14bb0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
14bc0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c The sqlite3_col
14bd0 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 umn_type() routi
14be0 6e 65 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b ne returns .** [
14bf0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c SQLITE_INTEGER |
14c00 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 datatype code]
14c10 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 for the initial
14c20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 data type.** of
14c30 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d the result colum
14c40 6e 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 n. The returned
14c50 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 value is one of
14c60 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 [SQLITE_INTEGER
14c70 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c ],.** [SQLITE_FL
14c80 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 OAT], [SQLITE_TE
14c90 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f XT], [SQLITE_BLO
14ca0 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e B], or [SQLITE_N
14cb0 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 ULL]. The value
14cc0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 .** returned by
14cd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
14ce0 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 ype() is only me
14cf0 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 aningful if no t
14d00 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f ype.** conversio
14d10 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 ns have occurred
14d20 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 as described be
14d30 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 low. After a ty
14d40 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a pe conversion,.*
14d50 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 * the value retu
14d60 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
14d70 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 column_type() is
14d80 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 undefined. Fut
14d90 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 ure.** versions
14da0 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 of SQLite may ch
14db0 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f ange the behavio
14dc0 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c r of sqlite3_col
14dd0 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f umn_type().** fo
14de0 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 llowing a type c
14df0 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a onversion..**.**
14e00 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 If the result i
14e10 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d s a BLOB or UTF-
14e20 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 8 string then th
14e30 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
14e40 5f 62 79 74 65 73 28 29 20 0a 2a 2a 20 72 6f 75 _bytes() .** rou
14e50 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 tine returns the
14e60 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
14e70 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 in that BLOB or
14e80 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 74 string..** If t
14e90 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 he result is a U
14ea0 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 TF-16 string, th
14eb0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
14ec0 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 n_bytes() conver
14ed0 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 ts.** the string
14ee0 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 to UTF-8 and th
14ef0 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e en returns the n
14f00 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a umber of bytes..
14f10 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 ** If the result
14f20 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 is a numeric va
14f30 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 lue then sqlite3
14f40 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 _column_bytes()
14f50 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 uses.** [sqlite3
14f60 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 _snprintf()] to
14f70 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c convert that val
14f80 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 ue to a UTF-8 st
14f90 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 ring and returns
14fa0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f .** the number o
14fb0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 f bytes in that
14fc0 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 76 string..** The v
14fd0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 64 6f alue returned do
14fe0 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 es not include t
14ff0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 he zero terminat
15000 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a or at the end.**
15010 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 of the string.
15020 20 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 For clarity: th
15030 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
15040 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
15050 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 f.** bytes in th
15060 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 e string, not th
15070 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 e number of char
15080 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 acters..**.** Th
15090 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
150a0 5f 62 79 74 65 73 31 36 28 29 20 72 6f 75 74 69 _bytes16() routi
150b0 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f ne is similar to
150c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
150d0 62 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c bytes().** but l
150e0 65 61 76 65 73 20 74 68 65 20 72 65 73 75 6c 74 eaves the result
150f0 20 69 6e 20 55 54 46 2d 31 36 20 69 6e 73 74 65 in UTF-16 inste
15100 61 64 20 6f 66 20 55 54 46 2d 38 2e 20 20 0a 2a ad of UTF-8. .*
15110 2a 20 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 * The zero termi
15120 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 nator is not inc
15130 6c 75 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f luded in this co
15140 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 unt..**.** These
15150 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 routines attemp
15160 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 t to convert the
15170 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 value where app
15180 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a ropriate. For.*
15190 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 * example, if th
151a0 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 e internal repre
151b0 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f sentation is FLO
151c0 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 AT and a text re
151d0 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 sult.** is reque
151e0 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 sted, [sqlite3_s
151f0 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 nprintf()] is us
15200 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f ed internally to
15210 20 64 6f 20 74 68 65 20 63 6f 6e 76 65 72 73 69 do the conversi
15220 6f 6e 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 on.** automatica
15230 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 lly. The follow
15240 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c ing table detail
15250 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e s the conversion
15260 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 61 70 s that.** are ap
15270 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c plied:.**.** <bl
15280 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 ockquote>.** <ta
15290 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a ble border="1">.
152a0 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 ** <tr><th> Inte
152b0 72 6e 61 6c 20 3c 74 68 3e 20 52 65 71 75 65 73 rnal <th> Reques
152c0 74 65 64 20 3c 74 68 3e 20 0a 2a 2a 20 3c 74 72 ted <th> .** <tr
152d0 3e 3c 74 68 3e 20 20 54 79 70 65 20 20 20 20 3c ><th> Type <
152e0 74 68 3e 20 20 20 20 54 79 70 65 20 20 20 3c 74 th> Type <t
152f0 68 3e 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a h> Conversion.**
15300 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 .** <tr><td> NU
15310 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 LL <td> INTEG
15320 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 ER <td> Result
15330 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 is 0.** <tr><td
15340 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 > NULL <td>
15350 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 FLOAT <td> R
15360 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 esult is 0.0.**
15370 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 <tr><td> NULL
15380 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 <td> TEXT
15390 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 <td> Result is
153a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 NULL pointer.**
153b0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 <tr><td> NULL
153c0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 <td> BLOB
153d0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 <td> Result is
153e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 NULL pointer.**
153f0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 <tr><td> INTEGER
15400 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 <td> FLOAT
15410 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 <td> Convert fr
15420 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c om integer to fl
15430 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 oat.** <tr><td>
15440 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 INTEGER <td>
15450 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 TEXT <td> ASC
15460 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 II rendering of
15470 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c the integer.** <
15480 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 tr><td> INTEGER
15490 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 <td> BLOB
154a0 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 66 6f 72 <td> Same as for
154b0 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a INTEGER->TEXT.*
154c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 * <tr><td> FLOA
154d0 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 T <td> INTEGER
154e0 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 <td> Convert
154f0 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e from float to in
15500 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 teger.** <tr><td
15510 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 > FLOAT <td>
15520 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 TEXT <td> A
15530 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f SCII rendering o
15540 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c f the float.** <
15550 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 tr><td> FLOAT
15560 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 <td> BLOB
15570 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f <td> Same as FLO
15580 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e AT->TEXT.** <tr>
15590 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 <td> TEXT <t
155a0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 d> INTEGER <td
155b0 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 > Use atoi().**
155c0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 <tr><td> TEXT
155d0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 <td> FLOAT
155e0 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 <td> Use atof()
155f0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 .** <tr><td> TE
15600 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f XT <td> BLO
15610 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 B <td> No cha
15620 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 nge.** <tr><td>
15630 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e BLOB <td> IN
15640 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e TEGER <td> Con
15650 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 vert to TEXT the
15660 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 n use atoi().**
15670 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 <tr><td> BLOB
15680 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 <td> FLOAT
15690 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f <td> Convert to
156a0 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 TEXT then use a
156b0 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 tof().** <tr><td
156c0 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 > BLOB <td>
156d0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 TEXT <td> A
156e0 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e dd a zero termin
156f0 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a ator if needed.*
15700 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f * </table>.** </
15710 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
15720 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 * The table abov
15730 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 e makes referenc
15740 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 e to standard C
15750 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e library function
15760 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 s atoi().** and
15770 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 atof(). SQLite
15780 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 does not really
15790 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 use these functi
157a0 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 ons. It has its
157b0 0a 2a 2a 20 6f 6e 20 65 71 75 61 76 61 6c 65 6e .** on equavalen
157c0 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 t internal routi
157d0 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 nes. The atoi()
157e0 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 and atof() name
157f0 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e s are.** used in
15800 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 the table for b
15810 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 revity and becau
15820 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 se they are fami
15830 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 liar to most.**
15840 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a C programmers..*
15850 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 *.** Note that w
15860 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 hen type convers
15870 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e ions occur, poin
15880 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 ters returned by
15890 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 prior.** calls
158a0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d to sqlite3_colum
158b0 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 n_blob(), sqlite
158c0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 3_column_text(),
158d0 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 and/or.** sqlit
158e0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
158f0 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 () may be invali
15900 64 61 74 65 64 2e 20 0a 2a 2a 20 54 79 70 65 20 dated. .** Type
15910 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 conversions and
15920 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 pointer invalida
15930 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 tions might occu
15940 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c r.** in the foll
15950 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a owing cases:.**.
15960 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 3c ** <ul>.** <li><
15970 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61 6c 20 p> The initial
15980 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f content is a BLO
15990 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f B and sqlite3_co
159a0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 0a 2a 2a 20 lumn_text() .**
159b0 20 20 20 20 20 20 20 20 20 6f 72 20 73 71 6c 69 or sqli
159c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
159d0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 6() is called.
159e0 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f A zero-terminato
159f0 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 r might.**
15a00 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 need to be a
15a10 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 dded to the stri
15a20 6e 67 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a ng.</p></li>.**.
15a30 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 ** <li><p> The
15a40 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 initial content
15a50 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e is UTF-8 text an
15a60 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e d sqlite3_column
15a70 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a _bytes16() or.**
15a80 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 sqlite
15a90 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
15aa0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 ) is called. Th
15ab0 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 e content must b
15ac0 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 e converted.**
15ad0 20 20 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 to UTF-1
15ae0 36 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 6.</p></li>.**.*
15af0 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 * <li><p> The i
15b00 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 nitial content i
15b10 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e s UTF-16 text an
15b20 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e d sqlite3_column
15b30 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 _bytes() or.**
15b40 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f sqlite3_
15b50 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 column_text() is
15b60 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f called. The co
15b70 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f ntent must be co
15b80 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 nverted.**
15b90 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 70 to UTF-8.</p
15ba0 3e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a ></li>.** </ul>.
15bb0 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e **.** Conversion
15bc0 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 s between UTF-16
15bd0 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 be and UTF-16le
15be0 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 are always done
15bf0 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a in place and do.
15c00 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 ** not invalidat
15c10 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 e a prior pointe
15c20 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 r, though of cou
15c30 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 rse the content
15c40 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a of the buffer.**
15c50 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 that the prior
15c60 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 pointer points t
15c70 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e o will have been
15c80 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 modified. Othe
15c90 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f r kinds.** of co
15ca0 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e nversion are don
15cb0 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 e in place when
15cc0 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 it is possible,
15cd0 62 75 74 20 73 6f 6d 65 74 69 6d 65 20 69 74 20 but sometime it
15ce0 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 is.** not possib
15cf0 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 le and in those
15d00 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e cases prior poin
15d10 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 ters are invalid
15d20 61 74 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 ated. .**.** Th
15d30 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 e safest and eas
15d40 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 iest to remember
15d50 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e policy is to in
15d60 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 voke these routi
15d70 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 nes.** in one of
15d80 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 the following w
15d90 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 20 3c 75 6c 3e ays:.**.** <ul>
15da0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 .** <li>sqlite3
15db0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 _column_text() f
15dc0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 ollowed by sqlit
15dd0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
15de0 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 )</li>.** <li>s
15df0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
15e00 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 ob() followed by
15e10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
15e20 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 bytes()</li>.**
15e30 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c <li>sqlite3_col
15e40 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c umn_text16() fol
15e50 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 lowed by sqlite3
15e60 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
15e70 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 2f 75 6c 3e )</li>.** </ul>
15e80 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 .**.** In other
15e90 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c words, you shoul
15ea0 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 d call sqlite3_c
15eb0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 73 71 olumn_text(), sq
15ec0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
15ed0 62 28 29 2c 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 b(),.** or sqlit
15ee0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
15ef0 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 () first to forc
15f00 65 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 e the result int
15f10 6f 20 74 68 65 20 64 65 73 69 72 65 64 0a 2a 2a o the desired.**
15f20 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e format, then in
15f30 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c voke sqlite3_col
15f40 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 20 73 umn_bytes() or s
15f50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
15f60 74 65 73 31 36 28 29 20 74 6f 0a 2a 2a 20 66 69 tes16() to.** fi
15f70 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 nd the size of t
15f80 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e he result. Do n
15f90 6f 74 20 6d 69 78 20 63 61 6c 6c 20 74 6f 20 73 ot mix call to s
15fa0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
15fb0 78 74 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 xt() or.** sqlit
15fc0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 e3_column_blob()
15fd0 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 with calls to s
15fe0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
15ff0 74 65 73 31 36 28 29 2e 20 20 41 6e 64 20 64 6f tes16(). And do
16000 20 6e 6f 74 0a 2a 2a 20 6d 69 78 20 63 61 6c 6c not.** mix call
16010 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c s to sqlite3_col
16020 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 77 69 74 umn_text16() wit
16030 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 h calls to sqlit
16040 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
16050 29 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 )..*/.const void
16060 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
16070 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 _blob(sqlite3_st
16080 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
16090 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 int sqlite3_colu
160a0 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 mn_bytes(sqlite3
160b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
160c0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 );.int sqlite3_c
160d0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 olumn_bytes16(sq
160e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
160f0 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 iCol);.double s
16100 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f qlite3_column_do
16110 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d uble(sqlite3_stm
16120 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 t*, int iCol);.i
16130 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nt sqlite3_colum
16140 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 n_int(sqlite3_st
16150 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
16160 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 sqlite3_int64 sq
16170 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 lite3_column_int
16180 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 64(sqlite3_stmt*
16190 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e , int iCol);.con
161a0 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 st unsigned char
161b0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
161c0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 _text(sqlite3_st
161d0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
161e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
161f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
16200 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
16210 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 int iCol);.int
16220 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
16230 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ype(sqlite3_stmt
16240 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 *, int iCol);.sq
16250 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c lite3_value *sql
16260 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 ite3_column_valu
16270 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
16280 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a int iCol);../*.
16290 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 ** CAPI3REF: Des
162a0 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 troy A Prepared
162b0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 Statement Object
162c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
162d0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 e3_finalize() fu
162e0 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 nction is called
162f0 20 74 6f 20 64 65 6c 65 74 65 20 61 20 0a 2a 2a to delete a .**
16300 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c [sqlite3_stmt |
16310 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 compiled SQL st
16320 61 74 65 6d 65 6e 74 5d 2e 20 49 66 20 74 68 65 atement]. If the
16330 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a statement was.*
16340 2a 20 65 78 65 63 75 74 65 64 20 73 75 63 63 65 * executed succe
16350 73 73 66 75 6c 6c 79 2c 20 6f 72 20 6e 6f 74 20 ssfully, or not
16360 65 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c executed at all,
16370 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 then SQLITE_OK
16380 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 is returned..**
16390 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 If execution of
163a0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61 the statement fa
163b0 69 6c 65 64 20 74 68 65 6e 20 61 6e 20 0a 2a 2a iled then an .**
163c0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c [SQLITE_ERROR |
163d0 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 error code] or
163e0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 [SQLITE_IOERR_RE
163f0 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 65 72 AD | extended er
16400 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73 20 ror code].** is
16410 72 65 74 75 72 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a returned. .**.**
16420 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 This routine ca
16430 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 n be called at a
16440 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 ny point during
16450 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 the execution of
16460 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
16470 5f 73 74 6d 74 20 7c 20 76 69 72 74 75 61 6c 20 _stmt | virtual
16480 6d 61 63 68 69 6e 65 5d 2e 20 20 49 66 20 74 68 machine]. If th
16490 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e e virtual machin
164a0 65 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 63 6f e has not .** co
164b0 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f mpleted executio
164c0 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74 n when this rout
164d0 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 ine is called, t
164e0 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 hat is like.** e
164f0 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 ncountering an e
16500 72 72 6f 72 20 6f 72 20 61 6e 20 69 6e 74 65 72 rror or an inter
16510 72 75 70 74 2e 20 20 28 53 65 65 20 5b 73 71 6c rupt. (See [sql
16520 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
16530 5d 2e 29 20 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 ].) .** Incomple
16540 74 65 20 75 70 64 61 74 65 73 20 6d 61 79 20 62 te updates may b
16550 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e e rolled back an
16560 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 d transactions c
16570 61 6e 63 65 6c 6c 65 64 2c 20 20 0a 2a 2a 20 64 ancelled, .** d
16580 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 epending on the
16590 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 circumstances, a
165a0 6e 64 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 nd the .** [SQLI
165b0 54 45 5f 45 52 52 4f 52 20 7c 20 72 65 73 75 6c TE_ERROR | resul
165c0 74 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 t code] returned
165d0 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 will be [SQLITE
165e0 5f 41 42 4f 52 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 _ABORT]..*/.int
165f0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
16600 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 (sqlite3_stmt *p
16610 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Stmt);../*.** CA
16620 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 PI3REF: Reset A
16630 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 Prepared Stateme
16640 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 nt Object.**.**
16650 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 The sqlite3_rese
16660 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 t() function is
16670 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 called to reset
16680 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 a .** [sqlite3_s
16690 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 tmt | compiled S
166a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 QL statement] ob
166b0 6a 65 63 74 2e 0a 2a 2a 20 62 61 63 6b 20 74 6f ject..** back to
166c0 20 69 74 27 73 20 69 6e 69 74 69 61 6c 20 73 74 it's initial st
166d0 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 ate, ready to be
166e0 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a re-executed..**
166f0 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 Any SQL stateme
16700 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 nt variables tha
16710 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 t had values bou
16720 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 nd to them using
16730 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 .** the [sqlite3
16740 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c _bind_blob | sql
16750 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 ite3_bind_*() AP
16760 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 I] retain their
16770 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b values..** Use [
16780 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 sqlite3_clear_bi
16790 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 ndings()] to res
167a0 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e et the bindings.
167b0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
167c0 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 reset(sqlite3_st
167d0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a mt *pStmt);../*.
167e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 ** CAPI3REF: Cre
167f0 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 ate Or Redefine
16800 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a SQL Functions.**
16810 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e .** The followin
16820 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 g two functions
16830 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 are used to add
16840 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 SQL functions or
16850 20 61 67 67 72 65 67 61 74 65 73 0a 2a 2a 20 6f aggregates.** o
16860 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 r to redefine th
16870 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 65 78 e behavior of ex
16880 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 isting SQL funct
16890 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 ions or aggregat
168a0 65 73 2e 20 20 54 68 65 0a 2a 2a 20 64 69 66 66 es. The.** diff
168b0 65 72 65 6e 63 65 20 6f 6e 6c 79 20 62 65 74 77 erence only betw
168c0 65 65 6e 20 74 68 65 20 74 77 6f 20 69 73 20 74 een the two is t
168d0 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 70 hat the second p
168e0 61 72 61 6d 65 74 65 72 2c 20 74 68 65 0a 2a 2a arameter, the.**
168f0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63 name of the (sc
16900 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f alar) function o
16910 72 20 61 67 67 72 65 67 61 74 65 2c 20 69 73 20 r aggregate, is
16920 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 encoded in UTF-8
16930 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f for.** sqlite3_
16940 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
16950 29 20 61 6e 64 20 55 54 46 2d 31 36 20 66 6f 72 ) and UTF-16 for
16960 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
16970 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a function16()..**
16980 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 .** The first ar
16990 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 5b 73 gument is the [s
169a0 71 6c 69 74 65 33 20 7c 20 64 61 74 61 62 61 73 qlite3 | databas
169b0 65 20 68 61 6e 64 6c 65 5d 20 74 68 61 74 20 68 e handle] that h
169c0 6f 6c 64 73 20 74 68 65 0a 2a 2a 20 53 51 4c 20 olds the.** SQL
169d0 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 function or aggr
169e0 65 67 61 74 65 20 69 73 20 74 6f 20 62 65 20 61 egate is to be a
169f0 64 64 65 64 20 6f 72 20 72 65 64 65 66 69 6e 65 dded or redefine
16a00 64 2e 20 49 66 20 61 20 73 69 6e 67 6c 65 0a 2a d. If a single.*
16a10 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 6d * program uses m
16a20 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 ore than one dat
16a30 61 62 61 73 65 20 68 61 6e 64 6c 65 20 69 6e 74 abase handle int
16a40 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 ernally, then SQ
16a50 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 6f L.** functions o
16a60 72 20 61 67 67 72 65 67 61 74 65 73 20 6d 75 73 r aggregates mus
16a70 74 20 62 65 20 61 64 64 65 64 20 69 6e 64 69 76 t be added indiv
16a80 69 64 75 61 6c 6c 79 20 74 6f 20 65 61 63 68 20 idually to each
16a90 64 61 74 61 62 61 73 65 0a 2a 2a 20 68 61 6e 64 database.** hand
16aa0 6c 65 20 77 69 74 68 20 77 68 69 63 68 20 74 68 le with which th
16ab0 65 79 20 77 69 6c 6c 20 62 65 20 75 73 65 64 2e ey will be used.
16ac0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e .**.** The secon
16ad0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 d parameter is t
16ae0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 he name of the S
16af0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 QL function to b
16b00 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 6f 72 20 e created.** or
16b10 72 65 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 redefined..** Th
16b20 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 e length of the
16b30 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 name is limited
16b40 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65 78 to 255 bytes, ex
16b50 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 0a clusive of the .
16b60 2a 2a 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 ** zero-terminat
16b70 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 or. Note that t
16b80 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c he name length l
16b90 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 73 imit is in bytes
16ba0 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 , not.** charact
16bb0 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 ers. Any attemp
16bc0 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 t to create a fu
16bd0 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f nction with a lo
16be0 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c nger name.** wil
16bf0 6c 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 53 l result in an S
16c00 51 4c 49 54 45 5f 45 52 52 4f 52 20 65 72 72 6f QLITE_ERROR erro
16c10 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 r..**.** The thi
16c20 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 rd parameter is
16c30 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 the number of ar
16c40 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 guments that the
16c50 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 SQL function or
16c60 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 .** aggregate ta
16c70 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70 61 72 kes. If this par
16c80 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 ameter is negati
16c90 76 65 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c ve, then the SQL
16ca0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 function or.**
16cb0 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 aggregate may ta
16cc0 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 ke any number of
16cd0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a arguments..**.*
16ce0 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 * The fourth par
16cf0 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 ameter, eTextRep
16d00 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 , specifies what
16d10 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 .** [SQLITE_UTF
16d20 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 8 | text encodin
16d30 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 g] this SQL func
16d40 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 tion prefers for
16d50 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 .** its paramete
16d60 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e rs. Any SQL fun
16d70 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 ction implementa
16d80 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 tion should be a
16d90 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 ble to work.** w
16da0 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20 ork with UTF-8,
16db0 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 UTF-16le, or UTF
16dc0 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 -16be. But some
16dd0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
16de0 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 may be.** more
16df0 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f efficient with o
16e00 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e ne encoding than
16e10 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 20 69 73 another. It is
16e20 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69 allowed to.** i
16e30 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 nvoke sqlite3_cr
16e40 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 eate_function()
16e50 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 or sqlite3_creat
16e60 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d e_function16() m
16e70 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 ultiple.** times
16e80 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 with the same f
16e90 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 unction but with
16ea0 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 different value
16eb0 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a s of eTextRep..*
16ec0 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 * When multiple
16ed0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
16ee0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 of the same func
16ef0 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 tion are availab
16f00 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 le, SQLite.** wi
16f10 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 ll pick the one
16f20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 that involves th
16f30 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f e least amount o
16f40 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f f data conversio
16f50 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 n..** If there i
16f60 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 s only a single
16f70 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 implementation w
16f80 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 hich does not ca
16f90 72 65 20 77 68 61 74 0a 2a 2a 20 74 65 78 74 20 re what.** text
16fa0 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 encoding is used
16fb0 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 , then the fourt
16fc0 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c h argument shoul
16fd0 64 20 62 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f d be.** [SQLITE_
16fe0 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ANY]..**.** The
16ff0 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 fifth parameter
17000 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 is an arbitrary
17010 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d pointer. The im
17020 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 plementation.**
17030 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 of the function
17040 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 can gain access
17050 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 to this pointer
17060 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 using.** [sqlite
17070 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 0a 3_user_data()]..
17080 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e 74 **.** The sevent
17090 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20 6e 69 h, eighth and ni
170a0 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 nth parameters,
170b0 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 xFunc, xStep and
170c0 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 xFinal, are.**
170d0 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 pointers to C-la
170e0 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 nguage functions
170f0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 that implement
17100 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 the SQL.** funct
17110 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 ion or aggregate
17120 2e 20 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 . A scalar SQL f
17130 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 unction requires
17140 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 an implementati
17150 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46 75 on of.** the xFu
17160 6e 63 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 nc callback only
17170 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 , NULL pointers
17180 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 should be passed
17190 20 61 73 20 74 68 65 20 78 53 74 65 70 0a 2a 2a as the xStep.**
171a0 20 61 6e 64 20 78 46 69 6e 61 6c 20 70 61 72 61 and xFinal para
171b0 6d 65 74 65 72 73 2e 20 41 6e 20 61 67 67 72 65 meters. An aggre
171c0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f gate SQL functio
171d0 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d n requires an im
171e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 plementation.**
171f0 6f 66 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 of xStep and xFi
17200 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f nal and NULL sho
17210 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 66 6f uld be passed fo
17220 72 20 78 46 75 6e 63 2e 20 54 6f 20 64 65 6c 65 r xFunc. To dele
17230 74 65 20 61 6e 0a 2a 2a 20 65 78 69 73 74 69 6e te an.** existin
17240 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f g SQL function o
17250 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 r aggregate, pas
17260 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 s NULL for all t
17270 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a hree function.**
17280 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a callback..**.**
17290 20 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 It is permitted
172a0 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c to register mul
172b0 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 tiple implementa
172c0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d tions of the sam
172d0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 e.** functions w
172e0 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d ith the same nam
172f0 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 e but with eithe
17300 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 r differing numb
17310 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 ers of.** argume
17320 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 nts or differing
17330 20 70 65 72 66 65 72 72 65 64 20 74 65 78 74 20 perferred text
17340 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51 4c 69 encodings. SQLi
17350 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 te will use.** t
17360 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
17370 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d n most closely m
17380 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 atches the way i
17390 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 n which the.** S
173a0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 QL function is u
173b0 73 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 sed..*/.int sqli
173c0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
173d0 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a ion(. sqlite3 *
173e0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a ,. const char *
173f0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 zFunctionName,.
17400 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 int nArg,. int
17410 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 eTextRep,. voi
17420 64 2a 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 d*,. void (*xFu
17430 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 nc)(sqlite3_cont
17440 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
17450 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
17460 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 d (*xStep)(sqlit
17470 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c e3_context*,int,
17480 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 sqlite3_value**)
17490 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 ,. void (*xFina
174a0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 l)(sqlite3_conte
174b0 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 xt*).);.int sqli
174c0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
174d0 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 ion16(. sqlite3
174e0 2a 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 *,. const void
174f0 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a *zFunctionName,.
17500 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e int nArg,. in
17510 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f t eTextRep,. vo
17520 69 64 2a 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 id*,. void (*xF
17530 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e unc)(sqlite3_con
17540 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 text*,int,sqlite
17550 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 3_value**),. vo
17560 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 id (*xStep)(sqli
17570 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
17580 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
17590 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e ),. void (*xFin
175a0 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 al)(sqlite3_cont
175b0 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ext*).);../*.**
175c0 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 CAPI3REF: Text E
175d0 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 ncodings.**.** T
175e0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 hese constant de
175f0 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 fine integer cod
17600 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e es that represen
17610 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a t the various.**
17620 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 text encodings
17630 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c supported by SQL
17640 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ite..*/.#define
17650 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 SQLITE_UTF8
17660 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 1.#define
17670 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 SQLITE_UTF16LE
17680 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 2.#define
17690 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 SQLITE_UTF16BE
176a0 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 3.#define
176b0 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 SQLITE_UTF16
176c0 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 4 /* Us
176d0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 e native byte or
176e0 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 der */.#define S
176f0 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 QLITE_ANY
17700 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 5 /* sql
17710 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
17720 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 tion only */.#de
17730 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 fine SQLITE_UTF1
17740 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 6_ALIGNED 8
17750 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 /* sqlite3_creat
17760 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 e_collation only
17770 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
17780 52 45 46 3a 20 4f 62 73 6f 6c 65 74 65 20 46 75 REF: Obsolete Fu
17790 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 nctions.**.** Th
177a0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 ese functions ar
177b0 65 20 61 6c 6c 20 6e 6f 77 20 6f 62 73 6f 6c 65 e all now obsole
177c0 74 65 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f te. In order to
177d0 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 maintain.** bac
177e0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 kwards compatibi
177f0 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 lity with older
17800 63 6f 64 65 2c 20 77 65 20 63 6f 6e 74 69 6e 75 code, we continu
17810 65 20 74 6f 20 73 75 70 70 6f 72 74 0a 2a 2a 20 e to support.**
17820 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e these functions.
17830 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 64 However, new d
17840 65 76 65 6c 6f 70 6d 65 6e 74 20 70 72 6f 6a 65 evelopment proje
17850 63 74 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 cts should avoid
17860 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 .** the use of t
17870 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 hese functions.
17880 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 To help encoura
17890 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f ge people to avo
178a0 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 id.** using thes
178b0 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 e functions, we
178c0 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f are not going to
178d0 20 74 65 6c 6c 20 79 6f 75 20 77 61 6e 74 20 74 tell you want t
178e0 68 65 79 20 64 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 hey do..*/.int s
178f0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
17900 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 _count(sqlite3_c
17910 6f 6e 74 65 78 74 2a 29 3b 0a 69 6e 74 20 73 71 ontext*);.int sq
17920 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 lite3_expired(sq
17930 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e lite3_stmt*);.in
17940 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 t sqlite3_transf
17950 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 er_bindings(sqli
17960 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 te3_stmt*, sqlit
17970 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 e3_stmt*);.int s
17980 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 qlite3_global_re
17990 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 76 6f 69 cover(void);.voi
179a0 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 d sqlite3_thread
179b0 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a _cleanup(void);.
179c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
179d0 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 Obtaining SQL F
179e0 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 unction Paramete
179f0 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 r Values.**.** T
17a00 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d he C-language im
17a10 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
17a20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e SQL functions an
17a30 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 d aggregates use
17a40 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 s.** this set of
17a50 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 interface routi
17a60 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 nes to access th
17a70 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 e parameter valu
17a80 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e es on.** the fun
17a90 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 ction or aggrega
17aa0 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 te..**.** The xF
17ab0 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 unc (for scalar
17ac0 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 functions) or xS
17ad0 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 tep (for aggrega
17ae0 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a tes) parameters.
17af0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ** to [sqlite3_c
17b00 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
17b10 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 ] and [sqlite3_c
17b20 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
17b30 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 ()].** define ca
17b40 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 llbacks that imp
17b50 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 lement the SQL f
17b60 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 unctions and agg
17b70 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 regates..** The
17b80 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 4th parameter to
17b90 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 these callbacks
17ba0 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 is an array of
17bb0 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b pointers to.** [
17bc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
17bd0 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 bjects. There i
17be0 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 s one [sqlite3_v
17bf0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 alue] object for
17c00 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 .** each paramet
17c10 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 er to the SQL fu
17c20 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 nction. These r
17c30 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 outines are used
17c40 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 to.** extract v
17c50 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b alues from the [
17c60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
17c70 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 bjects..**.** Th
17c80 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 ese routines wor
17c90 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 k just like the
17ca0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 0a 2a corresponding .*
17cb0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
17cc0 6e 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 n_blob | sqlite3
17cd0 5f 63 6f 6c 75 6d 6e 5f 2a 20 72 6f 75 74 69 6e _column_* routin
17ce0 65 73 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 es] except that
17cf0 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e .** these routin
17d00 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 es take a single
17d10 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a [sqlite3_value*
17d20 5d 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 ] pointer instea
17d30 64 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 d.** of an [sqli
17d40 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 te3_stmt*] point
17d50 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 er and an intege
17d60 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e r column number.
17d70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
17d80 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 e3_value_text16(
17d90 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 ) interface extr
17da0 61 63 74 73 20 61 20 55 54 46 31 36 20 73 74 72 acts a UTF16 str
17db0 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 ing.** in the na
17dc0 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 tive byte-order
17dd0 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 of the host mach
17de0 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c ine. The.** sql
17df0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
17e00 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 6be() and sqlite
17e10 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 3_value_text16le
17e20 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a () interfaces.**
17e30 20 65 78 74 72 61 63 74 20 55 54 46 31 36 20 73 extract UTF16 s
17e40 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e trings as big-en
17e50 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d dian and little-
17e60 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 endian respectiv
17e70 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ely..**.** The s
17e80 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d qlite3_value_num
17e90 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 eric_type() inte
17ea0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 rface attempts t
17eb0 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 o apply.** numer
17ec0 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 ic affinity to t
17ed0 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 he value. This
17ee0 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 means that an at
17ef0 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 tempt is.** made
17f00 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 to convert the
17f10 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 value to an inte
17f20 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 ger or floating
17f30 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 point. If.** su
17f40 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 ch a conversion
17f50 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 is possible with
17f60 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f out loss of info
17f70 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 72 64 65 rmation (in orde
17f80 72 0a 2a 2a 20 77 6f 72 64 73 20 69 66 20 74 68 r.** words if th
17f90 65 20 76 61 6c 75 65 20 69 73 20 6f 72 69 67 69 e value is origi
17fa0 6e 61 6c 20 61 20 73 74 72 69 6e 67 20 74 68 61 nal a string tha
17fb0 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e t looks like a n
17fc0 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 69 umber).** then i
17fd0 74 20 69 73 20 64 6f 6e 65 2e 20 20 4f 74 68 65 t is done. Othe
17fe0 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 rwise no convers
17ff0 69 6f 6e 20 6f 63 63 75 72 73 2e 20 20 54 68 65 ion occurs. The
18000 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 .** [SQLITE_INT
18010 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d EGER | datatype]
18020 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f after conversio
18030 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a n is returned..*
18040 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 *.** Please pay
18050 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e particular atten
18060 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 tion to the fact
18070 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 that the pointe
18080 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 72 65 74 r that.** is ret
18090 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 urned from [sqli
180a0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 te3_value_blob()
180b0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ], [sqlite3_valu
180c0 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a e_text()], or.**
180d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
180e0 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 text16()] can be
180f0 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 invalidated by
18100 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c a subsequent cal
18110 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 l to.** [sqlite3
18120 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c _value_bytes()],
18130 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
18140 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c bytes16()], [sql
18150 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 ite3_value_text(
18160 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 )],.** or [sqlit
18170 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 e3_value_text16(
18180 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 )]. .**.** Thes
18190 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 e routines must
181a0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 be called from t
181b0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 he same thread a
181c0 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e s.** the SQL fun
181d0 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c ction that suppl
181e0 69 65 64 20 74 68 65 20 73 71 6c 69 74 65 33 5f ied the sqlite3_
181f0 76 61 6c 75 65 2a 20 70 61 72 61 6d 65 74 65 72 value* parameter
18200 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 s..*/.const void
18210 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f *sqlite3_value_
18220 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c blob(sqlite3_val
18230 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 ue*);.int sqlite
18240 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 3_value_bytes(sq
18250 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 lite3_value*);.i
18260 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt sqlite3_value
18270 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 _bytes16(sqlite3
18280 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 _value*);.double
18290 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 sqlite3_value_d
182a0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 ouble(sqlite3_va
182b0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 lue*);.int sqlit
182c0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c e3_value_int(sql
182d0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 ite3_value*);.sq
182e0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 lite3_int64 sqli
182f0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 te3_value_int64(
18300 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
18310 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 .const unsigned
18320 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 char *sqlite3_va
18330 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 lue_text(sqlite3
18340 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 _value*);.const
18350 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 void *sqlite3_va
18360 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 lue_text16(sqlit
18370 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 e3_value*);.cons
18380 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
18390 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 value_text16le(s
183a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
183b0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
183c0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
183d0 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 be(sqlite3_value
183e0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f *);.int sqlite3_
183f0 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 value_type(sqlit
18400 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 e3_value*);.int
18410 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 sqlite3_value_nu
18420 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 meric_type(sqlit
18430 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a e3_value*);../*.
18440 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 ** CAPI3REF: Obt
18450 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 ain Aggregate Fu
18460 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a nction Context.*
18470 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 *.** The impleme
18480 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 ntation of aggre
18490 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f gate SQL functio
184a0 6e 73 20 75 73 65 20 74 68 69 73 20 72 6f 75 74 ns use this rout
184b0 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a ine to allocate.
184c0 2a 2a 20 61 20 73 74 72 75 63 74 75 72 65 20 66 ** a structure f
184d0 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 or storing their
184e0 20 73 74 61 74 65 2e 20 20 54 68 65 20 66 69 72 state. The fir
184f0 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 st time this rou
18500 74 69 6e 65 0a 2a 2a 20 69 73 20 63 61 6c 6c 65 tine.** is calle
18510 64 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c d for a particul
18520 61 72 20 61 67 67 72 65 67 61 74 65 2c 20 61 20 ar aggregate, a
18530 6e 65 77 20 73 74 72 75 63 74 75 72 65 20 6f 66 new structure of
18540 20 73 69 7a 65 20 6e 42 79 74 65 73 0a 2a 2a 20 size nBytes.**
18550 69 73 20 61 6c 6c 6f 63 61 74 65 64 2c 20 7a 65 is allocated, ze
18560 72 6f 65 64 2c 20 61 6e 64 20 72 65 74 75 72 6e roed, and return
18570 65 64 2e 20 20 4f 6e 20 73 75 62 73 65 71 75 65 ed. On subseque
18580 6e 74 20 63 61 6c 6c 73 20 28 66 6f 72 20 74 68 nt calls (for th
18590 65 0a 2a 2a 20 73 61 6d 65 20 61 67 67 72 65 67 e.** same aggreg
185a0 61 74 65 20 69 6e 73 74 61 6e 63 65 29 20 74 68 ate instance) th
185b0 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 e same buffer is
185c0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 returned. The
185d0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a implementation.*
185e0 2a 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 * of the aggrega
185f0 74 65 20 63 61 6e 20 75 73 65 20 74 68 65 20 72 te can use the r
18600 65 74 75 72 6e 65 64 20 62 75 66 66 65 72 20 74 eturned buffer t
18610 6f 20 61 63 63 75 6d 75 6c 61 74 65 20 64 61 74 o accumulate dat
18620 61 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 66 a..**.** The buf
18630 66 65 72 20 61 6c 6c 6f 63 61 74 65 64 20 69 73 fer allocated is
18640 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 freed automatic
18650 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20 77 ally by SQLite w
18660 68 61 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 han the aggregat
18670 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c e.** query concl
18680 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 udes..**.** The
18690 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
186a0 73 68 6f 75 6c 64 20 62 65 20 61 20 63 6f 70 79 should be a copy
186b0 20 6f 66 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c of the .** [sql
186c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 ite3_context | S
186d0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 QL function cont
186e0 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 ext] that is the
186f0 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 first.** parame
18700 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 ter to the callb
18710 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 ack routine that
18720 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 implements the
18730 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e aggregate.** fun
18740 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 ction..**.** Thi
18750 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 s routine must b
18760 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 e called from th
18770 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e e same thread in
18780 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 which.** the ag
18790 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 gregate SQL func
187a0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e tion is running.
187b0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 .*/.void *sqlite
187c0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 3_aggregate_cont
187d0 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ext(sqlite3_cont
187e0 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 ext*, int nBytes
187f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
18800 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f EF: User Data Fo
18810 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a r Functions.**.*
18820 2a 20 54 68 65 20 70 55 73 65 72 44 61 74 61 20 * The pUserData
18830 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
18840 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
18850 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 _function()].**
18860 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 and [sqlite3_cre
18870 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 ate_function16()
18880 5d 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73 ] routines.** us
18890 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 75 ed to register u
188a0 73 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 69 73 ser functions is
188b0 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 0a 2a 2a available to.**
188c0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 the implementat
188d0 69 6f 6e 20 6f 66 20 74 68 65 20 66 75 6e 63 74 ion of the funct
188e0 69 6f 6e 20 75 73 69 6e 67 20 74 68 69 73 20 63 ion using this c
188f0 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 all..**.** This
18900 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 routine must be
18910 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 called from the
18920 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 same thread in w
18930 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 hich.** the SQL
18940 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 6f 72 69 function was ori
18950 67 69 6e 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 2e ginally invoked.
18960 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 .*/.void *sqlite
18970 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 3_user_data(sqli
18980 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a te3_context*);..
18990 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
189a0 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 Function Auxilia
189b0 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 ry Data.**.** Th
189c0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 e following two
189d0 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 functions may be
189e0 20 75 73 65 64 20 62 79 20 73 63 61 6c 61 72 20 used by scalar
189f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f SQL functions to
18a00 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 .** associate me
18a10 74 61 2d 64 61 74 61 20 77 69 74 68 20 61 72 67 ta-data with arg
18a20 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 ument values. If
18a30 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 the same value
18a40 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 is passed to.**
18a50 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 multiple invocat
18a60 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 ions of the same
18a70 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 SQL function du
18a80 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 ring query execu
18a90 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 tion, under.** s
18aa0 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 ome circumstance
18ab0 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 s the associated
18ac0 20 6d 65 74 61 2d 64 61 74 61 20 6d 61 79 20 62 meta-data may b
18ad0 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 e preserved. Thi
18ae0 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 s may.** be used
18af0 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 , for example, t
18b00 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d o add a regular-
18b10 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 expression match
18b20 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 ing scalar.** fu
18b30 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 nction. The comp
18b40 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 iled version of
18b50 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 the regular expr
18b60 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 ession is stored
18b70 20 61 73 0a 2a 2a 20 6d 65 74 61 2d 64 61 74 61 as.** meta-data
18b80 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
18b90 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 the SQL value p
18ba0 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67 assed as the reg
18bb0 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a ular expression.
18bc0 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 ** pattern. The
18bd0 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 compiled regula
18be0 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e r expression can
18bf0 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 be reused on mu
18c00 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 ltiple.** invoca
18c10 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d tions of the sam
18c20 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 e function so th
18c30 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 at the original
18c40 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a pattern string.*
18c50 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 * does not need
18c60 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 to be recompiled
18c70 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 on each invocat
18c80 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ion..**.** The s
18c90 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 qlite3_get_auxda
18ca0 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 ta() interface r
18cb0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
18cc0 20 74 6f 20 74 68 65 20 6d 65 74 61 2d 64 61 74 to the meta-dat
18cd0 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 a.** associated
18ce0 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 with the Nth arg
18cf0 75 6d 65 6e 74 20 76 61 6c 75 65 20 74 6f 20 74 ument value to t
18d00 68 65 20 63 75 72 72 65 6e 74 20 53 51 4c 20 66 he current SQL f
18d10 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 2c unction.** call,
18d20 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 where N is the
18d30 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
18d40 2e 20 49 66 20 6e 6f 20 6d 65 74 61 2d 64 61 74 . If no meta-dat
18d50 61 20 68 61 73 20 62 65 65 6e 20 73 65 74 20 66 a has been set f
18d60 6f 72 0a 2a 2a 20 74 68 61 74 20 76 61 6c 75 65 or.** that value
18d70 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f , then a NULL po
18d80 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 inter is returne
18d90 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c d..**.** The sql
18da0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 ite3_set_auxdata
18db0 28 29 20 69 73 20 75 73 65 64 20 74 6f 20 61 73 () is used to as
18dc0 73 6f 63 69 61 74 65 20 6d 65 74 61 2d 64 61 74 sociate meta-dat
18dd0 61 20 77 69 74 68 20 61 6e 20 53 51 4c 0a 2a 2a a with an SQL.**
18de0 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 function argume
18df0 6e 74 2e 20 54 68 65 20 74 68 69 72 64 20 70 61 nt. The third pa
18e00 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 rameter is a poi
18e10 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 nter to the meta
18e20 2d 64 61 74 61 0a 2a 2a 20 74 6f 20 62 65 20 61 -data.** to be a
18e30 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
18e40 68 65 20 4e 74 68 20 75 73 65 72 20 66 75 6e 63 he Nth user func
18e50 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 20 76 61 tion argument va
18e60 6c 75 65 2e 20 54 68 65 20 66 6f 75 72 74 68 0a lue. The fourth.
18e70 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 73 70 65 ** parameter spe
18e80 63 69 66 69 65 73 20 61 20 64 65 73 74 72 75 63 cifies a destruc
18e90 74 6f 72 20 74 68 61 74 20 77 69 6c 6c 20 62 65 tor that will be
18ea0 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 6d called on the m
18eb0 65 74 61 2d 0a 2a 2a 20 64 61 74 61 20 70 6f 69 eta-.** data poi
18ec0 6e 74 65 72 20 74 6f 20 72 65 6c 65 61 73 65 20 nter to release
18ed0 69 74 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f it when it is no
18ee0 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 longer required
18ef0 2e 20 49 66 20 74 68 65 20 0a 2a 2a 20 64 65 73 . If the .** des
18f00 74 72 75 63 74 6f 72 20 69 73 20 4e 55 4c 4c 2c tructor is NULL,
18f10 20 69 74 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b it is not invok
18f20 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 ed..**.** In pra
18f30 63 74 69 63 65 2c 20 6d 65 74 61 2d 64 61 74 61 ctice, meta-data
18f40 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65 is preserved be
18f50 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 tween function c
18f60 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 alls for.** expr
18f70 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 essions that are
18f80 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d constant at com
18f90 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 pile time. This
18fa0 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c includes literal
18fb0 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 53 .** values and S
18fc0 51 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a QL variables..**
18fd0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
18fe0 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 e must be called
18ff0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 from the same t
19000 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a hread in which.*
19010 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 * the SQL functi
19020 6f 6e 20 77 61 73 20 6f 72 69 67 69 6e 61 6c 6c on was originall
19030 79 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2f 0a 76 6f y invoked..*/.vo
19040 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f id *sqlite3_get_
19050 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f auxdata(sqlite3_
19060 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a context*, int);.
19070 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 void sqlite3_set
19080 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 _auxdata(sqlite3
19090 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 2c 20 _context*, int,
190a0 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 void*, void (*)(
190b0 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a void*));.../*.**
190c0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 CAPI3REF: Const
190d0 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 ants Defining Sp
190e0 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 ecial Destructor
190f0 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 Behavior.**.**
19100 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 These are specia
19110 6c 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 l value for the
19120 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 destructor that
19130 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 is passed in as
19140 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 the.** final arg
19150 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 ument to routine
19160 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f s like [sqlite3_
19170 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 result_blob()].
19180 20 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 If the destruct
19190 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 or.** argument i
191a0 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c s SQLITE_STATIC,
191b0 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 it means that t
191c0 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 he content point
191d0 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a er is constant.*
191e0 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 * and will never
191f0 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 change. It doe
19200 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 s not need to be
19210 20 64 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65 destroyed. The
19220 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e .** SQLITE_TRAN
19230 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e SIENT value mean
19240 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 s that the conte
19250 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 nt will likely c
19260 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 hange in.** the
19270 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 near future and
19280 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 that SQLite shou
19290 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 ld make its own
192a0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a private copy of.
192b0 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 ** the content b
192c0 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e efore returning.
192d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 .**.** The typed
192e0 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 ef is necessary
192f0 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 to work around p
19300 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 roblems in certa
19310 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c in.** C++ compil
19320 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 ers. See ticket
19330 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 #2191..*/.typed
19340 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 ef void (*sqlite
19350 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 3_destructor_typ
19360 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 e)(void*);.#defi
19370 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 ne SQLITE_STATIC
19380 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f ((sqlite3_
19390 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 destructor_type)
193a0 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 0).#define SQLIT
193b0 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 E_TRANSIENT ((
193c0 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 sqlite3_destruct
193d0 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a or_type)-1)../*.
193e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 ** CAPI3REF: Set
193f0 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 ting The Result
19400 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 Of An SQL Functi
19410 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 on.**.** These r
19420 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 outines are used
19430 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 by the xFunc or
19440 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b xFinal callback
19450 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d s that.** implem
19460 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ent SQL function
19470 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 s and aggregates
19480 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 . See.** [sqlit
19490 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
194a0 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 on()] and [sqlit
194b0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
194c0 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 on16()].** for a
194d0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
194e0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ation..**.** The
194f0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 se functions wor
19500 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 k very much like
19510 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 the .** [sqlite
19520 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 3_bind_blob | sq
19530 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 5d 20 66 61 lite3_bind_*] fa
19540 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e mily of function
19550 73 20 75 73 65 64 0a 2a 2a 20 74 6f 20 62 69 6e s used.** to bin
19560 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 d values to host
19570 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 parameters in p
19580 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
19590 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 ts..** Refer to
195a0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
195b0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 bind_blob | sqli
195c0 74 65 33 5f 62 69 6e 64 5f 2a 20 64 6f 63 75 6d te3_bind_* docum
195d0 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 0a 2a 2a entation] for.**
195e0 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f additional info
195f0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 rmation..**.** T
19600 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
19610 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 t_error() and sq
19620 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
19630 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 or16() functions
19640 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d .** cause the im
19650 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 plemented SQL fu
19660 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 nction to throw
19670 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 20 20 54 an exception. T
19680 68 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 he.** parameter
19690 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c to sqlite3_resul
196a0 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c t_error() or sql
196b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
196c0 72 31 36 28 29 0a 2a 2a 20 69 73 20 74 68 65 20 r16().** is the
196d0 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 text of an error
196e0 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 message..**.**
196f0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
19700 6c 74 5f 74 6f 6f 62 69 67 28 29 20 63 61 75 73 lt_toobig() caus
19710 65 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 e the function i
19720 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a mplementation.**
19730 20 74 6f 20 74 68 72 6f 77 20 61 6e 64 20 65 72 to throw and er
19740 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 ror indicating t
19750 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 hat a string or
19760 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67 0a BLOB is to long.
19770 2a 2a 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e ** to represent.
19780 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
19790 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 tines must be ca
197a0 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e lled from within
197b0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 the same thread
197c0 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 as.** the SQL f
197d0 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 unction associat
197e0 65 64 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c ed with the [sql
197f0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f ite3_context] po
19800 69 6e 74 65 72 2e 0a 2a 2f 0a 76 6f 69 64 20 73 inter..*/.void s
19810 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
19820 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ob(sqlite3_conte
19830 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a xt*, const void*
19840 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 , int, void(*)(v
19850 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c oid*));.void sql
19860 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 ite3_result_doub
19870 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 le(sqlite3_conte
19880 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f xt*, double);.vo
19890 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
198a0 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f t_error(sqlite3_
198b0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
198c0 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 char*, int);.voi
198d0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
198e0 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 _error16(sqlite3
198f0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 _context*, const
19900 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f void*, int);.vo
19910 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
19920 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 t_error_toobig(s
19930 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
19940 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
19950 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 esult_int(sqlite
19960 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3_context*, int)
19970 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
19980 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 esult_int64(sqli
19990 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 te3_context*, sq
199a0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f lite3_int64);.vo
199b0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
199c0 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 t_null(sqlite3_c
199d0 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 ontext*);.void s
199e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
199f0 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 xt(sqlite3_conte
19a00 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a xt*, const char*
19a10 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 , int, void(*)(v
19a20 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c oid*));.void sql
19a30 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
19a40 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 16(sqlite3_conte
19a50 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a xt*, const void*
19a60 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 , int, void(*)(v
19a70 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c oid*));.void sql
19a80 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
19a90 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 16le(sqlite3_con
19aa0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 text*, const voi
19ab0 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 d*, int,void(*)(
19ac0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 void*));.void sq
19ad0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
19ae0 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f t16be(sqlite3_co
19af0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f ntext*, const vo
19b00 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 id*, int,void(*)
19b10 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 (void*));.void s
19b20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 qlite3_result_va
19b30 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 lue(sqlite3_cont
19b40 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 ext*, sqlite3_va
19b50 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 lue*);.void sqli
19b60 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 te3_result_zerob
19b70 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 lob(sqlite3_cont
19b80 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f ext*, int n);../
19b90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
19ba0 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 efine New Collat
19bb0 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a ing Sequences.**
19bc0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 .** These functi
19bd0 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 ons are used to
19be0 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f add new collatio
19bf0 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74 n sequences to t
19c00 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 2a 5d he.** [sqlite3*]
19c10 20 68 61 6e 64 6c 65 20 73 70 65 63 69 66 69 65 handle specifie
19c20 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 d as the first a
19c30 72 67 75 6d 65 6e 74 2e 20 0a 2a 2a 0a 2a 2a 20 rgument. .**.**
19c40 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 The name of the
19c50 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 new collation se
19c60 71 75 65 6e 63 65 20 69 73 20 73 70 65 63 69 66 quence is specif
19c70 69 65 64 20 61 73 20 61 20 55 54 46 2d 38 20 73 ied as a UTF-8 s
19c80 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c tring.** for sql
19c90 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
19ca0 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 ation() and sqli
19cb0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
19cc0 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 tion_v2().** and
19cd0 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 a UTF-16 string
19ce0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 for sqlite3_cre
19cf0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 ate_collation16(
19d00 29 2e 20 20 49 6e 20 61 6c 6c 20 63 61 73 65 73 ). In all cases
19d10 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20 .** the name is
19d20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 passed as the se
19d30 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 cond function ar
19d40 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 gument..**.** Th
19d50 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
19d60 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 must be one of
19d70 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 the constants [S
19d80 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 QLITE_UTF8],.**
19d90 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d [SQLITE_UTF16LE]
19da0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 or [SQLITE_UTF1
19db0 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 6BE], indicating
19dc0 20 74 68 61 74 20 74 68 65 20 75 73 65 72 2d 73 that the user-s
19dd0 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 upplied.** routi
19de0 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20 62 65 ne expects to be
19df0 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73 passed pointers
19e00 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f to strings enco
19e10 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c ded using UTF-8,
19e20 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c .** UTF-16 littl
19e30 65 2d 65 6e 64 69 61 6e 20 6f 72 20 55 54 46 2d e-endian or UTF-
19e40 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 20 72 65 16 big-endian re
19e50 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a spectively..**.*
19e60 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 * A pointer to t
19e70 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 65 64 he user supplied
19e80 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 routine must be
19e90 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 passed as the f
19ea0 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 ifth.** argument
19eb0 2e 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c . If it is NULL,
19ec0 20 74 68 69 73 20 69 73 20 74 68 65 20 73 61 6d this is the sam
19ed0 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68 e as deleting th
19ee0 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 e collation.** s
19ef0 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74 equence (so that
19f00 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 SQLite cannot c
19f10 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e all it anymore).
19f20 20 45 61 63 68 20 74 69 6d 65 20 74 68 65 20 75 Each time the u
19f30 73 65 72 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 ser.** supplied
19f40 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f function is invo
19f50 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73 73 65 ked, it is passe
19f60 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 d a copy of the
19f70 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73 0a void* passed as.
19f80 2a 2a 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 ** the fourth ar
19f90 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
19fa0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
19fb0 6f 6e 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 on() or.** sqlit
19fc0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
19fd0 69 6f 6e 31 36 28 29 20 61 73 20 69 74 73 20 66 ion16() as its f
19fe0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a irst parameter..
19ff0 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e **.** The remain
1a000 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f ing arguments to
1a010 20 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 the user-suppli
1a020 65 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74 ed routine are t
1a030 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 wo strings,.** e
1a040 61 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 20 ach represented
1a050 62 79 20 61 20 5b 6c 65 6e 67 74 68 2c 20 64 61 by a [length, da
1a060 74 61 5d 20 70 61 69 72 20 61 6e 64 20 65 6e 63 ta] pair and enc
1a070 6f 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f oded in the enco
1a080 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 ding.** that was
1a090 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 passed as the t
1a0a0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68 hird argument wh
1a0b0 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e en the collation
1a0c0 20 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a sequence was.**
1a0d0 20 72 65 67 69 73 74 65 72 65 64 2e 20 54 68 65 registered. The
1a0e0 20 75 73 65 72 20 72 6f 75 74 69 6e 65 20 73 68 user routine sh
1a0f0 6f 75 6c 64 20 72 65 74 75 72 6e 20 6e 65 67 61 ould return nega
1a100 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f tive, zero or po
1a110 73 69 74 69 76 65 20 69 66 0a 2a 2a 20 74 68 65 sitive if.** the
1a120 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 first string is
1a130 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 less than, equa
1a140 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 l to, or greater
1a150 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 than the second
1a160 0a 2a 2a 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e .** string. i.e.
1a170 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49 (STRING1 - STRI
1a180 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 NG2)..**.** The
1a190 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
1a1a0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f ollation_v2() wo
1a1b0 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 rks like sqlite3
1a1c0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
1a1d0 6e 28 29 0a 2a 2a 20 65 78 63 61 70 74 20 74 68 n().** excapt th
1a1e0 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65 at it takes an e
1a1f0 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68 xtra argument wh
1a200 69 63 68 20 69 73 20 61 20 64 65 73 74 72 75 63 ich is a destruc
1a210 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 tor for.** the c
1a220 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 ollation. The d
1a230 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c estructor is cal
1a240 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c led when the col
1a250 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 lation is.** des
1a260 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61 troyed and is pa
1a270 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 ssed a copy of t
1a280 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
1a290 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 ter void* pointe
1a2a0 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 r.** of the sqli
1a2b0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
1a2c0 74 69 6f 6e 5f 76 32 28 29 2e 20 20 43 6f 6c 6c tion_v2(). Coll
1a2d0 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72 ations are destr
1a2e0 6f 79 65 64 20 77 68 65 6e 0a 2a 2a 20 74 68 65 oyed when.** the
1a2f0 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e y are overridden
1a300 20 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 by later calls
1a310 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e to the collation
1a320 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 creation functi
1a330 6f 6e 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 ons.** or when t
1a340 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 64 61 he [sqlite3*] da
1a350 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 69 73 tabase handle is
1a360 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 closed using [s
1a370 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e qlite3_close()].
1a380 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
1a390 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
1a3a0 69 6f 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 ion_v2() interfa
1a3b0 63 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 ce is experiment
1a3c0 61 6c 20 61 6e 64 0a 2a 2a 20 73 75 62 6a 65 63 al and.** subjec
1a3d0 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 t to change in f
1a3e0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 20 uture releases.
1a3f0 20 54 68 65 20 6f 74 68 65 72 20 63 6f 6c 6c 61 The other colla
1a400 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 0a 2a 2a tion creation.**
1a410 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 73 functions are s
1a420 74 61 62 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 table..*/.int sq
1a430 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
1a440 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 lation(. sqlite
1a450 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 3*, . const cha
1a460 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 r *zName, . int
1a470 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f eTextRep, . vo
1a480 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d id*,. int(*xCom
1a490 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c pare)(void*,int,
1a4a0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c const void*,int,
1a4b0 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a const void*).);.
1a4c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 int sqlite3_crea
1a4d0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 te_collation_v2(
1a4e0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 . sqlite3*, .
1a4f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
1a500 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 e, . int eTextR
1a510 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 ep, . void*,.
1a520 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 int(*xCompare)(v
1a530 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 oid*,int,const v
1a540 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 oid*,int,const v
1a550 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 oid*),. void(*x
1a560 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a Destroy)(void*).
1a570 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 );.int sqlite3_c
1a580 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 reate_collation1
1a590 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 6(. sqlite3*, .
1a5a0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e const char *zN
1a5b0 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 ame, . int eTex
1a5c0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a tRep, . void*,.
1a5d0 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 int(*xCompare)
1a5e0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 (void*,int,const
1a5f0 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 void*,int,const
1a600 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a void*).);../*.*
1a610 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c * CAPI3REF: Coll
1a620 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c ation Needed Cal
1a630 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54 6f 20 lbacks.**.** To
1a640 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 avoid having to
1a650 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c register all col
1a660 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 lation sequences
1a670 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 before a databa
1a680 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 se.** can be use
1a690 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c d, a single call
1a6a0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 back function ma
1a6b0 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 y be registered
1a6c0 77 69 74 68 20 74 68 65 0a 2a 2a 20 64 61 74 61 with the.** data
1a6d0 62 61 73 65 20 68 61 6e 64 6c 65 20 74 6f 20 62 base handle to b
1a6e0 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76 65 e called wheneve
1a6f0 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 r an undefined c
1a700 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 ollation sequenc
1a710 65 20 69 73 0a 2a 2a 20 72 65 71 75 69 72 65 64 e is.** required
1a720 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 ..**.** If the f
1a730 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 unction is regis
1a740 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 tered using the
1a750 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
1a760 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a n_needed() API,.
1a770 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 ** then it is pa
1a780 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f ssed the names o
1a790 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c f undefined coll
1a7a0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 ation sequences
1a7b0 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e as strings.** en
1a7c0 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 coded in UTF-8.
1a7d0 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 If sqlite3_colla
1a7e0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 tion_needed16()
1a7f0 69 73 20 75 73 65 64 2c 20 74 68 65 20 6e 61 6d is used, the nam
1a800 65 73 0a 2a 2a 20 61 72 65 20 70 61 73 73 65 64 es.** are passed
1a810 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 as UTF-16 in ma
1a820 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 chine native byt
1a830 65 20 6f 72 64 65 72 2e 20 41 20 63 61 6c 6c 20 e order. A call
1a840 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 66 75 6e to either.** fun
1a850 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61 ction replaces a
1a860 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c ny existing call
1a870 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e back..**.** When
1a880 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 the callback is
1a890 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 invoked, the fi
1a8a0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 rst argument pas
1a8b0 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a sed is a copy.**
1a8c0 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 of the second a
1a8d0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
1a8e0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 e3_collation_nee
1a8f0 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 ded() or.** sqli
1a900 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 te3_collation_ne
1a910 65 64 65 64 31 36 28 29 2e 20 54 68 65 20 73 65 eded16(). The se
1a920 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 cond argument is
1a930 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a the database.**
1a940 20 68 61 6e 64 6c 65 2e 20 54 68 65 20 74 68 69 handle. The thi
1a950 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f rd argument is o
1a960 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 ne of [SQLITE_UT
1a970 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 F8], [SQLITE_UTF
1a980 31 36 42 45 5d 2c 20 6f 72 0a 2a 2a 20 5b 53 51 16BE], or.** [SQ
1a990 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 LITE_UTF16LE], i
1a9a0 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f ndicating the mo
1a9b0 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 st desirable for
1a9c0 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 m of the collati
1a9d0 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 on.** sequence f
1a9e0 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 unction required
1a9f0 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 . The fourth par
1aa00 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 ameter is the na
1aa10 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 me of the.** req
1aa20 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 uired collation
1aa30 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 sequence..**.**
1aa40 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e The callback fun
1aa50 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 ction should reg
1aa60 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65 ister the desire
1aa70 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e d collation usin
1aa80 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 g.** [sqlite3_cr
1aa90 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 eate_collation()
1aaa0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 ], [sqlite3_crea
1aab0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 te_collation16()
1aac0 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 ], or.** [sqlite
1aad0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
1aae0 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 on_v2()]..*/.int
1aaf0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 sqlite3_collati
1ab00 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c on_needed(. sql
1ab10 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c ite3*, . void*,
1ab20 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 . void(*)(void
1ab30 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 *,sqlite3*,int e
1ab40 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 TextRep,const ch
1ab50 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 ar*).);.int sqli
1ab60 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 te3_collation_ne
1ab70 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 eded16(. sqlite
1ab80 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 3*, . void*,.
1ab90 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 void(*)(void*,sq
1aba0 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 lite3*,int eText
1abb0 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 Rep,const void*)
1abc0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 .);../*.** Speci
1abd0 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 fy the key for a
1abe0 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 n encrypted data
1abf0 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 base. This rout
1ac00 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a ine should be.**
1ac10 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 called right af
1ac20 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e ter sqlite3_open
1ac30 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f ()..**.** The co
1ac40 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 de to implement
1ac50 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 this API is not
1ac60 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 available in the
1ac70 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a public release.
1ac80 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f ** of SQLite..*/
1ac90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 .int sqlite3_key
1aca0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
1acb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1acc0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 /* Database t
1acd0 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a o be rekeyed */.
1ace0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b const void *pK
1acf0 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 ey, int nKey
1ad00 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 /* The key */.)
1ad10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 ;../*.** Change
1ad20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 the key on an op
1ad30 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 en database. If
1ad40 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 the current dat
1ad50 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 abase is not.**
1ad60 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 encrypted, this
1ad70 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 routine will enc
1ad80 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 rypt it. If pNe
1ad90 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c w==0 or nNew==0,
1ada0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 the.** database
1adb0 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a is decrypted..*
1adc0 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f *.** The code to
1add0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 implement this
1ade0 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c API is not avail
1adf0 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c able in the publ
1ae00 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 ic release.** of
1ae10 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 SQLite..*/.int
1ae20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 sqlite3_rekey(.
1ae30 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
1ae40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1ae50 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 /* Database to b
1ae60 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 e rekeyed */. c
1ae70 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c onst void *pKey,
1ae80 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a int nKey /*
1ae90 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a The new key */.
1aea0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1aeb0 45 46 3a 20 20 53 75 73 70 65 6e 64 20 45 78 65 EF: Suspend Exe
1aec0 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f cution For A Sho
1aed0 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 rt Time.**.** Th
1aee0 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 is function caus
1aef0 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 es the current t
1af00 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 hread to suspend
1af10 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 61 20 execution.** a
1af20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 number of millis
1af30 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 econds specified
1af40 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 in its paramete
1af50 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 r..**.** If the
1af60 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d operating system
1af70 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 does not suppor
1af80 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 t sleep requests
1af90 20 77 69 74 68 20 0a 2a 2a 20 6d 69 6c 6c 69 73 with .** millis
1afa0 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c econd time resol
1afb0 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 ution, then the
1afc0 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 time will be rou
1afd0 6e 64 65 64 20 75 70 20 74 6f 20 0a 2a 2a 20 74 nded up to .** t
1afe0 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e he nearest secon
1aff0 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 d. The number of
1b000 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 milliseconds of
1b010 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 20 sleep actually
1b020 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 .** requested fr
1b030 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 om the operating
1b040 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 system is retur
1b050 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ned..*/.int sqli
1b060 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a te3_sleep(int);.
1b070 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1b080 20 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f Name Of The Fo
1b090 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d lder Holding Tem
1b0a0 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a porary Files.**.
1b0b0 2a 2a 20 49 66 20 74 68 69 73 20 67 6c 6f 62 61 ** If this globa
1b0c0 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 l variable is ma
1b0d0 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 de to point to a
1b0e0 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 string which is
1b0f0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 .** the name of
1b100 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 61 2e 20 a folder (a.ka.
1b110 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e directory), then
1b120 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 all temporary f
1b130 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 iles.** created
1b140 62 79 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 by SQLite will b
1b150 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 e placed in that
1b160 20 64 69 72 65 63 74 6f 72 79 2e 20 20 49 66 20 directory. If
1b170 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a this variable.**
1b180 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 is NULL pointer
1b190 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 64 6f , then SQLite do
1b1a0 65 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 es a search for
1b1b0 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 74 an appropriate t
1b1c0 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 66 69 6c 65 emporary.** file
1b1d0 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a directory..**.*
1b1e0 2a 20 4f 6e 63 65 20 5b 73 71 6c 69 74 65 33 5f * Once [sqlite3_
1b1f0 6f 70 65 6e 28 29 5d 20 68 61 73 20 62 65 65 6e open()] has been
1b200 20 63 61 6c 6c 65 64 2c 20 63 68 61 6e 67 69 6e called, changin
1b210 67 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 g this variable
1b220 77 69 6c 6c 0a 2a 2a 20 69 6e 76 61 6c 69 64 61 will.** invalida
1b230 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 te the current t
1b240 65 6d 70 6f 72 61 72 79 20 64 61 74 61 62 61 73 emporary databas
1b250 65 2c 20 69 66 20 61 6e 79 2e 20 20 47 65 6e 65 e, if any. Gene
1b260 72 61 6c 6c 79 20 73 70 65 61 6b 69 6e 67 2c 0a rally speaking,.
1b270 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 ** it is not saf
1b280 65 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 69 73 e to invoke this
1b290 20 72 6f 75 74 69 6e 65 20 61 66 74 65 72 20 5b routine after [
1b2a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 sqlite3_open()]
1b2b0 68 61 73 0a 2a 2a 20 62 65 65 6e 20 63 61 6c 6c has.** been call
1b2c0 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 ed..*/.SQLITE_EX
1b2d0 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 TERN char *sqlit
1b2e0 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 e3_temp_director
1b2f0 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 y;../*.** CAPI3R
1b300 45 46 3a 20 20 54 65 73 74 20 54 6f 20 53 65 65 EF: Test To See
1b310 20 49 66 20 54 68 65 20 44 61 74 61 62 73 65 20 If The Databse
1b320 49 73 20 49 6e 20 41 75 74 6f 2d 43 6f 6d 6d 69 Is In Auto-Commi
1b330 74 20 4d 6f 64 65 0a 2a 2a 0a 2a 2a 20 54 65 73 t Mode.**.** Tes
1b340 74 20 74 6f 20 73 65 65 20 77 68 65 74 68 65 72 t to see whether
1b350 20 6f 72 20 6e 6f 74 20 74 68 65 20 64 61 74 61 or not the data
1b360 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
1b370 69 73 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 is in autocommit
1b380 0a 2a 2a 20 6d 6f 64 65 2e 20 20 52 65 74 75 72 .** mode. Retur
1b390 6e 20 54 52 55 45 20 69 66 20 69 74 20 69 73 20 n TRUE if it is
1b3a0 61 6e 64 20 46 41 4c 53 45 20 69 66 20 6e 6f 74 and FALSE if not
1b3b0 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f . Autocommit mo
1b3c0 64 65 20 69 73 20 6f 6e 0a 2a 2a 20 62 79 20 64 de is on.** by d
1b3d0 65 66 61 75 6c 74 2e 20 20 41 75 74 6f 63 6f 6d efault. Autocom
1b3e0 6d 69 74 20 69 73 20 64 69 73 61 62 6c 65 64 20 mit is disabled
1b3f0 62 79 20 61 20 42 45 47 49 4e 20 73 74 61 74 65 by a BEGIN state
1b400 6d 65 6e 74 20 61 6e 64 20 72 65 65 6e 61 62 6c ment and reenabl
1b410 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 6e 65 78 ed.** by the nex
1b420 74 20 43 4f 4d 4d 49 54 20 6f 72 20 52 4f 4c 4c t COMMIT or ROLL
1b430 42 41 43 4b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 BACK..**.** If a
1b440 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68 nother thread ch
1b450 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f anges the autoco
1b460 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74 mmit status of t
1b470 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 he database.** c
1b480 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 onnection while
1b490 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 this routine is
1b4a0 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 running, then th
1b4b0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a e return value.*
1b4c0 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a * is undefined..
1b4d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 */.int sqlite3_g
1b4e0 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 et_autocommit(sq
1b4f0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
1b500 43 41 50 49 33 52 45 46 3a 20 20 46 69 6e 64 20 CAPI3REF: Find
1b510 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e The Database Han
1b520 64 6c 65 20 41 73 73 6f 63 69 61 74 65 64 20 57 dle Associated W
1b530 69 74 68 20 41 20 50 72 65 70 61 72 65 64 20 53 ith A Prepared S
1b540 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 52 tatement.**.** R
1b550 65 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 eturn the [sqlit
1b560 65 33 2a 5d 20 64 61 74 61 62 61 73 65 20 68 61 e3*] database ha
1b570 6e 64 6c 65 20 74 6f 20 77 68 69 63 68 20 61 0a ndle to which a.
1b580 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 ** [sqlite3_stmt
1b590 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 | prepared stat
1b5a0 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 0a ement] belongs..
1b5b0 2a 2a 20 54 68 69 73 20 69 73 20 74 68 65 20 73 ** This is the s
1b5c0 61 6d 65 20 64 61 74 61 62 61 73 65 20 68 61 6e ame database han
1b5d0 64 6c 65 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 dle that was.**
1b5e0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
1b5f0 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 nt to the [sqlit
1b600 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
1b610 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 or its variants
1b620 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 75 73 65 .** that was use
1b630 64 20 74 6f 20 63 72 65 61 74 65 20 74 68 65 20 d to create the
1b640 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 statement in the
1b650 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f first place..*/
1b660 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 .sqlite3 *sqlite
1b670 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 3_db_handle(sqli
1b680 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 0a 2f 2a te3_stmt*);.../*
1b690 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
1b6a0 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 mmit And Rollbac
1b6b0 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 k Notification C
1b6c0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54 allbacks.**.** T
1b6d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a hese routines.**
1b6e0 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 register callba
1b6f0 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 ck functions to
1b700 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 be invoked whene
1b710 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f ver a transactio
1b720 6e 0a 2a 2a 20 69 73 20 63 6f 6d 6d 69 74 74 65 n.** is committe
1b730 64 20 6f 72 20 72 6f 6c 6c 65 64 20 62 61 63 6b d or rolled back
1b740 2e 20 20 54 68 65 20 70 41 72 67 20 61 72 67 75 . The pArg argu
1b750 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 ment is passed t
1b760 68 72 6f 75 67 68 0a 2a 2a 20 74 6f 20 74 68 65 hrough.** to the
1b770 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20 74 callback. If t
1b780 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 he callback on a
1b790 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e commit hook fun
1b7a0 63 74 69 6f 6e 20 0a 2a 2a 20 72 65 74 75 72 6e ction .** return
1b7b0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e s non-zero, then
1b7c0 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 the commit is c
1b7d0 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 onverted into a
1b7e0 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 rollback..**.**
1b7f0 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 If another funct
1b800 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73 ion was previous
1b810 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69 ly registered, i
1b820 74 73 20 70 41 72 67 20 76 61 6c 75 65 20 69 73 ts pArg value is
1b830 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 returned..** Ot
1b840 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 herwise NULL is
1b850 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
1b860 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 Registering a NU
1b870 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 LL function disa
1b880 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 bles the callbac
1b890 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 k..**.** For the
1b8a0 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 purposes of thi
1b8b0 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 s API, a transac
1b8c0 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 tion is said to
1b8d0 68 61 76 65 20 62 65 65 6e 20 0a 2a 2a 20 72 6f have been .** ro
1b8e0 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 lled back if an
1b8f0 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 explicit "ROLLBA
1b900 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 CK" statement is
1b910 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a executed, or.**
1b920 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e an error or con
1b930 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 straint causes a
1b940 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 n implicit rollb
1b950 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 20 54 68 ack to occur. Th
1b960 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 e .** callback i
1b970 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 s not invoked if
1b980 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 a transaction i
1b990 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 s automatically
1b9a0 72 6f 6c 6c 65 64 0a 2a 2a 20 62 61 63 6b 20 62 rolled.** back b
1b9b0 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62 ecause the datab
1b9c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
1b9d0 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 s closed..**.**
1b9e0 54 68 65 73 65 20 61 72 65 20 65 78 70 65 72 69 These are experi
1b9f0 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 mental interface
1ba00 73 20 61 6e 64 20 61 72 65 20 73 75 62 6a 65 63 s and are subjec
1ba10 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a t to change..*/.
1ba20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
1ba30 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 mmit_hook(sqlite
1ba40 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 3*, int(*)(void*
1ba50 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 ), void*);.void
1ba60 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 *sqlite3_rollbac
1ba70 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c k_hook(sqlite3*,
1ba80 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 void(*)(void *)
1ba90 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a , void*);../*.**
1baa0 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 CAPI3REF: Data
1bab0 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 Change Notificat
1bac0 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a ion Callbacks.**
1bad0 0a 2a 2a 20 52 65 67 69 73 74 65 72 20 61 20 63 .** Register a c
1bae0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
1baf0 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61 with the databa
1bb00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 se connection id
1bb10 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 entified by the
1bb20 0a 2a 2a 20 66 69 72 73 74 20 61 72 67 75 6d 65 .** first argume
1bb30 6e 74 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 nt to be invoked
1bb40 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 whenever a row
1bb50 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 is updated, inse
1bb60 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e rted or deleted.
1bb70 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b .** Any callback
1bb80 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f set by a previo
1bb90 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 us call to this
1bba0 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68 65 function for the
1bbb0 20 73 61 6d 65 20 0a 2a 2a 20 64 61 74 61 62 61 same .** databa
1bbc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
1bbd0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a overridden..**.
1bbe0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 ** The second ar
1bbf0 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e gument is a poin
1bc00 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 ter to the funct
1bc10 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 ion to invoke wh
1bc20 65 6e 20 61 20 0a 2a 2a 20 72 6f 77 20 69 73 20 en a .** row is
1bc30 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 updated, inserte
1bc40 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 20 54 68 d or deleted. Th
1bc50 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
1bc60 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
1bc70 20 69 73 0a 2a 2a 20 61 20 63 6f 70 79 20 6f 66 is.** a copy of
1bc80 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d the third argum
1bc90 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 ent to sqlite3_u
1bca0 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 20 54 68 pdate_hook(). Th
1bcb0 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 e second callbac
1bcc0 6b 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 k .** argument i
1bcd0 73 20 6f 6e 65 20 6f 66 20 53 51 4c 49 54 45 5f s one of SQLITE_
1bce0 49 4e 53 45 52 54 2c 20 53 51 4c 49 54 45 5f 44 INSERT, SQLITE_D
1bcf0 45 4c 45 54 45 20 6f 72 20 53 51 4c 49 54 45 5f ELETE or SQLITE_
1bd00 55 50 44 41 54 45 2c 20 64 65 70 65 6e 64 69 6e UPDATE, dependin
1bd10 67 0a 2a 2a 20 6f 6e 20 74 68 65 20 6f 70 65 72 g.** on the oper
1bd20 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 ation that cause
1bd30 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 74 d the callback t
1bd40 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 20 54 68 o be invoked. Th
1bd50 65 20 74 68 69 72 64 20 61 6e 64 20 0a 2a 2a 20 e third and .**
1bd60 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 fourth arguments
1bd70 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
1bd80 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 contain pointer
1bd90 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 s to the databas
1bda0 65 20 61 6e 64 20 0a 2a 2a 20 74 61 62 6c 65 20 e and .** table
1bdb0 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 name containing
1bdc0 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 the affected row
1bdd0 2e 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c . The final call
1bde0 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 back parameter i
1bdf0 73 20 0a 2a 2a 20 74 68 65 20 72 6f 77 69 64 20 s .** the rowid
1be00 6f 66 20 74 68 65 20 72 6f 77 2e 20 49 6e 20 74 of the row. In t
1be10 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70 he case of an up
1be20 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74 68 date, this is th
1be30 65 20 72 6f 77 69 64 20 61 66 74 65 72 20 0a 2a e rowid after .*
1be40 2a 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b * the update tak
1be50 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 es place..**.**
1be60 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 The update hook
1be70 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 is not invoked w
1be80 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 hen internal sys
1be90 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a tem tables are.*
1bea0 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e * modified (i.e.
1beb0 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 sqlite_master a
1bec0 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e nd sqlite_sequen
1bed0 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e ce)..**.** If an
1bee0 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 other function w
1bef0 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 as previously re
1bf00 67 69 73 74 65 72 65 64 2c 20 69 74 73 20 70 41 gistered, its pA
1bf10 72 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 rg value is retu
1bf20 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 rned..** Otherwi
1bf30 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 se NULL is retur
1bf40 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 ned..*/.void *sq
1bf50 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f lite3_update_hoo
1bf60 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a k(. sqlite3*, .
1bf70 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a void(*)(void *
1bf80 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 ,int ,char const
1bf90 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c *,char const *,
1bfa0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a sqlite3_int64),.
1bfb0 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a void*.);../*.*
1bfc0 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 6e 61 * CAPI3REF: Ena
1bfd0 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 ble Or Disable S
1bfe0 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63 68 hared Pager Cach
1bff0 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 e.**.** This rou
1c000 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 tine enables or
1c010 64 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 disables the sha
1c020 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 ring of the data
1c030 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e base cache.** an
1c040 64 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 d schema data st
1c050 72 75 63 74 75 72 65 73 20 62 65 74 77 65 65 6e ructures between
1c060 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 6f 20 connections to
1c070 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
1c080 65 2e 0a 2a 2a 20 53 68 61 72 69 6e 67 20 69 73 e..** Sharing is
1c090 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 enabled if the
1c0a0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 argument is true
1c0b0 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66 and disabled if
1c0c0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a the argument.**
1c0d0 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a is false..**.**
1c0e0 20 42 65 67 69 6e 6e 69 6e 67 20 69 6e 20 53 51 Beginning in SQ
1c0f0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 Lite version 3.5
1c100 2e 30 2c 20 63 61 63 68 65 20 73 68 61 72 69 6e .0, cache sharin
1c110 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 g is enabled and
1c120 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 66 6f 72 disabled.** for
1c130 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 an entire proce
1c140 73 73 2e 20 20 49 6e 20 70 72 69 6f 72 20 76 65 ss. In prior ve
1c150 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
1c160 2c 20 73 68 61 72 69 6e 67 20 77 61 73 0a 2a 2a , sharing was.**
1c170 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 enabled or disa
1c180 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 bled for each th
1c190 72 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e read separately.
1c1a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68 65 .**.** The cache
1c1b0 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 sharing mode se
1c1c0 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 t by this interf
1c1d0 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 ace effects all
1c1e0 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 subsequent.** ca
1c1f0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
1c200 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 open()], [sqlite
1c210 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 3_open_v2()], an
1c220 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 d [sqlite3_open1
1c230 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 6()]..** Existin
1c240 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 g database conne
1c250 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 ctions continue
1c260 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 use the sharing
1c270 6d 6f 64 65 20 74 68 61 74 20 77 61 73 0a 2a 2a mode that was.**
1c280 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 in effect at th
1c290 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 e time they were
1c2a0 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 opened..**.** V
1c2b0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 irtual tables ca
1c2c0 6e 6e 6f 74 20 62 65 20 75 73 65 64 20 77 69 74 nnot be used wit
1c2d0 68 20 61 20 73 68 61 72 65 64 20 63 61 63 68 65 h a shared cache
1c2e0 2e 20 20 57 68 65 6e 20 73 68 61 72 65 64 0a 2a . When shared.*
1c2f0 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c * cache is enabl
1c300 65 64 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f ed, the sqlite3_
1c310 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 20 create_module()
1c320 41 50 49 20 75 73 65 64 20 74 6f 20 72 65 67 69 API used to regi
1c330 73 74 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20 ster.** virtual
1c340 74 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61 tables will alwa
1c350 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 ys return an err
1c360 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 or..**.** This r
1c370 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b outine returns [
1c380 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 SQLITE_OK] if sh
1c390 61 72 65 64 20 63 61 63 68 65 20 77 61 73 0a 2a ared cache was.*
1c3a0 2a 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 * enabled or dis
1c3b0 61 62 6c 65 64 20 73 75 63 63 65 73 73 66 75 6c abled successful
1c3c0 6c 79 2e 20 20 41 6e 20 5b 53 51 4c 49 54 45 5f ly. An [SQLITE_
1c3d0 45 52 52 4f 52 20 7c 20 65 72 72 6f 72 20 63 6f ERROR | error co
1c3e0 64 65 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e de].** is return
1c3f0 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a ed otherwise..**
1c400 0a 2a 2a 20 53 68 61 72 65 64 20 63 61 63 68 65 .** Shared cache
1c410 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 is disabled by
1c420 64 65 66 61 75 6c 74 20 66 6f 72 20 62 61 63 6b default for back
1c430 77 61 72 64 20 63 6f 6d 70 61 74 69 62 69 6c 69 ward compatibili
1c440 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ty..*/.int sqlit
1c450 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 e3_enable_shared
1c460 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a _cache(int);../*
1c470 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 41 .** CAPI3REF: A
1c480 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 ttempt To Free H
1c490 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a eap Memory.**.**
1c4a0 20 41 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 Attempt to free
1c4b0 20 4e 20 62 79 74 65 73 20 6f 66 20 68 65 61 70 N bytes of heap
1c4c0 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c memory by deall
1c4d0 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 ocating non-esse
1c4e0 6e 74 69 61 6c 0a 2a 2a 20 6d 65 6d 6f 72 79 20 ntial.** memory
1c4f0 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 68 65 6c 64 allocations held
1c500 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 by the database
1c510 20 6c 69 62 72 61 72 79 20 28 65 78 61 6d 70 6c library (exampl
1c520 65 3a 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 75 73 e: memory .** us
1c530 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 ed to cache data
1c540 62 61 73 65 20 70 61 67 65 73 20 74 6f 20 69 6d base pages to im
1c550 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 prove performanc
1c560 65 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 e)..**.** This f
1c570 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 unction is not a
1c580 20 70 61 72 74 20 6f 66 20 73 74 61 6e 64 61 72 part of standar
1c590 64 20 62 75 69 6c 64 73 2e 20 20 49 74 20 69 73 d builds. It is
1c5a0 20 6f 6e 6c 79 20 63 72 65 61 74 65 64 0a 2a 2a only created.**
1c5b0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f if SQLite is co
1c5c0 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 mpiled with the
1c5d0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 SQLITE_ENABLE_ME
1c5e0 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 20 MORY_MANAGEMENT
1c5f0 6d 61 63 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 macro..*/.int sq
1c600 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 lite3_release_me
1c610 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a mory(int);../*.*
1c620 2a 20 43 41 50 49 33 52 45 46 3a 20 20 49 6d 70 * CAPI3REF: Imp
1c630 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 ose A Limit On H
1c640 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 50 eap Size.**.** P
1c650 6c 61 63 65 20 61 20 22 73 6f 66 74 22 20 6c 69 lace a "soft" li
1c660 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e mit on the amoun
1c670 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 t of heap memory
1c680 20 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c that may be all
1c690 6f 63 61 74 65 64 0a 2a 2a 20 62 79 20 53 51 4c ocated.** by SQL
1c6a0 69 74 65 2e 20 20 49 66 20 61 6e 20 69 6e 74 65 ite. If an inte
1c6b0 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 rnal allocation
1c6c0 69 73 20 72 65 71 75 65 73 74 65 64 20 0a 2a 2a is requested .**
1c6d0 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65 that would exce
1c6e0 65 64 20 74 68 65 20 73 70 65 63 69 66 69 65 64 ed the specified
1c6f0 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65 33 limit, [sqlite3
1c700 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 _release_memory(
1c710 29 5d 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 )] is.** invoked
1c720 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d one or more tim
1c730 65 73 20 74 6f 20 66 72 65 65 20 75 70 20 73 6f es to free up so
1c740 6d 65 20 73 70 61 63 65 20 62 65 66 6f 72 65 20 me space before
1c750 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a the allocation.*
1c760 2a 20 69 73 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a * is made..**.**
1c770 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 63 61 The limit is ca
1c780 6c 6c 65 64 20 22 73 6f 66 74 22 2c 20 62 65 63 lled "soft", bec
1c790 61 75 73 65 20 69 66 20 5b 73 71 6c 69 74 65 33 ause if [sqlite3
1c7a0 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 _release_memory(
1c7b0 29 5d 20 63 61 6e 6e 6f 74 0a 2a 2a 20 66 72 65 )] cannot.** fre
1c7c0 65 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d e sufficient mem
1c7d0 6f 72 79 20 74 6f 20 70 72 65 76 65 6e 74 20 74 ory to prevent t
1c7e0 68 65 20 6c 69 6d 69 74 20 66 72 6f 6d 20 62 65 he limit from be
1c7f0 69 6e 67 20 65 78 63 65 65 64 65 64 2c 0a 2a 2a ing exceeded,.**
1c800 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 61 the memory is a
1c810 6c 6c 6f 63 61 74 65 64 20 61 6e 79 77 61 79 20 llocated anyway
1c820 61 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 and the current
1c830 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 operation procee
1c840 64 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 67 61 ds..**.** A nega
1c850 74 69 76 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c tive or zero val
1c860 75 65 20 66 6f 72 20 4e 20 6d 65 61 6e 73 20 74 ue for N means t
1c870 68 61 74 20 74 68 65 72 65 20 69 73 20 6e 6f 20 hat there is no
1c880 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 soft heap limit
1c890 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
1c8a0 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 release_memory()
1c8b0 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 ] will only be c
1c8c0 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 alled when memor
1c8d0 79 20 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a y is exhausted..
1c8e0 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 ** The default v
1c8f0 61 6c 75 65 20 66 6f 72 20 74 68 65 20 73 6f 66 alue for the sof
1c900 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 t heap limit is
1c910 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 zero..**.** SQLi
1c920 74 65 20 6d 61 6b 65 73 20 61 20 62 65 73 74 20 te makes a best
1c930 65 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20 effort to honor
1c940 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 the soft heap li
1c950 6d 69 74 2e 20 20 42 75 74 20 69 66 20 69 74 0a mit. But if it.
1c960 2a 2a 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 ** is unable to
1c970 72 65 64 75 63 65 20 6d 65 6d 6f 72 79 20 75 73 reduce memory us
1c980 61 67 65 20 62 65 6c 6f 77 20 74 68 65 20 73 6f age below the so
1c990 66 74 20 6c 69 6d 69 74 2c 20 65 78 65 63 75 74 ft limit, execut
1c9a0 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 ion will.** cont
1c9b0 69 6e 75 65 20 77 69 74 68 6f 75 74 20 65 72 72 inue without err
1c9c0 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63 61 74 69 or or notificati
1c9d0 6f 6e 2e 20 20 54 68 69 73 20 69 73 20 77 68 79 on. This is why
1c9e0 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 0a 2a the limit is .*
1c9f0 2a 20 63 61 6c 6c 65 64 20 61 20 22 73 6f 66 74 * called a "soft
1ca00 22 20 6c 69 6d 69 74 2e 20 20 49 74 20 69 73 20 " limit. It is
1ca10 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a advisory only..*
1ca20 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 *.** Prior to SQ
1ca30 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 Lite version 3.5
1ca40 2e 30 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 .0, this routine
1ca50 20 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65 only constraine
1ca60 64 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 d the memory.**
1ca70 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 61 20 73 allocated by a s
1ca80 69 6e 67 6c 65 20 74 68 72 65 61 64 20 2d 20 74 ingle thread - t
1ca90 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 he same thread i
1caa0 6e 20 77 68 69 63 68 20 74 68 69 73 20 72 6f 75 n which this rou
1cab0 74 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 tine.** runs. B
1cac0 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 eginning with SQ
1cad0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 Lite version 3.5
1cae0 2e 30 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 .0, the soft hea
1caf0 70 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70 p limit is.** ap
1cb00 70 6c 69 65 64 20 63 75 6d 75 6c 61 74 69 76 65 plied cumulative
1cb10 6c 79 20 74 6f 20 61 6c 6c 20 74 68 72 65 61 64 ly to all thread
1cb20 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 s..*/.void sqlit
1cb30 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d e3_soft_heap_lim
1cb40 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 it(int);../*.**
1cb50 43 41 50 49 33 52 45 46 3a 20 20 45 78 74 72 61 CAPI3REF: Extra
1cb60 63 74 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75 ct Metadata Abou
1cb70 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 t A Column Of A
1cb80 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 Table.**.** This
1cb90 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 74 75 routine.** retu
1cba0 72 6e 73 20 6d 65 74 61 2d 64 61 74 61 20 61 62 rns meta-data ab
1cbb0 6f 75 74 20 61 20 73 70 65 63 69 66 69 63 20 63 out a specific c
1cbc0 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69 olumn of a speci
1cbd0 66 69 63 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 fic database.**
1cbe0 74 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65 table accessible
1cbf0 20 75 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 using the conne
1cc00 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 70 61 73 ction handle pas
1cc10 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 sed as the first
1cc20 20 66 75 6e 63 74 69 6f 6e 20 0a 2a 2a 20 61 72 function .** ar
1cc30 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 gument..**.** Th
1cc40 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e e column is iden
1cc50 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65 tified by the se
1cc60 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20 cond, third and
1cc70 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
1cc80 73 20 74 6f 20 0a 2a 2a 20 74 68 69 73 20 66 75 s to .** this fu
1cc90 6e 63 74 69 6f 6e 2e 20 54 68 65 20 73 65 63 6f nction. The seco
1cca0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
1ccb0 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20 either the name
1ccc0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a of the database.
1ccd0 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c ** (i.e. "main",
1cce0 20 22 74 65 6d 70 22 20 6f 72 20 61 6e 20 61 74 "temp" or an at
1ccf0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 29 tached database)
1cd00 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 containing the
1cd10 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 specified.** tab
1cd20 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 69 le or NULL. If i
1cd30 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 t is NULL, then
1cd40 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61 74 all attached dat
1cd50 61 62 61 73 65 73 20 61 72 65 20 73 65 61 72 63 abases are searc
1cd60 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 hed.** for the t
1cd70 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73 able using the s
1cd80 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 61 73 ame algorithm as
1cd90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e the database en
1cda0 67 69 6e 65 20 75 73 65 73 20 74 6f 20 0a 2a 2a gine uses to .**
1cdb0 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 resolve unquali
1cdc0 66 69 65 64 20 74 61 62 6c 65 20 72 65 66 65 72 fied table refer
1cdd0 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ences..**.** The
1cde0 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 third and fourt
1cdf0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 h parameters to
1ce00 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 this function ar
1ce10 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e 64 20 e the table and
1ce20 63 6f 6c 75 6d 6e 20 0a 2a 2a 20 6e 61 6d 65 20 column .** name
1ce30 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20 63 of the desired c
1ce40 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 76 olumn, respectiv
1ce50 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 20 ely. Neither of
1ce60 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 these parameters
1ce70 20 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c .** may be NULL
1ce80 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74 61 20 69 6e 66 ..**.** Meta inf
1ce90 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 74 75 ormation is retu
1cea0 72 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67 20 rned by writing
1ceb0 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f to the memory lo
1cec0 63 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61 cations passed a
1ced0 73 0a 2a 2a 20 74 68 65 20 35 74 68 20 61 6e 64 s.** the 5th and
1cee0 20 73 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 subsequent para
1cef0 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 meters to this f
1cf00 75 6e 63 74 69 6f 6e 2e 20 41 6e 79 20 6f 66 20 unction. Any of
1cf10 74 68 65 73 65 20 0a 2a 2a 20 61 72 67 75 6d 65 these .** argume
1cf20 6e 74 73 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2c nts may be NULL,
1cf30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 in which case t
1cf40 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
1cf50 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 element of meta
1cf60 20 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e .** information
1cf70 20 69 73 20 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a is ommitted..**
1cf80 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 50 61 72 .** <pre>.** Par
1cf90 61 6d 65 74 65 72 20 20 20 20 20 4f 75 74 70 75 ameter Outpu
1cfa0 74 20 54 79 70 65 20 20 20 20 20 20 44 65 73 63 t Type Desc
1cfb0 72 69 70 74 69 6f 6e 0a 2a 2a 20 2d 2d 2d 2d 2d ription.** -----
1cfc0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
1cfd0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a --------------.*
1cfe0 2a 0a 2a 2a 20 20 20 35 74 68 20 20 20 20 20 20 *.** 5th
1cff0 20 20 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 20 const char*
1d000 20 20 20 20 44 61 74 61 20 74 79 70 65 0a 2a 2a Data type.**
1d010 20 20 20 36 74 68 20 20 20 20 20 20 20 20 20 63 6th c
1d020 6f 6e 73 74 20 63 68 61 72 2a 20 20 20 20 20 20 onst char*
1d030 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 66 61 Name of the defa
1d040 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 ult collation se
1d050 71 75 65 6e 63 65 20 0a 2a 2a 20 20 20 37 74 68 quence .** 7th
1d060 20 20 20 20 20 20 20 20 20 69 6e 74 20 20 20 20 int
1d070 20 20 20 20 20 20 20 20 20 20 54 72 75 65 20 69 True i
1d080 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 68 61 73 f the column has
1d090 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 a NOT NULL cons
1d0a0 74 72 61 69 6e 74 0a 2a 2a 20 20 20 38 74 68 20 traint.** 8th
1d0b0 20 20 20 20 20 20 20 20 69 6e 74 20 20 20 20 20 int
1d0c0 20 20 20 20 20 20 20 20 20 54 72 75 65 20 69 66 True if
1d0d0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 70 the column is p
1d0e0 61 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41 art of the PRIMA
1d0f0 52 59 20 4b 45 59 0a 2a 2a 20 20 20 39 74 68 20 RY KEY.** 9th
1d100 20 20 20 20 20 20 20 20 69 6e 74 20 20 20 20 20 int
1d110 20 20 20 20 20 20 20 20 20 54 72 75 65 20 69 66 True if
1d120 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 41 the column is A
1d130 55 54 4f 49 4e 43 52 45 4d 45 4e 54 0a 2a 2a 20 UTOINCREMENT.**
1d140 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 </pre>.**.**.**
1d150 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 The memory point
1d160 65 64 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 ed to by the cha
1d170 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 racter pointers
1d180 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 returned for the
1d190 20 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e .** declaration
1d1a0 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 type and collat
1d1b0 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 ion sequence is
1d1c0 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c valid only until
1d1d0 20 74 68 65 20 6e 65 78 74 20 0a 2a 2a 20 63 61 the next .** ca
1d1e0 6c 6c 20 74 6f 20 61 6e 79 20 73 71 6c 69 74 65 ll to any sqlite
1d1f0 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a API function..*
1d200 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63 *.** If the spec
1d210 69 66 69 65 64 20 74 61 62 6c 65 20 69 73 20 61 ified table is a
1d220 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 ctually a view,
1d230 74 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 69 73 then an error is
1d240 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
1d250 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65 If the specifie
1d260 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 d column is "row
1d270 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f id", "oid" or "_
1d280 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 20 0a rowid_" and an .
1d290 2a 2a 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41 ** INTEGER PRIMA
1d2a0 52 59 20 4b 45 59 20 63 6f 6c 75 6d 6e 20 68 61 RY KEY column ha
1d2b0 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c s been explicitl
1d2c0 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e y declared, then
1d2d0 20 74 68 65 20 6f 75 74 70 75 74 20 0a 2a 2a 20 the output .**
1d2e0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 parameters are s
1d2f0 65 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69 et for the expli
1d300 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 citly declared c
1d310 6f 6c 75 6d 6e 2e 20 49 66 20 74 68 65 72 65 20 olumn. If there
1d320 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 is no.** explici
1d330 74 6c 79 20 64 65 63 6c 61 72 65 64 20 49 50 4b tly declared IPK
1d340 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 column, then th
1d350 65 20 6f 75 74 70 75 74 20 70 61 72 61 6d 65 74 e output paramet
1d360 65 72 73 20 61 72 65 20 73 65 74 20 61 73 20 0a ers are set as .
1d370 2a 2a 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a ** follows:.**.*
1d380 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 * <pre>.** d
1d390 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 ata type: "INTEG
1d3a0 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 ER".** colla
1d3b0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 tion sequence: "
1d3c0 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e BINARY".** n
1d3d0 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 ot null: 0.**
1d3e0 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 primary key: 1
1d3f0 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 .** auto inc
1d400 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 rement: 0.** </p
1d410 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 re>.**.** This f
1d420 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 unction may load
1d430 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 one or more sch
1d440 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61 emas from databa
1d450 73 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a se files. If an.
1d460 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 ** error occurs
1d470 64 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63 during this proc
1d480 65 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72 ess, or if the r
1d490 65 71 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f equested table o
1d4a0 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e r column.** cann
1d4b0 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 ot be found, an
1d4c0 53 51 4c 49 54 45 20 65 72 72 6f 72 20 63 6f 64 SQLITE error cod
1d4d0 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e e is returned an
1d4e0 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 d an error messa
1d4f0 67 65 0a 2a 2a 20 6c 65 66 74 20 69 6e 20 74 68 ge.** left in th
1d500 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c e database handl
1d510 65 20 28 74 6f 20 62 65 20 72 65 74 72 69 65 76 e (to be retriev
1d520 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 ed using sqlite3
1d530 5f 65 72 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a _errmsg())..**.*
1d540 2a 20 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e * This API is on
1d550 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 ly available if
1d560 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 the library was
1d570 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 compiled with th
1d580 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42 e.** SQLITE_ENAB
1d590 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 LE_COLUMN_METADA
1d5a0 54 41 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 TA preprocessor
1d5b0 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a symbol defined..
1d5c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 */.int sqlite3_t
1d5d0 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 able_column_meta
1d5e0 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20 data(. sqlite3
1d5f0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
1d600 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f /* Connectio
1d610 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f n handle */. co
1d620 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d nst char *zDbNam
1d630 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 e, /* Dat
1d640 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55 abase name or NU
1d650 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 LL */. const ch
1d660 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 ar *zTableName,
1d670 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d /* Table nam
1d680 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
1d690 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 r *zColumnName,
1d6a0 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d /* Column nam
1d6b0 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 e */. char cons
1d6c0 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20 t **pzDataType,
1d6d0 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65 /* OUTPUT: De
1d6e0 63 6c 61 72 65 64 20 64 61 74 61 20 74 79 70 65 clared data type
1d6f0 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 */. char const
1d700 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 **pzCollSeq,
1d710 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c /* OUTPUT: Col
1d720 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 lation sequence
1d730 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 name */. int *p
1d740 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20 NotNull,
1d750 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a /* OUTPUT:
1d760 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c True if NOT NUL
1d770 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69 L constraint exi
1d780 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 sts */. int *pP
1d790 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20 rimaryKey,
1d7a0 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 /* OUTPUT:
1d7b0 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70 True if column p
1d7c0 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 art of PK */. i
1d7d0 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20 nt *pAutoinc
1d7e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 /* OU
1d7f0 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f TPUT: True if co
1d800 6c 75 6d 73 20 69 73 20 61 75 74 6f 2d 69 6e 63 lums is auto-inc
1d810 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a rement */.);../*
1d820 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f .** CAPI3REF: Lo
1d830 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 0a ad An Extension.
1d840 2a 2a 0a 2a 2a 20 41 74 74 65 6d 70 74 20 74 6f **.** Attempt to
1d850 20 6c 6f 61 64 20 61 6e 20 53 51 4c 69 74 65 20 load an SQLite
1d860 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 extension librar
1d870 79 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 y contained in t
1d880 68 65 20 66 69 6c 65 0a 2a 2a 20 7a 46 69 6c 65 he file.** zFile
1d890 2e 20 20 54 68 65 20 65 6e 74 72 79 20 70 6f 69 . The entry poi
1d8a0 6e 74 20 69 73 20 7a 50 72 6f 63 2e 20 20 7a 50 nt is zProc. zP
1d8b0 72 6f 63 20 6d 61 79 20 62 65 20 30 20 69 6e 20 roc may be 0 in
1d8c0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 0a 2a which case the.*
1d8d0 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 6e * name of the en
1d8e0 74 72 79 20 70 6f 69 6e 74 20 64 65 66 61 75 6c try point defaul
1d8f0 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65 ts to "sqlite3_e
1d900 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a xtension_init"..
1d910 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 5b 53 51 **.** Return [SQ
1d920 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 LITE_OK] on succ
1d930 65 73 73 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f ess and [SQLITE_
1d940 45 52 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68 ERROR] if someth
1d950 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a ing goes wrong..
1d960 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 65 72 72 6f **.** If an erro
1d970 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70 7a 45 r occurs and pzE
1d980 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c 20 rrMsg is not 0,
1d990 74 68 65 6e 20 66 69 6c 6c 20 2a 70 7a 45 72 72 then fill *pzErr
1d9a0 4d 73 67 20 77 69 74 68 20 0a 2a 2a 20 65 72 72 Msg with .** err
1d9b0 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 2e or message text.
1d9c0 20 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 The calling fu
1d9d0 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 66 72 nction should fr
1d9e0 65 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 0a 2a ee this memory.*
1d9f0 2a 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 * by calling [sq
1da00 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a lite3_free()]..*
1da10 2a 0a 2a 2a 20 45 78 74 65 6e 73 69 6f 6e 20 6c *.** Extension l
1da20 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65 20 65 oading must be e
1da30 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 nabled using [sq
1da40 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 lite3_enable_loa
1da50 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a d_extension()].*
1da60 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 * prior to calli
1da70 6e 67 20 74 68 69 73 20 41 50 49 20 6f 72 20 61 ng this API or a
1da80 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 n error will be
1da90 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 returned..*/.int
1daa0 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 sqlite3_load_ex
1dab0 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 tension(. sqlit
1dac0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
1dad0 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 74 /* Load the ext
1dae0 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 ension into this
1daf0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1db00 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 tion */. const
1db10 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 char *zFile,
1db20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 /* Name of the s
1db30 68 61 72 65 64 20 6c 69 62 72 61 72 79 20 63 6f hared library co
1db40 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 ntaining extensi
1db50 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 on */. const ch
1db60 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a ar *zProc, /*
1db70 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 Entry point. D
1db80 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c erived from zFil
1db90 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 e if 0 */. char
1dba0 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 20 **pzErrMsg
1dbb0 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 6d /* Put error m
1dbc0 65 73 73 61 67 65 20 68 65 72 65 20 69 66 20 6e essage here if n
1dbd0 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a ot 0 */.);../*.*
1dbe0 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 6e 61 * CAPI3REF: Ena
1dbf0 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 ble Or Disable E
1dc00 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 xtension Loading
1dc10 0a 2a 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f 74 .**.** So as not
1dc20 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74 to open securit
1dc30 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 y holes in older
1dc40 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 applications th
1dc50 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 at are.** unprep
1dc60 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74 ared to deal wit
1dc70 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 h extension load
1dc80 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 ing, and as a me
1dc90 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 ans of disabling
1dca0 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f .** extension lo
1dcb0 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c ading while eval
1dcc0 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 uating user-ente
1dcd0 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c red SQL, the fol
1dce0 6c 6f 77 69 6e 67 0a 2a 2a 20 41 50 49 20 69 73 lowing.** API is
1dcf0 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72 provided to tur
1dd00 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c n the [sqlite3_l
1dd10 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d oad_extension()]
1dd20 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e mechanism on an
1dd30 64 0a 2a 2a 20 6f 66 66 2e 20 20 49 74 20 69 73 d.** off. It is
1dd40 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e off by default.
1dd50 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 31 38 See ticket #18
1dd60 36 33 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 20 74 63..**.** Call t
1dd70 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 his routine with
1dd80 20 6f 6e 6f 66 66 3d 3d 31 20 74 6f 20 74 75 72 onoff==1 to tur
1dd90 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 n extension load
1dda0 69 6e 67 20 6f 6e 0a 2a 2a 20 61 6e 64 20 63 61 ing on.** and ca
1ddb0 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 ll it with onoff
1ddc0 3d 3d 30 20 74 6f 20 74 75 72 6e 20 69 74 20 62 ==0 to turn it b
1ddd0 61 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a ack off again..*
1dde0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e /.int sqlite3_en
1ddf0 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 able_load_extens
1de00 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c ion(sqlite3 *db,
1de10 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a int onoff);../*
1de20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 .** CAPI3REF: Ma
1de30 6b 65 20 41 72 72 61 6e 67 65 6d 65 6e 74 73 20 ke Arrangements
1de40 54 6f 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 To Automatically
1de50 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 Load An Extensi
1de60 6f 6e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 on.**.** Registe
1de70 72 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 65 r an extension e
1de80 6e 74 72 79 20 70 6f 69 6e 74 20 74 68 61 74 20 ntry point that
1de90 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 is automatically
1dea0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e invoked.** when
1deb0 65 76 65 72 20 61 20 6e 65 77 20 64 61 74 61 62 ever a new datab
1dec0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
1ded0 73 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 0a 2a s opened using.*
1dee0 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 * [sqlite3_open(
1def0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
1df00 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 n16()], or [sqli
1df10 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a te3_open_v2()]..
1df20 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 63 **.** This API c
1df30 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64 20 61 74 an be invoked at
1df40 20 70 72 6f 67 72 61 6d 20 73 74 61 72 74 75 70 program startup
1df50 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72 65 67 in order to reg
1df60 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 ister.** one or
1df70 6d 6f 72 65 20 73 74 61 74 69 63 61 6c 6c 79 20 more statically
1df80 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f 6e linked extension
1df90 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 61 s that will be a
1dfa0 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20 61 vailable.** to a
1dfb0 6c 6c 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 ll new database
1dfc0 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a connections..**.
1dfd0 2a 2a 20 44 75 70 6c 69 63 61 74 65 20 65 78 74 ** Duplicate ext
1dfe0 65 6e 73 69 6f 6e 73 20 61 72 65 20 64 65 74 65 ensions are dete
1dff0 63 74 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 cted so calling
1e000 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 6c this routine mul
1e010 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 tiple.** times w
1e020 69 74 68 20 74 68 65 20 73 61 6d 65 20 65 78 74 ith the same ext
1e030 65 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65 ension is harmle
1e040 73 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 ss..**.** This r
1e050 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20 outine stores a
1e060 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65 pointer to the e
1e070 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61 xtension in an a
1e080 72 72 61 79 0a 2a 2a 20 74 68 61 74 20 69 73 20 rray.** that is
1e090 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 6d 61 obtained from ma
1e0a0 6c 6c 6f 63 28 29 2e 20 20 49 66 20 79 6f 75 20 lloc(). If you
1e0b0 72 75 6e 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 run a memory lea
1e0c0 6b 0a 2a 2a 20 63 68 65 63 6b 65 72 20 6f 6e 20 k.** checker on
1e0d0 79 6f 75 72 20 70 72 6f 67 72 61 6d 20 61 6e 64 your program and
1e0e0 20 69 74 20 72 65 70 6f 72 74 73 20 61 20 6c 65 it reports a le
1e0f0 61 6b 20 62 65 63 61 75 73 65 20 6f 66 20 74 68 ak because of th
1e100 69 73 0a 2a 2a 20 61 72 72 61 79 2c 20 74 68 65 is.** array, the
1e110 6e 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 n invoke [sqlite
1e120 33 5f 61 75 74 6f 6d 61 74 69 63 5f 65 78 74 65 3_automatic_exte
1e130 6e 73 69 6f 6e 5f 72 65 73 65 74 28 29 5d 20 70 nsion_reset()] p
1e140 72 69 6f 72 0a 2a 2a 20 74 6f 20 73 68 75 74 64 rior.** to shutd
1e150 6f 77 6e 20 74 6f 20 66 72 65 65 20 74 68 65 20 own to free the
1e160 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 75 memory..**.** Au
1e170 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f tomatic extensio
1e180 6e 73 20 61 70 70 6c 79 20 61 63 72 6f 73 73 20 ns apply across
1e190 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a 0a all threads..**.
1e1a0 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 ** This interfac
1e1b0 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 e is experimenta
1e1c0 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 l and is subject
1e1d0 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a to change or.**
1e1e0 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 removal in futu
1e1f0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 re releases of S
1e200 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 QLite..*/.int sq
1e210 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e lite3_auto_exten
1e220 73 69 6f 6e 28 76 6f 69 64 20 2a 78 45 6e 74 72 sion(void *xEntr
1e230 79 50 6f 69 6e 74 29 3b 0a 0a 0a 2f 2a 0a 2a 2a yPoint);.../*.**
1e240 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 CAPI3REF: Reset
1e250 20 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65 6e Automatic Exten
1e260 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a sion Loading.**.
1e270 2a 2a 20 44 69 73 61 62 6c 65 20 61 6c 6c 20 70 ** Disable all p
1e280 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 reviously regist
1e290 65 72 65 64 20 61 75 74 6f 6d 61 74 69 63 20 65 ered automatic e
1e2a0 78 74 65 6e 73 69 6f 6e 73 2e 20 20 54 68 69 73 xtensions. This
1e2b0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f .** routine undo
1e2c0 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 es the effect of
1e2d0 20 61 6c 6c 20 70 72 69 6f 72 20 5b 73 71 6c 69 all prior [sqli
1e2e0 74 65 33 5f 61 75 74 6f 6d 61 74 69 63 5f 65 78 te3_automatic_ex
1e2f0 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 63 61 tension()].** ca
1e300 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 lls..**.** This
1e310 63 61 6c 6c 20 64 69 73 61 62 6c 65 64 20 61 75 call disabled au
1e320 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f tomatic extensio
1e330 6e 73 20 69 6e 20 61 6c 6c 20 74 68 72 65 61 64 ns in all thread
1e340 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e s..**.** This in
1e350 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72 terface is exper
1e360 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 imental and is s
1e370 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 ubject to change
1e380 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 or.** removal i
1e390 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
1e3a0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a s of SQLite..*/.
1e3b0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
1e3c0 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f et_auto_extensio
1e3d0 6e 28 76 6f 69 64 29 3b 0a 0a 0a 2f 2a 0a 2a 2a n(void);.../*.**
1e3e0 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 **** EXPERIMENTA
1e3f0 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 L - subject to c
1e400 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f hange without no
1e410 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a tice ***********
1e420 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e ***.**.** The in
1e430 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 terface to the v
1e440 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 irtual-table mec
1e450 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e hanism is curren
1e460 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a tly considered.*
1e470 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 * to be experime
1e480 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 ntal. The inter
1e490 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 face might chang
1e4a0 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c e in incompatibl
1e4b0 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 e ways..** If th
1e4c0 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 is is a problem
1e4d0 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 for you, do not
1e4e0 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 use the interfac
1e4f0 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a e at this time..
1e500 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 **.** When the v
1e510 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 irtual-table mec
1e520 68 61 6e 69 73 6d 20 73 74 61 62 6c 69 7a 65 73 hanism stablizes
1e530 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 , we will declar
1e540 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 e the.** interfa
1e550 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 ce fixed, suppor
1e560 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c t it indefinitel
1e570 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 y, and remove th
1e580 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a is comment..*/..
1e590 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73 /*.** Structures
1e5a0 20 75 73 65 64 20 62 79 20 74 68 65 20 76 69 72 used by the vir
1e5b0 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 tual table inter
1e5c0 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20 face.*/.typedef
1e5d0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 struct sqlite3_v
1e5e0 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62 tab sqlite3_vtab
1e5f0 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 ;.typedef struct
1e600 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 sqlite3_index_i
1e610 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 nfo sqlite3_inde
1e620 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20 x_info;.typedef
1e630 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 struct sqlite3_v
1e640 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74 tab_cursor sqlit
1e650 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a e3_vtab_cursor;.
1e660 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
1e670 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71 qlite3_module sq
1e680 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f lite3_module;../
1e690 2a 0a 2a 2a 20 41 20 6d 6f 64 75 6c 65 20 69 73 *.** A module is
1e6a0 20 61 20 63 6c 61 73 73 20 6f 66 20 76 69 72 74 a class of virt
1e6b0 75 61 6c 20 74 61 62 6c 65 73 2e 20 20 45 61 63 ual tables. Eac
1e6c0 68 20 6d 6f 64 75 6c 65 20 69 73 20 64 65 66 69 h module is defi
1e6d0 6e 65 64 0a 2a 2a 20 62 79 20 61 6e 20 69 6e 73 ned.** by an ins
1e6e0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 66 6f 6c tance of the fol
1e6f0 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 lowing structure
1e700 2e 20 20 54 68 69 73 20 73 74 72 75 63 74 75 72 . This structur
1e710 65 20 63 6f 6e 73 69 73 74 73 0a 2a 2a 20 6d 6f e consists.** mo
1e720 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 20 stly of methods
1e730 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a for the module..
1e740 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 */.struct sqlite
1e750 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 3_module {. int
1e760 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 iVersion;. int
1e770 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69 (*xCreate)(sqli
1e780 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 te3*, void *pAux
1e790 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,.
1e7a0 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 int argc, const
1e7b0 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 char *const*arg
1e7c0 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 v,.
1e7d0 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a sqlite3_vtab *
1e7e0 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 *ppVTab, char**)
1e7f0 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 ;. int (*xConne
1e800 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f ct)(sqlite3*, vo
1e810 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 id *pAux,.
1e820 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 int arg
1e830 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 c, const char *c
1e840 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 onst*argv,.
1e850 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 sqlite
1e860 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 3_vtab **ppVTab,
1e870 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 char**);. int
1e880 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 71 (*xBestIndex)(sq
1e890 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 lite3_vtab *pVTa
1e8a0 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 b, sqlite3_index
1e8b0 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 _info*);. int (
1e8c0 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 *xDisconnect)(sq
1e8d0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 lite3_vtab *pVTa
1e8e0 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 b);. int (*xDes
1e8f0 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74 troy)(sqlite3_vt
1e900 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e ab *pVTab);. in
1e910 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 t (*xOpen)(sqlit
1e920 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 e3_vtab *pVTab,
1e930 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 sqlite3_vtab_cur
1e940 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b sor **ppCursor);
1e950 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 . int (*xClose)
1e960 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 (sqlite3_vtab_cu
1e970 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a rsor*);. int (*
1e980 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33 xFilter)(sqlite3
1e990 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 _vtab_cursor*, i
1e9a0 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 nt idxNum, const
1e9b0 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 char *idxStr,.
1e9c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 i
1e9d0 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33 nt argc, sqlite3
1e9e0 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a _value **argv);.
1e9f0 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 int (*xNext)(s
1ea00 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 qlite3_vtab_curs
1ea10 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 or*);. int (*xE
1ea20 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 of)(sqlite3_vtab
1ea30 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 _cursor*);. int
1ea40 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 (*xColumn)(sqli
1ea50 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a te3_vtab_cursor*
1ea60 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 , sqlite3_contex
1ea70 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 t*, int);. int
1ea80 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65 (*xRowid)(sqlite
1ea90 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 3_vtab_cursor*,
1eaa0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 sqlite3_int64 *p
1eab0 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a Rowid);. int (*
1eac0 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 33 xUpdate)(sqlite3
1ead0 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 _vtab *, int, sq
1eae0 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 lite3_value **,
1eaf0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29 sqlite3_int64 *)
1eb00 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e ;. int (*xBegin
1eb10 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a )(sqlite3_vtab *
1eb20 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a pVTab);. int (*
1eb30 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 xSync)(sqlite3_v
1eb40 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 tab *pVTab);. i
1eb50 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 nt (*xCommit)(sq
1eb60 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 lite3_vtab *pVTa
1eb70 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c b);. int (*xRol
1eb80 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 lback)(sqlite3_v
1eb90 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 tab *pVTab);. i
1eba0 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 nt (*xFindFuncti
1ebb0 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 on)(sqlite3_vtab
1ebc0 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 *pVtab, int nAr
1ebd0 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a g, const char *z
1ebe0 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20 Name,.
1ebf0 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 voi
1ec00 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c d (**pxFunc)(sql
1ec10 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e ite3_context*,in
1ec20 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t,sqlite3_value*
1ec30 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 *),.
1ec40 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 void
1ec50 2a 2a 70 70 41 72 67 29 3b 0a 0a 20 20 69 6e 74 **ppArg);.. int
1ec60 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 (*xRename)(sqli
1ec70 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c te3_vtab *pVtab,
1ec80 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 const char *zNe
1ec90 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 w);.};../*.** Th
1eca0 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f e sqlite3_index_
1ecb0 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20 61 info structure a
1ecc0 6e 64 20 69 74 73 20 73 75 62 73 74 72 75 63 74 nd its substruct
1ecd0 75 72 65 73 20 69 73 20 75 73 65 64 20 74 6f 0a ures is used to.
1ece0 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 ** pass informat
1ecf0 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 ion into and rec
1ed00 65 69 76 65 20 74 68 65 20 72 65 70 6c 79 20 66 eive the reply f
1ed10 72 6f 6d 20 74 68 65 20 78 42 65 73 74 49 6e 64 rom the xBestInd
1ed20 65 78 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 ex.** method of
1ed30 61 6e 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c an sqlite3_modul
1ed40 65 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20 75 e. The fields u
1ed50 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 nder **Inputs**
1ed60 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 are the.** input
1ed70 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20 s to xBestIndex
1ed80 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c and are read-onl
1ed90 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20 69 y. xBestIndex i
1eda0 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 nserts its.** re
1edb0 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a sults into the *
1edc0 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 *Outputs** field
1edd0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43 6f s..**.** The aCo
1ede0 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 nstraint[] array
1edf0 20 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 records WHERE c
1ee00 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 lause constraint
1ee10 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d s of the.** form
1ee20 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 20 20 20 20 20 :.**.**
1ee30 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 0a 2a column OP expr.*
1ee40 2a 0a 2a 2a 20 57 68 65 72 65 20 4f 50 20 69 73 *.** Where OP is
1ee50 20 3d 2c 20 3c 2c 20 3c 3d 2c 20 3e 2c 20 6f 72 =, <, <=, >, or
1ee60 20 3e 3d 2e 20 20 54 68 65 20 70 61 72 74 69 63 >=. The partic
1ee70 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73 ular operator is
1ee80 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 43 stored.** in aC
1ee90 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20 onstraint[].op.
1eea0 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 The index of th
1eeb0 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 e column is stor
1eec0 65 64 20 69 6e 20 0a 2a 2a 20 61 43 6f 6e 73 74 ed in .** aConst
1eed0 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e raint[].iColumn.
1eee0 20 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e aConstraint[].
1eef0 75 73 61 62 6c 65 20 69 73 20 54 52 55 45 20 69 usable is TRUE i
1ef00 66 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e f the.** expr on
1ef10 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 the right-hand
1ef20 73 69 64 65 20 63 61 6e 20 62 65 20 65 76 61 6c side can be eval
1ef30 75 61 74 65 64 20 28 61 6e 64 20 74 68 75 73 20 uated (and thus
1ef40 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a the constraint.*
1ef50 2a 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e 64 * is usable) and
1ef60 20 66 61 6c 73 65 20 69 66 20 69 74 20 63 61 6e false if it can
1ef70 6e 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f not..**.** The o
1ef80 70 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 ptimizer automat
1ef90 69 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 74 ically inverts t
1efa0 65 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 6d erms of the form
1efb0 20 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e "expr OP column
1efc0 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f ".** and makes o
1efd0 74 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61 74 ther simplificat
1efe0 69 6e 6f 73 20 74 6f 20 74 68 65 20 57 48 45 52 inos to the WHER
1eff0 45 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 61 E clause in an a
1f000 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74 ttempt to.** get
1f010 20 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20 63 as many WHERE c
1f020 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74 6f lause terms into
1f030 20 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20 the form shown
1f040 61 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62 6c above as possibl
1f050 65 2e 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74 e..** The aConst
1f060 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e raint[] array on
1f070 6c 79 20 72 65 70 6f 72 74 73 20 57 48 45 52 45 ly reports WHERE
1f080 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e clause terms in
1f090 20 74 68 65 20 63 6f 72 72 65 63 74 0a 2a 2a 20 the correct.**
1f0a0 66 6f 72 6d 20 74 68 61 74 20 72 65 66 65 72 20 form that refer
1f0b0 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 to the particula
1f0c0 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 r virtual table
1f0d0 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a being queried..*
1f0e0 2a 0a 2a 2a 20 49 6e 66 6f 72 6d 61 74 69 6f 6e *.** Information
1f0f0 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52 about the ORDER
1f100 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 74 BY clause is st
1f110 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79 ored in aOrderBy
1f120 5b 5d 2e 0a 2a 2a 20 45 61 63 68 20 74 65 72 6d []..** Each term
1f130 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65 63 of aOrderBy rec
1f140 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 ords a column of
1f150 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c the ORDER BY cl
1f160 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ause..**.** The
1f170 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f xBestIndex metho
1f180 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e d must fill aCon
1f190 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 straintUsage[] w
1f1a0 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a ith information.
1f1b0 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70 61 ** about what pa
1f1c0 72 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73 73 rameters to pass
1f1d0 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 49 66 to xFilter. If
1f1e0 20 61 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65 argvIndex>0 the
1f1f0 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68 n.** the right-h
1f200 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65 20 and side of the
1f210 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 corresponding aC
1f220 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 onstraint[] is e
1f230 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 valuated.** and
1f240 62 65 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76 becomes the argv
1f250 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69 Index-th entry i
1f260 6e 20 61 72 67 76 2e 20 20 49 66 20 61 43 6f 6e n argv. If aCon
1f270 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f straintUsage[].o
1f280 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20 mit.** is true,
1f290 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 61 then the constra
1f2a0 69 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20 74 int is assumed t
1f2b0 6f 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c o be fully handl
1f2c0 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 72 ed by the.** vir
1f2d0 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69 tual table and i
1f2e0 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 67 s not checked ag
1f2f0 61 69 6e 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a ain by SQLite..*
1f300 2a 0a 2a 2a 20 54 68 65 20 69 64 78 4e 75 6d 20 *.** The idxNum
1f310 61 6e 64 20 69 64 78 50 74 72 20 76 61 6c 75 65 and idxPtr value
1f320 73 20 61 72 65 20 72 65 63 6f 72 64 65 64 20 61 s are recorded a
1f330 6e 64 20 70 61 73 73 65 64 20 69 6e 74 6f 20 78 nd passed into x
1f340 46 69 6c 74 65 72 2e 0a 2a 2a 20 73 71 6c 69 74 Filter..** sqlit
1f350 65 33 5f 66 72 65 65 28 29 20 69 73 20 75 73 65 e3_free() is use
1f360 64 20 74 6f 20 66 72 65 65 20 69 64 78 50 74 72 d to free idxPtr
1f370 20 69 66 20 6e 65 65 64 54 6f 46 72 65 65 49 64 if needToFreeId
1f380 78 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a xPtr is true..**
1f390 0a 2a 2a 20 54 68 65 20 6f 72 64 65 72 42 79 43 .** The orderByC
1f3a0 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 onsumed means th
1f3b0 61 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 78 at output from x
1f3c0 46 69 6c 74 65 72 20 77 69 6c 6c 20 6f 63 63 75 Filter will occu
1f3d0 72 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72 r in.** the corr
1f3e0 65 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61 74 ect order to sat
1f3f0 69 73 66 79 20 74 68 65 20 4f 52 44 45 52 20 42 isfy the ORDER B
1f400 59 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61 74 Y clause so that
1f410 20 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 no separate.**
1f420 73 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73 20 sorting step is
1f430 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 required..**.**
1f440 54 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 The estimatedCos
1f450 74 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65 73 t value is an es
1f460 74 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63 6f timate of the co
1f470 73 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a st of doing the.
1f480 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c 6f ** particular lo
1f490 6f 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 63 okup. A full sc
1f4a0 61 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77 69 an of a table wi
1f4b0 74 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f th N entries sho
1f4c0 75 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f uld have.** a co
1f4d0 73 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61 st of N. A bina
1f4e0 72 79 20 73 65 61 72 63 68 20 6f 66 20 61 20 74 ry search of a t
1f4f0 61 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 65 able of N entrie
1f500 73 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61 0a s should have a.
1f510 2a 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72 6f ** cost of appro
1f520 78 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e ximately log(N).
1f530 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 .*/.struct sqlit
1f540 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a e3_index_info {.
1f550 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20 /* Inputs */.
1f560 20 63 6f 6e 73 74 20 69 6e 74 20 6e 43 6f 6e 73 const int nCons
1f570 74 72 61 69 6e 74 3b 20 20 20 20 20 2f 2a 20 4e traint; /* N
1f580 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73 umber of entries
1f590 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 in aConstraint
1f5a0 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 */. const struc
1f5b0 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f t sqlite3_index_
1f5c0 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20 constraint {.
1f5d0 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 int iColumn;
1f5e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 /* C
1f5f0 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 olumn on left-ha
1f600 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74 nd side of const
1f610 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e raint */. un
1f620 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20 signed char op;
1f630 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74 /* Const
1f640 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a raint operator *
1f650 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 /. unsigned
1f660 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20 char usable;
1f670 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73 /* True if this
1f680 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75 constraint is u
1f690 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e sable */. in
1f6a0 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20 t iTermOffset;
1f6b0 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 /* Used
1f6c0 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65 internally - xBe
1f6d0 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69 stIndex should i
1f6e0 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 63 6f gnore */. } *co
1f6f0 6e 73 74 20 61 43 6f 6e 73 74 72 61 69 6e 74 3b nst aConstraint;
1f700 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f /* Table o
1f710 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 f WHERE clause c
1f720 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20 onstraints */.
1f730 63 6f 6e 73 74 20 69 6e 74 20 6e 4f 72 64 65 72 const int nOrder
1f740 42 79 3b 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 By; /* Nu
1f750 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e mber of terms in
1f760 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c the ORDER BY cl
1f770 61 75 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ause */. const
1f780 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 struct sqlite3_i
1f790 6e 64 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20 ndex_orderby {.
1f7a0 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b int iColumn;
1f7b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
1f7c0 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a Column number *
1f7d0 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 /. unsigned
1f7e0 63 68 61 72 20 64 65 73 63 3b 20 20 20 20 20 20 char desc;
1f7f0 20 2f 2a 20 54 72 75 65 20 66 6f 72 20 44 45 53 /* True for DES
1f800 43 2e 20 20 46 61 6c 73 65 20 66 6f 72 20 41 53 C. False for AS
1f810 43 2e 20 2a 2f 0a 20 20 7d 20 2a 63 6f 6e 73 74 C. */. } *const
1f820 20 61 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 aOrderBy;
1f830 20 20 20 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 /* The ORDER
1f840 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 0a 20 20 BY clause */..
1f850 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20 /* Outputs */.
1f860 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 struct sqlite3_i
1f870 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f ndex_constraint_
1f880 75 73 61 67 65 20 7b 0a 20 20 20 20 69 6e 74 20 usage {. int
1f890 61 72 67 76 49 6e 64 65 78 3b 20 20 20 20 20 20 argvIndex;
1f8a0 20 20 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63 /* if >0, c
1f8b0 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 70 61 72 onstraint is par
1f8c0 74 20 6f 66 20 61 72 67 76 20 74 6f 20 78 46 69 t of argv to xFi
1f8d0 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69 lter */. unsi
1f8e0 67 6e 65 64 20 63 68 61 72 20 6f 6d 69 74 3b 20 gned char omit;
1f8f0 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 /* Do not c
1f900 6f 64 65 20 61 20 74 65 73 74 20 66 6f 72 20 74 ode a test for t
1f910 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a his constraint *
1f920 2f 0a 20 20 7d 20 2a 63 6f 6e 73 74 20 61 43 6f /. } *const aCo
1f930 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b 0a 20 nstraintUsage;.
1f940 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20 20 20 int idxNum;
1f950 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e /* N
1f960 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20 69 64 umber used to id
1f970 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64 65 78 entify the index
1f980 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64 78 53 */. char *idxS
1f990 74 72 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 tr;
1f9a0 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73 73 /* String, poss
1f9b0 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 ibly obtained fr
1f9c0 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f om sqlite3_mallo
1f9d0 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54 c */. int needT
1f9e0 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20 20 20 oFreeIdxStr;
1f9f0 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53 74 72 /* Free idxStr
1fa00 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 using sqlite3_f
1fa10 72 65 65 28 29 20 69 66 20 74 72 75 65 20 2a 2f ree() if true */
1fa20 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 79 43 6f . int orderByCo
1fa30 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a nsumed; /*
1fa40 20 54 72 75 65 20 69 66 20 6f 75 74 70 75 74 20 True if output
1fa50 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64 65 72 is already order
1fa60 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65 ed */. double e
1fa70 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 20 20 stimatedCost;
1fa80 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 /* Estimated
1fa90 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20 74 68 cost of using th
1faa0 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 23 is index */.};.#
1fab0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
1fac0 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 DEX_CONSTRAINT_E
1fad0 51 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 Q 2.#define S
1fae0 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 QLITE_INDEX_CONS
1faf0 54 52 41 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 TRAINT_GT 4.#
1fb00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
1fb10 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c DEX_CONSTRAINT_L
1fb20 45 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 E 8.#define S
1fb30 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 QLITE_INDEX_CONS
1fb40 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a TRAINT_LT 16.
1fb50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
1fb60 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f NDEX_CONSTRAINT_
1fb70 47 45 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65 GE 32.#define
1fb80 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f SQLITE_INDEX_CO
1fb90 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 NSTRAINT_MATCH 6
1fba0 34 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 4../*.** This ro
1fbb0 75 74 69 6e 65 20 69 73 20 75 73 65 64 20 74 6f utine is used to
1fbc0 20 72 65 67 69 73 74 65 72 20 61 20 6e 65 77 20 register a new
1fbd0 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 77 69 74 68 module name with
1fbe0 20 61 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f an SQLite.** co
1fbf0 6e 6e 65 63 74 69 6f 6e 2e 20 20 4d 6f 64 75 6c nnection. Modul
1fc00 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20 e names must be
1fc10 72 65 67 69 73 74 65 72 65 64 20 62 65 66 6f 72 registered befor
1fc20 65 20 63 72 65 61 74 69 6e 67 20 6e 65 77 0a 2a e creating new.*
1fc30 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 * virtual tables
1fc40 20 6f 6e 20 74 68 65 20 6d 6f 64 75 6c 65 2c 20 on the module,
1fc50 6f 72 20 62 65 66 6f 72 65 20 75 73 69 6e 67 20 or before using
1fc60 70 72 65 65 78 69 73 74 69 6e 67 20 76 69 72 74 preexisting virt
1fc70 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 73 20 6f 66 ual.** tables of
1fc80 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a the module..*/.
1fc90 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 int sqlite3_crea
1fca0 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c te_module(. sql
1fcb0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
1fcc0 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 /* SQLit
1fcd0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 e connection to
1fce0 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 register module
1fcf0 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 with */. const
1fd00 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 char *zName,
1fd10 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 /* Name of
1fd20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 the module */.
1fd30 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f const sqlite3_mo
1fd40 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 dule *, /* Me
1fd50 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f thods for the mo
1fd60 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a dule */. void *
1fd70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1fd80 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 /* Client d
1fd90 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f ata for xCreate/
1fda0 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a xConnect */.);..
1fdb0 2f 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 /*.** This routi
1fdc0 6e 65 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 ne is identical
1fdd0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 to the sqlite3_c
1fde0 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 20 6d reate_module() m
1fdf0 65 74 68 6f 64 20 61 62 6f 76 65 2c 0a 2a 2a 20 ethod above,.**
1fe00 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 except that it a
1fe10 6c 6c 6f 77 73 20 61 20 64 65 73 74 72 75 63 74 llows a destruct
1fe20 6f 72 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 or function to b
1fe30 65 20 73 70 65 63 69 66 69 65 64 2e 20 49 74 20 e specified. It
1fe40 69 73 0a 2a 2a 20 65 76 65 6e 20 6d 6f 72 65 20 is.** even more
1fe50 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 74 68 61 experimental tha
1fe60 6e 20 74 68 65 20 72 65 73 74 20 6f 66 20 74 68 n the rest of th
1fe70 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 e virtual tables
1fe80 20 41 50 49 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c API..*/.int sql
1fe90 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 ite3_create_modu
1fea0 6c 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 le_v2(. sqlite3
1feb0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
1fec0 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f /* SQLite co
1fed0 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 nnection to regi
1fee0 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 ster module with
1fef0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
1ff00 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 *zName,
1ff10 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 /* Name of the
1ff20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 module */. cons
1ff30 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 t sqlite3_module
1ff40 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f 64 *, /* Method
1ff50 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 s for the module
1ff60 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 */. void *,
1ff70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1ff80 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 /* Client data
1ff90 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e for xCreate/xCon
1ffa0 6e 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a nect */. void(*
1ffb0 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 xDestroy)(void*)
1ffc0 20 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 /* Module d
1ffd0 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 estructor functi
1ffe0 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 on */.);../*.**
1fff0 45 76 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70 Every module imp
20000 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 lementation uses
20010 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 a subclass of t
20020 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 he following str
20030 75 63 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73 ucture.** to des
20040 63 72 69 62 65 20 61 20 70 61 72 74 69 63 75 6c cribe a particul
20050 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 ar instance of t
20060 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 he module. Each
20070 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a subclass will.*
20080 2a 20 62 65 20 74 61 79 6c 6f 72 65 64 20 74 6f * be taylored to
20090 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 the specific ne
200a0 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c eds of the modul
200b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
200c0 2e 20 20 20 54 68 65 0a 2a 2a 20 70 75 72 70 6f . The.** purpo
200d0 73 65 20 6f 66 20 74 68 69 73 20 73 75 70 65 72 se of this super
200e0 63 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66 69 class is to defi
200f0 6e 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64 ne certain field
20100 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d 6d 6f s that are commo
20110 6e 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 n.** to all modu
20120 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
20130 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 ns..**.** Virtua
20140 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 l tables methods
20150 20 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f can set an erro
20160 72 20 6d 65 73 73 61 67 65 20 62 79 20 61 73 73 r message by ass
20170 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 igning a.** stri
20180 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ng obtained from
20190 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 sqlite3_mprintf
201a0 28 29 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 () to zErrMsg.
201b0 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c The method shoul
201c0 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 74 d.** take care t
201d0 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73 74 hat any prior st
201e0 72 69 6e 67 20 69 73 20 66 72 65 65 64 20 62 79 ring is freed by
201f0 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 a call to sqlit
20200 65 33 5f 66 72 65 65 28 29 0a 2a 2a 20 70 72 69 e3_free().** pri
20210 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 or to assigning
20220 61 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20 a new string to
20230 7a 45 72 72 4d 73 67 2e 20 20 41 66 74 65 72 20 zErrMsg. After
20240 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 the error messag
20250 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65 e.** is delivere
20260 64 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65 d up to the clie
20270 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 nt application,
20280 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 the string will
20290 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 be automatically
202a0 0a 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c .** freed by sql
202b0 69 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20 ite3_free() and
202c0 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c the zErrMsg fiel
202d0 64 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 d will be zeroed
202e0 2e 20 20 4e 6f 74 65 0a 2a 2a 20 74 68 61 74 20 . Note.** that
202f0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
20300 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 66 72 ) and sqlite3_fr
20310 65 65 28 29 20 61 72 65 20 75 73 65 64 20 6f 6e ee() are used on
20320 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 the zErrMsg fie
20330 6c 64 0a 2a 2a 20 73 69 6e 63 65 20 76 69 72 74 ld.** since virt
20340 75 61 6c 20 74 61 62 6c 65 73 20 61 72 65 20 63 ual tables are c
20350 6f 6d 6d 6f 6e 6c 79 20 69 6d 70 6c 65 6d 65 6e ommonly implemen
20360 74 65 64 20 69 6e 20 6c 6f 61 64 61 62 6c 65 20 ted in loadable
20370 65 78 74 65 6e 73 69 6f 6e 73 20 77 68 69 63 68 extensions which
20380 0a 2a 2a 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 .** do not have
20390 61 63 63 65 73 73 20 74 6f 20 73 71 6c 69 74 65 access to sqlite
203a0 33 4d 50 72 69 6e 74 66 28 29 20 6f 72 20 73 71 3MPrintf() or sq
203b0 6c 69 74 65 33 46 72 65 65 28 29 2e 0a 2a 2f 0a lite3Free()..*/.
203c0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 struct sqlite3_v
203d0 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71 tab {. const sq
203e0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d lite3_module *pM
203f0 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d odule; /* The m
20400 6f 64 75 6c 65 20 66 6f 72 20 74 68 69 73 20 76 odule for this v
20410 69 72 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a irtual table */.
20420 20 20 69 6e 74 20 6e 52 65 66 3b 20 20 20 20 20 int nRef;
20430 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
20440 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e /* Used intern
20450 61 6c 6c 79 20 2a 2f 0a 20 20 63 68 61 72 20 2a ally */. char *
20460 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 20 20 20 zErrMsg;
20470 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 /* Err
20480 6f 72 20 6d 65 73 73 61 67 65 20 66 72 6f 6d 20 or message from
20490 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
204a0 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 ) */. /* Virtua
204b0 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e l table implemen
204c0 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 tations will typ
204d0 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 ically add addit
204e0 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a ional fields */.
204f0 7d 3b 0a 0a 2f 2a 20 45 76 65 72 79 20 6d 6f 64 };../* Every mod
20500 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ule implementati
20510 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 on uses a subcla
20520 73 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 ss of the follow
20530 69 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a 2a ing structure.**
20540 20 74 6f 20 64 65 73 63 72 69 62 65 20 63 75 72 to describe cur
20550 73 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74 20 sors that point
20560 69 6e 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c into the virtual
20570 20 74 61 62 6c 65 20 61 6e 64 20 61 72 65 20 75 table and are u
20580 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 sed.** to loop t
20590 68 72 6f 75 67 68 20 74 68 65 20 76 69 72 74 75 hrough the virtu
205a0 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73 6f al table. Curso
205b0 72 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 rs are created u
205c0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 78 4f 70 65 sing the.** xOpe
205d0 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 n method of the
205e0 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f module. Each mo
205f0 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 dule implementat
20600 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a ion will define.
20610 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f ** the content o
20620 66 20 61 20 63 75 72 73 6f 72 20 73 74 72 75 63 f a cursor struc
20630 74 75 72 65 20 74 6f 20 73 75 69 74 20 69 74 73 ture to suit its
20640 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a own needs..**.*
20650 2a 20 54 68 69 73 20 73 75 70 65 72 63 6c 61 73 * This superclas
20660 73 20 65 78 69 73 74 73 20 69 6e 20 6f 72 64 65 s exists in orde
20670 72 20 74 6f 20 64 65 66 69 6e 65 20 66 69 65 6c r to define fiel
20680 64 73 20 6f 66 20 74 68 65 20 63 75 72 73 6f 72 ds of the cursor
20690 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d that.** are com
206a0 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 mon to all imple
206b0 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 mentations..*/.s
206c0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 truct sqlite3_vt
206d0 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73 71 ab_cursor {. sq
206e0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 lite3_vtab *pVta
206f0 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74 75 b; /* Virtu
20700 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69 73 al table of this
20710 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 cursor */. /*
20720 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d Virtual table im
20730 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 plementations wi
20740 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 ll typically add
20750 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c additional fiel
20760 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 ds */.};../*.**
20770 54 68 65 20 78 43 72 65 61 74 65 20 61 6e 64 20 The xCreate and
20780 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 73 xConnect methods
20790 20 6f 66 20 61 20 6d 6f 64 75 6c 65 20 75 73 65 of a module use
207a0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 the following A
207b0 50 49 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65 PI.** to declare
207c0 20 74 68 65 20 66 6f 72 6d 61 74 20 28 74 68 65 the format (the
207d0 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61 74 names and datat
207e0 79 70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 ypes of the colu
207f0 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76 mns) of.** the v
20800 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 74 68 irtual tables th
20810 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f ey implement..*/
20820 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65 63 .int sqlite3_dec
20830 6c 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74 65 lare_vtab(sqlite
20840 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 3*, const char *
20850 7a 43 72 65 61 74 65 54 61 62 6c 65 29 3b 0a 0a zCreateTable);..
20860 2f 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 /*.** Virtual ta
20870 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65 bles can provide
20880 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70 alternative imp
20890 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 lementations of
208a0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 functions.** usi
208b0 6e 67 20 74 68 65 20 78 46 69 6e 64 46 75 6e 63 ng the xFindFunc
208c0 74 69 6f 6e 20 6d 65 74 68 6f 64 2e 20 20 42 75 tion method. Bu
208d0 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e t global version
208e0 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63 74 s of those funct
208f0 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69 ions.** must exi
20900 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 st in order to b
20910 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a e overloaded..**
20920 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 6d 61 6b .** This API mak
20930 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c es sure a global
20940 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75 version of a fu
20950 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61 nction with a pa
20960 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 rticular.** name
20970 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70 and number of p
20980 61 72 61 6d 65 74 65 72 73 20 65 78 69 73 74 73 arameters exists
20990 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75 . If no such fu
209a0 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a nction exists.**
209b0 20 62 65 66 6f 72 65 20 74 68 69 73 20 41 50 49 before this API
209c0 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65 is called, a ne
209d0 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72 w function is cr
209e0 65 61 74 65 64 2e 20 20 54 68 65 20 69 6d 70 6c eated. The impl
209f0 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 ementation.** of
20a00 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f the new functio
20a10 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65 73 20 n always causes
20a20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f 20 an exception to
20a30 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a be thrown. So.*
20a40 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 * the new functi
20a50 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66 on is not good f
20a60 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20 69 or anything by i
20a70 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79 tself. Its only
20a80 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20 74 .** purpose is t
20a90 6f 20 62 65 20 61 20 70 6c 61 63 65 2d 68 6f 6c o be a place-hol
20aa0 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 der function tha
20ab0 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61 t can be overloa
20ac0 64 65 64 0a 2a 2a 20 62 79 20 76 69 72 74 75 61 ded.** by virtua
20ad0 6c 20 74 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 l tables..**.**
20ae0 54 68 69 73 20 41 50 49 20 73 68 6f 75 6c 64 20 This API should
20af0 62 65 20 63 6f 6e 73 69 64 65 72 65 64 20 70 61 be considered pa
20b00 72 74 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 rt of the virtua
20b10 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61 63 l table interfac
20b20 65 2c 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 65 e,.** which is e
20b30 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 xperimental and
20b40 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 subject to chang
20b50 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 e..*/.int sqlite
20b60 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 3_overload_funct
20b70 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f ion(sqlite3*, co
20b80 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e nst char *zFuncN
20b90 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a ame, int nArg);.
20ba0 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 ./*.** The inter
20bb0 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 74 face to the virt
20bc0 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e ual-table mechan
20bd0 69 73 6d 20 64 65 66 69 6e 65 64 20 61 62 6f 76 ism defined abov
20be0 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f e (back up.** to
20bf0 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 a comment remar
20c00 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f kably similar to
20c10 20 74 68 69 73 20 6f 6e 65 29 20 69 73 20 63 75 this one) is cu
20c20 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 rrently consider
20c30 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 ed.** to be expe
20c40 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 rimental. The i
20c50 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 nterface might c
20c60 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 hange in incompa
20c70 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 tible ways..** I
20c80 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 f this is a prob
20c90 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 lem for you, do
20ca0 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 not use the inte
20cb0 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69 rface at this ti
20cc0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 me..**.** When t
20cd0 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 he virtual-table
20ce0 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 6c mechanism stabl
20cf0 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 izes, we will de
20d00 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 clare the.** int
20d10 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 erface fixed, su
20d20 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e pport it indefin
20d30 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 itely, and remov
20d40 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a e this comment..
20d50 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 **.****** EXPERI
20d60 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 MENTAL - subject
20d70 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f to change witho
20d80 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a ut notice ******
20d90 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a ********.*/../*.
20da0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 20 48 ** CAPI3REF: A H
20db0 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e andle To An Open
20dc0 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 BLOB.**.** An i
20dd0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 66 nstance of the f
20de0 6f 6c 6c 6f 77 69 6e 67 20 6f 70 61 71 75 65 20 ollowing opaque
20df0 73 74 72 75 63 74 75 72 65 20 69 73 20 75 73 65 structure is use
20e00 64 20 74 6f 20 0a 2a 2a 20 72 65 70 72 65 73 65 d to .** represe
20e10 6e 74 20 61 6e 20 62 6c 6f 62 2d 68 61 6e 64 6c nt an blob-handl
20e20 65 2e 20 20 41 20 62 6c 6f 62 2d 68 61 6e 64 6c e. A blob-handl
20e30 65 20 69 73 20 63 72 65 61 74 65 64 20 62 79 0a e is created by.
20e40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 ** [sqlite3_blob
20e50 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 64 65 73 _open()] and des
20e60 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 troyed by [sqlit
20e70 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d e3_blob_close()]
20e80 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 ..** The [sqlite
20e90 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 3_blob_read()] a
20ea0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 nd [sqlite3_blob
20eb0 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66 _write()] interf
20ec0 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 aces.** can be u
20ed0 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77 sed to read or w
20ee0 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 rite small subse
20ef0 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 6c ctions of the bl
20f00 6f 62 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 74 ob..** The [sqlt
20f10 69 65 33 5f 62 6c 6f 62 5f 73 69 7a 65 28 29 5d ie3_blob_size()]
20f20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
20f30 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 ns the size of t
20f40 68 65 0a 2a 2a 20 62 6c 6f 62 20 69 6e 20 62 79 he.** blob in by
20f50 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 tes..*/.typedef
20f60 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62 struct sqlite3_b
20f70 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 lob sqlite3_blob
20f80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
20f90 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 F: Open A BLOB F
20fa0 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 or Incremental I
20fb0 2f 4f 0a 2a 2a 0a 2a 2a 20 4f 70 65 6e 20 61 20 /O.**.** Open a
20fc0 68 61 6e 64 6c 65 20 74 6f 20 74 68 65 20 62 6c handle to the bl
20fd0 6f 62 20 6c 6f 63 61 74 65 64 20 69 6e 20 72 6f ob located in ro
20fe0 77 20 69 52 6f 77 2c 2c 20 63 6f 6c 75 6d 6e 20 w iRow,, column
20ff0 7a 43 6f 6c 75 6d 6e 2c 20 0a 2a 2a 20 74 61 62 zColumn, .** tab
21000 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 74 le zTable in dat
21010 61 62 61 73 65 20 7a 44 62 2e 20 69 2e 65 2e 20 abase zDb. i.e.
21020 74 68 65 20 73 61 6d 65 20 62 6c 6f 62 20 74 68 the same blob th
21030 61 74 20 77 6f 75 6c 64 0a 2a 2a 20 62 65 20 73 at would.** be s
21040 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a elected by:.**.*
21050 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53 * <pre>.** S
21060 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 ELECT zColumn FR
21070 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48 OM zDb.zTable WH
21080 45 52 45 20 72 6f 77 69 64 20 3d 20 69 52 6f 77 ERE rowid = iRow
21090 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a ;.** </pre>.**.*
210a0 2a 20 49 66 20 74 68 65 20 66 6c 61 67 73 20 70 * If the flags p
210b0 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d arameter is non-
210c0 7a 65 72 6f 2c 20 74 68 65 20 62 6c 6f 62 20 69 zero, the blob i
210d0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 0a 2a 2a s opened for .**
210e0 20 72 65 61 64 20 61 6e 64 20 77 72 69 74 65 20 read and write
210f0 61 63 63 65 73 73 2e 20 49 66 20 69 74 20 69 73 access. If it is
21100 20 7a 65 72 6f 2c 20 74 68 65 20 62 6c 6f 62 20 zero, the blob
21110 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 is opened for re
21120 61 64 20 0a 2a 2a 20 61 63 63 65 73 73 2e 0a 2a ad .** access..*
21130 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c *.** On success,
21140 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 [SQLITE_OK] is
21150 72 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65 returned and the
21160 20 6e 65 77 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 new .** [sqlite
21170 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61 3_blob | blob ha
21180 6e 64 6c 65 5d 20 69 73 20 77 72 69 74 74 65 6e ndle] is written
21190 20 74 6f 20 2a 70 70 42 6c 6f 62 2e 0a 2a 2a 20 to *ppBlob..**
211a0 4f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 Otherwise an err
211b0 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 or code is retur
211c0 6e 65 64 20 61 6e 64 20 0a 2a 2a 20 61 6e 79 20 ned and .** any
211d0 76 61 6c 75 65 20 77 72 69 74 74 65 6e 20 74 6f value written to
211e0 20 2a 70 70 42 6c 6f 62 20 73 68 6f 75 6c 64 20 *ppBlob should
211f0 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 74 not be used by t
21200 68 65 20 63 61 6c 6c 65 72 2e 0a 2a 2a 20 54 68 he caller..** Th
21210 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 is function sets
21220 20 74 68 65 20 64 61 74 61 62 61 73 65 2d 68 61 the database-ha
21230 6e 64 6c 65 20 65 72 72 6f 72 20 63 6f 64 65 20 ndle error code
21240 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61 and message.** a
21250 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73 ccessible via [s
21260 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 qlite3_errcode()
21270 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 ] and [sqlite3_e
21280 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 rrmsg()]..*/.int
21290 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 sqlite3_blob_op
212a0 65 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a en(. sqlite3*,.
212b0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 const char *zD
212c0 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 b,. const char
212d0 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 *zTable,. const
212e0 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a char *zColumn,.
212f0 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 sqlite3_int64
21300 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 iRow,. int flag
21310 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f s,. sqlite3_blo
21320 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f b **ppBlob.);../
21330 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 *.** CAPI3REF:
21340 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48 61 6e Close A BLOB Han
21350 64 6c 65 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 20 dle.**.** Close
21360 61 6e 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 an open [sqlite3
21370 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61 6e _blob | blob han
21380 64 6c 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c dle]..*/.int sql
21390 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 ite3_blob_close(
213a0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b sqlite3_blob *);
213b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
213c0 3a 20 20 52 65 74 75 72 6e 20 54 68 65 20 53 69 : Return The Si
213d0 7a 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c ze Of An Open BL
213e0 4f 42 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 OB.**.** Return
213f0 74 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 the size in byte
21400 73 20 6f 66 20 74 68 65 20 62 6c 6f 62 20 61 63 s of the blob ac
21410 63 65 73 73 69 62 6c 65 20 76 69 61 20 74 68 65 cessible via the
21420 20 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 open .** [sqlit
21430 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 e3_blob | blob-h
21440 61 6e 64 6c 65 5d 20 70 61 73 73 65 64 20 61 73 andle] passed as
21450 20 61 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2f an argument..*/
21460 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f .int sqlite3_blo
21470 62 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f b_bytes(sqlite3_
21480 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 blob *);../*.**
21490 43 41 50 49 33 52 45 46 3a 20 20 52 65 61 64 20 CAPI3REF: Read
214a0 44 61 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42 Data From A BLOB
214b0 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a Incrementally.*
214c0 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 *.** This functi
214d0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 on is used to re
214e0 61 64 20 64 61 74 61 20 66 72 6f 6d 20 61 6e 20 ad data from an
214f0 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 open .** [sqlite
21500 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61 3_blob | blob-ha
21510 6e 64 6c 65 5d 20 69 6e 74 6f 20 61 20 63 61 6c ndle] into a cal
21520 6c 65 72 20 73 75 70 70 6c 69 65 64 20 62 75 66 ler supplied buf
21530 66 65 72 2e 0a 2a 2a 20 6e 20 62 79 74 65 73 20 fer..** n bytes
21540 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 of data are copi
21550 65 64 20 69 6e 74 6f 20 62 75 66 66 65 72 0a 2a ed into buffer.*
21560 2a 20 7a 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 * z from the ope
21570 6e 20 62 6c 6f 62 2c 20 73 74 61 72 74 69 6e 67 n blob, starting
21580 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73 at offset iOffs
21590 65 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 et..**.** On suc
215a0 63 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 cess, SQLITE_OK
215b0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 4f 74 68 is returned. Oth
215c0 65 72 77 69 73 65 2c 20 61 6e 20 0a 2a 2a 20 5b erwise, an .** [
215d0 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 53 SQLITE_ERROR | S
215e0 51 4c 69 74 65 20 65 72 72 6f 72 20 63 6f 64 65 QLite error code
215f0 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 ] or an.** [SQLI
21600 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 TE_IOERR_READ |
21610 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 extended error c
21620 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 ode] is returned
21630 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
21640 5f 62 6c 6f 62 5f 72 65 61 64 28 73 71 6c 69 74 _blob_read(sqlit
21650 65 33 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 e3_blob *, void
21660 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69 *z, int n, int i
21670 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 Offset);../*.**
21680 43 41 50 49 33 52 45 46 3a 20 20 57 72 69 74 65 CAPI3REF: Write
21690 20 44 61 74 61 20 49 6e 74 6f 20 41 20 42 4c 4f Data Into A BLO
216a0 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a B Incrementally.
216b0 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 **.** This funct
216c0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 77 ion is used to w
216d0 72 69 74 65 20 64 61 74 61 20 69 6e 74 6f 20 61 rite data into a
216e0 6e 20 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 n open .** [sqli
216f0 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d te3_blob | blob-
21700 68 61 6e 64 6c 65 5d 20 66 72 6f 6d 20 61 20 75 handle] from a u
21710 73 65 72 20 73 75 70 70 6c 69 65 64 20 62 75 66 ser supplied buf
21720 66 65 72 2e 0a 2a 2a 20 6e 20 62 79 74 65 73 20 fer..** n bytes
21730 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 of data are copi
21740 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 66 66 ed from the buff
21750 65 72 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f er.** pointed to
21760 20 62 79 20 7a 20 69 6e 74 6f 20 74 68 65 20 6f by z into the o
21770 70 65 6e 20 62 6c 6f 62 2c 20 73 74 61 72 74 69 pen blob, starti
21780 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 ng at offset iOf
21790 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 fset..**.** If t
217a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 he [sqlite3_blob
217b0 20 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 | blob-handle]
217c0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 passed as the fi
217d0 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 rst argument.**
217e0 77 61 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20 66 was not opened f
217f0 6f 72 20 77 72 69 74 69 6e 67 20 28 74 68 65 20 or writing (the
21800 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 flags parameter
21810 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 to [sqlite3_blob
21820 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 2a 20 77 61 73 _open()].*** was
21830 20 7a 65 72 6f 29 2c 20 74 68 69 73 20 66 75 6e zero), this fun
21840 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 ction returns [S
21850 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e QLITE_READONLY].
21860 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 .**.** This func
21870 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f tion may only mo
21880 64 69 66 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 dify the content
21890 73 20 6f 66 20 74 68 65 20 62 6c 6f 62 2c 20 69 s of the blob, i
218a0 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 t is.** not poss
218b0 69 62 6c 65 20 74 6f 20 69 6e 63 72 65 61 73 65 ible to increase
218c0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62 the size of a b
218d0 6c 6f 62 20 75 73 69 6e 67 20 74 68 69 73 20 41 lob using this A
218e0 50 49 2e 20 49 66 0a 2a 2a 20 6f 66 66 73 65 74 PI. If.** offset
218f0 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 iOffset is less
21900 20 74 68 61 6e 20 6e 20 62 79 74 65 73 20 66 72 than n bytes fr
21910 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 om the end of th
21920 65 20 62 6c 6f 62 2c 20 0a 2a 2a 20 5b 53 51 4c e blob, .** [SQL
21930 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 ITE_ERROR] is re
21940 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 turned and no da
21950 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e 0a 2a ta is written..*
21960 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c *.** On success,
21970 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 SQLITE_OK is re
21980 74 75 72 6e 65 64 2e 20 4f 74 68 65 72 77 69 73 turned. Otherwis
21990 65 2c 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 e, an .** [SQLIT
219a0 45 5f 45 52 52 4f 52 20 7c 20 53 51 4c 69 74 65 E_ERROR | SQLite
219b0 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 error code] or
219c0 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f an.** [SQLITE_IO
219d0 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e ERR_READ | exten
219e0 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 ded error code]
219f0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a is returned..*/.
21a00 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 int sqlite3_blob
21a10 5f 77 72 69 74 65 28 73 71 6c 69 74 65 33 5f 62 _write(sqlite3_b
21a20 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 lob *, const voi
21a30 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 d *z, int n, int
21a40 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a iOffset);../*.*
21a50 2a 20 43 41 50 49 33 52 45 46 3a 20 20 56 69 72 * CAPI3REF: Vir
21a60 74 75 61 6c 20 46 69 6c 65 20 53 79 73 74 65 6d tual File System
21a70 20 4f 62 6a 65 63 74 73 0a 2a 2a 0a 2a 2a 20 41 Objects.**.** A
21a80 20 76 69 72 74 75 61 6c 20 66 69 6c 65 73 79 73 virtual filesys
21a90 74 65 6d 20 28 56 46 53 29 20 69 73 20 61 6e 20 tem (VFS) is an
21aa0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
21ab0 6a 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 51 4c ject.** that SQL
21ac0 69 74 65 20 75 73 65 73 20 74 6f 20 69 6e 74 65 ite uses to inte
21ad0 72 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 68 65 ract.** with the
21ae0 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 underlying oper
21af0 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 4d ating system. M
21b00 6f 73 74 20 62 75 69 6c 64 73 20 63 6f 6d 65 20 ost builds come
21b10 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 with a.** single
21b20 20 64 65 66 61 75 6c 74 20 56 46 53 20 74 68 61 default VFS tha
21b30 74 20 69 73 20 61 70 70 72 6f 70 72 69 61 74 65 t is appropriate
21b40 20 66 6f 72 20 74 68 65 20 68 6f 73 74 20 63 6f for the host co
21b50 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20 56 mputer..** New V
21b60 46 53 65 73 20 63 61 6e 20 62 65 20 72 65 67 69 FSes can be regi
21b70 73 74 65 72 65 64 20 61 6e 64 20 65 78 69 73 74 stered and exist
21b80 69 6e 67 20 56 46 53 65 73 20 63 61 6e 20 62 65 ing VFSes can be
21b90 20 75 6e 72 65 67 69 73 74 65 72 65 64 2e 0a 2a unregistered..*
21ba0 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 * The following
21bb0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 interfaces are p
21bc0 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 rovided..**.** T
21bd0 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 he sqlite3_vfs_f
21be0 69 6e 64 28 29 20 69 6e 74 65 72 66 61 63 65 20 ind() interface
21bf0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
21c00 72 20 74 6f 20 61 20 56 46 53 20 67 69 76 65 6e r to a VFS given
21c10 20 69 74 73 0a 2a 2a 20 6e 61 6d 65 2e 20 20 4e its.** name. N
21c20 61 6d 65 73 20 61 72 65 20 63 61 73 65 20 73 65 ames are case se
21c30 6e 73 69 74 69 76 65 2e 20 20 49 66 20 74 68 65 nsitive. If the
21c40 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c 20 re is no match,
21c50 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 a NULL.** pointe
21c60 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 r is returned.
21c70 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 20 4e If zVfsName is N
21c80 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 65 66 ULL then the def
21c90 61 75 6c 74 20 0a 2a 2a 20 56 46 53 20 69 73 20 ault .** VFS is
21ca0 72 65 74 75 72 6e 65 64 2e 20 20 49 66 20 61 20 returned. If a
21cb0 76 61 6c 69 64 20 56 46 53 20 70 6f 69 6e 74 65 valid VFS pointe
21cc0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2c 20 69 r is returned, i
21cd0 74 73 0a 2a 2a 20 76 66 73 4d 75 74 65 78 20 66 ts.** vfsMutex f
21ce0 69 65 6c 64 20 77 69 6c 6c 20 68 61 76 65 20 62 ield will have b
21cf0 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 een initialized
21d00 61 6e 64 20 6e 52 65 66 20 77 69 6c 6c 20 62 65 and nRef will be
21d10 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e .** greater than
21d20 20 7a 65 72 6f 2e 20 20 54 68 65 20 73 71 6c 69 zero. The sqli
21d30 74 65 33 5f 76 66 73 5f 72 65 6c 65 61 73 65 28 te3_vfs_release(
21d40 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c ) function shoul
21d50 64 0a 2a 2a 20 62 65 20 75 73 65 64 20 74 6f 20 d.** be used to
21d60 72 65 6c 65 61 73 65 20 74 68 65 20 56 46 53 20 release the VFS
21d70 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f when it is no lo
21d80 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 0a nger needed..**.
21d90 2a 2a 20 4e 65 77 20 56 46 53 65 73 20 61 72 65 ** New VFSes are
21da0 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 registered with
21db0 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 sqlite3_vfs_reg
21dc0 69 73 74 65 72 28 29 2e 20 20 45 61 63 68 0a 2a ister(). Each.*
21dd0 2a 20 6e 65 77 20 56 46 53 20 62 65 63 6f 6d 65 * new VFS become
21de0 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 s the default VF
21df0 53 20 69 66 20 74 68 65 20 6d 61 6b 65 44 66 6c S if the makeDfl
21e00 74 20 66 6c 61 67 20 69 73 20 73 65 74 2e 0a 2a t flag is set..*
21e10 2a 20 54 68 65 20 73 61 6d 65 20 56 46 53 20 63 * The same VFS c
21e20 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 an be registered
21e30 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 multiple times
21e40 77 69 74 68 6f 75 74 20 69 6e 6a 75 72 79 2e 0a without injury..
21e50 2a 2a 20 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78 ** To make an ex
21e60 69 73 74 69 6e 67 20 56 46 53 20 69 6e 74 6f 20 isting VFS into
21e70 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 2c the default VFS,
21e80 20 72 65 67 69 73 74 65 72 20 69 74 20 61 67 61 register it aga
21e90 69 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6d in.** with the m
21ea0 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 73 65 74 akeDflt flag set
21eb0 2e 0a 2a 2a 20 0a 2a 2a 20 55 6e 72 65 67 69 73 ..** .** Unregis
21ec0 74 65 72 20 61 20 56 46 53 20 77 69 74 68 20 74 ter a VFS with t
21ed0 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 he sqlite3_vfs_u
21ee0 6e 72 65 67 69 73 74 65 72 28 29 20 69 6e 74 65 nregister() inte
21ef0 72 66 61 63 65 2e 0a 2a 2a 20 49 66 20 74 68 65 rface..** If the
21f00 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 default VFS is
21f10 75 6e 72 65 67 69 73 74 65 72 65 64 2c 20 61 6e unregistered, an
21f20 6f 74 68 65 72 20 56 46 53 20 69 73 20 63 68 6f other VFS is cho
21f30 73 65 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64 65 sen as.** the de
21f40 66 61 75 6c 74 2e 20 20 54 68 65 20 63 68 6f 69 fault. The choi
21f50 63 65 20 66 6f 72 20 74 68 65 20 6e 65 77 20 56 ce for the new V
21f60 46 53 20 69 73 20 61 72 62 69 74 72 61 72 79 2e FS is arbitrary.
21f70 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 66 73 20 .*/.sqlite3_vfs
21f80 2a 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e *sqlite3_vfs_fin
21f90 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 d(const char *zV
21fa0 66 73 4e 61 6d 65 29 3b 0a 69 6e 74 20 73 71 6c fsName);.int sql
21fb0 69 74 65 33 5f 76 66 73 5f 72 65 6c 65 61 73 65 ite3_vfs_release
21fc0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a (sqlite3_vfs*);.
21fd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f int sqlite3_vfs_
21fe0 72 65 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 register(sqlite3
21ff0 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 _vfs*, int makeD
22000 66 6c 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 flt);.int sqlite
22010 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 3_vfs_unregister
22020 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a (sqlite3_vfs*);.
22030 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
22040 20 4d 75 74 65 78 65 73 0a 2a 2a 0a 2a 2a 20 54 Mutexes.**.** T
22050 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 he SQLite core u
22060 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e ses these routin
22070 65 73 20 66 6f 72 20 74 68 72 65 61 64 0a 2a 2a es for thread.**
22080 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e synchronization
22090 2e 20 20 54 68 6f 75 67 68 20 74 68 65 79 20 61 . Though they a
220a0 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 re intended for
220b0 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 internal.** use
220c0 62 79 20 53 51 4c 69 74 65 2c 20 63 6f 64 65 20 by SQLite, code
220d0 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e that links again
220e0 73 74 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 st SQLite is.**
220f0 70 65 72 6d 69 74 74 65 64 20 74 6f 20 75 73 65 permitted to use
22100 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f any of these ro
22110 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 utines..**.** Th
22120 65 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 e SQLite source
22130 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75 code contains mu
22140 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 ltiple implement
22150 61 74 69 6f 6e 73 20 0a 2a 2a 20 6f 66 20 74 68 ations .** of th
22160 65 73 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e ese mutex routin
22170 65 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 es that can be s
22180 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 elected at compi
22190 6c 65 2d 74 69 6d 65 0a 2a 2a 20 62 79 20 64 65 le-time.** by de
221a0 66 69 6e 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 fining one of th
221b0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 43 20 70 72 e following C pr
221c0 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f eprocessor macro
221d0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a s:.**.** <ul>.**
221e0 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d <li> SQLITE_M
221f0 55 54 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a 20 UTEX_PTHREAD.**
22200 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 <li> SQLITE_MU
22210 54 45 58 5f 57 49 4e 33 32 0a 2a 2a 20 3c 6c 69 TEX_WIN32.** <li
22220 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 > SQLITE_MUTEX
22230 5f 4e 4f 4f 50 0a 2a 2a 20 3c 6c 69 3e 20 20 20 _NOOP.** <li>
22240 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 SQLITE_MUTEX_APP
22250 44 45 46 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a DEF.** </ul>.**.
22260 2a 2a 20 49 66 20 6e 6f 6e 65 20 6f 66 20 74 68 ** If none of th
22270 65 20 61 62 6f 76 65 20 6d 61 63 72 6f 73 20 69 e above macros i
22280 73 20 64 65 66 69 6e 65 64 2c 20 74 68 65 20 63 s defined, the c
22290 6f 64 65 20 75 73 65 73 0a 2a 2a 20 61 20 64 65 ode uses.** a de
222a0 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61 fault implementa
222b0 74 69 6f 6e 2e 20 20 0a 2a 2a 20 0a 2a 2a 20 54 tion. .** .** T
222c0 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f he SQLITE_MUTEX_
222d0 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 NOOP implementat
222e0 69 6f 6e 20 69 73 20 61 20 73 65 74 20 6f 66 20 ion is a set of
222f0 72 6f 75 74 69 6e 65 73 20 0a 2a 2a 20 74 68 61 routines .** tha
22300 74 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20 6c t does no real l
22310 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73 20 61 70 ocking and is ap
22320 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73 propriate for us
22330 65 20 69 6e 20 0a 2a 2a 20 61 20 73 69 6e 67 6c e in .** a singl
22340 65 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 e-threaded appli
22350 63 61 74 69 6f 6e 2e 0a 2a 2a 20 0a 2a 2a 20 49 cation..** .** I
22360 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 f the SQLITE_MUT
22370 45 58 5f 41 50 50 44 45 46 20 69 73 20 64 65 66 EX_APPDEF is def
22380 69 6e 65 64 2c 20 74 68 65 6e 20 6e 6f 20 6d 75 ined, then no mu
22390 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 tex.** implement
223a0 61 74 69 6f 6e 20 69 73 20 69 6e 63 6c 75 64 65 ation is include
223b0 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 d with the libra
223c0 72 79 2e 20 20 54 68 65 0a 2a 2a 20 6d 75 74 65 ry. The.** mute
223d0 78 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 x interface rout
223e0 69 6e 65 73 20 64 65 66 69 6e 65 64 20 61 62 6f ines defined abo
223f0 76 65 20 61 72 65 20 65 78 74 65 72 6e 61 6c 0a ve are external.
22400 2a 2a 20 72 65 66 65 72 65 6e 63 65 73 20 69 6e ** references in
22410 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 the SQLite libr
22420 61 72 79 20 66 6f 72 20 77 68 69 63 68 20 69 6d ary for which im
22430 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a plementations.**
22440 20 6d 75 73 74 20 62 65 20 70 72 6f 76 69 64 65 must be provide
22450 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 d by the applica
22460 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 tion..**.** The
22470 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c sqlite3_mutex_al
22480 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 61 6c loc() routine al
22490 6c 6f 63 61 74 65 73 20 61 20 6e 65 77 0a 2a 2a locates a new.**
224a0 20 6d 75 74 65 78 20 61 6e 64 20 72 65 74 75 72 mutex and retur
224b0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
224c0 69 74 2e 20 20 49 66 20 69 74 20 72 65 74 75 72 it. If it retur
224d0 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 20 ns NULL.** that
224e0 6d 65 61 6e 73 20 74 68 61 74 20 61 20 6d 75 74 means that a mut
224f0 65 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 ex could not be
22500 61 6c 6c 6f 63 61 74 65 64 2e 20 20 53 51 4c 69 allocated. SQLi
22510 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77 69 6e te.** will unwin
22520 64 20 69 74 73 20 73 74 61 63 6b 20 61 6e 64 20 d its stack and
22530 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e return an error.
22540 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a The argument.*
22550 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 * to sqlite3_mut
22560 65 78 5f 61 6c 6c 6f 63 28 29 20 69 73 20 6f 6e ex_alloc() is on
22570 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 e of these integ
22580 65 72 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a er constants:.**
22590 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
225a0 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 SQLITE_MUTEX_F
225b0 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c AST.** <li> SQL
225c0 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 ITE_MUTEX_RECURS
225d0 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c IVE.** <li> SQL
225e0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 ITE_MUTEX_STATIC
225f0 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20 _MASTER.** <li>
22600 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 SQLITE_MUTEX_ST
22610 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e ATIC_MEM.** <li>
22620 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 SQLITE_MUTEX_S
22630 54 41 54 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c 2f TATIC_PRNG.** </
22640 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 ul>.**.** The fi
22650 72 73 74 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 rst two constant
22660 73 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f s cause sqlite3_
22670 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f mutex_alloc() to
22680 20 63 72 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77 create.** a new
22690 20 6d 75 74 65 78 2e 20 20 54 68 65 20 6e 65 77 mutex. The new
226a0 20 6d 75 74 65 78 20 69 73 20 72 65 63 75 72 73 mutex is recurs
226b0 69 76 65 20 77 68 65 6e 20 53 51 4c 49 54 45 5f ive when SQLITE_
226c0 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a MUTEX_RECURSIVE.
226d0 2a 2a 20 69 73 20 75 73 65 64 20 62 75 74 20 6e ** is used but n
226e0 6f 74 20 6e 65 63 65 73 73 61 72 69 6c 79 20 73 ot necessarily s
226f0 6f 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 o when SQLITE_MU
22700 54 45 58 5f 46 41 53 54 20 69 73 20 75 73 65 64 TEX_FAST is used
22710 2e 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 69 ..** The mutex i
22720 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f mplementation do
22730 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d es not need to m
22740 61 6b 65 20 61 20 64 69 73 74 69 6e 63 74 69 6f ake a distinctio
22750 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c n.** between SQL
22760 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 ITE_MUTEX_RECURS
22770 49 56 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d IVE and SQLITE_M
22780 55 54 45 58 5f 46 41 53 54 20 69 66 20 69 74 20 UTEX_FAST if it
22790 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 does.** not want
227a0 20 74 6f 2e 20 20 42 75 74 20 53 51 4c 69 74 65 to. But SQLite
227b0 20 77 69 6c 6c 20 6f 6e 6c 79 20 72 65 71 75 65 will only reque
227c0 73 74 20 61 20 72 65 63 75 72 73 69 76 65 20 6d st a recursive m
227d0 75 74 65 78 20 69 6e 0a 2a 2a 20 63 61 73 65 73 utex in.** cases
227e0 20 77 68 65 72 65 20 69 74 20 72 65 61 6c 6c 79 where it really
227f0 20 6e 65 65 64 73 20 6f 6e 65 2e 20 20 49 66 20 needs one. If
22800 61 20 66 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63 a faster non-rec
22810 75 72 73 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20 ursive mutex.**
22820 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 implementation i
22830 73 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74 s available on t
22840 68 65 20 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d he host platform
22850 2c 20 74 68 65 20 6d 75 74 65 78 20 73 75 62 73 , the mutex subs
22860 79 73 74 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 ystem.** might r
22870 65 74 75 72 6e 20 73 75 63 68 20 61 20 6d 75 74 eturn such a mut
22880 65 78 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 ex in response t
22890 6f 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 o SQLITE_MUTEX_F
228a0 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f AST..**.** The o
228b0 74 68 65 72 20 61 6c 6c 6f 77 65 64 20 70 61 72 ther allowed par
228c0 61 6d 65 74 65 72 73 20 74 6f 20 73 71 6c 69 74 ameters to sqlit
228d0 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 e3_mutex_alloc()
228e0 20 65 61 63 68 20 72 65 74 75 72 6e 0a 2a 2a 20 each return.**
228f0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 a pointer to a s
22900 74 61 74 69 63 20 70 72 65 65 78 69 73 74 69 6e tatic preexistin
22910 67 20 6d 75 74 65 78 2e 20 20 54 68 72 65 65 20 g mutex. Three
22920 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 static mutexes a
22930 72 65 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 68 re.** used by th
22940 65 20 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f e current versio
22950 6e 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 46 75 n of SQLite. Fu
22960 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 ture versions of
22970 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20 61 SQLite.** may a
22980 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 dd additional st
22990 61 74 69 63 20 6d 75 74 65 78 65 73 2e 20 20 53 atic mutexes. S
229a0 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72 tatic mutexes ar
229b0 65 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a e for internal.*
229c0 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 20 * use by SQLite
229d0 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 only. Applicati
229e0 6f 6e 73 20 74 68 61 74 20 75 73 65 20 53 51 4c ons that use SQL
229f0 69 74 65 20 6d 75 74 65 78 65 73 20 73 68 6f 75 ite mutexes shou
22a00 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20 74 ld.** use only t
22a10 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 he dynamic mutex
22a20 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 es returned by S
22a30 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 QLITE_MUTEX_FAST
22a40 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 or.** SQLITE_MU
22a50 54 45 58 5f 52 45 43 55 52 53 49 56 45 2e 0a 2a TEX_RECURSIVE..*
22a60 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 69 *.** Note that i
22a70 66 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 79 6e f one of the dyn
22a80 61 6d 69 63 20 6d 75 74 65 78 20 70 61 72 61 6d amic mutex param
22a90 65 74 65 72 73 20 28 53 51 4c 49 54 45 5f 4d 55 eters (SQLITE_MU
22aa0 54 45 58 5f 46 41 53 54 0a 2a 2a 20 6f 72 20 53 TEX_FAST.** or S
22ab0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 QLITE_MUTEX_RECU
22ac0 52 53 49 56 45 29 20 69 73 20 75 73 65 64 20 74 RSIVE) is used t
22ad0 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 hen sqlite3_mute
22ae0 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20 72 65 74 x_alloc().** ret
22af0 75 72 6e 73 20 61 20 64 69 66 66 65 72 65 6e 74 urns a different
22b00 20 6d 75 74 65 78 20 6f 6e 20 65 76 65 72 79 20 mutex on every
22b10 63 61 6c 6c 2e 20 20 42 75 74 20 66 6f 72 20 74 call. But for t
22b20 68 65 20 73 74 61 74 69 63 20 0a 2a 2a 20 6d 75 he static .** mu
22b30 74 65 78 20 74 79 70 65 73 2c 20 74 68 65 20 73 tex types, the s
22b40 61 6d 65 20 6d 75 74 65 78 20 69 73 20 72 65 74 ame mutex is ret
22b50 75 72 6e 65 64 20 6f 6e 20 65 76 65 72 79 20 63 urned on every c
22b60 61 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 all that has.**
22b70 74 68 65 20 73 61 6d 65 20 74 79 70 65 20 6e 75 the same type nu
22b80 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 mber..**.** The
22b90 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 sqlite3_mutex_fr
22ba0 65 65 28 29 20 72 6f 75 74 69 6e 65 20 64 65 61 ee() routine dea
22bb0 6c 6c 6f 63 61 74 65 73 20 61 20 70 72 65 76 69 llocates a previ
22bc0 6f 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 ously.** allocat
22bd0 65 64 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 ed dynamic mutex
22be0 2e 20 20 53 51 4c 69 74 65 20 69 73 20 63 61 72 . SQLite is car
22bf0 65 66 75 6c 20 74 6f 20 64 65 61 6c 6c 6f 63 61 eful to dealloca
22c00 74 65 20 65 76 65 72 79 0a 2a 2a 20 64 79 6e 61 te every.** dyna
22c10 6d 69 63 20 6d 75 74 65 78 20 74 68 61 74 20 69 mic mutex that i
22c20 74 20 61 6c 6c 6f 63 61 74 65 73 2e 20 20 54 68 t allocates. Th
22c30 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65 e dynamic mutexe
22c40 73 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 69 6e s must not be in
22c50 20 0a 2a 2a 20 75 73 65 20 77 68 65 6e 20 74 68 .** use when th
22c60 65 79 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 ey are deallocat
22c70 65 64 2e 20 20 41 74 74 65 6d 70 74 69 6e 67 20 ed. Attempting
22c80 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 20 to deallocate a
22c90 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20 static.** mutex
22ca0 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 results in undef
22cb0 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 20 20 ined behavior.
22cc0 53 51 4c 69 74 65 20 6e 65 76 65 72 20 64 65 61 SQLite never dea
22cd0 6c 6c 6f 63 61 74 65 73 0a 2a 2a 20 61 20 73 74 llocates.** a st
22ce0 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 0a 2a atic mutex..**.*
22cf0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 * The sqlite3_mu
22d00 74 65 78 5f 65 6e 74 65 72 28 29 20 61 6e 64 20 tex_enter() and
22d10 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 sqlite3_mutex_tr
22d20 79 28 29 20 72 6f 75 74 69 6e 65 73 20 61 74 74 y() routines att
22d30 65 6d 70 74 0a 2a 2a 20 74 6f 20 65 6e 74 65 72 empt.** to enter
22d40 20 61 20 6d 75 74 65 78 2e 20 20 49 66 20 61 6e a mutex. If an
22d50 6f 74 68 65 72 20 74 68 72 65 61 64 20 69 73 20 other thread is
22d60 61 6c 72 65 61 64 79 20 77 69 74 68 69 6e 20 74 already within t
22d70 68 65 20 6d 75 74 65 78 2c 0a 2a 2a 20 73 71 6c he mutex,.** sql
22d80 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 ite3_mutex_enter
22d90 28 29 20 77 69 6c 6c 20 62 6c 6f 63 6b 20 61 6e () will block an
22da0 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f d sqlite3_mutex_
22db0 74 72 79 28 29 20 77 69 6c 6c 20 72 65 74 75 72 try() will retur
22dc0 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59 n.** SQLITE_BUSY
22dd0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d . The sqlite3_m
22de0 75 74 65 78 5f 74 72 79 28 29 20 69 6e 74 65 72 utex_try() inter
22df0 66 61 63 65 20 72 65 74 75 72 6e 73 20 53 51 4c face returns SQL
22e00 49 54 45 5f 4f 4b 0a 2a 2a 20 75 70 6f 6e 20 73 ITE_OK.** upon s
22e10 75 63 63 65 73 73 66 75 6c 20 65 6e 74 72 79 2e uccessful entry.
22e20 20 20 4d 75 74 65 78 65 73 20 63 72 65 61 74 65 Mutexes create
22e30 64 20 75 73 69 6e 67 20 53 51 4c 49 54 45 5f 4d d using SQLITE_M
22e40 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 63 UTEX_RECURSIVE c
22e50 61 6e 0a 2a 2a 20 62 65 20 65 6e 74 65 72 65 64 an.** be entered
22e60 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 multiple times
22e70 62 79 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 by the same thre
22e80 61 64 2e 20 20 49 6e 20 73 75 63 68 20 63 61 73 ad. In such cas
22e90 65 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65 78 es the,.** mutex
22ea0 20 6d 75 73 74 20 62 65 20 65 78 69 74 65 64 20 must be exited
22eb0 61 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65 72 20 an equal number
22ec0 6f 66 20 74 69 6d 65 73 20 62 65 66 6f 72 65 20 of times before
22ed0 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a another thread.*
22ee0 2a 20 63 61 6e 20 65 6e 74 65 72 2e 20 20 49 66 * can enter. If
22ef0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 the same thread
22f00 20 74 72 69 65 73 20 74 6f 20 65 6e 74 65 72 20 tries to enter
22f10 61 6e 79 20 6f 74 68 65 72 20 6b 69 6e 64 20 6f any other kind o
22f20 66 20 6d 75 74 65 78 0a 2a 2a 20 6d 6f 72 65 20 f mutex.** more
22f30 74 68 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20 62 than once, the b
22f40 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 ehavior is undef
22f50 69 6e 65 64 2e 20 20 20 53 51 4c 69 74 65 20 77 ined. SQLite w
22f60 69 6c 6c 20 6e 65 76 65 72 20 65 78 68 69 62 69 ill never exhibi
22f70 74 0a 2a 2a 20 73 75 63 68 20 62 65 68 61 76 69 t.** such behavi
22f80 6f 72 20 69 6e 20 69 74 73 20 6f 77 6e 20 75 73 or in its own us
22f90 65 20 6f 66 20 6d 75 74 65 78 65 73 2e 0a 2a 2a e of mutexes..**
22fa0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
22fb0 6d 75 74 65 78 5f 65 78 69 74 28 29 20 72 6f 75 mutex_exit() rou
22fc0 74 69 6e 65 20 65 78 69 74 73 20 61 20 6d 75 74 tine exits a mut
22fd0 65 78 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 70 ex that was.** p
22fe0 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 72 65 reviously entere
22ff0 64 20 62 79 20 74 68 65 20 73 61 6d 65 20 74 68 d by the same th
23000 72 65 61 64 2e 20 20 54 68 65 20 62 65 68 61 76 read. The behav
23010 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 ior.** is undefi
23020 6e 65 64 20 69 66 20 74 68 65 20 6d 75 74 65 78 ned if the mutex
23030 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c is not currentl
23040 79 20 65 6e 74 65 72 65 64 20 6f 72 0a 2a 2a 20 y entered or.**
23050 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 is not currently
23060 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 53 51 4c allocated. SQL
23070 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 64 ite will never d
23080 6f 20 65 69 74 68 65 72 2e 0a 2a 2a 0a 2a 2a 20 o either..**.**
23090 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 The sqlite3_mute
230a0 78 5f 68 65 6c 64 28 29 20 61 6e 64 20 73 71 6c x_held() and sql
230b0 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 ite3_mutex_nothe
230c0 6c 64 28 29 20 72 6f 75 74 69 6e 65 73 0a 2a 2a ld() routines.**
230d0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f are intended fo
230e0 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 73 73 r use inside ass
230f0 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 ert() statements
23100 2e 20 20 54 68 65 79 20 73 68 6f 75 6c 64 0a 2a . They should.*
23110 2a 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 66 * return true if
23120 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20 74 68 the mutex in th
23130 65 69 72 20 61 72 67 75 6d 65 6e 74 20 69 73 20 eir argument is
23140 68 65 6c 64 20 6f 72 20 6e 6f 74 20 68 65 6c 64 held or not held
23150 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c ,.** respectivel
23160 79 2c 20 62 79 20 74 68 65 20 63 75 72 72 65 6e y, by the curren
23170 74 20 74 68 72 65 61 64 2e 20 54 68 65 20 69 6d t thread. The im
23180 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 0a plementation is.
23190 2a 2a 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20 ** not required
231a0 74 6f 20 70 72 6f 76 69 64 65 64 20 77 6f 72 6b to provided work
231b0 69 6e 67 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ing implementati
231c0 6f 6e 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 ons of these.**
231d0 72 6f 75 74 69 6e 65 73 20 61 73 20 74 68 65 69 routines as thei
231e0 72 20 69 6e 74 65 6e 64 65 64 20 75 73 65 20 69 r intended use i
231f0 73 20 77 69 74 68 69 6e 20 61 73 73 65 72 74 28 s within assert(
23200 29 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 ) statements.**
23210 6f 6e 6c 79 2e 20 20 49 66 20 74 68 65 20 69 6d only. If the im
23220 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 plementation doe
23230 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 77 6f s not provide wo
23240 72 6b 69 6e 67 0a 2a 2a 20 76 65 72 73 69 6f 6e rking.** version
23250 73 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 s of these routi
23260 6e 65 73 2c 20 69 74 20 6d 75 73 74 20 61 74 20 nes, it must at
23270 6c 65 61 73 74 20 70 72 6f 76 69 64 65 20 73 74 least provide st
23280 75 62 73 0a 2a 2a 20 74 68 61 74 20 61 6c 77 61 ubs.** that alwa
23290 79 73 20 72 65 74 75 72 6e 20 74 72 75 65 2e 0a ys return true..
232a0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 61 72 67 **.** If the arg
232b0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 ument to sqlite3
232c0 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 69 73 _mutex_held() is
232d0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
232e0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 6f 75 74 then.** the rout
232f0 69 6e 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 ine should retur
23300 6e 20 31 2e 20 20 54 68 69 73 20 73 65 65 6d 73 n 1. This seems
23310 20 63 6f 75 6e 74 65 72 2d 69 6e 74 75 69 74 69 counter-intuiti
23320 76 65 20 73 69 6e 63 65 0a 2a 2a 20 63 6c 65 61 ve since.** clea
23330 72 6c 79 20 74 68 65 20 6d 75 74 65 78 20 63 61 rly the mutex ca
23340 6e 6e 6f 74 20 62 65 20 68 65 6c 64 20 69 66 20 nnot be held if
23350 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 it does not exis
23360 74 2e 20 20 42 75 74 20 74 68 65 0a 2a 2a 20 74 t. But the.** t
23370 68 65 20 72 65 61 73 6f 6e 20 74 68 65 20 6d 75 he reason the mu
23380 74 65 78 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 tex does not exi
23390 73 74 20 69 73 20 62 65 63 61 75 73 65 20 74 68 st is because th
233a0 65 20 62 75 69 6c 64 20 69 73 20 6e 6f 74 0a 2a e build is not.*
233b0 2a 20 75 73 69 6e 67 20 6d 75 74 65 78 65 73 2e * using mutexes.
233c0 20 20 41 6e 64 20 77 65 20 64 6f 20 6e 6f 74 20 And we do not
233d0 77 61 6e 74 20 74 68 65 20 61 73 73 65 72 74 28 want the assert(
233e0 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 ) containing the
233f0 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 .** call to sqli
23400 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 te3_mutex_held()
23410 20 74 6f 20 66 61 69 6c 2c 20 73 6f 20 61 20 6e to fail, so a n
23420 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 69 on-zero return i
23430 73 0a 2a 2a 20 74 68 65 20 61 70 70 72 6f 70 72 s.** the appropr
23440 69 61 74 65 20 74 68 69 6e 67 20 74 6f 20 64 6f iate thing to do
23450 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d . The sqlite3_m
23460 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 20 0a utex_notheld() .
23470 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f ** interface sho
23480 75 6c 64 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 uld also return
23490 31 20 77 68 65 6e 20 67 69 76 65 6e 20 61 20 4e 1 when given a N
234a0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a ULL pointer..*/.
234b0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73 sqlite3_mutex *s
234c0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c qlite3_mutex_all
234d0 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 oc(int);.void sq
234e0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 lite3_mutex_free
234f0 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 (sqlite3_mutex*)
23500 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d ;.void sqlite3_m
23510 75 74 65 78 5f 65 6e 74 65 72 28 73 71 6c 69 74 utex_enter(sqlit
23520 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 e3_mutex*);.int
23530 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 sqlite3_mutex_tr
23540 79 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a y(sqlite3_mutex*
23550 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
23560 6d 75 74 65 78 5f 6c 65 61 76 65 28 73 71 6c 69 mutex_leave(sqli
23570 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 te3_mutex*);.int
23580 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 sqlite3_mutex_h
23590 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 eld(sqlite3_mute
235a0 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 x*);.int sqlite3
235b0 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 73 _mutex_notheld(s
235c0 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a qlite3_mutex*);.
235d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d #define SQLITE_M
235e0 55 54 45 58 5f 46 41 53 54 20 20 20 20 20 20 20 UTEX_FAST
235f0 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 0.#define
23600 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 SQLITE_MUTEX_REC
23610 55 52 53 49 56 45 20 20 20 20 20 20 20 20 31 0a URSIVE 1.
23620 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d #define SQLITE_M
23630 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 UTEX_STATIC_MAST
23640 45 52 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 ER 2.#define
23650 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 SQLITE_MUTEX_STA
23660 54 49 43 5f 4d 45 4d 20 20 20 20 20 20 20 33 0a TIC_MEM 3.
23670 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d #define SQLITE_M
23680 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 UTEX_STATIC_PRNG
23690 20 20 20 20 20 20 34 0a 0a 0a 2f 2a 0a 2a 2a 20 4.../*.**
236a0 55 6e 64 6f 20 74 68 65 20 68 61 63 6b 20 74 68 Undo the hack th
236b0 61 74 20 63 6f 6e 76 65 72 74 73 20 66 6c 6f 61 at converts floa
236c0 74 69 6e 67 20 70 6f 69 6e 74 20 74 79 70 65 73 ting point types
236d0 20 74 6f 20 69 6e 74 65 67 65 72 20 66 6f 72 0a to integer for.
236e0 2a 2a 20 62 75 69 6c 64 73 20 6f 6e 20 70 72 6f ** builds on pro
236f0 63 65 73 73 6f 72 73 20 77 69 74 68 6f 75 74 20 cessors without
23700 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 floating point s
23710 75 70 70 6f 72 74 2e 0a 2a 2f 0a 23 69 66 64 65 upport..*/.#ifde
23720 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c f SQLITE_OMIT_FL
23730 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 75 OATING_POINT.# u
23740 6e 64 65 66 20 64 6f 75 62 6c 65 0a 23 65 6e 64 ndef double.#end
23750 69 66 0a 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c if..#ifdef __cpl
23760 75 73 70 6c 75 73 0a 7d 20 20 2f 2a 20 45 6e 64 usplus.} /* End
23770 20 6f 66 20 74 68 65 20 27 65 78 74 65 72 6e 20 of the 'extern
23780 22 43 22 27 20 62 6c 6f 63 6b 20 2a 2f 0a 23 65 "C"' block */.#e
23790 6e 64 69 66 0a 23 65 6e 64 69 66 0a ndif.#endif.