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 38 33 20 32 30 30 38 2f in,v 1.283 2008/
05f0: 30 31 2f 33 31 20 31 37 3a 32 31 3a 32 32 20 64 01/31 17:21:22 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 20 7b ersion Numbers {
0840: 46 31 30 30 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 F10010}.**.** Th
0850: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e e SQLITE_VERSION
0860: 20 61 6e 64 20 53 51 4c 49 54 45 5f 56 45 52 53 and SQLITE_VERS
0870: 49 4f 4e 5f 4e 55 4d 42 45 52 20 23 64 65 66 69 ION_NUMBER #defi
0880: 6e 65 73 20 69 6e 0a 2a 2a 20 74 68 65 20 73 71 nes in.** the sq
0890: 6c 69 74 65 33 2e 68 20 66 69 6c 65 20 73 70 65 lite3.h file spe
08a0: 63 69 66 79 20 74 68 65 20 76 65 72 73 69 6f 6e cify the version
08b0: 20 6f 66 20 53 51 4c 69 74 65 20 77 69 74 68 20 of SQLite with
08c0: 77 68 69 63 68 0a 2a 2a 20 74 68 61 74 20 68 65 which.** that he
08d0: 61 64 65 72 20 66 69 6c 65 20 69 73 20 61 73 73 ader file is ass
08e0: 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 ociated..**.** T
08f0: 68 65 20 22 76 65 72 73 69 6f 6e 22 20 6f 66 20 he "version" of
0900: 53 51 4c 69 74 65 20 69 73 20 61 20 73 74 72 6f SQLite is a stro
0910: 6e 67 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 ng of the form "
0920: 58 2e 59 2e 5a 22 2e 0a 2a 2a 20 54 68 65 20 70 X.Y.Z"..** The p
0930: 68 72 61 73 65 20 22 61 6c 70 68 61 22 20 6f 72 hrase "alpha" or
0940: 20 22 62 65 74 61 22 20 6d 69 67 68 74 20 62 65 "beta" might be
0950: 20 61 70 70 65 6e 64 65 64 20 61 66 74 65 72 20 appended after
0960: 74 68 65 20 5a 2e 0a 2a 2a 20 54 68 65 20 58 20 the Z..** The X
0970: 76 61 6c 75 65 20 69 73 20 6d 61 6a 6f 72 20 76 value is major v
0980: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6c ersion number al
0990: 77 61 79 73 20 33 20 69 6e 20 53 51 4c 69 74 65 ways 3 in SQLite
09a0: 33 2e 0a 2a 2a 20 54 68 65 20 58 20 76 61 6c 75 3..** The X valu
09b0: 65 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77 e only changes w
09c0: 68 65 6e 20 20 62 61 63 6b 77 61 72 64 73 20 63 hen backwards c
09d0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 69 73 0a ompatibility is.
09e0: 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64 20 77 65 ** broken and we
09f0: 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65 76 65 72 intend to never
0a00: 20 62 72 65 61 6b 0a 2a 2a 20 62 61 63 6b 77 61 break.** backwa
0a10: 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 rds compatibilit
0a20: 79 2e 20 20 54 68 65 20 59 20 76 61 6c 75 65 20 y. The Y value
0a30: 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 is the minor ver
0a40: 73 69 6f 6e 0a 2a 2a 20 6e 75 6d 62 65 72 20 61 sion.** number a
0a50: 6e 64 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 nd only changes
0a60: 77 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72 when.** there ar
0a70: 65 20 6d 61 6a 6f 72 20 66 65 61 74 75 72 65 20 e major feature
0a80: 65 6e 68 61 6e 63 65 6d 65 6e 74 73 20 74 68 61 enhancements tha
0a90: 74 20 61 72 65 20 66 6f 72 77 61 72 64 73 20 63 t are forwards c
0aa0: 6f 6d 70 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74 ompatible.** but
0ab0: 20 6e 6f 74 20 62 61 63 6b 77 61 72 64 73 20 63 not backwards c
0ac0: 6f 6d 70 61 74 69 62 6c 65 2e 20 20 54 68 65 20 ompatible. The
0ad0: 5a 20 76 61 6c 75 65 20 69 73 20 72 65 6c 65 61 Z value is relea
0ae0: 73 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 61 6e 64 se number.** and
0af0: 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 is incremented
0b00: 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72 65 6c with.** each rel
0b10: 65 61 73 65 20 62 75 74 20 72 65 73 65 74 73 20 ease but resets
0b20: 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e 20 59 back to 0 when Y
0b30: 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 2e is incremented.
0b40: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
0b50: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 [sqlite3_libver
0b60: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c sion()] and [sql
0b70: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f ite3_libversion_
0b80: 6e 75 6d 62 65 72 28 29 5d 2e 0a 2a 2a 0a 2a 2a number()]..**.**
0b90: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
0ba0: 2a 2a 20 7b 46 31 30 30 31 31 7d 20 54 68 65 20 ** {F10011} The
0bb0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 23 SQLITE_VERSION #
0bc0: 64 65 66 69 6e 65 20 69 6e 20 74 68 65 20 73 71 define in the sq
0bd0: 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72 20 66 lite3.h header f
0be0: 69 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ile.**
0bf0: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73 evaluates to a s
0c00: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 tring literal th
0c10: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65 at is the SQLite
0c20: 20 76 65 72 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 version.**
0c30: 20 20 20 20 20 77 69 74 68 20 77 68 69 63 68 20 with which
0c40: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 20 the header file
0c50: 69 73 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a is associated..*
0c60: 2a 0a 2a 2a 20 7b 46 31 30 30 31 34 7d 20 54 68 *.** {F10014} Th
0c70: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e e SQLITE_VERSION
0c80: 5f 4e 55 4d 42 45 52 20 23 64 65 66 69 6e 65 20 _NUMBER #define
0c90: 72 65 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 resolves to an i
0ca0: 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 nteger.**
0cb0: 20 20 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 with the valu
0cc0: 65 20 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 e (X*1000000 +
0cd0: 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72 Y*1000 + Z) wher
0ce0: 65 20 58 2c 20 59 2c 20 61 6e 64 0a 2a 2a 20 20 e X, Y, and.**
0cf0: 20 20 20 20 20 20 20 20 5a 20 61 72 65 20 74 68 Z are th
0d00: 65 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 2c e major version,
0d10: 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 2c 20 minor version,
0d20: 61 6e 64 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 and release numb
0d30: 65 72 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 er..*/.#define S
0d40: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 QLITE_VERSION
0d50: 20 20 20 20 20 20 22 33 2e 35 2e 35 22 0a 23 64 "3.5.5".#d
0d60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 efine SQLITE_VER
0d70: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 30 35 SION_NUMBER 3005
0d80: 30 30 35 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 005../*.** CAPI3
0d90: 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 REF: Run-Time Li
0da0: 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 brary Version Nu
0db0: 6d 62 65 72 73 20 7b 46 31 30 30 32 30 7d 0a 2a mbers {F10020}.*
0dc0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 * KEYWORDS: sqli
0dd0: 74 65 33 5f 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a te3_version.**.*
0de0: 2a 20 54 68 65 73 65 20 66 65 61 74 75 72 65 73 * These features
0df0: 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d provide the sam
0e00: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 e information as
0e10: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 the [SQLITE_VER
0e20: 53 49 4f 4e 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 SION].** and [SQ
0e30: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d LITE_VERSION_NUM
0e40: 42 45 52 5d 20 23 64 65 66 69 6e 65 73 20 69 6e BER] #defines in
0e50: 20 74 68 65 20 68 65 61 64 65 72 2c 20 62 75 74 the header, but
0e60: 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 0a are associated.
0e70: 2a 2a 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 ** with the libr
0e80: 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 ary instead of t
0e90: 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 he header file.
0ea0: 20 43 61 75 74 69 6f 75 73 20 70 72 6f 67 72 61 Cautious progra
0eb0: 6d 6d 65 72 73 20 6d 69 67 68 74 0a 2a 2a 20 69 mmers might.** i
0ec0: 6e 63 6c 75 64 65 20 61 20 63 68 65 63 6b 20 69 nclude a check i
0ed0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 n their applicat
0ee0: 69 6f 6e 20 74 6f 20 76 65 72 69 66 79 20 74 68 ion to verify th
0ef0: 61 74 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c at .** sqlite3_l
0f00: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 ibversion_number
0f10: 28 29 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e () always return
0f20: 73 20 74 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 s the value .**
0f30: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f [SQLITE_VERSION_
0f40: 4e 55 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 54 NUMBER]..**.** T
0f50: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 he sqlite3_libve
0f60: 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e rsion() function
0f70: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 61 6d returns the sam
0f80: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 e information as
0f90: 20 69 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 71 is.** in the sq
0fa0: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 lite3_version[]
0fb0: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e string constant.
0fc0: 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 The function i
0fd0: 73 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f s provided.** fo
0fe0: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 r use in DLLs si
0ff0: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 nce DLL users us
1000: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 ually do not hav
1010: 65 20 64 69 72 65 63 74 20 61 63 63 65 73 73 20 e direct access
1020: 74 6f 20 73 74 72 69 6e 67 0a 2a 2a 20 63 6f 6e to string.** con
1030: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 stants within th
1040: 65 20 44 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 e DLL..**.** INV
1050: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
1060: 46 31 30 30 32 31 7d 20 54 68 65 20 5b 73 71 6c F10021} The [sql
1070: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f ite3_libversion_
1080: 6e 75 6d 62 65 72 28 29 5d 20 69 6e 74 65 72 66 number()] interf
1090: 61 63 65 20 72 65 74 75 72 6e 73 20 61 6e 20 69 ace returns an i
10a0: 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 nteger.**
10b0: 20 20 20 65 71 75 61 6c 20 74 6f 20 5b 53 51 4c equal to [SQL
10c0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 ITE_VERSION_NUMB
10d0: 45 52 5d 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 ER]. .**.** {F10
10e0: 30 32 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 022} The [sqlite
10f0: 33 5f 76 65 72 73 69 6f 6e 5d 20 73 74 72 69 6e 3_version] strin
1100: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 g constant conta
1110: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 ins the text of
1120: 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
1130: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d [SQLITE_VERSION]
1140: 20 73 74 72 69 6e 67 2e 20 0a 2a 2a 0a 2a 2a 20 string. .**.**
1150: 7b 46 31 30 30 32 33 7d 20 54 68 65 20 5b 73 71 {F10023} The [sq
1160: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e lite3_libversion
1170: 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 ()] function ret
1180: 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 urns.**
1190: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
11a0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 73 69 e [sqlite3_versi
11b0: 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 on] string const
11c0: 61 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 ant..*/.SQLITE_E
11d0: 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 XTERN const char
11e0: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e sqlite3_version
11f0: 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a [];.const char *
1200: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
1210: 6f 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 on(void);.int sq
1220: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e lite3_libversion
1230: 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a _number(void);..
1240: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1250: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 Test To See If T
1260: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 he Library Is Th
1270: 72 65 61 64 73 61 66 65 20 7b 46 31 30 31 30 30 readsafe {F10100
1280: 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 }.**.** SQLite c
1290: 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 an be compiled w
12a0: 69 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d ith or without m
12b0: 75 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a utexes. When.**
12c0: 20 74 68 65 20 53 51 4c 49 54 45 5f 54 48 52 45 the SQLITE_THRE
12d0: 41 44 53 41 46 45 20 43 20 70 72 65 70 72 6f 63 ADSAFE C preproc
12e0: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 74 essor macro is t
12f0: 72 75 65 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 rue, mutexes.**
1300: 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 are enabled and
1310: 53 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 SQLite is thread
1320: 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68 61 74 safe. When that
1330: 20 6d 61 63 72 6f 20 6f 73 20 66 61 6c 73 65 2c macro os false,
1340: 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 .** the mutexes
1350: 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 are omitted. Wi
1360: 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 thout the mutexe
1370: 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 s, it is not saf
1380: 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 e.** to use SQLi
1390: 74 65 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 te from more tha
13a0: 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a n one thread..**
13b0: 0a 2a 2a 20 54 68 65 72 65 20 69 73 20 61 20 6d .** There is a m
13c0: 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 easurable perfor
13d0: 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 20 66 6f mance penalty fo
13e0: 72 20 65 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 r enabling mutex
13f0: 65 73 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 es..** So if spe
1400: 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 ed is of utmost
1410: 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d importance, it m
1420: 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69 akes sense to di
1430: 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 sable.** the mut
1440: 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d exes. But for m
1450: 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d aximum safety, m
1460: 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65 utexes should be
1470: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68 65 enabled..** The
1480: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f default behavio
1490: 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 r is for mutexes
14a0: 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a to be enabled..
14b0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 **.** This inter
14c0: 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 face can be used
14d0: 20 62 79 20 61 20 70 72 6f 67 72 61 6d 20 74 6f by a program to
14e0: 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 make sure that
14f0: 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f the.** version o
1500: 66 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 f SQLite that it
1510: 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 is linking agai
1520: 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 nst was compiled
1530: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 with.** the des
1540: 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 ired setting of
1550: 74 68 65 20 53 51 4c 49 54 45 5f 54 48 52 45 41 the SQLITE_THREA
1560: 44 53 41 46 45 20 6d 61 63 72 6f 2e 0a 2a 2a 0a DSAFE macro..**.
1570: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
1580: 2a 0a 2a 2a 20 7b 46 31 30 31 30 31 7d 20 54 68 *.** {F10101} Th
1590: 65 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 e [sqlite3_threa
15a0: 64 73 61 66 65 28 29 5d 20 66 75 6e 63 74 69 6f dsafe()] functio
15b0: 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 7a 65 72 n returns nonzer
15c0: 6f 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 o if.**
15d0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 SQLite was comp
15e0: 69 6c 65 64 20 77 69 74 68 20 69 74 73 20 6d 75 iled with its mu
15f0: 74 65 78 65 73 20 65 6e 61 62 6c 65 64 20 6f 72 texes enabled or
1600: 20 7a 65 72 6f 0a 2a 2a 20 20 20 20 20 20 20 20 zero.**
1610: 20 20 69 66 20 53 51 4c 69 74 65 20 77 61 73 20 if SQLite was
1620: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 compiled with mu
1630: 74 65 78 65 73 20 64 69 73 61 62 6c 65 64 2e 0a texes disabled..
1640: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 */.int sqlite3_t
1650: 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b hreadsafe(void);
1660: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1670: 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 : Database Conne
1680: 63 74 69 6f 6e 20 48 61 6e 64 6c 65 20 7b 46 31 ction Handle {F1
1690: 32 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 2000}.** KEYWORD
16a0: 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e S: {database con
16b0: 6e 65 63 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 45 nection}.**.** E
16c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 ach open SQLite
16d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 database is repr
16e0: 65 73 65 6e 74 65 64 20 62 79 20 70 6f 69 6e 74 esented by point
16f0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 er to an instanc
1700: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 70 61 71 e of the.** opaq
1710: 75 65 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d ue structure nam
1720: 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 ed "sqlite3". I
1730: 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 t is useful to t
1740: 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 hink of an sqlit
1750: 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 e3.** pointer as
1760: 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 an object. The
1770: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
1780: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ], [sqlite3_open
1790: 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 16()], and.** [s
17a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
17b0: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 ] interfaces are
17c0: 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 its constructor
17d0: 73 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 s.** and [sqlite
17e0: 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 74 3_close()] is it
17f0: 73 20 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 s destructor. T
1800: 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 here are many ot
1810: 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a her interfaces.*
1820: 2a 20 28 73 75 63 68 20 61 73 20 5b 73 71 6c 69 * (such as [sqli
1830: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
1840: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 ], [sqlite3_crea
1850: 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 te_function()],
1860: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
1870: 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 busy_timeout()]
1880: 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 to name but thre
1890: 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 e) that are meth
18a0: 6f 64 73 20 6f 6e 20 74 68 69 73 0a 2a 2a 20 6f ods on this.** o
18b0: 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 bject..*/.typede
18c0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
18d0: 20 73 71 6c 69 74 65 33 3b 0a 0a 0a 2f 2a 0a 2a sqlite3;.../*.*
18e0: 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 * CAPI3REF: 64-B
18f0: 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 it Integer Types
1900: 20 7b 46 31 30 32 30 30 7d 0a 2a 2a 20 4b 45 59 {F10200}.** KEY
1910: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e WORDS: sqlite_in
1920: 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 t64 sqlite_uint6
1930: 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 4.**.** Because
1940: 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 there is no cros
1950: 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 s-platform way t
1960: 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 o specify 64-bit
1970: 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a integer types.*
1980: 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 * SQLite include
1990: 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 s typedefs for 6
19a0: 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 4-bit signed and
19b0: 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 unsigned intege
19c0: 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 rs..**.** The sq
19d0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 lite3_int64 and
19e0: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 sqlite3_uint64 a
19f0: 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 re the preferred
1a00: 20 74 79 70 65 0a 2a 2a 20 64 65 66 69 6e 69 74 type.** definit
1a10: 69 6f 6e 73 2e 20 20 54 68 65 20 73 71 6c 69 74 ions. The sqlit
1a20: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 e_int64 and sqli
1a30: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 te_uint64 types
1a40: 61 72 65 0a 2a 2a 20 73 75 70 70 6f 72 74 65 64 are.** supported
1a50: 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 for backwards c
1a60: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c ompatibility onl
1a70: 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 y..**.** INVARIA
1a80: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 NTS:.**.** {F102
1a90: 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 5f 01} The [sqlite_
1aa0: 69 6e 74 36 34 5d 20 61 6e 64 20 5b 73 71 6c 69 int64] and [sqli
1ab0: 74 65 33 5f 69 6e 74 36 34 5d 20 74 79 70 65 73 te3_int64] types
1ac0: 20 73 70 65 63 69 66 79 20 61 0a 2a 2a 20 20 20 specify a.**
1ad0: 20 20 20 20 20 20 20 36 34 2d 62 69 74 20 73 69 64-bit si
1ae0: 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a gned integer..**
1af0: 0a 2a 2a 20 7b 46 31 30 32 30 32 7d 20 54 68 65 .** {F10202} The
1b00: 20 5b 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 5d [sqlite_uint64]
1b10: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 75 69 and [sqlite3_ui
1b20: 6e 74 36 34 5d 20 74 79 70 65 73 20 73 70 65 63 nt64] types spec
1b30: 69 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ify.**
1b40: 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 a 64-bit unsigne
1b50: 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2f 0a 23 69 d integer..*/.#i
1b60: 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 fdef SQLITE_INT6
1b70: 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 4_TYPE. typedef
1b80: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 SQLITE_INT64_TY
1b90: 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b PE sqlite_int64;
1ba0: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 . typedef unsig
1bb0: 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 ned SQLITE_INT64
1bc0: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e _TYPE sqlite_uin
1bd0: 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e t64;.#elif defin
1be0: 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 ed(_MSC_VER) ||
1bf0: 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e defined(__BORLAN
1c00: 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 DC__). typedef
1c10: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 __int64 sqlite_i
1c20: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 nt64;. typedef
1c30: 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 unsigned __int64
1c40: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a sqlite_uint64;.
1c50: 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 #else. typedef
1c60: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 long long int sq
1c70: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 lite_int64;. ty
1c80: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c pedef unsigned l
1c90: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c ong long int sql
1ca0: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 ite_uint64;.#end
1cb0: 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 if.typedef sqlit
1cc0: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f e_int64 sqlite3_
1cd0: 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 int64;.typedef s
1ce0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c qlite_uint64 sql
1cf0: 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a ite3_uint64;../*
1d00: 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 .** If compiling
1d10: 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 for a processor
1d20: 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 that lacks floa
1d30: 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f ting point suppo
1d40: 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 rt,.** substitut
1d50: 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c e integer for fl
1d60: 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 0a 2a 2f 0a oating-point.*/.
1d70: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d #ifdef SQLITE_OM
1d80: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e IT_FLOATING_POIN
1d90: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c T.# define doubl
1da0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a e sqlite3_int64.
1db0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 #endif../*.** CA
1dc0: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 PI3REF: Closing
1dd0: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 A Database Conne
1de0: 63 74 69 6f 6e 20 7b 46 31 32 30 31 30 7d 0a 2a ction {F12010}.*
1df0: 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
1e00: 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75 63 e is the destruc
1e10: 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71 6c tor for the [sql
1e20: 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 20 20 0a ite3] object. .
1e30: 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f **.** Applicatio
1e40: 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 ns should [sqlit
1e50: 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 e3_finalize | fi
1e60: 6e 61 6c 69 7a 65 5d 20 61 6c 6c 0a 2a 2a 20 5b nalize] all.** [
1e70: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1e80: 6e 74 73 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c nts] and.** [sql
1e90: 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 ite3_blob_close
1ea0: 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 73 71 | close] all [sq
1eb0: 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 42 4c 4f lite3_blob | BLO
1ec0: 42 73 5d 20 0a 2a 2a 20 61 73 73 6f 63 69 61 74 Bs] .** associat
1ed0: 65 64 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c ed with the [sql
1ee0: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 ite3] object pri
1ef0: 6f 72 0a 2a 2a 20 74 6f 20 61 74 74 65 6d 70 74 or.** to attempt
1f00: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 ing to close the
1f10: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 [sqlite3] objec
1f20: 74 2e 0a 2a 2a 0a 2a 2a 20 3c 74 6f 64 6f 3e 57 t..**.** <todo>W
1f30: 68 61 74 20 68 61 70 70 65 6e 73 20 74 6f 20 70 hat happens to p
1f40: 65 6e 64 69 6e 67 20 74 72 61 6e 73 61 63 74 69 ending transacti
1f50: 6f 6e 73 3f 20 20 41 72 65 20 74 68 65 79 0a 2a ons? Are they.*
1f60: 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2c 20 6f * rolled back, o
1f70: 72 20 61 62 61 6e 64 6f 6e 65 64 3f 3c 2f 74 6f r abandoned?</to
1f80: 64 6f 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 do>.**.** INVARI
1f90: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 ANTS:.**.** {F12
1fa0: 30 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 011} The [sqlite
1fb0: 33 5f 63 6c 6f 73 65 28 29 5d 20 69 6e 74 65 72 3_close()] inter
1fc0: 66 61 63 65 20 64 65 73 74 72 6f 79 73 20 61 6e face destroys an
1fd0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 [sqlite3] objec
1fe0: 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c t.** al
1ff0: 6c 6f 63 61 74 65 64 20 62 79 20 61 20 70 72 69 located by a pri
2000: 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 or call to [sqli
2010: 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 te3_open()],.**
2020: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
2030: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 3_open16()], or
2040: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
2050: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 ()]..**.** {F120
2060: 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 12} The [sqlite3
2070: 5f 63 6c 6f 73 65 28 29 5d 20 66 75 6e 63 74 69 _close()] functi
2080: 6f 6e 20 72 65 6c 65 61 73 65 73 20 61 6c 6c 20 on releases all
2090: 6d 65 6d 6f 72 79 20 75 73 65 64 20 62 79 20 74 memory used by t
20a0: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 he.** c
20b0: 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 63 6c onnection and cl
20c0: 6f 73 65 73 20 61 6c 6c 20 6f 70 65 6e 20 66 69 oses all open fi
20d0: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 les..**.** {F120
20e0: 31 33 7d 20 49 66 20 74 68 65 20 64 61 74 61 62 13} If the datab
20f0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 ase connection c
2100: 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 ontains.**
2110: 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 [prepared st
2120: 61 74 65 6d 65 6e 74 73 5d 20 74 68 61 74 20 68 atements] that h
2130: 61 76 65 20 6e 6f 74 20 62 65 65 6e 0a 2a 2a 20 ave not been.**
2140: 20 20 20 20 20 20 20 20 20 66 69 6e 61 6c 69 7a finaliz
2150: 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 ed by [sqlite3_f
2160: 69 6e 61 6c 69 7a 65 28 29 5d 2c 20 74 68 65 6e inalize()], then
2170: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 [sqlite3_close(
2180: 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 )].** r
2190: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 eturns [SQLITE_B
21a0: 55 53 59 5d 20 61 6e 64 20 6c 65 61 76 65 73 20 USY] and leaves
21b0: 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f the connection o
21c0: 70 65 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 pen..**.** {F120
21d0: 31 34 7d 20 47 69 76 69 6e 67 20 73 71 6c 69 74 14} Giving sqlit
21e0: 65 33 5f 63 6c 6f 73 65 28 29 20 61 20 4e 55 4c e3_close() a NUL
21f0: 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 L pointer is a h
2200: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a armless no-op..*
2210: 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 *.** LIMITATIONS
2220: 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 30 31 35 7d :.**.** {U12015}
2230: 20 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 The parameter t
2240: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 o [sqlite3_close
2250: 28 29 5d 20 6d 75 73 74 20 62 65 20 61 6e 20 5b ()] must be an [
2260: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 0a sqlite3] object.
2270: 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e ** poin
2280: 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 6f ter previously o
2290: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
22a0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 lite3_open()] or
22b0: 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 the .**
22c0: 20 20 65 71 75 69 76 61 6c 65 6e 74 2c 20 6f 72 equivalent, or
22d0: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 NULL..**.** {U1
22e0: 32 30 31 36 7d 20 54 68 65 20 70 61 72 61 6d 65 2016} The parame
22f0: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
2300: 63 6c 6f 73 65 28 29 5d 20 6d 75 73 74 20 6e 6f close()] must no
2310: 74 20 68 61 76 65 20 62 65 65 6e 20 70 72 65 76 t have been prev
2320: 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 iously.**
2330: 20 20 20 63 6c 6f 73 65 64 2e 0a 2a 2f 0a 69 6e closed..*/.in
2340: 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 t sqlite3_close(
2350: 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a sqlite3 *);../*.
2360: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 ** The type for
2370: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 a callback funct
2380: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 ion..** This is
2390: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 legacy and depre
23a0: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e cated. It is in
23b0: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f cluded for histo
23c0: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 rical.** compati
23d0: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f bility and is no
23e0: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f t documented..*/
23f0: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 .typedef int (*s
2400: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 qlite3_callback)
2410: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a (void*,int,char*
2420: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a *, char**);../*.
2430: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 ** CAPI3REF: One
2440: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63 -Step Query Exec
2450: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 20 ution Interface
2460: 7b 46 31 32 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 {F12100}.**.** T
2470: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 he sqlite3_exec(
2480: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 ) interface is a
2490: 20 63 6f 6e 76 65 6e 69 65 6e 74 20 77 61 79 20 convenient way
24a0: 6f 66 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 6f 6e of running.** on
24b0: 65 20 6f 72 20 6d 6f 72 65 20 53 51 4c 20 73 74 e or more SQL st
24c0: 61 74 65 6d 65 6e 74 73 20 77 69 74 68 6f 75 74 atements without
24d0: 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 a lot of C code
24e0: 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c 20 73 74 . The.** SQL st
24f0: 61 74 65 6d 65 6e 74 73 20 61 72 65 20 70 61 73 atements are pas
2500: 73 65 64 20 69 6e 20 61 73 20 74 68 65 20 73 65 sed in as the se
2510: 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 cond parameter t
2520: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 o.** sqlite3_exe
2530: 63 28 29 2e 20 20 54 68 65 20 73 74 61 74 65 6d c(). The statem
2540: 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 ents are evaluat
2550: 65 64 20 6f 6e 65 20 62 79 20 6f 6e 65 0a 2a 2a ed one by one.**
2560: 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 61 6e until either an
2570: 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 69 6e 74 error or an int
2580: 65 72 72 75 70 74 20 69 73 20 65 6e 63 6f 75 6e errupt is encoun
2590: 74 65 72 65 64 20 6f 72 0a 2a 2a 20 75 6e 74 69 tered or.** unti
25a0: 6c 20 74 68 65 79 20 61 72 65 20 61 6c 6c 20 64 l they are all d
25b0: 6f 6e 65 2e 20 20 54 68 65 20 33 72 64 20 70 61 one. The 3rd pa
25c0: 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 6f 70 rameter is an op
25d0: 74 69 6f 6e 61 6c 0a 2a 2a 20 63 61 6c 6c 62 61 tional.** callba
25e0: 63 6b 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b ck that is invok
25f0: 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 ed once for each
2600: 20 72 6f 77 20 6f 66 20 61 6e 79 20 71 75 65 72 row of any quer
2610: 79 20 72 65 73 75 6c 74 73 0a 2a 2a 20 70 72 6f y results.** pro
2620: 64 75 63 65 64 20 62 79 20 74 68 65 20 53 51 4c duced by the SQL
2630: 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 54 68 statements. Th
2640: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 5th parameter
2650: 74 65 6c 6c 73 20 77 68 65 72 65 0a 2a 2a 20 74 tells where.** t
2660: 6f 20 77 72 69 74 65 20 61 6e 79 20 65 72 72 6f o write any erro
2670: 72 20 6d 65 73 73 61 67 65 73 2e 0a 2a 2a 0a 2a r messages..**.*
2680: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 * The sqlite3_ex
2690: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 ec() interface i
26a0: 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e s implemented in
26b0: 20 74 65 72 6d 73 20 6f 66 0a 2a 2a 20 5b 73 71 terms of.** [sq
26c0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
26d0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 ()], [sqlite3_st
26e0: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 ep()], and [sqli
26f0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e te3_finalize()].
2700: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
2710: 65 78 65 63 28 29 20 72 6f 75 74 69 6e 65 20 64 exec() routine d
2720: 6f 65 73 20 6e 6f 74 68 69 6e 67 20 74 68 61 74 oes nothing that
2730: 20 63 61 6e 6e 6f 74 20 62 65 20 64 6f 6e 65 0a cannot be done.
2740: 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 ** by [sqlite3_p
2750: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 repare_v2()], [s
2760: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 qlite3_step()],
2770: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e and [sqlite3_fin
2780: 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 alize()]..** The
2790: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
27a0: 69 73 20 6a 75 73 74 20 61 20 63 6f 6e 76 65 6e is just a conven
27b0: 69 65 6e 74 20 77 72 61 70 70 65 72 2e 0a 2a 2a ient wrapper..**
27c0: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
27d0: 2a 2a 20 0a 2a 2a 20 7b 46 31 32 31 30 31 7d 20 ** .** {F12101}
27e0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 The [sqlite3_exe
27f0: 63 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 65 c()] interface e
2800: 76 61 6c 75 61 74 65 73 20 7a 65 72 6f 20 6f 72 valuates zero or
2810: 20 6d 6f 72 65 20 55 54 46 2d 38 0a 2a 2a 20 20 more UTF-8.**
2820: 20 20 20 20 20 20 20 20 65 6e 63 6f 64 65 64 2c encoded,
2830: 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 semicolon-separ
2840: 61 74 65 64 2c 20 53 51 4c 20 73 74 61 74 65 6d ated, SQL statem
2850: 65 6e 74 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 ents in the.**
2860: 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 zero-ter
2870: 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 20 6f minated string o
2880: 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 f its 2nd parame
2890: 74 65 72 20 77 69 74 68 69 6e 20 74 68 65 0a 2a ter within the.*
28a0: 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 * conte
28b0: 78 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 xt of the [sqlit
28c0: 65 33 5d 20 6f 62 6a 65 63 74 20 67 69 76 65 6e e3] object given
28d0: 20 69 6e 20 74 68 65 20 31 73 74 20 70 61 72 61 in the 1st para
28e0: 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 meter..**.** {F1
28f0: 32 31 30 34 7d 20 54 68 65 20 72 65 74 75 72 6e 2104} The return
2900: 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 value of [sqlit
2910: 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20 53 51 e3_exec()] is SQ
2920: 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6c 6c 0a 2a LITE_OK if all.*
2930: 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 73 * SQL s
2940: 74 61 74 65 6d 65 6e 74 73 20 72 75 6e 20 73 75 tatements run su
2950: 63 63 65 73 73 66 75 6c 6c 79 2e 0a 2a 2a 0a 2a ccessfully..**.*
2960: 2a 20 7b 46 31 32 31 30 35 7d 20 54 68 65 20 72 * {F12105} The r
2970: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 5b eturn value of [
2980: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 sqlite3_exec()]
2990: 69 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 is an appropriat
29a0: 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e e .** n
29b0: 6f 6e 2d 7a 65 72 6f 20 65 72 72 6f 72 20 63 6f on-zero error co
29c0: 64 65 20 69 66 20 61 6e 79 20 53 51 4c 20 73 74 de if any SQL st
29d0: 61 74 65 6d 65 6e 74 20 66 61 69 6c 73 2e 0a 2a atement fails..*
29e0: 2a 0a 2a 2a 20 7b 46 31 32 31 30 37 7d 20 49 66 *.** {F12107} If
29f0: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 one or more of
2a00: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
2a10: 74 73 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 71 ts handed to [sq
2a20: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a lite3_exec()].**
2a30: 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e return
2a40: 20 72 65 73 75 6c 74 73 20 61 6e 64 20 74 68 65 results and the
2a50: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 3rd parameter i
2a60: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e s not NULL, then
2a70: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
2a80: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
2a90: 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20 on specified by
2aa0: 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 the 3rd paramete
2ab0: 72 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 r is.**
2ac0: 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f invoked once fo
2ad0: 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 72 65 r each row of re
2ae0: 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 sult..**.** {F12
2af0: 31 31 30 7d 20 49 66 20 74 68 65 20 63 61 6c 6c 110} If the call
2b00: 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 6e back returns a n
2b10: 6f 6e 2d 7a 65 72 6f 20 76 61 6c 75 65 20 74 68 on-zero value th
2b20: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 en [sqlite3_exec
2b30: 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ()].**
2b40: 77 69 6c 6c 20 61 62 6f 72 74 65 64 20 74 68 65 will aborted the
2b50: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 SQL statement i
2b60: 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 65 t is currently e
2b70: 76 61 6c 75 61 74 69 6e 67 2c 0a 2a 2a 20 20 20 valuating,.**
2b80: 20 20 20 20 20 20 20 73 6b 69 70 20 61 6c 6c 20 skip all
2b90: 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 subsequent SQL s
2ba0: 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 72 tatements, and r
2bb0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 41 42 eturn [SQLITE_AB
2bc0: 4f 52 54 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 20 ORT]..**
2bd0: 20 20 3c 74 6f 64 6f 3e 57 68 61 74 20 68 61 70 <todo>What hap
2be0: 70 65 6e 73 20 74 6f 20 2a 65 72 72 6d 73 67 20 pens to *errmsg
2bf0: 68 65 72 65 3f 20 20 44 6f 65 73 20 74 68 65 20 here? Does the
2c00: 72 65 73 75 6c 74 20 63 6f 64 65 20 66 6f 72 0a result code for.
2c10: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 ** sqli
2c20: 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 67 65 te3_errcode() ge
2c30: 74 20 73 65 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a t set?</todo>.**
2c40: 0a 2a 2a 20 7b 46 31 32 31 31 33 7d 20 54 68 65 .** {F12113} The
2c50: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 [sqlite3_exec()
2c60: 5d 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 70 ] routine will p
2c70: 61 73 73 20 69 74 73 20 34 74 68 20 70 61 72 61 ass its 4th para
2c80: 6d 65 74 65 72 20 74 68 72 6f 75 67 68 0a 2a 2a meter through.**
2c90: 20 20 20 20 20 20 20 20 20 20 61 73 20 74 68 65 as the
2ca0: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 6f 1st parameter o
2cb0: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a f the callback..
2cc0: 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31 36 7d 20 54 **.** {F12116} T
2cd0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 he [sqlite3_exec
2ce0: 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 65 74 73 ()] routine sets
2cf0: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
2d00: 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 er of its.**
2d10: 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 callback t
2d20: 6f 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 o be the number
2d30: 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 of columns in th
2d40: 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 e current row of
2d50: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 .** res
2d60: 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 ult..**.** {F121
2d70: 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 19} The [sqlite3
2d80: 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 _exec()] routine
2d90: 20 73 65 74 73 20 74 68 65 20 33 72 64 20 70 61 sets the 3rd pa
2da0: 72 61 6d 65 74 65 72 20 6f 66 20 69 74 73 20 0a rameter of its .
2db0: 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c ** call
2dc0: 62 61 63 6b 20 74 6f 20 62 65 20 61 6e 20 61 72 back to be an ar
2dd0: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 ray of pointers
2de0: 74 6f 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 to strings holdi
2df0: 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 ng the.**
2e00: 20 20 20 76 61 6c 75 65 73 20 66 6f 72 20 65 61 values for ea
2e10: 63 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 ch column in the
2e20: 20 63 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20 current result
2e30: 73 65 74 20 72 6f 77 20 61 73 0a 2a 2a 20 20 20 set row as.**
2e40: 20 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20 obtained
2e50: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f from [sqlite3_co
2e60: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a lumn_text()]..**
2e70: 0a 2a 2a 20 7b 46 31 32 31 32 32 7d 20 54 68 65 .** {F12122} The
2e80: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 [sqlite3_exec()
2e90: 5d 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 74 ] routine sets t
2ea0: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 he 4th parameter
2eb0: 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 of its.**
2ec0: 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 callback to
2ed0: 62 65 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 be an array of p
2ee0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e ointers to strin
2ef0: 67 73 20 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a gs holding the.*
2f00: 2a 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65 73 * names
2f10: 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d of result colum
2f20: 6e 73 20 61 73 20 6f 62 74 61 69 6e 65 64 20 66 ns as obtained f
2f30: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c rom [sqlite3_col
2f40: 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a umn_name()]..**.
2f50: 2a 2a 20 7b 46 31 32 31 32 35 7d 20 49 66 20 74 ** {F12125} If t
2f60: 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 he 3rd parameter
2f70: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 to [sqlite3_exe
2f80: 63 28 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 c()] is NULL the
2f90: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 n.** [s
2fa0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6e qlite3_exec()] n
2fb0: 65 76 65 72 20 69 6e 76 6f 6b 65 73 20 61 20 63 ever invokes a c
2fc0: 61 6c 6c 62 61 63 6b 2e 20 20 41 6c 6c 20 71 75 allback. All qu
2fd0: 65 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ery.**
2fe0: 72 65 73 75 6c 74 73 20 61 72 65 20 73 69 6c 65 results are sile
2ff0: 6e 74 6c 79 20 64 69 73 63 61 72 64 65 64 2e 0a ntly discarded..
3000: 2a 2a 0a 2a 2a 20 7b 46 31 32 31 32 38 7d 20 49 **.** {F12128} I
3010: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 f an error occur
3020: 73 20 77 68 69 6c 65 20 70 61 72 73 69 6e 67 20 s while parsing
3030: 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 61 6e or evaluating an
3040: 79 20 6f 66 20 74 68 65 20 53 51 4c 0a 2a 2a 20 y of the SQL.**
3050: 20 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 stateme
3060: 6e 74 73 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 nts handed to [s
3070: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 74 qlite3_exec()] t
3080: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 hen [sqlite3_exe
3090: 63 28 29 5d 20 77 69 6c 6c 0a 2a 2a 20 20 20 20 c()] will.**
30a0: 20 20 20 20 20 20 72 65 74 75 72 6e 20 61 6e 20 return an
30b0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 [error code] oth
30c0: 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
30d0: 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 OK]..**.** {F121
30e0: 33 31 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20 31} If an error
30f0: 6f 63 63 75 72 73 20 77 68 69 6c 65 20 70 61 72 occurs while par
3100: 73 69 6e 67 20 6f 72 20 65 76 61 6c 75 61 74 69 sing or evaluati
3110: 6e 67 20 61 6e 79 20 6f 66 20 74 68 65 20 53 51 ng any of the SQ
3120: 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61 L.** ha
3130: 6e 64 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 nded to [sqlite3
3140: 5f 65 78 65 63 28 29 5d 20 61 6e 64 20 69 66 20 _exec()] and if
3150: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 the 5th paramete
3160: 72 20 28 65 72 72 6d 73 67 29 0a 2a 2a 20 20 20 r (errmsg).**
3170: 20 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69 74 to [sqlit
3180: 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20 6e 6f e3_exec()] is no
3190: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6e 20 t NULL, then an
31a0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 error message is
31b0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c .** all
31c0: 6f 63 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 ocated using the
31d0: 20 65 71 75 69 76 61 6c 65 6e 74 20 6f 66 20 5b equivalent of [
31e0: 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
31f0: 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 )] and.**
3200: 20 20 20 2a 65 72 72 6d 73 67 20 69 73 20 6d 61 *errmsg is ma
3210: 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 de to point to t
3220: 68 61 74 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a hat message..**.
3230: 2a 2a 20 7b 46 31 32 31 33 34 7d 20 54 68 65 20 ** {F12134} The
3240: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
3250: 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f routine does no
3260: 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c t change the val
3270: 75 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 ue of.**
3280: 20 20 2a 65 72 72 6d 73 67 20 69 66 20 65 72 72 *errmsg if err
3290: 6d 73 67 20 69 73 20 4e 55 4c 4c 20 6f 72 20 69 msg is NULL or i
32a0: 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 65 f there are no e
32b0: 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 rrors..**.** {F1
32c0: 32 31 33 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 2137} The [sqlit
32d0: 65 33 5f 65 78 65 63 28 29 5d 20 66 75 6e 63 74 e3_exec()] funct
32e0: 69 6f 6e 20 73 65 74 73 20 74 68 65 20 65 72 72 ion sets the err
32f0: 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 or code and mess
3300: 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 age.**
3310: 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b accessible via [
3320: 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
3330: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
3340: 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a errmsg()]..**.**
3350: 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a LIMITATIONS:.**
3360: 0a 2a 2a 20 7b 55 31 32 31 34 31 7d 20 54 68 65 .** {U12141} The
3370: 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
3380: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 to [sqlite3_exe
3390: 63 28 29 5d 20 6d 75 73 74 20 62 65 20 61 6e 20 c()] must be an
33a0: 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 0a 2a valid and open.*
33b0: 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 * [data
33c0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
33d0: 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34 32 7d ..**.** {U12142}
33e0: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f The database co
33f0: 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f nnection must no
3400: 74 20 62 65 20 63 6c 6f 73 65 64 20 77 68 69 6c t be closed whil
3410: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 e.** [s
3420: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 qlite3_exec()] i
3430: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 0a 2a s running..** .*
3440: 2a 20 7b 55 31 32 31 34 33 7d 20 54 68 65 20 63 * {U12143} The c
3450: 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 alling function
3460: 69 73 20 73 68 6f 75 6c 64 20 75 73 65 20 5b 73 is should use [s
3470: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 74 qlite3_free()] t
3480: 6f 20 66 72 65 65 0a 2a 2a 20 20 20 20 20 20 20 o free.**
3490: 20 20 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 the memory th
34a0: 61 74 20 2a 65 72 72 6d 73 67 20 69 73 20 6c 65 at *errmsg is le
34b0: 66 74 20 70 6f 69 6e 74 69 6e 67 20 61 74 20 6f ft pointing at o
34c0: 6e 63 65 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a nce the error.**
34d0: 20 20 20 20 20 20 20 20 20 20 6d 65 73 73 61 67 messag
34e0: 65 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e e is no longer n
34f0: 65 65 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 eeded..**.** {U1
3500: 32 31 34 35 7d 20 54 68 65 20 53 51 4c 20 73 74 2145} The SQL st
3510: 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 20 atement text in
3520: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
3530: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 r to [sqlite3_ex
3540: 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 ec()].**
3550: 20 20 6d 75 73 74 20 72 65 6d 61 69 6e 20 75 6e must remain un
3560: 63 68 61 6e 67 65 64 20 77 68 69 6c 65 20 5b 73 changed while [s
3570: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 qlite3_exec()] i
3580: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e s running..*/.in
3590: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a t sqlite3_exec(.
35a0: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 sqlite3*,
35b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
35c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
35d0: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 An open database
35e0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
35f0: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 *sql,
3600: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3610: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 /* SQL to be ev
3620: 61 6c 75 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 aluted */. int
3630: 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 (*callback)(void
3640: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 *,int,char**,cha
3650: 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 r**), /* Callba
3660: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 ck function */.
3670: 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 void *,
3680: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3690: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 /* 1
36a0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 st argument to c
36b0: 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 allback */. cha
36c0: 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 r **errmsg
36d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
36e0: 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 /* Error
36f0: 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 msg written her
3700: 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 e */.);../*.** C
3710: 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 API3REF: Result
3720: 43 6f 64 65 73 20 7b 46 31 30 32 31 30 7d 0a 2a Codes {F10210}.*
3730: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 * KEYWORDS: SQLI
3740: 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 TE_OK {error cod
3750: 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d e} {error codes}
3760: 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 .**.** Many SQLi
3770: 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 te functions ret
3780: 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 urn an integer r
3790: 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 esult code from
37a0: 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a the set shown.**
37b0: 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 here in order t
37c0: 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 o indicates succ
37d0: 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a ess or failure..
37e0: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
37f0: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 [SQLITE_IOERR_RE
3800: 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 AD | extended re
3810: 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23 sult codes].*/.#
3820: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b define SQLITE_OK
3830: 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 0 /
3840: 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73 * Successful res
3850: 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e ult */./* beginn
3860: 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 ing-of-error-cod
3870: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 es */.#define SQ
3880: 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20 LITE_ERROR
3890: 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 1 /* SQL err
38a0: 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 or or missing da
38b0: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e tabase */.#defin
38c0: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 e SQLITE_INTERNA
38d0: 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 L 2 /* Int
38e0: 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f ernal logic erro
38f0: 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 r in SQLite */.#
3900: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 define SQLITE_PE
3910: 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f RM 3 /
3920: 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73 * Access permiss
3930: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 ion denied */.#d
3940: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f efine SQLITE_ABO
3950: 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a RT 4 /*
3960: 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e Callback routin
3970: 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61 e requested an a
3980: 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 bort */.#define
3990: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20 SQLITE_BUSY
39a0: 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64 5 /* The d
39b0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 atabase file is
39c0: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e locked */.#defin
39d0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 e SQLITE_LOCKED
39e0: 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74 6 /* A t
39f0: 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61 able in the data
3a00: 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a base is locked *
3a10: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
3a20: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20 _NOMEM 7
3a30: 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 /* A malloc()
3a40: 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e failed */.#defin
3a50: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c e SQLITE_READONL
3a60: 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74 Y 8 /* Att
3a70: 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20 empt to write a
3a80: 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 readonly databas
3a90: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
3aa0: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20 ITE_INTERRUPT
3ab0: 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 9 /* Operatio
3ac0: 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20 n terminated by
3ad0: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
3ae0: 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 t()*/.#define SQ
3af0: 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20 LITE_IOERR
3b00: 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 10 /* Some ki
3b10: 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 nd of disk I/O e
3b20: 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f rror occurred */
3b30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3b40: 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20 CORRUPT 11
3b50: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 /* The database
3b60: 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d disk image is m
3b70: 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 alformed */.#def
3b80: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f ine SQLITE_NOTFO
3b90: 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 4e UND 12 /* N
3ba0: 4f 54 20 55 53 45 44 2e 20 54 61 62 6c 65 20 6f OT USED. Table o
3bb0: 72 20 72 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75 r record not fou
3bc0: 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 nd */.#define SQ
3bd0: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 LITE_FULL
3be0: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 13 /* Inserti
3bf0: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 on failed becaus
3c00: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 e database is fu
3c10: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ll */.#define SQ
3c20: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 LITE_CANTOPEN
3c30: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 14 /* Unable
3c40: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 to open the data
3c50: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 base file */.#de
3c60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 fine SQLITE_PROT
3c70: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 OCOL 15 /*
3c80: 4e 4f 54 20 55 53 45 44 2e 20 44 61 74 61 62 61 NOT USED. Databa
3c90: 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c se lock protocol
3ca0: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e error */.#defin
3cb0: 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 e SQLITE_EMPTY
3cc0: 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 16 /* Dat
3cd0: 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a abase is empty *
3ce0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
3cf0: 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 _SCHEMA 17
3d00: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 /* The databas
3d10: 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 e schema changed
3d20: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
3d30: 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 TE_TOOBIG 1
3d40: 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 8 /* String or
3d50: 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 BLOB exceeds si
3d60: 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 ze limit */.#def
3d70: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 ine SQLITE_CONST
3d80: 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 RAINT 19 /* A
3d90: 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 bort due to cons
3da0: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e traint violation
3db0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
3dc0: 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 TE_MISMATCH 2
3dd0: 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 0 /* Data type
3de0: 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 mismatch */.#de
3df0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 fine SQLITE_MISU
3e00: 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 SE 21 /*
3e10: 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 Library used inc
3e20: 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 orrectly */.#def
3e30: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 ine SQLITE_NOLFS
3e40: 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 22 /* U
3e50: 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 ses OS features
3e60: 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e not supported on
3e70: 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 host */.#define
3e80: 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 SQLITE_AUTH
3e90: 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 23 /* Auth
3ea0: 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 orization denied
3eb0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
3ec0: 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 TE_FORMAT 2
3ed0: 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 4 /* Auxiliary
3ee0: 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 database format
3ef0: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e error */.#defin
3f00: 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 e SQLITE_RANGE
3f10: 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 25 /* 2nd
3f20: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
3f30: 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f lite3_bind out o
3f40: 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 f range */.#defi
3f50: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 ne SQLITE_NOTADB
3f60: 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 26 /* Fi
3f70: 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 le opened that i
3f80: 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 s not a database
3f90: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 file */.#define
3fa0: 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 SQLITE_ROW
3fb0: 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 100 /* sqli
3fc0: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 te3_step() has a
3fd0: 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 nother row ready
3fe0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
3ff0: 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 TE_DONE 1
4000: 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 01 /* sqlite3_s
4010: 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 tep() has finish
4020: 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a ed executing */.
4030: 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d /* end-of-error-
4040: 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 codes */../*.**
4050: 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 CAPI3REF: Extend
4060: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 ed Result Codes
4070: 7b 46 31 30 32 32 30 7d 0a 2a 2a 20 4b 45 59 57 {F10220}.** KEYW
4080: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 ORDS: {extended
4090: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 error code} {ext
40a0: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 ended error code
40b0: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 s}.** KEYWORDS:
40c0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 {extended result
40d0: 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e codes}.**.** In
40e0: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e its default con
40f0: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 figuration, SQLi
4100: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 te API routines
4110: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 return one of 26
4120: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c integer.** [SQL
4130: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 ITE_OK | result
4140: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 codes]. However
4150: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 , experience has
4160: 20 73 68 6f 77 6e 20 74 68 61 74 0a 2a 2a 20 6d shown that.** m
4170: 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 65 73 any of these res
4180: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f ult codes are to
4190: 6f 20 63 6f 75 72 73 65 2d 67 72 61 69 6e 65 64 o course-grained
41a0: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 . They do not p
41b0: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 rovide as.** muc
41c0: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 h information ab
41d0: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 out problems as
41e0: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 programmers migh
41f0: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 t like. In an e
4200: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 ffort to.** addr
4210: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 ess this, newer
4220: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
4230: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e te (version 3.3.
4240: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 8 and later) inc
4250: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 lude.** support
4260: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 for additional r
4270: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 esult codes that
4280: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 provide more de
4290: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 tailed informati
42a0: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f on.** about erro
42b0: 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 rs. The extended
42c0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 result codes ar
42d0: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 e enabled or dis
42e0: 61 62 6c 65 64 0a 2a 2a 20 66 6f 72 20 65 61 63 abled.** for eac
42f0: 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 h database conne
4300: 63 74 69 6f 6e 20 75 73 69 6e 67 20 74 68 65 20 ction using the
4310: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 [sqlite3_extende
4320: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 d_result_codes()
4330: 5d 0a 2a 2a 20 41 50 49 2e 0a 2a 2a 20 0a 2a 2a ].** API..** .**
4340: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61 Some of the ava
4350: 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20 ilable extended
4360: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 result codes are
4370: 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a listed here..**
4380: 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20 One may expect
4390: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 the number of ex
43a0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
43b0: 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61 des will be expa
43c0: 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e nd.** over time.
43d0: 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 Software that
43e0: 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65 uses extended re
43f0: 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c sult codes shoul
4400: 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73 d expect.** to s
4410: 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f ee new result co
4420: 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65 des in future re
4430: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
4440: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 ..**.** The SQLI
4450: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64 TE_OK result cod
4460: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20 e will never be
4470: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69 extended. It wi
4480: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 ll always.** be
4490: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2a exactly zero..**
44a0: 20 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a .** INVARIANTS:
44b0: 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 32 33 7d 20 .**.** {F10223}
44c0: 54 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d The symbolic nam
44d0: 65 20 66 6f 72 20 61 6e 20 65 78 74 65 6e 64 65 e for an extende
44e0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61 6c d result code al
44f0: 77 61 79 73 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a ways contains.**
4500: 20 20 20 20 20 20 20 20 20 20 61 20 72 65 6c 61 a rela
4510: 74 65 64 20 70 72 69 6d 61 72 79 20 72 65 73 75 ted primary resu
4520: 6c 74 20 63 6f 64 65 20 61 73 20 61 20 70 72 65 lt code as a pre
4530: 66 69 78 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 fix..**.** {F102
4540: 32 34 7d 20 50 72 69 6d 61 72 79 20 72 65 73 75 24} Primary resu
4550: 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73 20 63 6f lt code names co
4560: 6e 74 61 69 6e 20 61 20 73 69 6e 67 6c 65 20 22 ntain a single "
4570: 5f 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a _" character..**
4580: 0a 2a 2a 20 7b 46 31 30 32 32 35 7d 20 45 78 74 .** {F10225} Ext
4590: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
45a0: 65 20 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 20 e names contain
45b0: 74 77 6f 20 6f 72 20 6d 6f 72 65 20 22 5f 22 20 two or more "_"
45c0: 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a characters..**.*
45d0: 2a 20 7b 46 31 30 32 32 36 7d 20 54 68 65 20 6e * {F10226} The n
45e0: 75 6d 65 72 69 63 20 76 61 6c 75 65 20 6f 66 20 umeric value of
45f0: 61 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 an extended resu
4600: 6c 74 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73 lt code contains
4610: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
4620: 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 6f numeric value o
4630: 66 20 69 74 73 20 63 6f 72 72 65 73 70 6f 6e 64 f its correspond
4640: 69 6e 67 20 70 72 69 6d 61 72 79 20 72 65 73 75 ing primary resu
4650: 6c 74 20 63 6f 64 65 20 69 74 0a 2a 2a 20 20 20 lt code it.**
4660: 20 20 20 20 20 20 20 69 74 73 20 6c 65 61 73 74 its least
4670: 20 73 69 67 6e 69 66 69 63 61 6e 74 20 38 20 62 significant 8 b
4680: 69 74 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 its..*/.#define
4690: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 SQLITE_IOERR_REA
46a0: 44 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 D (SQLI
46b0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 TE_IOERR | (1<<8
46c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
46d0: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 E_IOERR_SHORT_RE
46e0: 41 44 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f AD (SQLITE_IO
46f0: 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 ERR | (2<<8)).#d
4700: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
4710: 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 RR_WRITE
4720: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
4730: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (3<<8)).#define
4740: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 SQLITE_IOERR_FS
4750: 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c YNC (SQL
4760: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c ITE_IOERR | (4<<
4770: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4780: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 TE_IOERR_DIR_FSY
4790: 4e 43 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 NC (SQLITE_I
47a0: 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 OERR | (5<<8)).#
47b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
47c0: 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 ERR_TRUNCATE
47d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
47e0: 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (6<<8)).#defin
47f0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 e SQLITE_IOERR_F
4800: 53 54 41 54 20 20 20 20 20 20 20 20 20 28 53 51 STAT (SQ
4810: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c LITE_IOERR | (7<
4820: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
4830: 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b ITE_IOERR_UNLOCK
4840: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
4850: 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a IOERR | (8<<8)).
4860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
4870: 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 OERR_RDLOCK
4880: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
4890: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 | (9<<8)).#defi
48a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
48b0: 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 28 53 DELETE (S
48c0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 QLITE_IOERR | (1
48d0: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 0<<8)).#define S
48e0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 QLITE_IOERR_BLOC
48f0: 4b 45 44 20 20 20 20 20 20 20 28 53 51 4c 49 54 KED (SQLIT
4900: 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 E_IOERR | (11<<8
4910: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
4920: 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 E_IOERR_NOMEM
4930: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
4940: 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 0a ERR | (12<<8))..
4950: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
4960: 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f Flags For File O
4970: 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 7b pen Operations {
4980: 46 31 30 32 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 F10230}.**.** Th
4990: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 ese bit values a
49a0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 re intended for
49b0: 75 73 65 20 69 6e 20 74 68 65 6e 0a 2a 2a 20 33 use in then.** 3
49c0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
49d0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 the [sqlite3_ope
49e0: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 n_v2()] interfac
49f0: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 e and.** in the
4a00: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 4th parameter to
4a10: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f the xOpen metho
4a20: 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c d of the.** [sql
4a30: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
4a40: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
4a50: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c ITE_OPEN_READONL
4a60: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 Y 0x0000
4a70: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 0001.#define SQL
4a80: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
4a90: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 TE 0x0000
4aa0: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 0002.#define SQL
4ab0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 ITE_OPEN_CREATE
4ac0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
4ad0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 0004.#define SQL
4ae0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f ITE_OPEN_DELETEO
4af0: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 NCLOSE 0x0000
4b00: 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 0008.#define SQL
4b10: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 ITE_OPEN_EXCLUSI
4b20: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 VE 0x0000
4b30: 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0010.#define SQL
4b40: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 ITE_OPEN_MAIN_DB
4b50: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
4b60: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0100.#define SQL
4b70: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 ITE_OPEN_TEMP_DB
4b80: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
4b90: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0200.#define SQL
4ba0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 ITE_OPEN_TRANSIE
4bb0: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 NT_DB 0x0000
4bc0: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0400.#define SQL
4bd0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f ITE_OPEN_MAIN_JO
4be0: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 URNAL 0x0000
4bf0: 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0800.#define SQL
4c00: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f ITE_OPEN_TEMP_JO
4c10: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 URNAL 0x0000
4c20: 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 1000.#define SQL
4c30: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 ITE_OPEN_SUBJOUR
4c40: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 NAL 0x0000
4c50: 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 2000.#define SQL
4c60: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f ITE_OPEN_MASTER_
4c70: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 JOURNAL 0x0000
4c80: 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 4000../*.** CAPI
4c90: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 3REF: Device Cha
4ca0: 72 61 63 74 65 72 69 73 74 69 63 73 20 7b 46 31 racteristics {F1
4cb0: 30 32 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 0240}.**.** The
4cc0: 78 44 65 76 69 63 65 43 61 70 61 62 69 6c 69 74 xDeviceCapabilit
4cd0: 69 65 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 ies method of th
4ce0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 e [sqlite3_io_me
4cf0: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 thods].** object
4d00: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 returns an inte
4d10: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 ger which is a v
4d20: 65 63 74 6f 72 20 6f 66 20 74 68 65 20 74 68 65 ector of the the
4d30: 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 se.** bit values
4d40: 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 expressing I/O
4d50: 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 characteristics
4d60: 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 of the mass stor
4d70: 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 age.** device th
4d80: 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c at holds the fil
4d90: 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 e that the [sqli
4da0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a te3_io_methods].
4db0: 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a ** refers to..**
4dc0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 .** The SQLITE_I
4dd0: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 OCAP_ATOMIC prop
4de0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 erty means that
4df0: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a all writes of.**
4e00: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 any size are at
4e10: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 omic. The SQLIT
4e20: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e E_IOCAP_ATOMICnn
4e30: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e n values.** mean
4e40: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 that writes of
4e50: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 blocks that are
4e60: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a nnn bytes in siz
4e70: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 e and.** are ali
4e80: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 gned to an addre
4e90: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 ss which is an i
4ea0: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 nteger multiple
4eb0: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 of.** nnn are at
4ec0: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 omic. The SQLIT
4ed0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 E_IOCAP_SAFE_APP
4ee0: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a END value means.
4ef0: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 ** that when dat
4f00: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f a is appended to
4f10: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 a file, the dat
4f20: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a a is appended.**
4f30: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 first then the
4f40: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 size of the file
4f50: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 is extended, ne
4f60: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a ver the other.**
4f70: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 way around. Th
4f80: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 e SQLITE_IOCAP_S
4f90: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 EQUENTIAL proper
4fa0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a ty means that.**
4fb0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 information is
4fc0: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 written to disk
4fd0: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 in the same orde
4fe0: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f r as calls.** to
4ff0: 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 xWrite()..*/.#d
5000: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
5010: 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 AP_ATOMIC
5020: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 0x00000001.#d
5030: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
5040: 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 AP_ATOMIC512
5050: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 0x00000002.#d
5060: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
5070: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 AP_ATOMIC1K
5080: 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 0x00000004.#d
5090: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
50a0: 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 AP_ATOMIC2K
50b0: 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 0x00000008.#d
50c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
50d0: 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 AP_ATOMIC4K
50e0: 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 0x00000010.#d
50f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
5100: 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 AP_ATOMIC8K
5110: 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 0x00000020.#d
5120: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
5130: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 AP_ATOMIC16K
5140: 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 0x00000040.#d
5150: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
5160: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 AP_ATOMIC32K
5170: 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 0x00000080.#d
5180: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
5190: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 AP_ATOMIC64K
51a0: 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 0x00000100.#d
51b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
51c0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 AP_SAFE_APPEND
51d0: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 0x00000200.#d
51e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
51f0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 AP_SEQUENTIAL
5200: 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 0x00000400../
5210: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
5220: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 ile Locking Leve
5230: 6c 73 20 7b 46 31 30 32 35 30 7d 0a 2a 2a 0a 2a ls {F10250}.**.*
5240: 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e * SQLite uses on
5250: 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 e of these integ
5260: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 er values as the
5270: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d second.** argum
5280: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 ent to calls it
5290: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f makes to the xLo
52a0: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b ck() and xUnlock
52b0: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 () methods.** of
52c0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f an [sqlite3_io_
52d0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e methods] object.
52e0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
52f0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 TE_LOCK_NONE
5300: 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 0.#define
5310: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 SQLITE_LOCK_SHAR
5320: 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 ED 1.#def
5330: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f ine SQLITE_LOCK_
5340: 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a RESERVED 2.
5350: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
5360: 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 OCK_PENDING
5370: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 3.#define SQLI
5380: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 TE_LOCK_EXCLUSIV
5390: 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 E 4../*.** C
53a0: 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f API3REF: Synchro
53b0: 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c nization Type Fl
53c0: 61 67 73 20 7b 46 31 30 32 36 30 7d 0a 2a 2a 0a ags {F10260}.**.
53d0: 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 ** When SQLite i
53e0: 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 nvokes the xSync
53f0: 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a () method of an.
5400: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d ** [sqlite3_io_m
5410: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 ethods] object i
5420: 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 t uses a combina
5430: 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 74 tion of the.** t
5440: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c hese integer val
5450: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e ues as the secon
5460: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a d argument..**.*
5470: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 * When the SQLIT
5480: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 E_SYNC_DATAONLY
5490: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 flag is used, it
54a0: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a means that the.
54b0: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f ** sync operatio
54c0: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 n only needs to
54d0: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 flush data to ma
54e0: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f ss storage. Ino
54f0: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f de.** informatio
5500: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c n need not be fl
5510: 75 73 68 65 64 2e 20 54 68 65 20 53 51 4c 49 54 ushed. The SQLIT
5520: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 6d 65 E_SYNC_NORMAL me
5530: 61 6e 73 20 0a 2a 2a 20 74 6f 20 75 73 65 20 6e ans .** to use n
5540: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 ormal fsync() se
5550: 6d 61 6e 74 69 63 73 2e 20 54 68 65 20 53 51 4c mantics. The SQL
5560: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c ITE_SYNC_FULL fl
5570: 61 67 20 6d 65 61 6e 73 20 0a 2a 2a 20 74 6f 20 ag means .** to
5580: 75 73 65 20 4d 61 63 20 4f 53 2d 58 20 73 74 79 use Mac OS-X sty
5590: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 le fullsync inst
55a0: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a ead of fsync()..
55b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
55c0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 E_SYNC_NORMAL
55d0: 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 0x00002.#de
55e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 fine SQLITE_SYNC
55f0: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 _FULL 0
5600: 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 x00003.#define S
5610: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f QLITE_SYNC_DATAO
5620: 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30 NLY 0x00010
5630: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 .../*.** CAPI3RE
5640: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 F: OS Interface
5650: 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 Open File Handle
5660: 20 7b 46 31 31 31 31 30 7d 0a 2a 2a 0a 2a 2a 20 {F11110}.**.**
5670: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 An [sqlite3_file
5680: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 ] object represe
5690: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 nts an open file
56a0: 20 69 6e 20 74 68 65 20 4f 53 0a 2a 2a 20 69 6e in the OS.** in
56b0: 74 65 72 66 61 63 65 20 6c 61 79 65 72 2e 20 20 terface layer.
56c0: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e Individual OS in
56d0: 74 65 72 66 61 63 65 20 69 6d 70 6c 65 6d 65 6e terface implemen
56e0: 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 tations will.**
56f0: 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 want to subclass
5700: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 this object by
5710: 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 appending additi
5720: 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 onal fields.** f
5730: 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 or their own use
5740: 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 . The pMethods
5750: 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 entry is a point
5760: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c er to an.** [sql
5770: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
5780: 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 object that def
5790: 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 ines methods for
57a0: 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 performing.** I
57b0: 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e /O operations on
57c0: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a the open file..
57d0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
57e0: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 t sqlite3_file s
57f0: 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 qlite3_file;.str
5800: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 uct sqlite3_file
5810: 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 {. const struc
5820: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 t sqlite3_io_met
5830: 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 hods *pMethods;
5840: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 /* Methods for
5850: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a an open file */.
5860: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 };../*.** CAPI3R
5870: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 EF: OS Interface
5880: 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 File Virtual Me
5890: 74 68 6f 64 73 20 4f 62 6a 65 63 74 20 7b 46 31 thods Object {F1
58a0: 31 31 32 30 7d 0a 2a 2a 0a 2a 2a 20 45 76 65 72 1120}.**.** Ever
58b0: 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 y file opened by
58c0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 the [sqlite3_vf
58d0: 73 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 s] xOpen method
58e0: 63 6f 6e 74 61 69 6e 73 20 61 20 70 6f 69 6e 74 contains a point
58f0: 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 69 6e 73 74 er to.** an inst
5900: 61 6e 63 65 20 6f 66 20 74 68 65 20 74 68 69 73 ance of the this
5910: 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f object. This o
5920: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 bject defines th
5930: 65 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 75 73 65 e.** methods use
5940: 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 d to perform var
5950: 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 20 ious operations
5960: 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e against the open
5970: 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 file..**.** The
5980: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 flags argument
5990: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 to xSync may be
59a0: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 one of [SQLITE_S
59b0: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a YNC_NORMAL] or.*
59c0: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 * [SQLITE_SYNC_F
59d0: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 ULL]. The first
59e0: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e choice is the n
59f0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a ormal fsync()..*
5a00: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f The second cho
5a10: 69 63 65 20 69 73 20 61 6e 0a 2a 2a 20 4f 53 2d ice is an.** OS-
5a20: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 X style fullsync
5a30: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 . The SQLITE_SY
5a40: 4e 43 5f 44 41 54 41 20 66 6c 61 67 20 6d 61 79 NC_DATA flag may
5a50: 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 0a 2a be ORed in to.*
5a60: 2a 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 * indicate that
5a70: 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 only the data of
5a80: 20 74 68 65 20 66 69 6c 65 20 61 6e 64 20 6e 6f the file and no
5a90: 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 t its inode need
5aa0: 73 20 74 6f 20 62 65 0a 2a 2a 20 73 79 6e 63 65 s to be.** synce
5ab0: 64 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 69 6e d..** .** The in
5ac0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 teger values to
5ad0: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c xLock() and xUnl
5ae0: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 ock() are one of
5af0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
5b00: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f [SQLITE_LOCK_NO
5b10: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 NE],.** <li> [SQ
5b20: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 LITE_LOCK_SHARED
5b30: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 ],.** <li> [SQLI
5b40: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 TE_LOCK_RESERVED
5b50: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 ],.** <li> [SQLI
5b60: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d TE_LOCK_PENDING]
5b70: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 , or.** <li> [SQ
5b80: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 LITE_LOCK_EXCLUS
5b90: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a IVE]..** </ul>.*
5ba0: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 * xLock() increa
5bb0: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 ses the lock. xU
5bc0: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 nlock() decrease
5bd0: 73 20 74 68 65 20 6c 6f 63 6b 2e 20 20 0a 2a 2a s the lock. .**
5be0: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 The xCheckReser
5bf0: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 vedLock() method
5c00: 20 6c 6f 6f 6b 73 0a 2a 2a 20 74 6f 20 73 65 65 looks.** to see
5c10: 20 69 66 20 61 6e 79 20 64 61 74 61 62 61 73 65 if any database
5c20: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 65 69 74 connection, eit
5c30: 68 65 72 20 69 6e 20 74 68 69 73 0a 2a 2a 20 70 her in this.** p
5c40: 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d rocess or in som
5c50: 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c e other process,
5c60: 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 6e 20 52 is holding an R
5c70: 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 ESERVED,.** PEND
5c80: 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 ING, or EXCLUSIV
5c90: 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 E lock on the fi
5ca0: 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 le. It returns
5cb0: 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 true.** if such
5cc0: 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e a lock exists an
5cd0: 64 20 66 61 6c 73 65 20 69 66 20 6e 6f 74 2e 0a d false if not..
5ce0: 2a 2a 20 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 ** .** The xFile
5cf0: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 Control() method
5d00: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e is a generic in
5d10: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c terface that all
5d20: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 ows custom.** VF
5d30: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e S implementation
5d40: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f s to directly co
5d50: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 ntrol an open fi
5d60: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 le using the.**
5d70: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
5d80: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 ntrol()] interfa
5d90: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 ce. The second
5da0: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 0a 2a 2a "op" argument.**
5db0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6f is an integer o
5dc0: 70 63 6f 64 65 2e 20 20 20 54 68 65 20 74 68 69 pcode. The thi
5dd0: 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 rd.** argument i
5de0: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e s a generic poin
5df0: 74 65 72 20 77 68 69 63 68 20 69 73 20 69 6e 74 ter which is int
5e00: 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 70 6f ended to be a po
5e10: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 20 73 74 inter.** to a st
5e20: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 ructure that may
5e30: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e contain argumen
5e40: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 ts or space in w
5e50: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 hich to.** write
5e60: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 return values.
5e70: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 Potential uses
5e80: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c for xFileControl
5e90: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 () might be.** f
5ea0: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 unctions to enab
5eb0: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b le blocking lock
5ec0: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c s with timeouts,
5ed0: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a to change the.*
5ee0: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 * locking strate
5ef0: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 gy (for example
5f00: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 to use dot-file
5f10: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 locks), to inqui
5f20: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 re.** about the
5f30: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b status of a lock
5f40: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 , or to break st
5f50: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 ale locks. The
5f60: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 SQLite.** core r
5f70: 65 73 65 72 76 65 73 20 6f 70 63 6f 64 65 73 20 eserves opcodes
5f80: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f less than 100 fo
5f90: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 20 0a r its own use. .
5fa0: 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e ** A [SQLITE_FCN
5fb0: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c TL_LOCKSTATE | l
5fc0: 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 ist of opcodes]
5fd0: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 less than 100 is
5fe0: 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 available..** A
5ff0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 pplications that
6000: 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d define a custom
6010: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 xFileControl me
6020: 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 thod should use
6030: 6f 70 63 6f 64 65 73 20 0a 2a 2a 20 67 72 65 61 opcodes .** grea
6040: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 ter than 100 to
6050: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e avoid conflicts.
6060: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 .**.** The xSect
6070: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 orSize() method
6080: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 returns the sect
6090: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a or size of the.*
60a0: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e * device that un
60b0: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 derlies the file
60c0: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 . The sector si
60d0: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e ze is the.** min
60e0: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 imum write that
60f0: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 can be performed
6100: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 without disturb
6110: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 ing.** other byt
6120: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 es in the file.
6130: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 The xDeviceChar
6140: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a acteristics().**
6150: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 method returns
6160: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 a bit vector des
6170: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 cribing behavior
6180: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 s of the.** unde
6190: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a rlying device:.*
61a0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
61b0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
61c0: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 ATOMIC].** <li>
61d0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
61e0: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e OMIC512].** <li>
61f0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
6200: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e TOMIC1K].** <li>
6210: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
6220: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e TOMIC2K].** <li>
6230: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
6240: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e TOMIC4K].** <li>
6250: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
6260: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e TOMIC8K].** <li>
6270: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
6280: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 TOMIC16K].** <li
6290: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
62a0: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c ATOMIC32K].** <l
62b0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
62c0: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c _ATOMIC64K].** <
62d0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
62e0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a P_SAFE_APPEND].*
62f0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
6300: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d OCAP_SEQUENTIAL]
6310: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
6320: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
6330: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 _ATOMIC property
6340: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 means that all
6350: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 writes of.** any
6360: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 size are atomic
6370: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
6380: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 CAP_ATOMICnnn va
6390: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 lues.** mean tha
63a0: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 t writes of bloc
63b0: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 ks that are nnn
63c0: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e bytes in size an
63d0: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 d.** are aligned
63e0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 to an address w
63f0: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 hich is an integ
6400: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a er multiple of.*
6410: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 * nnn are atomic
6420: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
6430: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 CAP_SAFE_APPEND
6440: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 value means.** t
6450: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 hat when data is
6460: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 appended to a f
6470: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 ile, the data is
6480: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 appended.** fir
6490: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 st then the size
64a0: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 of the file is
64b0: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 extended, never
64c0: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 the other.** way
64d0: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 around. The SQ
64e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 LITE_IOCAP_SEQUE
64f0: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d NTIAL property m
6500: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 eans that.** inf
6510: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 ormation is writ
6520: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 ten to disk in t
6530: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 he same order as
6540: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 calls.** to xWr
6550: 69 74 65 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 ite()..*/.typede
6560: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
6570: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 _io_methods sqli
6580: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a te3_io_methods;.
6590: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 struct sqlite3_i
65a0: 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e o_methods {. in
65b0: 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e t iVersion;. in
65c0: 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 t (*xClose)(sqli
65d0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e te3_file*);. in
65e0: 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 t (*xRead)(sqlit
65f0: 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c e3_file*, void*,
6600: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 int iAmt, sqlit
6610: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b e3_int64 iOfst);
6620: 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 . int (*xWrite)
6630: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
6640: 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
6650: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 iAmt, sqlite3_i
6660: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 nt64 iOfst);. i
6670: 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 nt (*xTruncate)(
6680: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 sqlite3_file*, s
6690: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a qlite3_int64 siz
66a0: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e e);. int (*xSyn
66b0: 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a c)(sqlite3_file*
66c0: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 , int flags);.
66d0: 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 int (*xFileSize)
66e0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
66f0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 sqlite3_int64 *p
6700: 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 Size);. int (*x
6710: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 Lock)(sqlite3_fi
6720: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 le*, int);. int
6730: 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 (*xUnlock)(sqli
6740: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b te3_file*, int);
6750: 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 . int (*xCheckR
6760: 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c eservedLock)(sql
6770: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 ite3_file*);. i
6780: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f nt (*xFileContro
6790: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a l)(sqlite3_file*
67a0: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a , int op, void *
67b0: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 pArg);. int (*x
67c0: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 SectorSize)(sqli
67d0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e te3_file*);. in
67e0: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 t (*xDeviceChara
67f0: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 cteristics)(sqli
6800: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a te3_file*);. /*
6810: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 Additional meth
6820: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 ods may be added
6830: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 in future relea
6840: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a ses */.};../*.**
6850: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 CAPI3REF: Stand
6860: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c ard File Control
6870: 20 4f 70 63 6f 64 65 73 20 7b 46 31 31 33 31 30 Opcodes {F11310
6880: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e }.**.** These in
6890: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 teger constants
68a0: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 are opcodes for
68b0: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c the xFileControl
68c0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 method.** of th
68d0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 e [sqlite3_io_me
68e0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e thods] object an
68f0: 64 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 d to the [sqlite
6900: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
6910: 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a ].** interface..
6920: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 **.** The [SQLIT
6930: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 E_FCNTL_LOCKSTAT
6940: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 E] opcode is use
6950: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e d for debugging.
6960: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 This.** opcode
6970: 20 63 61 73 65 73 20 74 68 65 20 78 46 69 6c 65 cases the xFile
6980: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 Control method t
6990: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 o write the curr
69a0: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 ent state of.**
69b0: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 the lock (one of
69c0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f [SQLITE_LOCK_NO
69d0: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 NE], [SQLITE_LOC
69e0: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 K_SHARED],.** [S
69f0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 QLITE_LOCK_RESER
6a00: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f VED], [SQLITE_LO
6a10: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 CK_PENDING], or
6a20: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 [SQLITE_LOCK_EXC
6a30: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f LUSIVE]).** into
6a40: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 an integer that
6a50: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 the pArg argume
6a60: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 nt points to. Th
6a70: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a is capability.**
6a80: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 is used during
6a90: 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 testing and only
6aa0: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 needs to be sup
6ab0: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 ported when SQLI
6ac0: 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 TE_TEST.** is de
6ad0: 66 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e fined..*/.#defin
6ae0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c e SQLITE_FCNTL_L
6af0: 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 OCKSTATE
6b00: 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 1../*.** CAPI3RE
6b10: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 20 F: Mutex Handle
6b20: 7b 46 31 37 31 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 {F17110}.**.** T
6b30: 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 he mutex module
6b40: 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 within SQLite de
6b50: 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d fines [sqlite3_m
6b60: 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a utex] to be an.*
6b70: 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 * abstract type
6b80: 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 for a mutex obje
6b90: 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 ct. The SQLite
6ba0: 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 core never looks
6bb0: 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 .** at the inter
6bc0: 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 nal representati
6bd0: 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 on of an [sqlite
6be0: 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 3_mutex]. It on
6bf0: 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 ly.** deals with
6c00: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 pointers to the
6c10: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d [sqlite3_mutex]
6c20: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d object..**.** M
6c30: 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 utexes are creat
6c40: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ed using [sqlite
6c50: 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 3_mutex_alloc()]
6c60: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
6c70: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 uct sqlite3_mute
6c80: 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b x sqlite3_mutex;
6c90: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
6ca0: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f : OS Interface O
6cb0: 62 6a 65 63 74 20 7b 46 31 31 31 34 30 7d 0a 2a bject {F11140}.*
6cc0: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 *.** An instance
6cd0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 of this object
6ce0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 defines the inte
6cf0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 74 68 rface between th
6d00: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 72 65 e.** SQLite core
6d10: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 and the underly
6d20: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 ing operating sy
6d30: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 stem. The "vfs"
6d40: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 .** in the name
6d50: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 of the object st
6d60: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 ands for "virtua
6d70: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a l file system"..
6d80: 2a 2a 0a 2a 2a 20 54 68 65 20 69 56 65 72 73 69 **.** The iVersi
6d90: 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 on field is init
6da0: 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 ially 1 but may
6db0: 62 65 20 6c 61 72 67 65 72 20 66 6f 72 20 66 75 be larger for fu
6dc0: 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 ture.** versions
6dd0: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 of SQLite. Add
6de0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d itional fields m
6df0: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 ay be appended t
6e00: 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 o this.** object
6e10: 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 when the iVersi
6e20: 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 on value is incr
6e30: 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 eased..**.** The
6e40: 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 szOsFile field
6e50: 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 is the size of t
6e60: 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 he subclassed [s
6e70: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 qlite3_file].**
6e80: 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 structure used b
6e90: 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 y this VFS. mxP
6ea0: 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d athname is the m
6eb0: 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
6ec0: 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 .** a pathname i
6ed0: 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a n this VFS..**.*
6ee0: 2a 20 52 65 67 69 73 74 65 72 65 64 20 76 66 73 * Registered vfs
6ef0: 20 6d 6f 64 75 6c 65 73 20 61 72 65 20 6b 65 70 modules are kep
6f00: 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 t on a linked li
6f10: 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 st formed by.**
6f20: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 the pNext pointe
6f30: 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 r. The [sqlite3
6f40: 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d _vfs_register()]
6f50: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 .** and [sqlite3
6f60: 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 _vfs_unregister(
6f70: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 )] interfaces ma
6f80: 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a nage this list.*
6f90: 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 * in a thread-sa
6fa0: 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 fe way. The [sq
6fb0: 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 lite3_vfs_find()
6fc0: 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 ] interface.** s
6fd0: 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 earches the list
6fe0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 ..**.** The pNex
6ff0: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f t field is the o
7000: 6e 6c 79 20 66 69 65 6c 64 73 20 69 6e 20 74 68 nly fields in th
7010: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 0a 2a e sqlite3_vfs .*
7020: 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 * structure that
7030: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 SQLite will eve
7040: 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 r modify. SQLit
7050: 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 e will only acce
7060: 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 ss.** or modify
7070: 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 this field while
7080: 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 holding a parti
7090: 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 cular static mut
70a0: 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 ex..** The appli
70b0: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 cation should ne
70c0: 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 ver modify anyth
70d0: 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 ing within the s
70e0: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 qlite3_vfs.** ob
70f0: 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 ject once the ob
7100: 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 ject has been re
7110: 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 gistered..**.**
7120: 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 The zName field
7130: 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f holds the name o
7140: 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 f the VFS module
7150: 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 . The name must
7160: 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 .** be unique ac
7170: 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 ross all VFS mod
7180: 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 ules..**.** {F11
7190: 31 34 31 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 141} SQLite will
71a0: 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 guarantee that
71b0: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 73 74 the zFilename st
71c0: 72 69 6e 67 20 70 61 73 73 65 64 20 74 6f 0a 2a ring passed to.*
71d0: 2a 20 78 4f 70 65 6e 28 29 20 69 73 20 61 20 66 * xOpen() is a f
71e0: 75 6c 6c 20 70 61 74 68 6e 61 6d 65 20 61 73 20 ull pathname as
71f0: 67 65 6e 65 72 61 74 65 64 20 62 79 20 78 46 75 generated by xFu
7200: 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 61 6e 64 llPathname() and
7210: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 74 72 .** that the str
7220: 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 ing will be vali
7230: 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 d and unchanged
7240: 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 until xClose() i
7250: 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 20 7b 45 s.** called. {E
7260: 4e 44 7d 20 53 6f 20 74 68 65 20 5b 73 71 6c 69 ND} So the [sqli
7270: 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 74 te3_file] can st
7280: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f ore a pointer to
7290: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 the.** filename
72a0: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 if it needs to
72b0: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c remember the fil
72c0: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 ename for some r
72d0: 65 61 73 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 eason..**.** {F1
72e0: 31 31 34 32 7d 20 54 68 65 20 66 6c 61 67 73 20 1142} The flags
72f0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 argument to xOpe
7300: 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c n() includes all
7310: 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 bits set in.**
7320: 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 the flags argume
7330: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f nt to [sqlite3_o
7340: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 pen_v2()]. Or i
7350: 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 f [sqlite3_open(
7360: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 )].** or [sqlite
7370: 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 3_open16()] is u
7380: 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 sed, then flags
7390: 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 includes at leas
73a0: 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 t.** [SQLITE_OPE
73b0: 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b N_READWRITE] | [
73c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 SQLITE_OPEN_CREA
73d0: 54 45 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 49 66 TE]. {END}.** If
73e0: 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 xOpen() opens a
73f0: 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 file read-only
7400: 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f then it sets *pO
7410: 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e utFlags to.** in
7420: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 clude [SQLITE_OP
7430: 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f EN_READONLY]. O
7440: 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f ther bits in *pO
7450: 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 0a 2a utFlags may be.*
7460: 2a 20 73 65 74 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 * set..** .** {F
7470: 31 31 31 34 33 7d 20 53 51 4c 69 74 65 20 77 69 11143} SQLite wi
7480: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 ll also add one
7490: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 of the following
74a0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f flags to the xO
74b0: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 pen().** call, d
74c0: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 epending on the
74d0: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 object being ope
74e0: 6e 65 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e ned:.** .** <ul>
74f0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
7500: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a E_OPEN_MAIN_DB].
7510: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
7520: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e _OPEN_MAIN_JOURN
7530: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 AL].** <li> [SQ
7540: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 LITE_OPEN_TEMP_D
7550: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c B].** <li> [SQL
7560: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f ITE_OPEN_TEMP_JO
7570: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 URNAL].** <li>
7580: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 [SQLITE_OPEN_TRA
7590: 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c NSIENT_DB].** <l
75a0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
75b0: 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 _SUBJOURNAL].**
75c0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
75d0: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 EN_MASTER_JOURNA
75e0: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 L].** </ul> {END
75f0: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 }.**.** The file
7600: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 I/O implementat
7610: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 ion can use the
7620: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 object type flag
7630: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 73 20 s to.** changes
7640: 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 the way it deals
7650: 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f with files. Fo
7660: 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 r example, an ap
7670: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 plication.** tha
7680: 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 t does not care
7690: 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f about crash reco
76a0: 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b very or rollback
76b0: 2c 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 , might make.**
76c0: 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f the open of a jo
76d0: 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d urnal file a no-
76e0: 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 op. Writes to t
76f0: 68 69 73 20 6a 6f 75 72 6e 61 6c 20 61 72 65 0a his journal are.
7700: 2a 2a 20 61 6c 73 6f 20 61 20 6e 6f 2d 6f 70 2e ** also a no-op.
7710: 20 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f Any attempt to
7720: 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 read the journa
7730: 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f l return SQLITE_
7740: 49 4f 45 52 52 2e 0a 2a 2a 20 4f 72 20 74 68 65 IOERR..** Or the
7750: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
7760: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 might recognize
7770: 74 68 65 20 61 20 64 61 74 61 62 61 73 65 20 66 the a database f
7780: 69 6c 65 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 64 ile will.** be d
7790: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 oing page-aligne
77a0: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 d sector reads a
77b0: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 nd writes in a r
77c0: 61 6e 64 6f 6d 20 6f 72 64 65 72 0a 2a 2a 20 61 andom order.** a
77d0: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f nd set up its I/
77e0: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f O subsystem acco
77f0: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 20 0a 2a 2a 20 rdingly..** .**
7800: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 SQLite might als
7810: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 o add one of the
7820: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 following flags
7830: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a to the xOpen.**
7840: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 20 0a 2a 2a 20 method:.** .**
7850: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 <ul>.** <li> [SQ
7860: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
7870: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e ONCLOSE].** <li>
7880: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 [SQLITE_OPEN_EX
7890: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c CLUSIVE].** </ul
78a0: 3e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31 34 35 >.** .** {F11145
78b0: 7d 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 } The [SQLITE_OP
78c0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 EN_DELETEONCLOSE
78d0: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 ] flag means the
78e0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a file should be.
78f0: 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 ** deleted when
7900: 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 7b it is closed. {
7910: 46 31 31 31 34 36 7d 20 54 68 65 20 5b 53 51 4c F11146} The [SQL
7920: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f ITE_OPEN_DELETEO
7930: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 NCLOSE].** will
7940: 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 be set for TEMP
7950: 20 64 61 74 61 62 61 73 65 73 2c 20 6a 6f 75 72 databases, jour
7960: 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 62 nals and for sub
7970: 6a 6f 75 72 6e 61 6c 73 2e 20 0a 2a 2a 20 7b 46 journals. .** {F
7980: 31 31 31 34 37 7d 20 54 68 65 20 5b 53 51 4c 49 11147} The [SQLI
7990: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 TE_OPEN_EXCLUSIV
79a0: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 E] flag means th
79b0: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 e file should be
79c0: 20 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f 72 20 65 opened.** for e
79d0: 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e xclusive access.
79e0: 20 20 54 68 69 73 20 66 6c 61 67 20 69 73 20 73 This flag is s
79f0: 65 74 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65 73 et for all files
7a00: 20 65 78 63 65 70 74 0a 2a 2a 20 66 6f 72 20 74 except.** for t
7a10: 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 he main database
7a20: 20 66 69 6c 65 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 file. {END}.**
7a30: 0a 2a 2a 20 7b 46 31 31 31 34 38 7d 20 41 74 20 .** {F11148} At
7a40: 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 least szOsFile b
7a50: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 69 ytes of memory i
7a60: 73 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 s allocated by S
7a70: 51 4c 69 74 65 20 0a 2a 2a 20 74 6f 20 68 6f 6c QLite .** to hol
7a80: 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f d the [sqlite3_
7a90: 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 file] structure
7aa0: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 passed as the th
7ab0: 69 72 64 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 ird .** argument
7ac0: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 7b 45 4e 44 to xOpen. {END
7ad0: 7d 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 } The xOpen met
7ae0: 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 hod does not hav
7af0: 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 e to.** allocate
7b00: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 the structure;
7b10: 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 it should just f
7b20: 69 6c 6c 20 69 74 20 69 6e 2e 0a 2a 2a 20 0a 2a ill it in..** .*
7b30: 2a 20 7b 46 31 31 31 34 39 7d 20 54 68 65 20 66 * {F11149} The f
7b40: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f lags argument to
7b50: 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 xAccess() may b
7b60: 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 e [SQLITE_ACCESS
7b70: 5f 45 58 49 53 54 53 5d 20 0a 2a 2a 20 74 6f 20 _EXISTS] .** to
7b80: 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 test for the exi
7b90: 73 74 61 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 stance of a file
7ba0: 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f ,.** or [SQLITE_
7bb0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 ACCESS_READWRITE
7bc0: 5d 20 74 6f 20 74 65 73 74 20 74 6f 20 73 65 65 ] to test to see
7bd0: 0a 2a 2a 20 69 66 20 61 20 66 69 6c 65 20 69 73 .** if a file is
7be0: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 readable and wr
7bf0: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 itable, or [SQLI
7c00: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a TE_ACCESS_READ].
7c10: 2a 2a 20 74 6f 20 74 65 73 74 20 74 6f 20 73 65 ** to test to se
7c20: 65 20 69 66 20 61 20 66 69 6c 65 20 69 73 20 61 e if a file is a
7c30: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 t least readable
7c40: 2e 20 20 7b 45 4e 44 7d 20 54 68 65 20 66 69 6c . {END} The fil
7c50: 65 20 63 61 6e 20 62 65 20 61 20 0a 2a 2a 20 64 e can be a .** d
7c60: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 0a 2a 2a irectory..** .**
7c70: 20 7b 46 31 31 31 35 30 7d 20 53 51 4c 69 74 65 {F11150} SQLite
7c80: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c will always all
7c90: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d ocate at least m
7ca0: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 xPathname+1 byte
7cb0: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6f 75 74 70 for.** the outp
7cc0: 75 74 20 62 75 66 66 65 72 73 20 66 6f 72 20 78 ut buffers for x
7cd0: 47 65 74 54 65 6d 70 6e 61 6d 65 20 61 6e 64 20 GetTempname and
7ce0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 7b xFullPathname. {
7cf0: 46 31 31 31 35 31 7d 20 54 68 65 20 65 78 61 63 F11151} The exac
7d00: 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 74 68 65 t.** size of the
7d10: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 69 output buffer i
7d20: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 s also passed as
7d30: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 a parameter to
7d40: 62 6f 74 68 20 0a 2a 2a 20 6d 65 74 68 6f 64 73 both .** methods
7d50: 2e 20 7b 45 4e 44 7d 20 49 66 20 74 68 65 20 6f . {END} If the o
7d60: 75 74 70 75 74 20 62 75 66 66 65 72 20 69 73 20 utput buffer is
7d70: 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 not large enough
7d80: 2c 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 , SQLITE_CANTOPE
7d90: 4e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 N.** should be r
7da0: 65 74 75 72 6e 65 64 2e 20 41 73 20 74 68 69 73 eturned. As this
7db0: 20 69 73 20 68 61 6e 64 6c 65 64 20 61 73 20 61 is handled as a
7dc0: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 fatal error by
7dd0: 53 51 4c 69 74 65 2c 0a 2a 2a 20 76 66 73 20 69 SQLite,.** vfs i
7de0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 mplementations s
7df0: 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 20 74 hould endeavor t
7e00: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 o prevent this b
7e10: 79 20 73 65 74 74 69 6e 67 20 0a 2a 2a 20 6d 78 y setting .** mx
7e20: 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 Pathname to a su
7e30: 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 fficiently large
7e40: 20 76 61 6c 75 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 value..** .** T
7e50: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 he xRandomness()
7e60: 2c 20 78 53 6c 65 65 70 28 29 2c 20 61 6e 64 20 , xSleep(), and
7e70: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 xCurrentTime() i
7e80: 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 nterfaces.** are
7e90: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 not strictly a
7ea0: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 part of the file
7eb0: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 system, but they
7ec0: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 are.** included
7ed0: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 in the VFS stru
7ee0: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 cture for comple
7ef0: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 teness..** The x
7f00: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e Randomness() fun
7f10: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 ction attempts t
7f20: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 o return nBytes
7f30: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 bytes.** of good
7f40: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e -quality randomn
7f50: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 ess into zOut.
7f60: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 The return value
7f70: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 is.** the actua
7f80: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 l number of byte
7f90: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 s of randomness
7fa0: 6f 62 74 61 69 6e 65 64 2e 20 20 54 68 65 0a 2a obtained. The.*
7fb0: 2a 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f * xSleep() metho
7fc0: 64 20 63 61 75 73 65 20 74 68 65 20 63 61 6c 6c d cause the call
7fd0: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c ing thread to sl
7fe0: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 eep for at.** le
7ff0: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f ast the number o
8000: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 f microseconds g
8010: 69 76 65 6e 2e 20 20 54 68 65 20 78 43 75 72 72 iven. The xCurr
8020: 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 entTime().** met
8030: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 hod returns a Ju
8040: 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 lian Day Number
8050: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 for the current
8060: 64 61 74 65 20 61 6e 64 0a 2a 2a 20 74 69 6d 65 date and.** time
8070: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
8080: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 uct sqlite3_vfs
8090: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73 74 72 sqlite3_vfs;.str
80a0: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 uct sqlite3_vfs
80b0: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e {. int iVersion
80c0: 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 ; /*
80d0: 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f Structure versio
80e0: 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 69 6e n number */. in
80f0: 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 t szOsFile;
8100: 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f /* Size o
8110: 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c f subclassed sql
8120: 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 ite3_file */. i
8130: 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 nt mxPathname;
8140: 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d /* Maxim
8150: 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 um file pathname
8160: 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c length */. sql
8170: 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b ite3_vfs *pNext;
8180: 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 /* Next re
8190: 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a gistered VFS */.
81a0: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e const char *zN
81b0: 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 ame; /* Na
81c0: 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 me of this virtu
81d0: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a al file system *
81e0: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 /. void *pAppDa
81f0: 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 ta; /*
8200: 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 Pointer to appli
8210: 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 cation-specific
8220: 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a data */. int (*
8230: 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 xOpen)(sqlite3_v
8240: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
8250: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f *zName, sqlite3_
8260: 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 file*,.
8270: 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c int flags,
8280: 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 int *pOutFlags)
8290: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 ;. int (*xDelet
82a0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c e)(sqlite3_vfs*,
82b0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
82c0: 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 me, int syncDir)
82d0: 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 ;. int (*xAcces
82e0: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c s)(sqlite3_vfs*,
82f0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
8300: 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a me, int flags);.
8310: 20 20 69 6e 74 20 28 2a 78 47 65 74 54 65 6d 70 int (*xGetTemp
8320: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 name)(sqlite3_vf
8330: 73 2a 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 s*, int nOut, ch
8340: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 ar *zOut);. int
8350: 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 (*xFullPathname
8360: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
8370: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
8380: 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 e, int nOut, cha
8390: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 r *zOut);. void
83a0: 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c *(*xDlOpen)(sql
83b0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
83c0: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 char *zFilename
83d0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 );. void (*xDlE
83e0: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 rror)(sqlite3_vf
83f0: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 s*, int nByte, c
8400: 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 har *zErrMsg);.
8410: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 53 79 6d 29 void *(*xDlSym)
8420: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f (sqlite3_vfs*,vo
8430: 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 id*, const char
8440: 2a 7a 53 79 6d 62 6f 6c 29 3b 0a 20 20 76 6f 69 *zSymbol);. voi
8450: 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 d (*xDlClose)(sq
8460: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 lite3_vfs*, void
8470: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e *);. int (*xRan
8480: 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 domness)(sqlite3
8490: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 _vfs*, int nByte
84a0: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 , char *zOut);.
84b0: 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 int (*xSleep)(s
84c0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 qlite3_vfs*, int
84d0: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a microseconds);.
84e0: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 int (*xCurrent
84f0: 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 Time)(sqlite3_vf
8500: 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 s*, double*);.
8510: 2f 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 /* New fields ma
8520: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e y be appended in
8530: 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 figure versions
8540: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a . The iVersion.
8550: 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 ** value will
8560: 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 increment whenev
8570: 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e er this happens.
8580: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.};../*.** CA
8590: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f PI3REF: Flags fo
85a0: 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46 r the xAccess VF
85b0: 53 20 6d 65 74 68 6f 64 20 7b 46 31 31 31 39 30 S method {F11190
85c0: 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31 39 31 7d }.**.** {F11191}
85d0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 These integer c
85e0: 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 onstants can be
85f0: 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 used as the thir
8600: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a d parameter to.*
8610: 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 * the xAccess me
8620: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 thod of an [sqli
8630: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e te3_vfs] object.
8640: 20 7b 45 4e 44 7d 20 20 54 68 65 79 20 64 65 74 {END} They det
8650: 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 6b 69 ermine.** the ki
8660: 6e 64 20 6f 66 20 77 68 61 74 20 6b 69 6e 64 20 nd of what kind
8670: 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 of permissions t
8680: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f he xAccess metho
8690: 64 20 69 73 0a 2a 2a 20 6c 6f 6f 6b 69 6e 67 20 d is.** looking
86a0: 66 6f 72 2e 20 20 7b 46 31 31 31 39 32 7d 20 57 for. {F11192} W
86b0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 ith SQLITE_ACCES
86c0: 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 S_EXISTS, the xA
86d0: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 ccess method.**
86e0: 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 74 6f simply checks to
86f0: 20 73 65 65 20 69 66 20 74 68 65 20 66 69 6c 65 see if the file
8700: 20 65 78 69 73 74 73 2e 20 7b 46 31 31 31 39 33 exists. {F11193
8710: 7d 20 57 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 } With.** SQLITE
8720: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 _ACCESS_READWRIT
8730: 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d E, the xAccess m
8740: 65 74 68 6f 64 20 63 68 65 63 6b 73 20 74 6f 20 ethod checks to
8750: 73 65 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 see.** if the fi
8760: 6c 65 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 le is both reada
8770: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 ble and writable
8780: 2e 20 20 7b 46 31 31 31 39 34 7d 20 57 69 74 68 . {F11194} With
8790: 0a 2a 2a 20 53 51 4c 49 54 45 5f 41 43 43 45 53 .** SQLITE_ACCES
87a0: 53 5f 52 45 41 44 20 74 68 65 20 78 41 63 63 65 S_READ the xAcce
87b0: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 ss method.** che
87c0: 63 6b 73 20 74 6f 20 73 65 65 20 69 66 20 74 68 cks to see if th
87d0: 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 e file is readab
87e0: 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 le..*/.#define S
87f0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 QLITE_ACCESS_EXI
8800: 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 STS 0.#define
8810: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 SQLITE_ACCESS_R
8820: 45 41 44 57 52 49 54 45 20 31 0a 23 64 65 66 69 EADWRITE 1.#defi
8830: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 ne SQLITE_ACCESS
8840: 5f 52 45 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a _READ 2../*
8850: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e .** CAPI3REF: En
8860: 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 able Or Disable
8870: 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 Extended Result
8880: 43 6f 64 65 73 20 7b 46 31 32 32 30 30 7d 0a 2a Codes {F12200}.*
8890: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
88a0: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 _extended_result
88b0: 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 _codes() routine
88c0: 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 enables or disa
88d0: 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c bles the.** [SQL
88e0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c ITE_IOERR_READ |
88f0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 extended result
8900: 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 codes] feature
8910: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 54 68 of SQLite..** Th
8920: 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c e extended resul
8930: 74 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 t codes are disa
8940: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 bled by default
8950: 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a for historical.*
8960: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e * compatibility.
8970: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
8980: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 30 31 S:.**.** {F12201
8990: 7d 20 45 61 63 68 20 6e 65 77 20 5b 64 61 74 61 } Each new [data
89a0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
89b0: 20 68 61 73 20 74 68 65 20 0a 2a 2a 20 20 20 20 has the .**
89c0: 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64 20 [extended
89d0: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 result codes] fe
89e0: 61 74 75 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 ature.**
89f0: 20 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 disabled by de
8a00: 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 fault..**.** {F1
8a10: 32 32 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 2202} The [sqlit
8a20: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 e3_extended_resu
8a30: 6c 74 5f 63 6f 64 65 73 28 44 2c 46 29 5d 20 69 lt_codes(D,F)] i
8a40: 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 65 6e nterface will en
8a50: 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 able.**
8a60: 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c [extended resul
8a70: 74 20 63 6f 64 65 73 5d 20 66 6f 72 20 74 68 65 t codes] for the
8a80: 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 .** [d
8a90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
8aa0: 6f 6e 5d 20 44 20 69 66 20 74 68 65 20 46 20 70 on] D if the F p
8ab0: 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 arameter.**
8ac0: 20 20 20 20 20 69 73 20 74 72 75 65 2c 20 6f 72 is true, or
8ad0: 20 64 69 73 61 62 6c 65 20 74 68 65 6d 20 69 66 disable them if
8ae0: 20 46 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2f 0a F is false..*/.
8af0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 int sqlite3_exte
8b00: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 nded_result_code
8b10: 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 s(sqlite3*, int
8b20: 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 onoff);../*.** C
8b30: 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e API3REF: Last In
8b40: 73 65 72 74 20 52 6f 77 69 64 20 7b 46 31 32 32 sert Rowid {F122
8b50: 32 30 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 20}.**.** Each e
8b60: 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 ntry in an SQLit
8b70: 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e e table has a un
8b80: 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e ique 64-bit sign
8b90: 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 ed.** integer ke
8ba0: 79 20 63 61 6c 6c 65 64 20 74 68 65 20 22 72 6f y called the "ro
8bb0: 77 69 64 22 2e 20 54 68 65 20 72 6f 77 69 64 20 wid". The rowid
8bc0: 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 is always availa
8bd0: 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 ble.** as an und
8be0: 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e eclared column n
8bf0: 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c amed ROWID, OID,
8c00: 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c or _ROWID_ as l
8c10: 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 ong as those.**
8c20: 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c names are not al
8c30: 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 so used by expli
8c40: 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 citly declared c
8c50: 6f 6c 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68 olumns. If.** th
8c60: 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f e table has a co
8c70: 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 49 4e 54 lumn of type INT
8c80: 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 EGER PRIMARY KEY
8c90: 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d then that colum
8ca0: 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 n.** is another
8cb0: 61 6e 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 an alias for the
8cc0: 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 rowid..**.** Th
8cd0: 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 is routine retur
8ce0: 6e 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 ns the rowid of
8cf0: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a the most recent.
8d00: 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 49 4e ** successful IN
8d10: 53 45 52 54 20 69 6e 74 6f 20 74 68 65 20 64 61 SERT into the da
8d20: 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 tabase from the
8d30: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
8d40: 69 6f 6e 0a 2a 2a 20 73 68 6f 77 6e 20 69 6e 20 ion.** shown in
8d50: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
8d60: 6e 74 2e 20 20 49 66 20 6e 6f 20 73 75 63 63 65 nt. If no succe
8d70: 73 73 66 75 6c 20 69 6e 73 65 72 74 73 0a 2a 2a ssful inserts.**
8d80: 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 have ever occur
8d90: 72 65 64 20 6f 6e 20 74 68 69 73 20 64 61 74 61 red on this data
8da0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c base connection,
8db0: 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 zero is returne
8dc0: 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 49 d..**.** If an I
8dd0: 4e 53 45 52 54 20 6f 63 63 75 72 73 20 77 69 74 NSERT occurs wit
8de0: 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74 hin a trigger, t
8df0: 68 65 6e 20 74 68 65 20 72 6f 77 69 64 20 6f 66 hen the rowid of
8e00: 20 74 68 65 0a 2a 2a 20 69 6e 73 65 72 74 65 64 the.** inserted
8e10: 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64 row is returned
8e20: 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 by this routine
8e30: 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 as long as the
8e40: 74 72 69 67 67 65 72 0a 2a 2a 20 69 73 20 72 75 trigger.** is ru
8e50: 6e 6e 69 6e 67 2e 20 20 42 75 74 20 6f 6e 63 65 nning. But once
8e60: 20 74 68 65 20 74 72 69 67 67 65 72 20 74 65 72 the trigger ter
8e70: 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c minates, the val
8e80: 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 ue returned.** b
8e90: 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 y this routine r
8ea0: 65 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 everts to the la
8eb0: 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 st value inserte
8ec0: 64 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 d before the.**
8ed0: 74 72 69 67 67 65 72 20 66 69 72 65 64 2e 0a 2a trigger fired..*
8ee0: 2a 0a 2a 2a 20 41 6e 20 49 4e 53 45 52 54 20 74 *.** An INSERT t
8ef0: 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f hat fails due to
8f00: 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 a constraint vi
8f10: 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 olation is not a
8f20: 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 69 .** successful i
8f30: 6e 73 65 72 74 20 61 6e 64 20 64 6f 65 73 20 6e nsert and does n
8f40: 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 ot change the va
8f50: 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 lue returned by
8f60: 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e this.** routine.
8f70: 20 20 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 Thus INSERT OR
8f80: 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 FAIL, INSERT OR
8f90: 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 IGNORE, INSERT
8fa0: 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 OR ROLLBACK,.**
8fb0: 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 and INSERT OR AB
8fc0: 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e ORT make no chan
8fd0: 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 ges to the retur
8fe0: 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a n value of this.
8ff0: 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 ** routine when
9000: 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 their insertion
9010: 66 61 69 6c 73 2e 20 20 57 68 65 6e 20 49 4e 53 fails. When INS
9020: 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 0a ERT OR REPLACE .
9030: 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 ** encounters a
9040: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 constraint viola
9050: 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f tion, it does no
9060: 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 t fail. The.**
9070: 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 INSERT continues
9080: 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 to completion a
9090: 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f fter deleting ro
90a0: 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a ws that caused.*
90b0: 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 * the constraint
90c0: 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 problem so INSE
90d0: 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 RT OR REPLACE wi
90e0: 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 ll always change
90f0: 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 .** the return v
9100: 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 alue of this int
9110: 65 72 66 61 63 65 2e 20 0a 2a 2a 0a 2a 2a 20 46 erface. .**.** F
9120: 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 or the purposes
9130: 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c of this routine,
9140: 20 61 6e 20 69 6e 73 65 72 74 20 69 73 20 63 6f an insert is co
9150: 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 nsidered to.** b
9160: 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 e successful eve
9170: 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 n if it is subse
9180: 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 quently rolled b
9190: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 ack..**.** INVAR
91a0: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 IANTS:.**.** {F1
91b0: 32 32 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 2221} The [sqlit
91c0: 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 e3_last_insert_r
91d0: 6f 77 69 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e owid()] function
91e0: 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 returns the.**
91f0: 20 20 20 20 20 20 20 20 20 72 6f 77 69 64 20 6f rowid o
9200: 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e f the most recen
9210: 74 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 73 t successful ins
9220: 65 72 74 20 64 6f 6e 65 0a 2a 2a 20 20 20 20 20 ert done.**
9230: 20 20 20 20 20 6f 6e 20 74 68 65 20 73 61 6d 65 on the same
9240: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
9250: 74 69 6f 6e 20 61 6e 64 20 77 69 74 68 69 6e 20 tion and within
9260: 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 the same.**
9270: 20 20 20 20 20 74 72 69 67 67 65 72 20 63 6f 6e trigger con
9280: 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66 text, or zero if
9290: 20 74 68 65 72 65 20 68 61 76 65 0a 2a 2a 20 20 there have.**
92a0: 20 20 20 20 20 20 20 20 62 65 65 6e 20 6e 6f 20 been no
92b0: 71 75 61 6c 69 66 79 69 6e 67 20 69 6e 73 65 72 qualifying inser
92c0: 74 73 20 6f 6e 20 74 68 61 74 20 63 6f 6e 6e 65 ts on that conne
92d0: 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 ction..**.** {F1
92e0: 32 32 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 2223} The [sqlit
92f0: 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 e3_last_insert_r
9300: 6f 77 69 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e owid()] function
9310: 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 returns.**
9320: 20 20 20 20 20 73 61 6d 65 20 76 61 6c 75 65 20 same value
9330: 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d when called from
9340: 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 the same trigge
9350: 72 20 63 6f 6e 74 65 78 74 0a 2a 2a 20 20 20 20 r context.**
9360: 20 20 20 20 20 20 69 6d 6d 65 64 69 61 74 65 6c immediatel
9370: 79 20 62 65 66 6f 72 65 20 61 6e 64 20 61 66 74 y before and aft
9380: 65 72 20 61 20 52 4f 4c 4c 42 41 43 4b 2e 0a 2a er a ROLLBACK..*
9390: 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 *.** LIMITATIONS
93a0: 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 33 32 7d :.**.** {U12232}
93b0: 20 49 66 20 73 65 70 61 72 61 74 65 20 74 68 72 If separate thr
93c0: 65 61 64 20 64 6f 65 73 20 61 20 6e 65 77 20 69 ead does a new i
93d0: 6e 73 65 72 74 20 6f 6e 20 74 68 65 20 73 61 6d nsert on the sam
93e0: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 e.** da
93f0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
9400: 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c n while the [sql
9410: 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 ite3_last_insert
9420: 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 20 20 20 _rowid()].**
9430: 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 69 function i
9440: 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 s running and th
9450: 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c us changes the l
9460: 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 ast insert rowid
9470: 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 ,.** th
9480: 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 en the value ret
9490: 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 urned by [sqlite
94a0: 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 3_last_insert_ro
94b0: 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20 wid()] is.**
94c0: 20 20 20 20 20 20 75 6e 70 72 65 64 69 63 74 61 unpredicta
94d0: 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f ble and might no
94e0: 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 t equal either t
94f0: 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 he old or the ne
9500: 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 61 w.** la
9510: 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 2e st insert rowid.
9520: 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 .*/.sqlite3_int6
9530: 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 4 sqlite3_last_i
9540: 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 nsert_rowid(sqli
9550: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
9560: 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 PI3REF: Count Th
9570: 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 e Number Of Rows
9580: 20 4d 6f 64 69 66 69 65 64 20 7b 46 31 32 32 34 Modified {F1224
9590: 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 0}.**.** This fu
95a0: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 nction returns t
95b0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 he number of dat
95c0: 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 abase rows that
95d0: 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 were changed.**
95e0: 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 or inserted or d
95f0: 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f eleted by the mo
9600: 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 st recently comp
9610: 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d leted SQL statem
9620: 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 63 6f ent.** on the co
9630: 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69 nnection specifi
9640: 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 ed by the first
9650: 70 61 72 61 6d 65 74 65 72 2e 20 20 4f 6e 6c 79 parameter. Only
9660: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 68 61 74 .** changes that
9670: 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 are directly sp
9680: 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 49 ecified by the I
9690: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f NSERT, UPDATE, o
96a0: 72 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 r.** DELETE stat
96b0: 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 ement are counte
96c0: 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 d. Auxiliary ch
96d0: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a anges caused by.
96e0: 2a 2a 20 74 72 69 67 67 65 72 73 20 61 72 65 20 ** triggers are
96f0: 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 55 73 65 not counted. Use
9700: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f the [sqlite3_to
9710: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 tal_changes()] f
9720: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69 unction.** to fi
9730: 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d nd the total num
9740: 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 ber of changes i
9750: 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 ncluding changes
9760: 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67 caused by trigg
9770: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 72 6f ers..**.** A "ro
9780: 77 20 63 68 61 6e 67 65 73 22 20 69 73 20 61 20 w changes" is a
9790: 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 change to a sing
97a0: 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 le row of a sing
97b0: 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 le table.** caus
97c0: 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c ed by an INSERT,
97d0: 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 DELETE, or UPDA
97e0: 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 TE statement. R
97f0: 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 ows that.** are
9800: 63 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 changed as side
9810: 65 66 66 65 63 74 73 20 6f 66 20 52 45 50 4c 41 effects of REPLA
9820: 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 CE constraint re
9830: 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c solution,.** rol
9840: 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f lback, ABORT pro
9850: 63 65 73 73 69 6e 67 2c 20 44 52 4f 50 20 54 41 cessing, DROP TA
9860: 42 4c 45 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f BLE, or by any o
9870: 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 ther.** mechanis
9880: 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 ms do not count
9890: 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 as direct row ch
98a0: 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 anges..**.** A "
98b0: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 trigger context"
98c0: 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 is a scope of e
98d0: 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 xecution that be
98e0: 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 gins and.** ends
98f0: 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74 with the script
9900: 20 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20 20 of a trigger.
9910: 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 Most SQL stateme
9920: 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 nts are.** evalu
9930: 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 ated outside of
9940: 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 any trigger. Th
9950: 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c is is the "top l
9960: 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 evel".** trigger
9970: 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 context. If a
9980: 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72 trigger fires fr
9990: 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c om the top level
99a0: 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 , a.** new trigg
99b0: 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e er context is en
99c0: 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 tered for the du
99d0: 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f ration of that o
99e0: 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 ne.** trigger.
99f0: 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61 Subtriggers crea
9a00: 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 te subcontexts f
9a10: 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f or their duratio
9a20: 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 n..**.** Calling
9a30: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 [sqlite3_exec()
9a40: 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 ] or [sqlite3_st
9a50: 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c ep()] recursivel
9a60: 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 y does.** not cr
9a70: 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 eate a new trigg
9a80: 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a er context..**.*
9a90: 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 * This function
9aa0: 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
9ab0: 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 er of direct row
9ac0: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a changes in the.
9ad0: 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 ** most recent I
9ae0: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f NSERT, UPDATE, o
9af0: 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 r DELETE stateme
9b00: 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 nt within the sa
9b10: 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f me.** trigger co
9b20: 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 6f 20 ntext..**.** So
9b30: 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d when called from
9b40: 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 the top level,
9b50: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 this function re
9b60: 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d turns the.** num
9b70: 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 ber of changes i
9b80: 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e n the most recen
9b90: 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 t INSERT, UPDATE
9ba0: 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 , or DELETE.** t
9bb0: 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 hat also occurre
9bc0: 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 d at the top lev
9bd0: 65 6c 2e 0a 2a 2a 20 57 69 74 68 69 6e 20 74 68 el..** Within th
9be0: 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 e body of a trig
9bf0: 67 65 72 2c 20 74 68 65 20 73 71 6c 69 74 65 33 ger, the sqlite3
9c00: 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 _changes() inter
9c10: 66 61 63 65 0a 2a 2a 20 63 61 6e 20 62 65 20 63 face.** can be c
9c20: 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 alled to find th
9c30: 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 e number of.** c
9c40: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f hanges in the mo
9c50: 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 st recently comp
9c60: 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 leted INSERT, UP
9c70: 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a DATE, or DELETE.
9c80: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 ** statement wit
9c90: 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 hin the body of
9ca0: 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 the same trigger
9cb0: 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 ..** However, th
9cc0: 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 e number returne
9cd0: 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 d does not inclu
9ce0: 64 65 20 69 6e 20 63 68 61 6e 67 65 73 0a 2a 2a de in changes.**
9cf0: 20 63 61 75 73 65 64 20 62 79 20 73 75 62 74 72 caused by subtr
9d00: 69 67 67 65 72 73 20 73 69 6e 63 65 20 74 68 65 iggers since the
9d10: 79 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e y have their own
9d20: 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 context..**.**
9d30: 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 SQLite implement
9d40: 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 s the command "D
9d50: 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 ELETE FROM table
9d60: 22 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 57 " without.** a W
9d70: 48 45 52 45 20 63 6c 61 75 73 65 20 62 79 20 64 HERE clause by d
9d80: 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 ropping and recr
9d90: 65 61 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 eating the table
9da0: 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75 63 68 . (This is much
9db0: 0a 2a 2a 20 66 61 73 74 65 72 20 74 68 61 6e 20 .** faster than
9dc0: 67 6f 69 6e 67 20 74 68 72 6f 75 67 68 20 61 6e going through an
9dd0: 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 d deleting indiv
9de0: 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 idual elements f
9df0: 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 61 62 6c 65 rom the.** table
9e00: 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 .) Because of t
9e10: 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e his optimization
9e20: 2c 20 74 68 65 20 64 65 6c 65 74 69 6f 6e 73 20 , the deletions
9e30: 69 6e 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 in.** "DELETE FR
9e40: 4f 4d 20 74 61 62 6c 65 22 20 61 72 65 20 6e 6f OM table" are no
9e50: 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 61 6e t row changes an
9e60: 64 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f d will not be co
9e70: 75 6e 74 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 unted.** by the
9e80: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
9e90: 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f ) or [sqlite3_to
9ea0: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 tal_changes()] f
9eb0: 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20 54 6f 20 unctions..** To
9ec0: 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 get an accurate
9ed0: 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d count of the num
9ee0: 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 ber of rows dele
9ef0: 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c ted, use.** "DEL
9f00: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 ETE FROM table W
9f10: 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e HERE 1" instead.
9f20: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
9f30: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 34 31 S:.**.** {F12241
9f40: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 } The [sqlite3_c
9f50: 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 hanges()] functi
9f60: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e on returns the n
9f70: 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 umber of.**
9f80: 20 20 20 20 20 72 6f 77 20 63 68 61 6e 67 65 73 row changes
9f90: 20 63 61 75 73 65 64 20 62 79 20 74 68 65 20 6d caused by the m
9fa0: 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 ost recent INSER
9fb0: 54 2c 20 55 50 44 41 54 45 2c 0a 2a 2a 20 20 20 T, UPDATE,.**
9fc0: 20 20 20 20 20 20 20 6f 72 20 44 45 4c 45 54 45 or DELETE
9fd0: 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 statement on th
9fe0: 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 e same database
9ff0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 0a 2a connection and.*
a000: 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 69 * withi
a010: 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 n the same trigg
a020: 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a er context, or z
a030: 65 72 6f 20 69 66 20 74 68 65 72 65 20 68 61 76 ero if there hav
a040: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f e.** no
a050: 74 20 62 65 65 6e 20 61 6e 79 20 71 75 61 6c 69 t been any quali
a060: 66 79 69 6e 67 20 72 6f 77 20 63 68 61 6e 67 65 fying row change
a070: 73 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 s..**.** LIMITAT
a080: 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 IONS:.**.** {U12
a090: 32 35 32 7d 20 49 66 20 61 20 73 65 70 61 72 61 252} If a separa
a0a0: 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 te thread makes
a0b0: 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 changes on the s
a0c0: 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e ame database con
a0d0: 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 nection.**
a0e0: 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 while [sqlit
a0f0: 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 e3_changes()] is
a100: 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 running then th
a110: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
a120: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 .** is
a130: 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e unpredictable an
a140: 64 20 75 6e 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a d unmeaningful..
a150: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 */.int sqlite3_c
a160: 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 hanges(sqlite3*)
a170: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
a180: 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 F: Total Number
a190: 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 Of Rows Modified
a1a0: 20 7b 46 31 32 32 36 30 7d 0a 2a 2a 2a 0a 2a 2a {F12260}.***.**
a1b0: 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 This function r
a1c0: 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
a1d0: 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 r of row changes
a1e0: 20 63 61 75 73 65 64 0a 2a 2a 20 62 79 20 49 4e caused.** by IN
a1f0: 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 SERT, UPDATE or
a200: 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 DELETE statement
a210: 73 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 s since the data
a220: 62 61 73 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 77 base handle.** w
a230: 61 73 20 6f 70 65 6e 65 64 2e 20 20 54 68 65 20 as opened. The
a240: 63 6f 75 6e 74 20 69 6e 63 6c 75 64 65 73 20 61 count includes a
a250: 6c 6c 20 63 68 61 6e 67 65 73 20 66 72 6f 6d 20 ll changes from
a260: 61 6c 6c 20 74 72 69 67 67 65 72 0a 2a 2a 20 63 all trigger.** c
a270: 6f 6e 74 65 78 74 73 2e 20 20 42 75 74 20 74 68 ontexts. But th
a280: 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 e count does not
a290: 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 include changes
a2a0: 20 75 73 65 64 20 74 6f 0a 2a 2a 20 69 6d 70 6c used to.** impl
a2b0: 65 6d 65 6e 74 20 52 45 50 4c 41 43 45 20 63 6f ement REPLACE co
a2c0: 6e 73 74 72 61 69 6e 74 73 2c 20 64 6f 20 72 6f nstraints, do ro
a2d0: 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 llbacks or ABORT
a2e0: 20 70 72 6f 63 65 73 73 69 6e 67 2c 0a 2a 2a 20 processing,.**
a2f0: 6f 72 20 44 52 4f 50 20 74 61 62 6c 65 20 70 72 or DROP table pr
a300: 6f 63 65 73 73 69 6e 67 2e 0a 2a 2a 20 54 68 65 ocessing..** The
a310: 20 63 68 61 6e 67 65 73 0a 2a 2a 20 61 72 65 20 changes.** are
a320: 63 6f 75 6e 74 65 64 20 61 73 20 73 6f 6f 6e 20 counted as soon
a330: 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 as the statement
a340: 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d that makes them
a350: 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 0a 2a is completed .*
a360: 2a 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 * (when the stat
a370: 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 69 73 20 ement handle is
a380: 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 passed to [sqlit
a390: 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 0a e3_reset()] or .
a3a0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ** [sqlite3_fina
a3b0: 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 lize()])..**.**
a3c0: 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 SQLite implement
a3d0: 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 s the command "D
a3e0: 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 ELETE FROM table
a3f0: 22 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 57 " without.** a W
a400: 48 45 52 45 20 63 6c 61 75 73 65 20 62 79 20 64 HERE clause by d
a410: 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 ropping and recr
a420: 65 61 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 eating the table
a430: 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75 63 68 . (This is much
a440: 0a 2a 2a 20 66 61 73 74 65 72 20 74 68 61 6e 20 .** faster than
a450: 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 going.** through
a460: 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e and deleting in
a470: 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 dividual element
a480: 73 20 66 6f 72 6d 20 74 68 65 20 74 61 62 6c 65 s form the table
a490: 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66 0a 2a .) Because of.*
a4a0: 2a 20 74 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 * this optimizat
a4b0: 69 6f 6e 2c 20 74 68 65 20 63 68 61 6e 67 65 20 ion, the change
a4c0: 63 6f 75 6e 74 20 66 6f 72 20 22 44 45 4c 45 54 count for "DELET
a4d0: 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 E FROM table" wi
a4e0: 6c 6c 20 62 65 0a 2a 2a 20 7a 65 72 6f 20 72 65 ll be.** zero re
a4f0: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 gardless of the
a500: 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e number of elemen
a510: 74 73 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 ts that were ori
a520: 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65 0a 2a ginally in the.*
a530: 2a 20 74 61 62 6c 65 2e 20 54 6f 20 67 65 74 20 * table. To get
a540: 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e an accurate coun
a550: 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 t of the number
a560: 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c of rows deleted,
a570: 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 use.** "DELETE
a580: 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 FROM table WHERE
a590: 20 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 1" instead..**.
a5a0: 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 ** See also the
a5b0: 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 [sqlite3_changes
a5c0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a ()] interface..*
a5d0: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
a5e0: 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 32 32 36 31 7d .** .** {F12261}
a5f0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f The [sqlite3_to
a600: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 72 tal_changes()] r
a610: 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c eturns the total
a620: 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 number.**
a630: 20 20 20 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 of row chang
a640: 65 73 20 63 61 75 73 65 64 20 62 79 20 49 4e 53 es caused by INS
a650: 45 52 54 2c 20 55 50 44 41 54 45 2c 20 61 6e 64 ERT, UPDATE, and
a660: 2f 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 20 20 /or DELETE.**
a670: 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 statement
a680: 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 s on the same [d
a690: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
a6a0: 6f 6e 5d 2c 20 69 6e 20 61 6e 79 0a 2a 2a 20 20 on], in any.**
a6b0: 20 20 20 20 20 20 20 20 74 72 69 67 67 65 72 20 trigger
a6c0: 63 6f 6e 74 65 78 74 2c 20 73 69 6e 63 65 20 74 context, since t
a6d0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
a6e0: 65 63 74 69 6f 6e 20 77 61 73 0a 2a 2a 20 20 20 ection was.**
a6f0: 20 20 20 20 20 20 20 63 72 65 61 74 65 64 2e 0a created..
a700: 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e **.** LIMITATION
a710: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 36 34 S:.**.** {U12264
a720: 7d 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 } If a separate
a730: 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 thread makes cha
a740: 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 nges on the same
a750: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
a760: 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 tion.**
a770: 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f while [sqlite3_
a780: 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d total_changes()]
a790: 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e is running then
a7a0: 20 74 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 20 the value .**
a7b0: 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 65 64 returned
a7c0: 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c is unpredictabl
a7d0: 65 20 61 6e 64 20 75 6e 6d 65 61 6e 69 6e 67 66 e and unmeaningf
a7e0: 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ul..*/.int sqlit
a7f0: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
a800: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
a810: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 ** CAPI3REF: Int
a820: 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 errupt A Long-Ru
a830: 6e 6e 69 6e 67 20 51 75 65 72 79 20 7b 46 31 32 nning Query {F12
a840: 32 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 270}.**.** This
a850: 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 function causes
a860: 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 any pending data
a870: 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 base operation t
a880: 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 o abort and.** r
a890: 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 eturn at its ear
a8a0: 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 liest opportunit
a8b0: 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 y. This routine
a8c0: 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 is typically.**
a8d0: 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e called in respon
a8e0: 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 se to a user act
a8f0: 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 ion such as pres
a900: 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a sing "Cancel".**
a910: 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 or Ctrl-C where
a920: 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 the user wants
a930: 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 a long query ope
a940: 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a ration to halt.*
a950: 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a * immediately..*
a960: 2a 0a 2a 2a 20 49 74 20 69 73 20 73 61 66 65 20 *.** It is safe
a970: 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 to call this rou
a980: 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 tine from a thre
a990: 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f ad different fro
a9a0: 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 m the.** thread
a9b0: 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c that is currentl
a9c0: 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 y running the da
a9d0: 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e tabase operation
a9e0: 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 . But it.** is
a9f0: 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c not safe to call
aa00: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 this routine wi
aa10: 74 68 20 61 20 64 61 74 61 62 61 73 65 20 63 6f th a database co
aa20: 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 0a 2a 2a nnection that.**
aa30: 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 is closed or mi
aa40: 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 ght close before
aa50: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
aa60: 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a pt() returns..**
aa70: 0a 2a 2a 20 49 66 20 61 6e 20 53 51 4c 20 69 73 .** If an SQL is
aa80: 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e very nearly fin
aa90: 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d ished at the tim
aaa0: 65 20 77 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 e when sqlite3_i
aab0: 6e 74 65 72 72 75 70 74 28 29 0a 2a 2a 20 69 73 nterrupt().** is
aac0: 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 called, then it
aad0: 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 might not have
aae0: 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 20 74 an opportunity t
aaf0: 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 o be interrupted
ab00: 2e 0a 2a 2a 20 49 74 20 6d 69 67 68 74 20 63 6f ..** It might co
ab10: 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 ntinue to comple
ab20: 74 69 6f 6e 2e 0a 2a 2a 20 41 6e 20 53 51 4c 20 tion..** An SQL
ab30: 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 operation that i
ab40: 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 s interrupted wi
ab50: 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 ll return.** [SQ
ab60: 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e LITE_INTERRUPT].
ab70: 20 20 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 If the interru
ab80: 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 pted SQL operati
ab90: 6f 6e 20 69 73 20 61 6e 0a 2a 2a 20 49 4e 53 45 on is an.** INSE
aba0: 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 RT, UPDATE, or D
abb0: 45 4c 45 54 45 20 74 68 61 74 20 69 73 20 69 6e ELETE that is in
abc0: 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 side an explicit
abd0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 0a 2a transaction, .*
abe0: 2a 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 * then the entir
abf0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 69 e transaction wi
ac00: 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 ll be rolled bac
ac10: 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e k automatically.
ac20: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 .** A call to sq
ac30: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
ac40: 29 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 ) has no effect
ac50: 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 on SQL statement
ac60: 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 s.** that are st
ac70: 61 72 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 arted after sqli
ac80: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 te3_interrupt()
ac90: 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 returns..**.** I
aca0: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
acb0: 20 7b 46 31 32 32 37 31 7d 20 54 68 65 20 5b 73 {F12271} The [s
acc0: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
acd0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 ()] interface wi
ace0: 6c 6c 20 66 6f 72 63 65 20 61 6c 6c 20 72 75 6e ll force all run
acf0: 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 ning.**
ad00: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
ad10: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
ad20: 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
ad30: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
ad40: 20 20 20 20 20 20 20 20 20 74 6f 20 68 61 6c 74 to halt
ad50: 20 61 66 74 65 72 20 70 72 6f 63 65 73 73 69 6e after processin
ad60: 67 20 61 74 20 6d 6f 73 74 20 6f 6e 65 20 61 64 g at most one ad
ad70: 64 69 74 69 6f 6e 61 6c 20 72 6f 77 20 6f 66 0a ditional row of.
ad80: 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61 ** data
ad90: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 37 32 7d ..**.** {F12272}
ada0: 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 Any SQL stateme
adb0: 6e 74 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 nt that is inter
adc0: 72 75 70 74 65 64 20 62 79 20 5b 73 71 6c 69 74 rupted by [sqlit
add0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a e3_interrupt()].
ade0: 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c ** will
adf0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
ae00: 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 0a 2a INTERRUPT]..**.*
ae10: 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a * LIMITATIONS:.*
ae20: 2a 0a 2a 2a 20 7b 55 31 32 32 37 39 7d 20 49 66 *.** {U12279} If
ae30: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
ae40: 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 nnection closes
ae50: 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 while [sqlite3_i
ae60: 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20 nterrupt()].**
ae70: 20 20 20 20 20 20 20 20 69 73 20 72 75 6e 6e 69 is runni
ae80: 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e ng then bad thin
ae90: 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 gs will likely h
aea0: 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 appen..*/.void s
aeb0: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
aec0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
aed0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 ** CAPI3REF: Det
aee0: 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c ermine If An SQL
aef0: 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f Statement Is Co
af00: 6d 70 6c 65 74 65 20 7b 46 31 30 35 31 30 7d 0a mplete {F10510}.
af10: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
af20: 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 ines are useful
af30: 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 for command-line
af40: 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d input to determ
af50: 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 ine if the.** cu
af60: 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 rrently entered
af70: 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f text seems to fo
af80: 72 6d 20 63 6f 6d 70 6c 65 74 65 20 61 20 53 51 rm complete a SQ
af90: 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a L statement or.*
afa0: 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 * if additional
afb0: 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 input is needed
afc0: 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 before sending t
afd0: 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 he text into.**
afe0: 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 SQLite for parsi
aff0: 6e 67 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 ng. These routi
b000: 6e 65 73 20 72 65 74 75 72 6e 20 74 72 75 65 20 nes return true
b010: 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 if the input str
b020: 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 ing.** appears t
b030: 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 o be a complete
b040: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 SQL statement.
b050: 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a A statement is j
b060: 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 udged to be.** c
b070: 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e omplete if it en
b080: 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f ds with a semico
b090: 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 lon token and is
b0a0: 20 6e 6f 74 20 61 20 66 72 61 67 6d 65 6e 74 20 not a fragment
b0b0: 6f 66 20 61 0a 2a 2a 20 43 52 45 41 54 45 20 54 of a.** CREATE T
b0c0: 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 RIGGER statement
b0d0: 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 . Semicolons th
b0e0: 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 at are embedded
b0f0: 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 within.** string
b100: 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f literals or quo
b110: 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e ted identifier n
b120: 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 ames or comments
b130: 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 are not.** inde
b140: 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 pendent tokens (
b150: 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 they are part of
b160: 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 the token in wh
b170: 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 ich they are.**
b180: 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 embedded) and th
b190: 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 us do not count
b1a0: 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 as a statement t
b1b0: 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a erminator..**.**
b1c0: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
b1d0: 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 do not parse the
b1e0: 20 53 51 4c 20 61 6e 64 0a 2a 2a 20 73 6f 20 77 SQL and.** so w
b1f0: 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 ill not detect s
b200: 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 yntactically inc
b210: 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a orrect SQL..**.*
b220: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
b230: 0a 2a 2a 20 7b 46 31 30 35 31 31 7d 20 54 68 65 .** {F10511} The
b240: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 sqlite3_complet
b250: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f e() and sqlite3_
b260: 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 66 75 6e complete16() fun
b270: 63 74 69 6f 6e 73 0a 2a 2a 20 20 20 20 20 20 20 ctions.**
b280: 20 20 20 72 65 74 75 72 6e 20 74 72 75 65 20 28 return true (
b290: 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 61 6e 64 non-zero) if and
b2a0: 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 6c 61 73 only if the las
b2b0: 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f t.** no
b2c0: 6e 2d 77 68 69 74 65 73 70 61 63 65 20 74 6f 6b n-whitespace tok
b2d0: 65 6e 20 69 6e 20 74 68 65 69 72 20 69 6e 70 75 en in their inpu
b2e0: 74 20 69 73 20 61 20 73 65 6d 69 63 6f 6c 6f 6e t is a semicolon
b2f0: 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 that.**
b300: 20 20 69 73 20 6e 6f 74 20 69 6e 20 62 65 74 77 is not in betw
b310: 65 65 6e 20 74 68 65 20 42 45 47 49 4e 20 61 6e een the BEGIN an
b320: 64 20 45 4e 44 20 6f 66 20 61 20 43 52 45 41 54 d END of a CREAT
b330: 45 20 54 52 49 47 47 45 52 0a 2a 2a 20 20 20 20 E TRIGGER.**
b340: 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 2e statement.
b350: 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f .**.** LIMITATIO
b360: 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 30 35 31 NS:.**.** {U1051
b370: 32 7d 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 2} The input to
b380: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 sqlite3_complete
b390: 28 29 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 () must be a zer
b3a0: 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 o-terminated.**
b3b0: 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20 73 UTF-8 s
b3c0: 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 tring..**.** {U1
b3d0: 30 35 31 33 7d 20 54 68 65 20 69 6e 70 75 74 20 0513} The input
b3e0: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c to sqlite3_compl
b3f0: 65 74 65 31 36 28 29 20 6d 75 73 74 20 62 65 20 ete16() must be
b400: 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
b410: 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54 d.** UT
b420: 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e F-16 string in n
b430: 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
b440: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
b450: 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 _complete(const
b460: 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 char *sql);.int
b470: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 sqlite3_complete
b480: 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 16(const void *s
b490: 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ql);../*.** CAPI
b4a0: 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 3REF: Register A
b4b0: 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e Callback To Han
b4c0: 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 dle SQLITE_BUSY
b4d0: 45 72 72 6f 72 73 20 7b 46 31 32 33 31 30 7d 0a Errors {F12310}.
b4e0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
b4f0: 6e 65 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 ne identifies a
b500: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
b510: 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 0a n that might be.
b520: 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 ** invoked whene
b530: 76 65 72 20 61 6e 20 61 74 74 65 6d 70 74 20 69 ver an attempt i
b540: 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 s made to open a
b550: 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 database table
b560: 0a 2a 2a 20 74 68 61 74 20 61 6e 6f 74 68 65 72 .** that another
b570: 20 74 68 72 65 61 64 20 6f 72 20 70 72 6f 63 65 thread or proce
b580: 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a ss has locked..*
b590: 2a 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61 * If the busy ca
b5a0: 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 llback is NULL,
b5b0: 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 then [SQLITE_BUS
b5c0: 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 Y].** or [SQLITE
b5d0: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a _IOERR_BLOCKED].
b5e0: 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 ** is returned i
b5f0: 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 mmediately upon
b600: 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 encountering the
b610: 20 6c 6f 63 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 lock..** If the
b620: 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 busy callback i
b630: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e s not NULL, then
b640: 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b the.** callback
b650: 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 will be invoked
b660: 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 with two argume
b670: 6e 74 73 2e 20 20 54 68 65 0a 2a 2a 20 66 69 72 nts. The.** fir
b680: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 st argument to t
b690: 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 he handler is a
b6a0: 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 copy of the void
b6b0: 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a * pointer which.
b6c0: 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 ** is the third
b6d0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 argument to this
b6e0: 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 65 20 73 routine. The s
b6f0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 econd argument t
b700: 6f 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 o.** the handler
b710: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
b720: 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 f times that the
b730: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 busy handler ha
b740: 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 s.** been invoke
b750: 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 d for this locki
b760: 6e 67 20 65 76 65 6e 74 2e 20 20 20 49 66 20 74 ng event. If t
b770: 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 he.** busy callb
b780: 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 ack returns 0, t
b790: 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 hen no additiona
b7a0: 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d l attempts are m
b7b0: 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 ade to.** access
b7c0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e the database an
b7d0: 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 d [SQLITE_BUSY]
b7e0: 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 or [SQLITE_IOERR
b7f0: 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 _BLOCKED] is ret
b800: 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 urned..** If the
b810: 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
b820: 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e s non-zero, then
b830: 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 another attempt
b840: 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f .** is made to o
b850: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 pen the database
b860: 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 for reading and
b870: 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 the cycle repea
b880: 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 ts..**.** The pr
b890: 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 esence of a busy
b8a0: 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f handler does no
b8b0: 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 t guarantee that
b8c0: 0a 2a 2a 20 69 74 20 77 69 6c 6c 20 62 65 20 69 .** it will be i
b8d0: 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 72 nvoked when ther
b8e0: 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e e is lock conten
b8f0: 74 69 6f 6e 2e 0a 2a 2a 20 49 66 20 53 51 4c 69 tion..** If SQLi
b900: 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 te determines th
b910: 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 at invoking the
b920: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6f 75 busy handler cou
b930: 6c 64 20 72 65 73 75 6c 74 20 69 6e 0a 2a 2a 20 ld result in.**
b940: 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 a deadlock, it w
b950: 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 ill go ahead and
b960: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
b970: 42 55 53 59 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c BUSY] or.** [SQL
b980: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 ITE_IOERR_BLOCKE
b990: 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e D] instead of in
b9a0: 76 6f 6b 69 6e 67 20 74 68 65 0a 2a 2a 20 62 75 voking the.** bu
b9b0: 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 sy handler..** C
b9c0: 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 onsider a scenar
b9d0: 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f io where one pro
b9e0: 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 cess is holding
b9f0: 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 a read lock that
ba00: 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 .** it is trying
ba10: 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 to promote to a
ba20: 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 reserved lock a
ba30: 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 nd.** a second p
ba40: 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e rocess is holdin
ba50: 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 g a reserved loc
ba60: 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 k that it is try
ba70: 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 ing.** to promot
ba80: 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 e to an exclusiv
ba90: 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 e lock. The fir
baa0: 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f st process canno
bab0: 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 t proceed.** bec
bac0: 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b ause it is block
bad0: 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 ed by the second
bae0: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 and the second
baf0: 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a process cannot.*
bb00: 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 * proceed becaus
bb10: 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 e it is blocked
bb20: 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 by the first. I
bb30: 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 f both processes
bb40: 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 .** invoke the b
bb50: 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 usy handlers, ne
bb60: 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 ither will make
bb70: 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 any progress. T
bb80: 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c herefore,.** SQL
bb90: 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ite returns [SQL
bba0: 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 ITE_BUSY] for th
bbb0: 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c e first process,
bbc0: 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 hoping that thi
bbd0: 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 s.** will induce
bbe0: 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 the first proce
bbf0: 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 ss to release it
bc00: 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 s read lock and
bc10: 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 allow.** the sec
bc20: 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 ond process to p
bc30: 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 roceed..**.** Th
bc40: 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 e default busy c
bc50: 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e allback is NULL.
bc60: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 .**.** The [SQLI
bc70: 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 TE_BUSY] error i
bc80: 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b s converted to [
bc90: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f SQLITE_IOERR_BLO
bca0: 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 CKED].** when SQ
bcb0: 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d Lite is in the m
bcc0: 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 iddle of a large
bcd0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 transaction whe
bce0: 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 re all the.** ch
bcf0: 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 anges will not f
bd00: 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d it into the in-m
bd10: 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 emory cache. SQ
bd20: 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 Lite will.** alr
bd30: 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 eady hold a RESE
bd40: 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 RVED lock on the
bd50: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 database file,
bd60: 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 but it needs.**
bd70: 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 to promote this
bd80: 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 lock to EXCLUSIV
bd90: 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e E so that it can
bda0: 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 spill cache.**
bdb0: 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 pages into the d
bdc0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 atabase file wit
bdd0: 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e hout harm to con
bde0: 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 current.** reade
bdf0: 72 73 2e 20 20 49 66 20 69 74 20 69 73 20 75 6e rs. If it is un
be00: 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 able to promote
be10: 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 the lock, then t
be20: 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 he in-memory.**
be30: 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 cache will be le
be40: 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 ft in an inconsi
be50: 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 stent state and
be60: 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 so the error.**
be70: 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 code is promoted
be80: 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 from the relati
be90: 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c vely benign [SQL
bea0: 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 ITE_BUSY] to.**
beb0: 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 the more severe
bec0: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c [SQLITE_IOERR_BL
bed0: 4f 43 4b 45 44 5d 2e 20 20 54 68 69 73 20 65 72 OCKED]. This er
bee0: 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 ror code promoti
bef0: 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 on.** forces an
bf00: 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 automatic rollba
bf10: 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 ck of the change
bf20: 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c s. See the.** <
bf30: 61 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 a href="http://w
bf40: 77 77 2e 73 71 6c 69 74 65 2e 6f 72 67 2f 63 76 ww.sqlite.org/cv
bf50: 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 strac/wiki?p=Cor
bf60: 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 ruptionFollowing
bf70: 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 BusyError">.** C
bf80: 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 orruptionFollowi
bf90: 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 ngBusyError</a>
bfa0: 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 wiki page for a
bfb0: 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 discussion of wh
bfc0: 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 y.** this is imp
bfd0: 6f 72 74 61 6e 74 2e 0a 2a 2a 09 0a 2a 2a 20 54 ortant..**..** T
bfe0: 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 here can only be
bff0: 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 a single busy h
c000: 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 andler defined f
c010: 6f 72 20 65 61 63 68 20 64 61 74 61 62 61 73 65 or each database
c020: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 .** connection.
c030: 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 Setting a new b
c040: 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 usy handler clea
c050: 72 73 20 61 6e 79 20 70 72 65 76 69 6f 75 73 20 rs any previous
c060: 6f 6e 65 2e 20 0a 2a 2a 20 4e 6f 74 65 20 74 68 one. .** Note th
c070: 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 at calling [sqli
c080: 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 te3_busy_timeout
c090: 28 29 5d 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 ()] will also se
c0a0: 74 20 6f 72 20 63 6c 65 61 72 0a 2a 2a 20 74 68 t or clear.** th
c0b0: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a e busy handler..
c0c0: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
c0d0: 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 31 7d :.**.** {F12311}
c0e0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 75 The [sqlite3_bu
c0f0: 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 66 75 sy_handler()] fu
c100: 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 nction replaces
c110: 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
c120: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c .** cal
c130: 6c 62 61 63 6b 20 69 6e 20 74 68 65 20 64 61 74 lback in the dat
c140: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
c150: 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 identified by t
c160: 68 65 20 31 73 74 0a 2a 2a 20 20 20 20 20 20 20 he 1st.**
c170: 20 20 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 parameter wit
c180: 68 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e h a new busy han
c190: 64 6c 65 72 20 69 64 65 6e 74 69 66 69 65 64 20 dler identified
c1a0: 62 79 20 74 68 65 20 32 6e 64 20 61 6e 64 20 33 by the 2nd and 3
c1b0: 72 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 rd.** p
c1c0: 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a arameters..**.**
c1d0: 20 7b 46 31 32 33 31 32 7d 20 54 68 65 20 64 65 {F12312} The de
c1e0: 66 61 75 6c 74 20 62 75 73 79 20 68 61 6e 64 6c fault busy handl
c1f0: 65 72 20 66 6f 72 20 6e 65 77 20 64 61 74 61 62 er for new datab
c200: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 ase connections
c210: 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b is NULL..**.** {
c220: 46 31 32 33 31 34 7d 20 57 68 65 6e 20 74 77 6f F12314} When two
c230: 20 6f 72 20 6d 6f 72 65 20 64 61 74 61 62 61 73 or more databas
c240: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 61 e connection sha
c250: 72 65 20 61 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 re a common cach
c260: 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 e,.** t
c270: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 he busy handler
c280: 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 for the database
c290: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 75 72 72 connection curr
c2a0: 65 6e 74 6c 79 20 75 73 69 6e 67 0a 2a 2a 20 20 ently using.**
c2b0: 20 20 20 20 20 20 20 20 74 68 65 20 63 61 63 68 the cach
c2c0: 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 e is invoked whe
c2d0: 6e 20 74 68 65 20 63 61 63 68 65 20 65 6e 63 6f n the cache enco
c2e0: 75 6e 74 65 72 73 20 61 20 6c 6f 63 6b 2e 0a 2a unters a lock..*
c2f0: 2a 0a 2a 2a 20 7b 46 31 32 33 31 36 7d 20 49 66 *.** {F12316} If
c300: 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 a busy handler
c310: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
c320: 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 zero, then the
c330: 53 51 4c 69 74 65 0a 2a 2a 20 20 20 20 20 20 20 SQLite.**
c340: 20 20 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 interface tha
c350: 74 20 70 72 6f 76 6f 6b 65 64 20 74 68 65 20 6c t provoked the l
c360: 6f 63 6b 69 6e 67 20 65 76 65 6e 74 20 77 69 6c ocking event wil
c370: 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 l return.**
c380: 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 42 55 53 [SQLITE_BUS
c390: 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 Y]..**.** {F1231
c3a0: 38 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 8} SQLite will i
c3b0: 6e 76 6f 6b 65 73 20 74 68 65 20 62 75 73 79 20 nvokes the busy
c3c0: 68 61 6e 64 6c 65 72 20 77 69 74 68 20 74 77 6f handler with two
c3d0: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a argument which.
c3e0: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20 ** are
c3f0: 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 6f a copy of the po
c400: 69 6e 74 65 72 20 73 75 70 70 6c 69 65 64 20 62 inter supplied b
c410: 79 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 y the 3rd parame
c420: 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 ter to.**
c430: 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 [sqlite3_busy
c440: 5f 68 61 6e 64 6c 65 72 28 29 5d 20 61 6e 64 20 _handler()] and
c450: 61 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e a count of the n
c460: 75 6d 62 65 72 20 6f 66 20 70 72 69 6f 72 0a 2a umber of prior.*
c470: 2a 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f 63 * invoc
c480: 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 ations of the bu
c490: 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 74 sy handler for t
c4a0: 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 he same locking
c4b0: 65 76 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d event..**.** LIM
c4c0: 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 ITATIONS:.**.**
c4d0: 7b 55 31 32 33 31 39 7d 20 41 20 62 75 73 79 20 {U12319} A busy
c4e0: 68 61 6e 64 6c 65 72 20 73 68 6f 75 6c 64 20 6e handler should n
c4f0: 6f 74 20 63 61 6c 6c 20 63 6c 6f 73 65 20 74 68 ot call close th
c500: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
c510: 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 ction.**
c520: 20 20 6f 72 20 70 72 65 70 61 72 65 64 20 73 74 or prepared st
c530: 61 74 65 6d 65 6e 74 20 74 68 61 74 20 69 6e 76 atement that inv
c540: 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 oked the busy ha
c550: 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ndler..*/.int sq
c560: 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
c570: 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 er(sqlite3*, int
c580: 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 (*)(void*,int),
c590: 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 void*);../*.** C
c5a0: 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 API3REF: Set A B
c5b0: 75 73 79 20 54 69 6d 65 6f 75 74 20 7b 46 31 32 usy Timeout {F12
c5c0: 33 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 340}.**.** This
c5d0: 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b routine sets a [
c5e0: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e sqlite3_busy_han
c5f0: 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 dler | busy hand
c600: 6c 65 72 5d 0a 2a 2a 20 74 68 61 74 20 73 6c 65 ler].** that sle
c610: 65 70 73 20 66 6f 72 20 61 20 77 68 69 6c 65 20 eps for a while
c620: 77 68 65 6e 20 61 0a 2a 2a 20 74 61 62 6c 65 20 when a.** table
c630: 69 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 is locked. The
c640: 68 61 6e 64 6c 65 72 20 77 69 6c 6c 20 73 6c 65 handler will sle
c650: 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 ep multiple time
c660: 73 20 75 6e 74 69 6c 20 0a 2a 2a 20 61 74 20 6c s until .** at l
c670: 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 east "ms" millis
c680: 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 econds of sleepi
c690: 6e 67 20 68 61 76 65 20 62 65 65 6e 20 64 6f 6e ng have been don
c6a0: 65 2e 20 7b 46 31 32 33 34 33 7d 20 41 66 74 65 e. {F12343} Afte
c6b0: 72 0a 2a 2a 20 22 6d 73 22 20 6d 69 6c 6c 69 73 r.** "ms" millis
c6c0: 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 econds of sleepi
c6d0: 6e 67 2c 20 74 68 65 20 68 61 6e 64 6c 65 72 20 ng, the handler
c6e0: 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 0a returns 0 which.
c6f0: 2a 2a 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 ** causes [sqlit
c700: 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 e3_step()] to re
c710: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 turn [SQLITE_BUS
c720: 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f Y] or [SQLITE_IO
c730: 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a ERR_BLOCKED]..**
c740: 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 .** Calling this
c750: 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e routine with an
c760: 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 argument less t
c770: 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 han or equal to
c780: 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 zero.** turns of
c790: 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c f all busy handl
c7a0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 ers..**.** There
c7b0: 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 can only be a s
c7c0: 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c ingle busy handl
c7d0: 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 er for a particu
c7e0: 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 lar database.**
c7f0: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 49 66 20 connection. If
c800: 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e another busy han
c810: 64 6c 65 72 20 77 61 73 20 64 65 66 69 6e 65 64 dler was defined
c820: 20 20 0a 2a 2a 20 28 75 73 69 6e 67 20 5b 73 71 .** (using [sq
c830: 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
c840: 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 er()]) prior to
c850: 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 calling.** this
c860: 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 routine, that ot
c870: 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 her busy handler
c880: 20 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a 2a 0a is cleared..**.
c890: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
c8a0: 2a 0a 2a 2a 20 7b 46 31 32 33 34 31 7d 20 54 68 *.** {F12341} Th
c8b0: 65 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f e [sqlite3_busy_
c8c0: 74 69 6d 65 6f 75 74 28 29 5d 20 66 75 6e 63 74 timeout()] funct
c8d0: 69 6f 6e 20 6f 76 65 72 72 69 64 65 73 20 61 6e ion overrides an
c8e0: 79 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 y prior.**
c8f0: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 [sqlite3_bus
c900: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 6f 72 20 y_timeout()] or
c910: 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 [sqlite3_busy_ha
c920: 6e 64 6c 65 72 28 29 5d 20 73 65 74 74 69 6e 67 ndler()] setting
c930: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20 .** on
c940: 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
c950: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a e connection..**
c960: 0a 2a 2a 20 7b 46 31 32 33 34 33 7d 20 49 66 20 .** {F12343} If
c970: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
c980: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 r to [sqlite3_bu
c990: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 sy_timeout()] is
c9a0: 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 less than.**
c9b0: 20 20 20 20 20 20 20 6f 72 20 65 71 75 61 6c 20 or equal
c9c0: 74 6f 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 to zero, then th
c9d0: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 e busy handler i
c9e0: 73 20 63 6c 65 61 72 65 64 20 73 6f 20 74 68 61 s cleared so tha
c9f0: 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c t.** al
ca00: 6c 20 73 75 62 73 65 71 75 65 6e 74 20 6c 6f 63 l subsequent loc
ca10: 6b 69 6e 67 20 65 76 65 6e 74 73 20 69 6d 6d 65 king events imme
ca20: 64 69 61 74 65 6c 79 20 72 65 74 75 72 6e 20 5b diately return [
ca30: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a SQLITE_BUSY]..**
ca40: 0a 2a 2a 20 7b 46 31 32 33 34 34 7d 20 49 66 20 .** {F12344} If
ca50: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
ca60: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 r to [sqlite3_bu
ca70: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 sy_timeout()] is
ca80: 20 61 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 20 a positive.**
ca90: 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 4e number N
caa0: 2c 20 74 68 65 6e 20 61 20 62 75 73 79 20 68 61 , then a busy ha
cab0: 6e 64 6c 65 72 20 69 73 20 73 65 74 20 74 68 61 ndler is set tha
cac0: 74 20 72 65 70 65 61 74 65 64 6c 79 20 63 61 6c t repeatedly cal
cad0: 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 ls.** t
cae0: 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 he xSleep() meth
caf0: 6f 64 20 69 6e 20 74 68 65 20 56 46 53 20 69 6e od in the VFS in
cb00: 74 65 72 66 61 63 65 20 75 6e 74 69 6c 20 65 69 terface until ei
cb10: 74 68 65 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 ther the.**
cb20: 20 20 20 20 20 6c 6f 63 6b 20 63 6c 65 61 72 73 lock clears
cb30: 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 63 75 or until the cu
cb40: 6d 75 6c 61 74 69 76 65 20 73 6c 65 65 70 20 74 mulative sleep t
cb50: 69 6d 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 ime reported bac
cb60: 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 k.** by
cb70: 20 78 53 6c 65 65 70 28 29 20 65 78 63 65 65 64 xSleep() exceed
cb80: 73 20 4e 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 s N milliseconds
cb90: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
cba0: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 _busy_timeout(sq
cbb0: 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b lite3*, int ms);
cbc0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
cbd0: 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f : Convenience Ro
cbe0: 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 utines For Runni
cbf0: 6e 67 20 51 75 65 72 69 65 73 20 7b 46 31 32 33 ng Queries {F123
cc00: 37 30 7d 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 70}.**.** Defini
cc10: 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c tion: A <b>resul
cc20: 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d t table</b> is m
cc30: 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 emory data struc
cc40: 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 ture created by
cc50: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
cc60: 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 get_table()] int
cc70: 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c erface. A resul
cc80: 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 t table records
cc90: 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 the.** complete
cca0: 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 query results fr
ccb0: 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 om one or more q
ccc0: 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 ueries..**.** Th
ccd0: 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 e table conceptu
cce0: 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 ally has a numbe
ccf0: 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f r of rows and co
cd00: 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 lumns. But.** t
cd10: 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 hese numbers are
cd20: 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 not part of the
cd30: 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 result table it
cd40: 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 self. These.**
cd50: 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 numbers are obta
cd60: 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e ined separately.
cd70: 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e Let N be the n
cd80: 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a umber of rows.**
cd90: 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 and M be the nu
cda0: 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e mber of columns.
cdb0: 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 .**.** A result
cdc0: 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 table is an arra
cdd0: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f y of pointers to
cde0: 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
cdf0: 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 .** UTF-8 string
ce00: 73 2e 20 20 54 68 65 72 65 20 61 72 65 20 28 4e s. There are (N
ce10: 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 +1)*M elements i
ce20: 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 0a 2a n the array. .*
ce30: 2a 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f * The first M po
ce40: 69 6e 74 65 72 73 20 70 6f 69 6e 74 20 74 6f 20 inters point to
ce50: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
ce60: 73 74 72 69 6e 67 73 20 74 68 61 74 20 0a 2a 2a strings that .**
ce70: 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d contain the nam
ce80: 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e es of the column
ce90: 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e s..** The remain
cea0: 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 ing entries all
ceb0: 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 point to query r
cec0: 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 0a 2a 2a esults. NULL.**
ced0: 20 76 61 6c 75 65 73 20 61 72 65 20 67 69 76 65 values are give
cee0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
cef0: 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 All other valu
cf00: 65 73 20 61 72 65 20 69 6e 0a 2a 2a 20 74 68 65 es are in.** the
cf10: 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 ir UTF-8 zero-te
cf20: 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 20 rminated string
cf30: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 representation a
cf40: 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a s returned by.**
cf50: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
cf60: 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 _text()]..**.**
cf70: 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d A result table m
cf80: 69 67 68 74 20 63 6f 6e 73 69 73 74 73 20 6f 66 ight consists of
cf90: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d one or more mem
cfa0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e ory allocations.
cfb0: 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 .** It is not sa
cfc0: 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 fe to pass a res
cfd0: 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 ult table direct
cfe0: 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 ly to [sqlite3_f
cff0: 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 ree()]..** A res
d000: 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 ult table should
d010: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 be deallocated
d020: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 using [sqlite3_f
d030: 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a ree_table()]..**
d040: 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 6c .** As an exampl
d050: 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 e of the result
d060: 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 table format, su
d070: 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 ppose a query re
d080: 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f sult.** is as fo
d090: 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c llows:.**.** <bl
d0a0: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
d0b0: 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 * Name
d0c0: 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 | Age.**
d0d0: 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d -----------
d0e0: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 ------------.**
d0f0: 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 Alice
d100: 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 | 43.**
d110: 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 Bob |
d120: 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 28.** Cin
d130: 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a dy | 21.**
d140: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
d150: 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 ote>.**.** There
d160: 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 are two column
d170: 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 (M==2) and three
d180: 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 rows (N==3). T
d190: 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c hus the.** resul
d1a0: 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e t table has 8 en
d1b0: 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 tries. Suppose
d1c0: 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 the result table
d1d0: 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e is stored.** in
d1e0: 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 an array names
d1f0: 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 azResult. Then
d200: 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 azResult holds t
d210: 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a his content:.**.
d220: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
d230: 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 pre>.** a
d240: 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d zResult[0] =
d250: 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 "Name";.**
d260: 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
d270: 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 1] = "Age";.**
d280: 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
d290: 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 91;2] = "Alice";
d2a0: 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
d2b0: 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 ult[3] = "43
d2c0: 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
d2d0: 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 esult[4] = "
d2e0: 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 Bob";.**
d2f0: 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 azResult[5]
d300: 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 = "28";.**
d310: 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 azResult[6
d320: 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 ] = "Cindy";.**
d330: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
d340: 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a #91;7] = "21";.*
d350: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
d360: 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 uote>.**.** The
d370: 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
d380: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 e() function eva
d390: 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f luates one or mo
d3a0: 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d re.** semicolon-
d3b0: 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 separated SQL st
d3c0: 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 atements in the
d3d0: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
d3e0: 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 UTF-8.** string
d3f0: 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d of its 2nd param
d400: 65 74 65 72 2e 20 20 49 74 20 72 65 74 75 72 6e eter. It return
d410: 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 s a result table
d420: 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 to the.** point
d430: 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 er given in its
d440: 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 3rd parameter..*
d450: 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 63 *.** After the c
d460: 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 alling function
d470: 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 has finished usi
d480: 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2c 20 69 ng the result, i
d490: 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 61 73 t should .** pas
d4a0: 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f s the pointer to
d4b0: 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c the result tabl
d4c0: 65 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 e to sqlite3_fre
d4d0: 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 e_table() in ord
d4e0: 65 72 20 74 6f 20 0a 2a 2a 20 72 65 6c 65 61 73 er to .** releas
d4f0: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 e the memory tha
d500: 74 20 77 61 73 20 6d 61 6c 6c 6f 63 2d 65 64 2e t was malloc-ed.
d510: 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 Because of the
d520: 20 77 61 79 20 74 68 65 20 0a 2a 2a 20 5b 73 71 way the .** [sq
d530: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
d540: 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 happens within s
d550: 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
d560: 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a (), the calling.
d570: 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 ** function must
d580: 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c not try to call
d590: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
d5a0: 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c ] directly. Onl
d5b0: 79 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 y .** [sqlite3_f
d5c0: 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 ree_table()] is
d5d0: 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 able to release
d5e0: 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 the memory prope
d5f0: 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a rly and safely..
d600: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
d610: 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 3_get_table() in
d620: 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 terface is imple
d630: 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 mented as a wrap
d640: 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 per around.** [s
d650: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 qlite3_exec()].
d660: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 The sqlite3_get
d670: 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 _table() routine
d680: 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 does not have a
d690: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 ccess.** to any
d6a0: 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 internal data st
d6b0: 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 ructures of SQLi
d6c0: 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c te. It uses onl
d6d0: 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 y the public.**
d6e0: 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 interface define
d6f0: 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f d here. As a co
d700: 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 nsequence, error
d710: 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 s that occur in
d720: 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c the.** wrapper l
d730: 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 ayer outside of
d740: 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 the internal [sq
d750: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 lite3_exec()] ca
d760: 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 ll are not.** re
d770: 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 flected in subse
d780: 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b quent calls to [
d790: 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
d7a0: 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
d7b0: 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 3_errmsg()]..**.
d7c0: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
d7d0: 2a 0a 2a 2a 20 7b 46 31 32 33 37 31 7d 20 49 66 *.** {F12371} If
d7e0: 20 61 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f a [sqlite3_get_
d7f0: 74 61 62 6c 65 28 29 5d 20 66 61 69 6c 73 20 61 table()] fails a
d800: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
d810: 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 on, then.**
d820: 20 20 20 20 20 69 74 20 66 72 65 65 73 20 74 68 it frees th
d830: 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 75 e result table u
d840: 6e 64 65 72 20 63 6f 6e 73 74 72 75 63 74 69 6f nder constructio
d850: 6e 2c 20 61 62 6f 72 74 73 20 74 68 65 0a 2a 2a n, aborts the.**
d860: 20 20 20 20 20 20 20 20 20 20 71 75 65 72 79 20 query
d870: 69 6e 20 70 72 6f 63 65 73 73 2c 20 73 6b 69 70 in process, skip
d880: 73 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 s any subsequent
d890: 20 71 75 65 72 69 65 73 2c 20 73 65 74 73 20 74 queries, sets t
d8a0: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 2a he.** *
d8b0: 72 65 73 75 6c 74 70 20 6f 75 74 70 75 74 20 70 resultp output p
d8c0: 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20 61 ointer to NULL a
d8d0: 6e 64 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 nd returns [SQLI
d8e0: 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a TE_NOMEM]..**.**
d8f0: 20 7b 46 31 32 33 37 33 7d 20 49 66 20 74 68 65 {F12373} If the
d900: 20 6e 63 6f 6c 75 6d 6e 20 70 61 72 61 6d 65 74 ncolumn paramet
d910: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 er to [sqlite3_g
d920: 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e et_table()] is n
d930: 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 ot NULL.**
d940: 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 then [sqlite
d950: 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 77 3_get_table()] w
d960: 72 69 74 65 20 74 68 65 20 6e 75 6d 62 65 72 20 rite the number
d970: 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 of columns in th
d980: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 e.** re
d990: 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20 sult set of the
d9a0: 71 75 65 72 79 20 69 6e 74 6f 20 2a 6e 63 6f 6c query into *ncol
d9b0: 75 6d 6e 20 69 66 20 74 68 65 20 71 75 65 72 79 umn if the query
d9c0: 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 is.**
d9d0: 73 75 63 63 65 73 73 66 75 6c 20 28 69 66 20 74 successful (if t
d9e0: 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 he function retu
d9f0: 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 29 2e 0a rns SQLITE_OK)..
da00: 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 34 7d 20 49 **.** {F12374} I
da10: 66 20 74 68 65 20 6e 72 6f 77 20 70 61 72 61 6d f the nrow param
da20: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 eter to [sqlite3
da30: 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 73 _get_table()] is
da40: 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 not NULL.**
da50: 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 then [sqli
da60: 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d te3_get_table()]
da70: 20 77 72 69 74 65 20 74 68 65 20 6e 75 6d 62 65 write the numbe
da80: 72 20 6f 66 20 72 6f 77 73 20 69 6e 20 74 68 65 r of rows in the
da90: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 .** res
daa0: 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20 71 ult set of the q
dab0: 75 65 72 79 20 69 6e 74 6f 20 2a 6e 72 6f 77 20 uery into *nrow
dac0: 69 66 20 74 68 65 20 71 75 65 72 79 20 69 73 0a if the query is.
dad0: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 75 63 63 ** succ
dae0: 65 73 73 66 75 6c 20 28 69 66 20 74 68 65 20 66 essful (if the f
daf0: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
db00: 53 51 4c 49 54 45 5f 4f 4b 29 2e 0a 2a 2a 0a 2a SQLITE_OK)..**.*
db10: 2a 20 7b 46 31 32 33 37 36 7d 20 54 68 65 20 5b * {F12376} The [
db20: 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
db30: 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 65 e()] function se
db40: 74 73 20 69 74 73 20 2a 6e 63 6f 6c 75 6d 6e 20 ts its *ncolumn
db50: 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 value.**
db60: 20 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 to the number
db70: 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 of columns in th
db80: 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 e result set of
db90: 74 68 65 20 71 75 65 72 79 20 69 6e 20 74 68 65 the query in the
dba0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 71 6c .** sql
dbb0: 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 74 parameter, or t
dbc0: 6f 20 7a 65 72 6f 20 69 66 20 74 68 65 20 71 75 o zero if the qu
dbd0: 65 72 79 20 69 6e 20 73 71 6c 20 68 61 73 20 61 ery in sql has a
dbe0: 6e 20 65 6d 70 74 79 0a 2a 2a 20 20 20 20 20 20 n empty.**
dbf0: 20 20 20 20 72 65 73 75 6c 74 20 73 65 74 2e 0a result set..
dc00: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 */.int sqlite3_g
dc10: 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 et_table(. sqli
dc20: 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 te3*,
dc30: 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 /* An open dat
dc40: 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 abase */. const
dc50: 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 char *sql,
dc60: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 /* SQL to be ev
dc70: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 aluated */. cha
dc80: 72 20 2a 2a 2a 70 52 65 73 75 6c 74 2c 20 20 20 r ***pResult,
dc90: 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 /* Results of
dca0: 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 the query */.
dcb0: 69 6e 74 20 2a 6e 72 6f 77 2c 20 20 20 20 20 20 int *nrow,
dcc0: 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 /* Number
dcd0: 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 of result rows w
dce0: 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 ritten here */.
dcf0: 20 69 6e 74 20 2a 6e 63 6f 6c 75 6d 6e 2c 20 20 int *ncolumn,
dd00: 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 /* Number
dd10: 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d of result colum
dd20: 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 ns written here
dd30: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d */. char **errm
dd40: 73 67 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 sg /* Er
dd50: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 ror msg written
dd60: 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 here */.);.void
dd70: 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 sqlite3_free_tab
dd80: 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 le(char **result
dd90: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
dda0: 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 EF: Formatted St
ddb0: 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 ring Printing Fu
ddc0: 6e 63 74 69 6f 6e 73 20 7b 46 31 37 34 30 30 7d nctions {F17400}
ddd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
dde0: 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 61 6c tines are workal
ddf0: 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 ikes of the "pri
de00: 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 ntf()" family of
de10: 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 functions.** fr
de20: 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 om the standard
de30: 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a C library..**.**
de40: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 The sqlite3_mpr
de50: 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 intf() and sqlit
de60: 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f e3_vmprintf() ro
de70: 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 utines write the
de80: 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e ir.** results in
de90: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e to memory obtain
dea0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
deb0: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 _malloc()]..** T
dec0: 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 he strings retur
ded0: 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f ned by these two
dee0: 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 routines should
def0: 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 be.** released
df00: 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 by [sqlite3_free
df10: 28 29 5d 2e 20 20 20 42 6f 74 68 20 72 6f 75 74 ()]. Both rout
df20: 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a ines return a.**
df30: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 NULL pointer if
df40: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
df50: 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f ()] is unable to
df60: 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 allocate enough
df70: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f .** memory to ho
df80: 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 ld the resulting
df90: 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 string..**.** I
dfa0: 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e n sqlite3_snprin
dfb0: 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 tf() routine is
dfc0: 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 similar to "snpr
dfd0: 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 intf()" from.**
dfe0: 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c the standard C l
dff0: 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 ibrary. The res
e000: 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 ult is written i
e010: 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 nto the.** buffe
e020: 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 r supplied as th
e030: 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
e040: 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 er whose size is
e050: 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 given by.** the
e060: 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
e070: 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 . Note that the
e080: 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 order of the.**
e090: 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 first two parame
e0a0: 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 ters is reversed
e0b0: 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 from snprintf()
e0c0: 2e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a . This is an.**
e0d0: 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 historical acci
e0e0: 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 dent that cannot
e0f0: 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 be fixed withou
e100: 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 t breaking.** ba
e110: 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 ckwards compatib
e120: 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61 6c 73 ility. Note als
e130: 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 o that sqlite3_s
e140: 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 nprintf().** ret
e150: 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
e160: 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 o its buffer ins
e170: 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 tead of the numb
e180: 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 er of.** charact
e190: 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 ers actually wri
e1a0: 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 tten into the bu
e1b0: 66 66 65 72 2e 20 20 57 65 20 61 64 6d 69 74 20 ffer. We admit
e1c0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 that.** the numb
e1d0: 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 er of characters
e1e0: 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 written would b
e1f0: 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 e a more useful
e200: 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 return.** value
e210: 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 but we cannot ch
e220: 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 ange the impleme
e230: 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 ntation of sqlit
e240: 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a e3_snprintf().**
e250: 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 now without bre
e260: 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c aking compatibil
e270: 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f ity..**.** As lo
e280: 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 ng as the buffer
e290: 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 size is greater
e2a0: 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 than zero, sqli
e2b0: 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a te3_snprintf().*
e2c0: 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 * guarantees tha
e2d0: 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 t the buffer is
e2e0: 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d always zero-term
e2f0: 69 6e 61 74 65 64 2e 20 20 54 68 65 20 66 69 72 inated. The fir
e300: 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 st.** parameter
e310: 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c "n" is the total
e320: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 size of the buf
e330: 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 fer, including s
e340: 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 pace for.** the
e350: 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e zero terminator.
e360: 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 So the longest
e370: 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e string that can
e380: 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a be completely.*
e390: 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 * written will b
e3a0: 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 e n-1 characters
e3b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f ..**.** These ro
e3c0: 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 utines all imple
e3d0: 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 ment some additi
e3e0: 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a onal formatting.
e3f0: 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 ** options that
e400: 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 are useful for c
e410: 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 onstructing SQL
e420: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 statements..** A
e430: 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 ll of the usual
e440: 70 72 69 6e 74 66 20 66 6f 72 6d 61 74 74 69 6e printf formattin
e450: 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e g options apply.
e460: 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 In addition, t
e470: 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 here.** is are "
e480: 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 %q", "%Q", and "
e490: 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a %z" options..**.
e4a0: 2a 2a 20 54 68 65 20 25 71 20 6f 70 74 69 6f 6e ** The %q option
e4b0: 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 works like %s i
e4c0: 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69 n that it substi
e4d0: 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 tutes a null-ter
e4e0: 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e minated.** strin
e4f0: 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d g from the argum
e500: 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 ent list. But %
e510: 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 q also doubles e
e520: 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 very '\'' charac
e530: 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 ter..** %q is de
e540: 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 signed for use i
e550: 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c nside a string l
e560: 69 74 65 72 61 6c 2e 20 20 42 79 20 64 6f 75 62 iteral. By doub
e570: 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a ling each '\''.*
e580: 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 * character it e
e590: 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 scapes that char
e5a0: 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 acter and allows
e5b0: 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 it to be insert
e5c0: 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 ed into.** the s
e5d0: 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 tring..**.** For
e5e0: 20 65 78 61 6d 70 6c 65 2c 20 73 6f 20 73 6f 6d example, so som
e5f0: 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c e string variabl
e600: 65 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 e contains text
e610: 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a as follows:.**.*
e620: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
e630: 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 re>.** char *zT
e640: 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 ext = "It's a ha
e650: 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f ppy day!";.** </
e660: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
e670: 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 >.**.** One can
e680: 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e use this text in
e690: 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e an SQL statemen
e6a0: 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a t as follows:.**
e6b0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
e6c0: 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a <pre>.** char *
e6d0: 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d zSQL = sqlite3_m
e6e0: 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 printf("INSERT I
e6f0: 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 NTO table VALUES
e700: 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b ('%q')", zText);
e710: 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 .** sqlite3_exe
e720: 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 c(db, zSQL, 0, 0
e730: 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 , 0);.** sqlite
e740: 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 3_free(zSQL);.**
e750: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
e760: 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 ote>.**.** Becau
e770: 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 se the %q format
e780: 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c string is used,
e790: 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 the '\'' charac
e7a0: 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 ter in zText.**
e7b0: 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 is escaped and t
e7c0: 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 he SQL generated
e7d0: 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a is as follows:.
e7e0: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
e7f0: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 e><pre>.** INSE
e800: 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 RT INTO table1 V
e810: 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 ALUES('It''s a h
e820: 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c appy day!').** <
e830: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
e840: 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 e>.**.** This is
e850: 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 correct. Had w
e860: 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 e used %s instea
e870: 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e d of %q, the gen
e880: 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f erated SQL.** wo
e890: 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 uld have looked
e8a0: 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a like this:.**.**
e8b0: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
e8c0: 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e e>.** INSERT IN
e8d0: 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 TO table1 VALUES
e8e0: 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 ('It's a happy d
e8f0: 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e ay!');.** </pre>
e900: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
e910: 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 .** This second
e920: 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 example is an SQ
e930: 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 L syntax error.
e940: 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 As a general ru
e950: 6c 65 20 79 6f 75 0a 2a 2a 20 73 68 6f 75 6c 64 le you.** should
e960: 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 always use %q i
e970: 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 nstead of %s whe
e980: 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 n inserting text
e990: 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 0a into a string .
e9a0: 2a 2a 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a ** literal..**.*
e9b0: 2a 20 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 * The %Q option
e9c0: 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 works like %q ex
e9d0: 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 cept it also add
e9e0: 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 s single quotes
e9f0: 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 around.** the ou
ea00: 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 tside of the tot
ea10: 61 6c 20 73 74 72 69 6e 67 2e 20 20 4f 72 20 69 al string. Or i
ea20: 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 f the parameter
ea30: 69 6e 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a in the argument.
ea40: 2a 2a 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c ** list is a NUL
ea50: 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 L pointer, %Q su
ea60: 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 bstitutes the te
ea70: 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f xt "NULL" (witho
ea80: 75 74 20 73 69 6e 67 6c 65 0a 2a 2a 20 71 75 6f ut single.** quo
ea90: 74 65 73 29 20 69 6e 20 70 6c 61 63 65 20 6f 66 tes) in place of
eaa0: 20 74 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e 20 the %Q option.
eab0: 7b 45 4e 44 7d 20 20 53 6f 2c 20 66 6f 72 20 65 {END} So, for e
eac0: 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c xample, one coul
ead0: 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c d say:.**.** <bl
eae0: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
eaf0: 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 * char *zSQL =
eb00: 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
eb10: 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 "INSERT INTO tab
eb20: 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 le VALUES(%Q)",
eb30: 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 zText);.** sqli
eb40: 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 te3_exec(db, zSQ
eb50: 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 L, 0, 0, 0);.**
eb60: 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 sqlite3_free(zS
eb70: 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f QL);.** </pre></
eb80: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
eb90: 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 * The code above
eba0: 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 will render a c
ebb0: 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 orrect SQL state
ebc0: 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c ment in the zSQL
ebd0: 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 .** variable eve
ebe0: 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 n if the zText v
ebf0: 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c ariable is a NUL
ec00: 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a L pointer..**.**
ec10: 20 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 The "%z" format
ec20: 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b ting option work
ec30: 73 20 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 s exactly like "
ec40: 25 73 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 %s" with the.**
ec50: 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 addition that af
ec60: 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 ter the string h
ec70: 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 as been read and
ec80: 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 copied into.**
ec90: 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c the result, [sql
eca0: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 ite3_free()] is
ecb0: 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e called on the in
ecc0: 70 75 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 put string. {END
ecd0: 7d 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e }.**.** INVARIAN
ece0: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 TS:.**.** {F1740
ecf0: 33 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 3} The [sqlite3
ed00: 5f 6d 70 72 69 6e 74 66 28 29 5d 20 61 6e 64 20 _mprintf()] and
ed10: 5b 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 [sqlite3_vmprint
ed20: 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a f()] interfaces.
ed30: 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74 ** ret
ed40: 75 72 6e 20 65 69 74 68 65 72 20 70 6f 69 6e 74 urn either point
ed50: 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d ers to zero-term
ed60: 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 inated UTF-8 str
ed70: 69 6e 67 73 20 68 65 6c 64 20 69 6e 0a 2a 2a 20 ings held in.**
ed80: 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 memory
ed90: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
eda0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
edb0: 5d 20 6f 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ] or NULL pointe
edc0: 72 73 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 rs if.**
edd0: 20 20 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 a call to [sq
ede0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
edf0: 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 fails..**.** {F1
ee00: 37 34 30 36 7d 20 20 54 68 65 20 5b 73 71 6c 69 7406} The [sqli
ee10: 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 te3_snprintf()]
ee20: 69 6e 74 65 72 66 61 63 65 20 77 72 69 74 65 73 interface writes
ee30: 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
ee40: 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 ed.**
ee50: 55 54 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 74 UTF-8 string int
ee60: 6f 20 74 68 65 20 62 75 66 66 65 72 20 70 6f 69 o the buffer poi
ee70: 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 73 nted to by the s
ee80: 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a econd parameter.
ee90: 2a 2a 20 20 20 20 20 20 20 20 20 20 20 70 72 6f ** pro
eea0: 76 69 64 65 64 20 74 68 61 74 20 74 68 65 20 66 vided that the f
eeb0: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 irst parameter i
eec0: 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a s greater than z
eed0: 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 ero..**.** {F174
eee0: 30 37 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 07} The [sqlite
eef0: 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 3_snprintf()] in
ef00: 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 terface does not
ef10: 20 77 72 69 74 65 73 20 73 6c 6f 74 73 20 6f 66 writes slots of
ef20: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 74 .** it
ef30: 73 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 s output buffer
ef40: 28 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 (the second para
ef50: 6d 65 74 65 72 29 20 6f 75 74 73 69 64 65 20 74 meter) outside t
ef60: 68 65 20 72 61 6e 67 65 0a 2a 2a 20 20 20 20 20 he range.**
ef70: 20 20 20 20 20 20 6f 66 20 30 20 74 68 72 6f 75 of 0 throu
ef80: 67 68 20 4e 2d 31 20 28 77 68 65 72 65 20 4e 20 gh N-1 (where N
ef90: 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 is the first par
efa0: 61 6d 65 74 65 72 29 0a 2a 2a 20 20 20 20 20 20 ameter).**
efb0: 20 20 20 20 20 72 65 67 61 72 64 6c 65 73 73 20 regardless
efc0: 6f 66 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 of the length of
efd0: 20 74 68 65 20 73 74 72 69 6e 67 0a 2a 2a 20 20 the string.**
efe0: 20 20 20 20 20 20 20 20 20 72 65 71 75 65 73 74 request
eff0: 65 64 20 62 79 20 74 68 65 20 66 6f 72 6d 61 74 ed by the format
f000: 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a specification..
f010: 2a 2a 20 20 20 0a 2a 2f 0a 63 68 61 72 20 2a 73 ** .*/.char *s
f020: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 qlite3_mprintf(c
f030: 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b onst char*,...);
f040: 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 .char *sqlite3_v
f050: 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 mprintf(const ch
f060: 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 ar*, va_list);.c
f070: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 har *sqlite3_snp
f080: 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c rintf(int,char*,
f090: 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e const char*, ...
f0a0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
f0b0: 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 EF: Memory Alloc
f0c0: 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 20 ation Subsystem
f0d0: 7b 46 31 37 33 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 {F17300}.**.** T
f0e0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 20 he SQLite core
f0f0: 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 uses these three
f100: 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c routines for al
f110: 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 l of its own.**
f120: 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 internal memory
f130: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 allocation needs
f140: 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 . "Core" in the
f150: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 previous sentenc
f160: 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e e.** does not in
f170: 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d clude operating-
f180: 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 system specific
f190: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 VFS implementati
f1a0: 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 77 69 6e 64 on. The.** wind
f1b0: 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 ows VFS uses nat
f1c0: 69 76 65 20 6d 61 6c 6c 6f 63 20 61 6e 64 20 66 ive malloc and f
f1d0: 72 65 65 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 ree for some ope
f1e0: 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 rations..**.** T
f1f0: 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f he sqlite3_mallo
f200: 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 c() routine retu
f210: 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
f220: 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d a block.** of m
f230: 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e emory at least N
f240: 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 bytes in length
f250: 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 , where N is the
f260: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 49 parameter..** I
f270: 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 f sqlite3_malloc
f280: 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 () is unable to
f290: 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e obtain sufficien
f2a0: 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 t free.** memory
f2b0: 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e , it returns a N
f2c0: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 ULL pointer. If
f2d0: 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e the parameter N
f2e0: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d to.** sqlite3_m
f2f0: 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 alloc() is zero
f300: 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e or negative then
f310: 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
f320: 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e ) returns.** a N
f330: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a ULL pointer..**.
f340: 2a 2a 20 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 ** Calling sqlit
f350: 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 e3_free() with a
f360: 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 pointer previou
f370: 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 sly returned.**
f380: 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f by sqlite3_mallo
f390: 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 c() or sqlite3_r
f3a0: 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 ealloc() release
f3b0: 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f s that memory so
f3c0: 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 .** that it migh
f3d0: 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 54 68 t be reused. Th
f3e0: 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 e sqlite3_free()
f3f0: 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 routine is.** a
f400: 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c no-op if is cal
f410: 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 led with a NULL
f420: 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e pointer. Passin
f430: 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 g a NULL pointer
f440: 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 .** to sqlite3_f
f450: 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 ree() is harmles
f460: 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 s. After being
f470: 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a freed, memory.**
f480: 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 should neither
f490: 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 be read nor writ
f4a0: 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 ten. Even readi
f4b0: 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 ng previously fr
f4c0: 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 eed.** memory mi
f4d0: 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 ght result in a
f4e0: 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 segmentation fau
f4f0: 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 lt or other seve
f500: 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d re error..** Mem
f510: 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 ory corruption,
f520: 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 a segmentation f
f530: 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 ault, or other s
f540: 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d evere error.** m
f550: 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 ight result if s
f560: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 qlite3_free() is
f570: 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e called with a n
f580: 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 on-NULL pointer
f590: 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 that.** was not
f5a0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 obtained from sq
f5b0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f lite3_malloc() o
f5c0: 72 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 r sqlite3_free()
f5d0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
f5e0: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e te3_realloc() in
f5f0: 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 terface attempts
f600: 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 to resize a.**
f610: 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c prior memory all
f620: 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 ocation to be at
f630: 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 least N bytes,
f640: 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a where N is the.*
f650: 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 * second paramet
f660: 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 er. The memory
f670: 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 allocation to be
f680: 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 resized is the
f690: 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 first.** paramet
f6a0: 65 72 2e 20 20 49 66 20 74 68 65 20 66 69 72 73 er. If the firs
f6b0: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 t parameter to s
f6c0: 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
f6d0: 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f .** is a NULL po
f6e0: 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 inter then its b
f6f0: 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 ehavior is ident
f700: 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a ical to calling.
f710: 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f ** sqlite3_mallo
f720: 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 c(N) where N is
f730: 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
f740: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
f750: 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66 realloc()..** If
f760: 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
f770: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
f780: 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 _realloc() is ze
f790: 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 ro or.** negativ
f7a0: 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 e then the behav
f7b0: 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 ior is exactly t
f7c0: 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 he same as calli
f7d0: 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 ng.** sqlite3_fr
f7e0: 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73 ee(P) where P is
f7f0: 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
f800: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
f810: 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 53 71 realloc()..** Sq
f820: 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 lite3_realloc()
f830: 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
f840: 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c r to a memory al
f850: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 location.** of a
f860: 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 t least N bytes
f870: 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 in size or NULL
f880: 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 if sufficient me
f890: 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 mory is unavaila
f8a0: 62 6c 65 2e 0a 2a 2a 20 49 66 20 4d 20 69 73 20 ble..** If M is
f8b0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
f8c0: 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e prior allocation
f8d0: 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 , then min(N,M)
f8e0: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 bytes.** of the
f8f0: 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e prior allocation
f900: 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f are copied into
f910: 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f the beginning o
f920: 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 f buffer returne
f930: 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f d.** by sqlite3_
f940: 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 realloc() and th
f950: 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 e prior allocati
f960: 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 on is freed..**
f970: 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c If sqlite3_reall
f980: 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c oc() returns NUL
f990: 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f L, then the prio
f9a0: 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 r allocation.**
f9b0: 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a is not freed..**
f9c0: 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 72 .** The memory r
f9d0: 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
f9e0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 e3_malloc() and
f9f0: 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
fa00: 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 ).** is always a
fa10: 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 ligned to at lea
fa20: 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 st an 8 byte bou
fa30: 6e 64 61 72 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a ndary. {END}.**.
fa40: 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 69 ** The default i
fa50: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a mplementation.**
fa60: 20 6f 66 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 of the memory a
fa70: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 llocation subsys
fa80: 74 65 6d 20 75 73 65 73 20 74 68 65 20 6d 61 6c tem uses the mal
fa90: 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 loc(), realloc()
faa0: 0a 2a 2a 20 61 6e 64 20 66 72 65 65 28 29 20 70 .** and free() p
fab0: 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 73 rovided by the s
fac0: 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 tandard C librar
fad0: 79 2e 20 7b 46 31 37 33 38 32 7d 20 48 6f 77 65 y. {F17382} Howe
fae0: 76 65 72 2c 20 69 66 20 0a 2a 2a 20 53 51 4c 69 ver, if .** SQLi
faf0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
fb00: 69 74 68 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e ith the followin
fb10: 67 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 g C preprocessor
fb20: 20 6d 61 63 72 6f 0a 2a 2a 0a 2a 2a 20 3c 62 6c macro.**.** <bl
fb30: 6f 63 6b 71 75 6f 74 65 3e 20 53 51 4c 49 54 45 ockquote> SQLITE
fb40: 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e _MEMORY_SIZE=<i>
fb50: 4e 4e 4e 3c 2f 69 3e 20 3c 2f 62 6c 6f 63 6b 71 NNN</i> </blockq
fb60: 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 uote>.**.** wher
fb70: 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 69 73 20 e <i>NNN</i> is
fb80: 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e an integer, then
fb90: 20 53 51 4c 69 74 65 20 63 72 65 61 74 65 20 61 SQLite create a
fba0: 20 73 74 61 74 69 63 0a 2a 2a 20 61 72 72 61 79 static.** array
fbb0: 20 6f 66 20 61 74 20 6c 65 61 73 74 20 3c 69 3e of at least <i>
fbc0: 4e 4e 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e NNN</i> bytes in
fbd0: 20 73 69 7a 65 20 61 6e 64 20 75 73 65 20 74 68 size and use th
fbe0: 61 74 20 61 72 72 61 79 0a 2a 2a 20 66 6f 72 20 at array.** for
fbf0: 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d all of its dynam
fc00: 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ic memory alloca
fc10: 74 69 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44 tion needs. {END
fc20: 7d 20 20 41 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a } Additional.**
fc30: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
fc40: 72 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 r options may be
fc50: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 added in future
fc60: 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a releases..**.**
fc70: 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 In SQLite versi
fc80: 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 on 3.5.0 and 3.5
fc90: 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 .1, it was possi
fca0: 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a ble to define.**
fcb0: 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 the SQLITE_OMIT
fcc0: 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 _MEMORY_ALLOCATI
fcd0: 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 ON which would c
fce0: 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 ause the built-i
fcf0: 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 n.** implementat
fd00: 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 ion of these rou
fd10: 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 tines to be omit
fd20: 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 ted. That capab
fd30: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c ility.** is no l
fd40: 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 onger provided.
fd50: 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d Only built-in m
fd60: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 emory allocators
fd70: 20 63 61 6e 20 62 65 0a 2a 2a 20 75 73 65 64 2e can be.** used.
fd80: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 77 69 6e 64 6f .**.** The windo
fd90: 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 ws OS interface
fda0: 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 layer calls.** t
fdb0: 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 he system malloc
fdc0: 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 () and free() di
fdd0: 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 rectly when conv
fde0: 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 erting.** filena
fdf0: 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 mes between the
fe00: 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 UTF-8 encoding u
fe10: 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a sed by SQLite.**
fe20: 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 and whatever fi
fe30: 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 lename encoding
fe40: 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 is used by the p
fe50: 61 72 74 69 63 75 6c 61 72 20 77 69 6e 64 6f 77 articular window
fe60: 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f s.** installatio
fe70: 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 n. Memory alloc
fe80: 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 ation errors are
fe90: 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a detected, but.*
fea0: 2a 20 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 * they are repor
feb0: 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c ted back as [SQL
fec0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 ITE_CANTOPEN] or
fed0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 .** [SQLITE_IOER
fee0: 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b R] rather than [
fef0: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a SQLITE_NOMEM]..*
ff00: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
ff10: 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 30 33 7d 20 .**.** {F17303}
ff20: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 The [sqlite3_ma
ff30: 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66 61 lloc(N)] interfa
ff40: 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 ce returns eithe
ff50: 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 0a r a pointer to .
ff60: 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e 65 77 ** new
ff70: 6c 79 20 63 68 65 63 6b 65 64 2d 6f 75 74 20 62 ly checked-out b
ff80: 6c 6f 63 6b 20 6f 66 20 61 74 20 6c 65 61 73 74 lock of at least
ff90: 20 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f N bytes of memo
ffa0: 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 ry.**
ffb0: 74 68 61 74 20 69 73 20 38 2d 62 79 74 65 20 61 that is 8-byte a
ffc0: 6c 69 67 6e 65 64 2c 20 0a 2a 2a 20 20 20 20 20 ligned, .**
ffd0: 20 20 20 20 20 20 6f 72 20 69 74 20 72 65 74 75 or it retu
ffe0: 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69 74 20 69 rns NULL if it i
fff0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 66 75 6c 66 s unable to fulf
10000 69 6c 6c 20 74 68 65 20 72 65 71 75 65 73 74 2e ill the request.
10010 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 30 34 7d 20 .**.** {F17304}
10020 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 The [sqlite3_ma
10030 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66 61 lloc(N)] interfa
10040 63 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c ce returns a NUL
10050 4c 20 70 6f 69 6e 74 65 72 20 69 66 0a 2a 2a 20 L pointer if.**
10060 20 20 20 20 20 20 20 20 20 20 4e 20 69 73 20 6c N is l
10070 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 ess than or equa
10080 6c 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a l to zero..**.**
10090 20 7b 46 31 37 33 30 35 7d 20 20 54 68 65 20 5b {F17305} The [
100a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 5d sqlite3_free(P)]
100b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 6c 65 61 interface relea
100c0 73 65 73 20 6d 65 6d 6f 72 79 20 70 72 65 76 69 ses memory previ
100d0 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 ously.**
100e0 20 20 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d returned from
100f0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
10100 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
10110 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 realloc()],.**
10120 20 20 20 20 20 20 20 20 20 6d 61 6b 69 6e 67 20 making
10130 69 74 20 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 it available for
10140 20 72 65 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 reuse..**.** {F
10150 31 37 33 30 36 7d 20 20 41 20 63 61 6c 6c 20 74 17306} A call t
10160 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 o [sqlite3_free(
10170 4e 55 4c 4c 29 5d 20 69 73 20 61 20 68 61 72 6d NULL)] is a harm
10180 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a less no-op..**.*
10190 2a 20 7b 46 31 37 33 31 30 7d 20 20 41 20 63 61 * {F17310} A ca
101a0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 ll to [sqlite3_r
101b0 65 61 6c 6c 6f 63 28 30 2c 4e 29 5d 20 69 73 20 ealloc(0,N)] is
101c0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 61 20 equivalent to a
101d0 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 call.**
101e0 20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 to [sqlite3_ma
101f0 6c 6c 6f 63 28 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 lloc(N)]..**.**
10200 7b 46 31 37 33 31 32 7d 20 20 41 20 63 61 6c 6c {F17312} A call
10210 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 to [sqlite3_rea
10220 6c 6c 6f 63 28 50 2c 30 29 5d 20 69 73 20 65 71 lloc(P,0)] is eq
10230 75 69 76 61 6c 65 6e 74 20 74 6f 20 61 20 63 61 uivalent to a ca
10240 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 ll.**
10250 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 to [sqlite3_free
10260 28 50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 (P)]..**.** {F17
10270 33 31 35 7d 20 20 54 68 65 20 53 51 4c 69 74 65 315} The SQLite
10280 20 63 6f 72 65 20 75 73 65 73 20 5b 73 71 6c 69 core uses [sqli
10290 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b te3_malloc()], [
102a0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
102b0 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 )],.**
102c0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 72 and [sqlite3_fr
102d0 65 65 28 29 5d 20 66 6f 72 20 61 6c 6c 20 6f 66 ee()] for all of
102e0 20 69 74 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f its memory allo
102f0 63 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 cation and.**
10300 20 20 20 20 20 20 20 20 64 65 61 6c 6c 6f 63 61 dealloca
10310 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a tion needs..**.*
10320 2a 20 7b 46 31 37 33 31 38 7d 20 20 54 68 65 20 * {F17318} The
10330 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
10340 28 50 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 (P,N)] interface
10350 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 20 returns either
10360 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 a pointer.**
10370 20 20 20 20 20 20 20 74 6f 20 61 20 62 6c 6f 63 to a bloc
10380 6b 20 6f 66 20 63 68 65 63 6b 65 64 2d 6f 75 74 k of checked-out
10390 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 memory of at le
103a0 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 ast N bytes in s
103b0 69 7a 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ize.**
103c0 20 74 68 61 74 20 69 73 20 38 2d 62 79 74 65 20 that is 8-byte
103d0 61 6c 69 67 6e 65 64 2c 20 6f 72 20 61 20 4e 55 aligned, or a NU
103e0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
103f0 2a 20 7b 46 31 37 33 32 31 7d 20 20 57 68 65 6e * {F17321} When
10400 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f [sqlite3_reallo
10410 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 c(P,N)] returns
10420 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 a non-NULL point
10430 65 72 2c 20 69 74 20 66 69 72 73 74 0a 2a 2a 20 er, it first.**
10440 20 20 20 20 20 20 20 20 20 20 63 6f 70 69 65 73 copies
10450 20 74 68 65 20 66 69 72 73 74 20 4b 20 62 79 74 the first K byt
10460 65 73 20 6f 66 20 63 6f 6e 74 65 6e 74 20 66 72 es of content fr
10470 6f 6d 20 50 20 69 6e 74 6f 20 74 68 65 20 6e 65 om P into the ne
10480 77 6c 79 20 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a wly allocated.**
10490 20 20 20 20 20 20 20 20 20 20 20 77 68 65 72 65 where
104a0 20 4b 20 69 73 20 74 68 65 20 6c 65 73 73 6f 72 K is the lessor
104b0 20 6f 66 20 4e 20 61 6e 64 20 74 68 65 20 73 69 of N and the si
104c0 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 ze of the buffer
104d0 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 32 P..**.** {F1732
104e0 32 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 2} When [sqlite
104f0 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 3_realloc(P,N)]
10500 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 returns a non-NU
10510 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66 LL pointer, it f
10520 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 irst.**
10530 20 20 72 65 6c 65 61 73 65 73 20 74 68 65 20 62 releases the b
10540 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b uffer P..**.** {
10550 46 31 37 33 32 33 7d 20 20 57 68 65 6e 20 5b 73 F17323} When [s
10560 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 qlite3_realloc(P
10570 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 4e 55 4c ,N)] returns NUL
10580 4c 2c 20 74 68 65 20 62 75 66 66 65 72 20 50 20 L, the buffer P
10590 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 is.**
105a0 6e 6f 74 20 6d 6f 64 69 66 69 65 64 20 6f 72 20 not modified or
105b0 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 released..**.**
105c0 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a LIMITATIONS:.**.
105d0 2a 2a 20 7b 55 31 37 33 35 30 7d 20 20 54 68 65 ** {U17350} The
105e0 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e pointer argumen
105f0 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 ts to [sqlite3_f
10600 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 ree()] and [sqli
10610 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a te3_realloc()].*
10620 2a 20 20 20 20 20 20 20 20 20 20 20 6d 75 73 74 * must
10630 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 be either NULL
10640 6f 72 20 65 6c 73 65 20 61 20 70 6f 69 6e 74 65 or else a pointe
10650 72 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 r obtained from
10660 61 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 a prior.**
10670 20 20 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e 20 invocation
10680 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c of [sqlite3_mall
10690 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 oc()] or [sqlite
106a0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 3_realloc()] tha
106b0 74 20 68 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 t has.**
106c0 20 20 20 6e 6f 74 20 62 65 65 6e 20 72 65 6c 65 not been rele
106d0 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 37 ased..**.** {U17
106e0 33 35 31 7d 20 20 54 68 65 20 61 70 70 6c 69 63 351} The applic
106f0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 ation must not r
10700 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 ead or write any
10710 20 70 61 72 74 20 6f 66 20 0a 2a 2a 20 20 20 20 part of .**
10720 20 20 20 20 20 20 20 61 20 62 6c 6f 63 6b 20 6f a block o
10730 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 f memory after i
10740 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 t has been relea
10750 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 sed using.**
10760 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
10770 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 free()] or [sqli
10780 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a te3_realloc()]..
10790 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 **.*/.void *sqli
107a0 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b te3_malloc(int);
107b0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 .void *sqlite3_r
107c0 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e ealloc(void*, in
107d0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 t);.void sqlite3
107e0 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f _free(void*);../
107f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
10800 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 emory Allocator
10810 53 74 61 74 69 73 74 69 63 73 20 7b 46 31 37 33 Statistics {F173
10820 37 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 70}.**.** SQLite
10830 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 provides these
10840 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 two interfaces f
10850 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 or reporting on
10860 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 the status.** of
10870 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 the [sqlite3_ma
10880 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 lloc()], [sqlite
10890 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 3_free()], and [
108a0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
108b0 29 5d 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 )].** the memory
108c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 allocation subs
108d0 79 73 74 65 6d 20 69 6e 63 6c 75 64 65 64 20 77 ystem included w
108e0 69 74 68 69 6e 20 74 68 65 20 53 51 4c 69 74 65 ithin the SQLite
108f0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
10900 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37 TS:.**.** {F1737
10910 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 1} The [sqlite3_
10920 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 memory_used()] r
10930 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 outine returns t
10940 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e he.** n
10950 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f umber of bytes o
10960 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 f memory current
10970 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 0a ly outstanding .
10980 2a 2a 20 20 20 20 20 20 20 20 20 20 28 6d 61 6c ** (mal
10990 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 loced but not fr
109a0 65 65 64 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 eed)..**.** {F17
109b0 33 37 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 373} The [sqlite
109c0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 3_memory_highwat
109d0 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 er()] routine re
109e0 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 turns the maximu
109f0 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 m.** va
10a00 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f lue of [sqlite3_
10a10 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 0a memory_used()] .
10a20 2a 2a 20 20 20 20 20 20 20 20 20 20 73 69 6e 63 ** sinc
10a30 65 20 74 68 65 20 68 69 67 68 77 61 74 65 72 20 e the highwater
10a40 6d 61 72 6b 20 77 61 73 20 6c 61 73 74 20 72 65 mark was last re
10a50 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 set..**.** {F173
10a60 37 34 7d 20 54 68 65 20 76 61 6c 75 65 73 20 72 74} The values r
10a70 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 eturned by [sqli
10a80 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 te3_memory_used(
10a90 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 )] and.**
10aa0 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f [sqlite3_memo
10ab0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 ry_highwater()]
10ac0 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 include any over
10ad0 68 65 61 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 head.**
10ae0 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 added by SQLite
10af0 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e in its implemen
10b00 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 tation of [sqlit
10b10 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a e3_malloc()],.**
10b20 20 20 20 20 20 20 20 20 20 20 62 75 74 20 6e 6f but no
10b30 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 t overhead added
10b40 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 by the any unde
10b50 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 rlying system li
10b60 62 72 61 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 brary.**
10b70 20 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 routines that
10b80 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
10b90 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 20 )] may call..**
10ba0 0a 2a 2a 20 7b 46 31 37 33 37 35 7d 20 54 68 65 .** {F17375} The
10bb0 20 6d 65 6d 6f 72 79 20 68 69 67 68 77 61 74 65 memory highwate
10bc0 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 r mark is reset
10bd0 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 to the current v
10be0 61 6c 75 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 alue of.**
10bf0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d [sqlite3_mem
10c00 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 ory_used()] if a
10c10 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 nd only if the p
10c20 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 arameter to.**
10c30 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
10c40 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 _memory_highwate
10c50 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 54 r()] is true. T
10c60 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
10c70 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 d.** by
10c80 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
10c90 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 _highwater(1)] i
10ca0 73 20 74 68 65 20 68 69 67 68 77 61 74 65 72 20 s the highwater
10cb0 6d 61 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 mark.**
10cc0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 prior to the re
10cd0 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f set..*/.sqlite3_
10ce0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 int64 sqlite3_me
10cf0 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b mory_used(void);
10d00 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 .sqlite3_int64 s
10d10 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
10d20 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 ghwater(int rese
10d30 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 tFlag);../*.** C
10d40 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 API3REF: Compile
10d50 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 -Time Authorizat
10d60 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 ion Callbacks {F
10d70 31 32 35 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 12500}.**.** Thi
10d80 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 s routine regist
10d90 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 ers a authorizer
10da0 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 callback with a
10db0 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 64 particular.** d
10dc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
10dd0 6f 6e 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 on, supplied in
10de0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
10df0 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f nt..** The autho
10e00 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 rizer callback i
10e10 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c s invoked as SQL
10e20 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 statements are
10e30 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a being compiled.*
10e40 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 * by [sqlite3_pr
10e50 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 epare()] or its
10e60 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 variants [sqlite
10e70 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 3_prepare_v2()],
10e80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
10e90 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 pare16()] and [s
10ea0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
10eb0 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 61 72 69 _v2()]. At vari
10ec0 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 ous.** points du
10ed0 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 ring the compila
10ee0 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 tion process, as
10ef0 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 logic is being
10f00 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 created.** to pe
10f10 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 rform various ac
10f20 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f tions, the autho
10f30 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 rizer callback i
10f40 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 s invoked to.**
10f50 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 see if those act
10f60 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 ions are allowed
10f70 2e 20 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 . The authorize
10f80 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c r callback shoul
10f90 64 0a 2a 2a 20 72 65 74 75 72 6e 20 53 51 4c 49 d.** return SQLI
10fa0 54 45 5f 4f 4b 20 74 6f 20 61 6c 6c 6f 77 20 74 TE_OK to allow t
10fb0 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 he action, [SQLI
10fc0 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 TE_IGNORE] to di
10fd0 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 sallow the.** sp
10fe0 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 ecific action bu
10ff0 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 t allow the SQL
11000 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e statement to con
11010 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 tinue to be.** c
11020 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c ompiled, or [SQL
11030 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 ITE_DENY] to cau
11040 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 se the entire SQ
11050 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 L statement to b
11060 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 e.** rejected wi
11070 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 20 49 th an error. I
11080 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 f the authorizer
11090 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
110a0 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f s.** any value o
110b0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
110c0 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 E_IGNORE], [SQLI
110d0 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 TE_OK], or [SQLI
110e0 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e TE_DENY].** then
110f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
11100 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 e_v2()] or equiv
11110 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 alent call that
11120 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 triggered.** the
11130 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c authorizer will
11140 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 fail with an er
11150 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a ror message..**.
11160 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c ** When the call
11170 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 back returns [SQ
11180 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d LITE_OK], that m
11190 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 eans the operati
111a0 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 on.** requested
111b0 69 73 20 6f 6b 2e 20 20 57 68 65 6e 20 74 68 65 is ok. When the
111c0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
111d0 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c s [SQLITE_DENY],
111e0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
111f0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
11200 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c r equivalent cal
11210 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 l that triggered
11220 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a the.** authoriz
11230 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 er will fail wit
11240 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 h an error messa
11250 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 ge explaining th
11260 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 at.** access is
11270 64 65 6e 69 65 64 2e 20 20 49 66 20 74 68 65 20 denied. If the
11280 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 authorizer code
11290 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d is [SQLITE_READ]
112a0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c .** and the call
112b0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 back returns [SQ
112c0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 LITE_IGNORE] the
112d0 6e 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a n the prepared.*
112e0 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 * statement is c
112f0 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 69 6e onstructed to in
11300 73 65 72 74 20 61 20 4e 55 4c 4c 20 76 61 6c 75 sert a NULL valu
11310 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a e in place of.**
11320 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d the table colum
11330 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 n that would hav
11340 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 e.** been read i
11350 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 f [SQLITE_OK] ha
11360 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e d been returned.
11370 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 The [SQLITE_IG
11380 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 NORE].** return
11390 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 can be used to d
113a0 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 eny an untrusted
113b0 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 user access to
113c0 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f individual.** co
113d0 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 lumns of a table
113e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 ..**.** The firs
113f0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 t parameter to t
11400 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
11410 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 llback is a copy
11420 20 6f 66 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 of.** the third
11430 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
11440 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 e sqlite3_set_au
11450 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 thorizer() inter
11460 66 61 63 65 2e 0a 2a 2a 20 54 68 65 20 73 65 63 face..** The sec
11470 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ond parameter to
11480 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 the callback is
11490 20 61 6e 20 69 6e 74 65 67 65 72 20 0a 2a 2a 20 an integer .**
114a0 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 [SQLITE_COPY | a
114b0 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 ction code] that
114c0 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 70 specifies the p
114d0 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e articular action
114e0 0a 2a 2a 20 74 6f 20 62 65 20 61 75 74 68 6f 72 .** to be author
114f0 69 7a 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 ized. The third
11500 74 68 72 6f 75 67 68 20 73 69 78 74 68 0a 2a 2a through sixth.**
11510 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 parameters to t
11520 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 he callback are
11530 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
11540 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e strings that con
11550 74 61 69 6e 20 0a 2a 2a 20 61 64 64 69 74 69 6f tain .** additio
11560 6e 61 6c 20 64 65 74 61 69 6c 73 20 61 62 6f 75 nal details abou
11570 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 t the action to
11580 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a be authorized..*
11590 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a *.** An authoriz
115a0 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 er is used when
115b0 70 72 65 70 61 72 69 6e 67 20 53 51 4c 20 73 74 preparing SQL st
115c0 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e atements from an
115d0 20 75 6e 74 72 75 73 74 65 64 0a 2a 2a 20 73 6f untrusted.** so
115e0 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 urce, to ensure
115f0 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 that the SQL sta
11600 74 65 6d 65 6e 74 73 20 64 6f 20 6e 6f 74 20 74 tements do not t
11610 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 ry to access dat
11620 61 0a 2a 2a 20 74 68 61 74 20 74 68 65 79 20 61 a.** that they a
11630 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 re not allowed t
11640 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 o see, or that t
11650 68 65 79 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 hey do not try t
11660 6f 0a 2a 2a 20 65 78 65 63 75 74 65 20 6d 61 6c o.** execute mal
11670 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 icious statement
11680 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 s that damage th
11690 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 e database. For
116a0 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 .** example, an
116b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 application may
116c0 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 allow a user to
116d0 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a enter arbitrary.
116e0 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 ** SQL queries f
116f0 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 or evaluation by
11700 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 a database. Bu
11710 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f t the applicatio
11720 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 n does.** not wa
11730 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 nt the user to b
11740 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 e able to make a
11750 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 rbitrary changes
11760 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 to the.** datab
11770 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 ase. An authori
11780 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 zer could then b
11790 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 e put in place w
117a0 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 hile the.** user
117b0 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 -entered SQL is
117c0 62 65 69 6e 67 20 70 72 65 70 61 72 65 64 20 74 being prepared t
117d0 68 61 74 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 hat disallows ev
117e0 65 72 79 74 68 69 6e 67 0a 2a 2a 20 65 78 63 65 erything.** exce
117f0 70 74 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d pt SELECT statem
11800 65 6e 74 73 2e 20 20 0a 2a 2a 0a 2a 2a 20 4f 6e ents. .**.** On
11810 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 ly a single auth
11820 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e orizer can be in
11830 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 place on a data
11840 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
11850 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 ** at a time. E
11860 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 ach call to sqli
11870 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
11880 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 er overrides the
11890 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c .** previous cal
118a0 6c 2e 20 20 44 69 73 61 62 6c 65 20 74 68 65 20 l. Disable the
118b0 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e authorizer by in
118c0 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 stalling a NULL
118d0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 callback..** The
118e0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 authorizer is d
118f0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 isabled by defau
11900 6c 74 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 lt..**.** Note t
11910 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a hat the authoriz
11920 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 er callback is i
11930 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 nvoked only duri
11940 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ng .** [sqlite3_
11950 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 prepare()] or it
11960 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 s variants. Aut
11970 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f horization is no
11980 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 t.** performed d
11990 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 uring statement
119a0 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 evaluation in [s
119b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a qlite3_step()]..
119c0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
119d0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 31 7d :.**.** {F12501}
119e0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 The [sqlite3_se
119f0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 44 2c 2e t_authorizer(D,.
11a00 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 ..)] interface r
11a10 65 67 69 73 74 65 72 73 20 61 0a 2a 2a 20 20 20 egisters a.**
11a20 20 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65 authorize
11a30 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 r callback with
11a40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
11a50 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 ion D..**.** {F1
11a60 32 35 30 32 7d 20 54 68 65 20 61 75 74 68 6f 72 2502} The author
11a70 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 izer callback is
11a80 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 invoked as SQL
11a90 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a statements are.*
11aa0 2a 20 20 20 20 20 20 20 20 20 20 62 65 69 6e 67 * being
11ab0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 0a 2a 2a 20 compiled.**.**
11ac0 7b 46 31 32 35 30 33 7d 20 49 66 20 74 68 65 20 {F12503} If the
11ad0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
11ae0 61 63 6b 20 72 65 74 75 72 6e 73 20 61 6e 79 20 ack returns any
11af0 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e value other than
11b00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 .** [SQ
11b10 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 LITE_IGNORE], [S
11b20 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 QLITE_OK], or [S
11b30 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 68 65 6e QLITE_DENY] then
11b40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
11b50 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
11b60 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 e_v2()] or equiv
11b70 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 alent call that
11b80 63 61 75 73 65 64 0a 2a 2a 20 20 20 20 20 20 20 caused.**
11b90 20 20 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 the authorize
11ba0 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75 r callback to ru
11bb0 6e 20 73 68 61 6c 6c 20 66 61 69 6c 20 77 69 74 n shall fail wit
11bc0 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 h an.**
11bd0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
11be0 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 error code and a
11bf0 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 n appropriate er
11c00 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a ror message..**.
11c10 2a 2a 20 7b 46 31 32 35 30 34 7d 20 57 68 65 6e ** {F12504} When
11c20 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
11c30 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
11c40 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 [SQLITE_OK], th
11c50 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 20 e operation.**
11c60 20 20 20 20 20 20 20 20 64 65 73 63 72 69 62 65 describe
11c70 64 20 69 73 20 63 6f 64 65 64 20 6e 6f 72 6d 61 d is coded norma
11c80 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 lly..**.** {F125
11c90 30 35 7d 20 57 68 65 6e 20 74 68 65 20 61 75 74 05} When the aut
11ca0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
11cb0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
11cc0 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 20 _DENY], the.**
11cd0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
11ce0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
11cf0 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c r equivalent cal
11d00 6c 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 l that caused th
11d10 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 e.** au
11d20 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
11d30 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20 66 k to run shall f
11d40 61 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ail.**
11d50 77 69 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f with an [SQLITE_
11d60 45 52 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f 64 ERROR] error cod
11d70 65 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d e and an error m
11d80 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 essage.**
11d90 20 20 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 explaining th
11da0 61 74 20 61 63 63 65 73 73 20 69 73 20 64 65 6e at access is den
11db0 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 ied..**.** {F125
11dc0 30 36 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 06} If the autho
11dd0 72 69 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20 rizer code (the
11de0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 2nd parameter to
11df0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 0a the authorizer.
11e00 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c ** call
11e10 62 61 63 6b 29 20 69 73 20 5b 53 51 4c 49 54 45 back) is [SQLITE
11e20 5f 52 45 41 44 5d 20 61 6e 64 20 74 68 65 20 61 _READ] and the a
11e30 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
11e40 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 ck returns.**
11e50 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 [SQLITE_I
11e60 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 GNORE] then the
11e70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
11e80 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 nt is constructe
11e90 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 d to.**
11ea0 20 69 6e 73 65 72 74 20 61 20 4e 55 4c 4c 20 76 insert a NULL v
11eb0 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 alue in place of
11ec0 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d the table colum
11ed0 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 n that would hav
11ee0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 e.** be
11ef0 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 en read if [SQLI
11f00 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 TE_OK] had been
11f10 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
11f20 7b 46 31 32 35 30 37 7d 20 49 66 20 74 68 65 20 {F12507} If the
11f30 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 authorizer code
11f40 28 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 (the 2nd paramet
11f50 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 er to the author
11f60 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 izer.**
11f70 20 63 61 6c 6c 62 61 63 6b 29 20 69 73 20 61 6e callback) is an
11f80 79 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 ything other tha
11f90 6e 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 2c n [SQLITE_READ],
11fa0 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 then.**
11fb0 20 20 61 20 72 65 74 75 72 6e 20 6f 66 20 5b 53 a return of [S
11fc0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 68 61 QLITE_IGNORE] ha
11fd0 73 20 74 68 65 20 73 61 6d 65 20 65 66 66 65 63 s the same effec
11fe0 74 20 61 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e t as [SQLITE_DEN
11ff0 59 5d 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 Y]. .**.** {F125
12000 31 30 7d 20 54 68 65 20 66 69 72 73 74 20 70 61 10} The first pa
12010 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 rameter to the a
12020 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
12030 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a ck is a copy of.
12040 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
12050 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
12060 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
12070 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 set_authorizer()
12080 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a ] interface..**.
12090 2a 2a 20 7b 46 31 32 35 31 31 7d 20 54 68 65 20 ** {F12511} The
120a0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
120b0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
120c0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 0a is an integer .
120d0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c ** [SQL
120e0 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f ITE_COPY | actio
120f0 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 n code] that spe
12100 63 69 66 69 65 73 20 74 68 65 20 70 61 72 74 69 cifies the parti
12110 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20 cular action.**
12120 20 20 20 20 20 20 20 20 20 74 6f 20 62 65 20 61 to be a
12130 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a uthorized..**.**
12140 20 7b 46 31 32 35 31 32 7d 20 54 68 65 20 74 68 {F12512} The th
12150 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 ird through sixt
12160 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 h parameters to
12170 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 the callback are
12180 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 .** zer
12190 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 o-terminated str
121a0 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 ings that contai
121b0 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 n .** a
121c0 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c dditional detail
121d0 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 s about the acti
121e0 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 on to be authori
121f0 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 zed..**.** {F125
12200 32 30 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20} Each call to
12210 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
12220 74 68 6f 72 69 7a 65 72 28 29 5d 20 6f 76 65 72 thorizer()] over
12230 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 rides the.**
12240 20 20 20 20 20 20 61 6e 79 20 70 72 65 76 69 6f any previo
12250 75 73 6c 79 20 69 6e 73 74 61 6c 6c 65 64 20 61 usly installed a
12260 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a uthorizer..**.**
12270 20 7b 46 31 32 35 32 31 7d 20 41 20 4e 55 4c 4c {F12521} A NULL
12280 20 61 75 74 68 6f 72 69 7a 65 72 20 6d 65 61 6e authorizer mean
12290 73 20 74 68 61 74 20 6e 6f 20 61 75 74 68 6f 72 s that no author
122a0 69 7a 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 ization.**
122b0 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 callback is
122c0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b invoked..**.** {
122d0 46 31 32 35 32 32 7d 20 54 68 65 20 64 65 66 61 F12522} The defa
122e0 75 6c 74 20 61 75 74 68 6f 72 69 7a 65 72 20 69 ult authorizer i
122f0 73 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 s NULL..*/.int s
12300 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
12310 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 rizer(. sqlite3
12320 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 *,. int (*xAuth
12330 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 )(void*,int,cons
12340 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 t char*,const ch
12350 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c ar*,const char*,
12360 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 const char*),.
12370 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a void *pUserData.
12380 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
12390 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 EF: Authorizer R
123a0 65 74 75 72 6e 20 43 6f 64 65 73 20 7b 46 31 32 eturn Codes {F12
123b0 35 39 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 590}.**.** The [
123c0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
123d0 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 orizer | authori
123e0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e zer callback fun
123f0 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 ction] must.** r
12400 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 eturn either [SQ
12410 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 LITE_OK] or one
12420 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e of these two con
12430 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a stants in order.
12440 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c ** to signal SQL
12450 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e ite whether or n
12460 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 ot the action is
12470 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 permitted. See
12480 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
12490 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 _set_authorizer
124a0 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 | authorizer doc
124b0 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 umentation] for
124c0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e additional.** in
124d0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 formation..*/.#d
124e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e efine SQLITE_DEN
124f0 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 Y 1 /* Abort
12500 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
12510 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 nt with an error
12520 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
12530 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a TE_IGNORE 2 /*
12540 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 Don't allow acc
12550 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 ess, but don't g
12560 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 enerate an error
12570 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
12580 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 REF: Authorizer
12590 41 63 74 69 6f 6e 20 43 6f 64 65 73 20 7b 46 31 Action Codes {F1
125a0 32 35 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 2550}.**.** The
125b0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 [sqlite3_set_aut
125c0 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 horizer()] inter
125d0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 face registers a
125e0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
125f0 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e on.** that is in
12600 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 voked to authori
12610 7a 65 72 20 63 65 72 74 61 69 6e 20 53 51 4c 20 zer certain SQL
12620 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e statement action
12630 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e s. The.** secon
12640 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 d parameter to t
12650 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 he callback is a
12660 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 n integer code t
12670 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a hat specifies.**
12680 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 what action is
12690 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 being authorized
126a0 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 . These are the
126b0 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 integer action
126c0 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 codes that.** th
126d0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
126e0 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 lback may be pas
126f0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 sed..**.** These
12700 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c action code val
12710 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 ues signify what
12720 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 kind of operati
12730 6f 6e 20 69 73 20 74 6f 20 62 65 20 0a 2a 2a 20 on is to be .**
12740 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 authorized. The
12750 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 3rd and 4th par
12760 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 ameters to the a
12770 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 uthorization.**
12780 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
12790 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 n will be parame
127a0 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 ters or NULL dep
127b0 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 ending on which
127c0 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 of these.** code
127d0 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 s is used as the
127e0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
127f0 72 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 61 r. The 5th para
12800 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 meter to the.**
12810 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
12820 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 ack is the name
12830 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 of the database
12840 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c ("main", "temp",
12850 20 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 .** etc.) if ap
12860 70 6c 69 63 61 62 6c 65 2e 20 20 54 68 65 20 36 plicable. The 6
12870 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
12880 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
12890 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 allback.** is th
128a0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e e name of the in
128b0 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 ner-most trigger
128c0 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 or view that is
128d0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 responsible for
128e0 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 .** the access a
128f0 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 ttempt or NULL i
12900 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 f this access at
12910 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c tempt is directl
12920 79 20 66 72 6f 6d 20 0a 2a 2a 20 74 6f 70 2d 6c y from .** top-l
12930 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a evel SQL code..*
12940 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
12950 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 31 7d 20 .**.** {F12551}
12960 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
12970 65 74 65 72 20 74 6f 20 61 6e 20 0a 2a 2a 20 20 eter to an .**
12980 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
12990 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 _set_authorizer
129a0 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c | authorizer cal
129b0 6c 62 61 63 6b 20 69 73 20 61 6c 77 61 79 73 20 lback is always
129c0 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 an integer.**
129d0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 [SQLITE_C
129e0 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 OPY | authorizer
129f0 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 code] that spec
12a00 69 66 69 65 73 20 77 68 61 74 20 61 63 74 69 6f ifies what actio
12a10 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 n.** is
12a20 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 being authorize
12a30 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 32 d..**.** {F12552
12a40 7d 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 } The 3rd and 4t
12a50 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 h parameters to
12a60 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 the .**
12a70 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
12a80 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f thorizer | autho
12a90 72 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 rization callbac
12aa0 6b 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 20 k function].**
12ab0 20 20 20 20 20 20 20 20 77 69 6c 6c 20 62 65 20 will be
12ac0 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 parameters or NU
12ad0 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 LL depending on
12ae0 77 68 69 63 68 20 0a 2a 2a 20 20 20 20 20 20 20 which .**
12af0 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 [SQLITE_COPY
12b00 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 | authorizer cod
12b10 65 5d 20 69 73 20 75 73 65 64 20 61 73 20 74 68 e] is used as th
12b20 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
12b30 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 er..**.** {F1255
12b40 33 7d 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 3} The 5th param
12b50 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 eter to the.**
12b60 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
12b70 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 _set_authorizer
12b80 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c | authorizer cal
12b90 6c 62 61 63 6b 5d 20 69 73 20 74 68 65 20 6e 61 lback] is the na
12ba0 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f me.** o
12bb0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 f the database (
12bc0 65 78 61 6d 70 6c 65 3a 20 22 6d 61 69 6e 22 2c example: "main",
12bd0 20 22 74 65 6d 70 22 2c 20 65 74 63 2e 29 20 69 "temp", etc.) i
12be0 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 0a 2a 2a f applicable..**
12bf0 0a 2a 2a 20 7b 46 31 32 35 35 34 7d 20 54 68 65 .** {F12554} The
12c00 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6th parameter t
12c10 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 o the.**
12c20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 [sqlite3_set_a
12c30 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 uthorizer | auth
12c40 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d orizer callback]
12c50 20 69 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 is the name.**
12c60 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 of the
12c70 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 inner-most trigg
12c80 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 er or view that
12c90 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 is responsible f
12ca0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 or.** t
12cb0 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 he access attemp
12cc0 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 t or NULL if thi
12cd0 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 s access attempt
12ce0 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f is directly fro
12cf0 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 m .** t
12d00 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 op-level SQL cod
12d10 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a e..*/./*********
12d20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
12d30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
12d40 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a ** 3rd *********
12d50 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a *** 4th ********
12d60 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ***/.#define SQL
12d70 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 ITE_CREATE_INDEX
12d80 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 1 /*
12d90 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 Index Name
12da0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
12db0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
12dc0 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 TE_CREATE_TABLE
12dd0 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 2 /*
12de0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
12df0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
12e00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
12e10 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e E_CREATE_TEMP_IN
12e20 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 DEX 3 /* I
12e30 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 ndex Name T
12e40 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
12e50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
12e60 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 _CREATE_TEMP_TAB
12e70 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 LE 4 /* Ta
12e80 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
12e90 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
12ea0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
12eb0 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 CREATE_TEMP_TRIG
12ec0 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 GER 5 /* Tri
12ed0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 gger Name Tab
12ee0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
12ef0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
12f00 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 REATE_TEMP_VIEW
12f10 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 6 /* View
12f20 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c Name NULL
12f30 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
12f40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
12f50 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 EATE_TRIGGER
12f60 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 7 /* Trigg
12f70 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 er Name Table
12f80 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
12f90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
12fa0 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 ATE_VIEW
12fb0 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 8 /* View N
12fc0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 ame NULL
12fd0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
12fe0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 fine SQLITE_DELE
12ff0 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TE
13000 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 9 /* Table N
13010 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
13020 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
13030 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
13040 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 INDEX
13050 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 10 /* Index Na
13060 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 me Table Na
13070 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
13080 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
13090 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 ABLE 1
130a0 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 1 /* Table Nam
130b0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
130c0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
130d0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 e SQLITE_DROP_TE
130e0 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 MP_INDEX 12
130f0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 /* Index Name
13100 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 Table Name
13110 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
13120 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d SQLITE_DROP_TEM
13130 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 P_TABLE 13
13140 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
13150 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
13160 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
13170 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 SQLITE_DROP_TEMP
13180 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 _TRIGGER 14
13190 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 /* Trigger Name
131a0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
131b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
131c0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f QLITE_DROP_TEMP_
131d0 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 VIEW 15
131e0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 /* View Name
131f0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
13200 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
13210 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 LITE_DROP_TRIGGE
13220 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f R 16 /
13230 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 * Trigger Name
13240 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
13250 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
13260 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 ITE_DROP_VIEW
13270 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 17 /*
13280 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 View Name
13290 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
132a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
132b0 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 TE_INSERT
132c0 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 18 /*
132d0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
132e0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
132f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
13300 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 E_PRAGMA
13310 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 19 /* P
13320 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 ragma Name 1
13330 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a st arg or NULL *
13340 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
13350 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 _READ
13360 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 20 /* Ta
13370 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f ble Name Co
13380 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f lumn Name */
13390 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
133a0 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 SELECT
133b0 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 21 /* NUL
133c0 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c L NUL
133d0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
133e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
133f0 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 RANSACTION
13400 20 20 20 20 32 32 20 20 20 2f 2a 20 4e 55 4c 4c 22 /* NULL
13410 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c NULL
13420 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
13430 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 define SQLITE_UP
13440 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 DATE
13450 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 23 /* Table
13460 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d Name Colum
13470 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 n Name */.#d
13480 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 efine SQLITE_ATT
13490 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 ACH
134a0 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 24 /* Filena
134b0 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 me NULL
134c0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
134d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 fine SQLITE_DETA
134e0 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 CH
134f0 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 25 /* Databas
13500 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 e Name NULL
13510 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
13520 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 ine SQLITE_ALTER
13530 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 _TABLE
13540 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 26 /* Database
13550 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 Name Table Na
13560 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
13570 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 ne SQLITE_REINDE
13580 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 X 2
13590 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 7 /* Index Nam
135a0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
135b0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
135c0 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 e SQLITE_ANALYZE
135d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 28
135e0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
135f0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
13600 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
13610 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 SQLITE_CREATE_V
13620 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 TABLE 29
13630 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
13640 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 Module Name
13650 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
13660 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 SQLITE_DROP_VTAB
13670 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20 LE 30
13680 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
13690 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 Module Name
136a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
136b0 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 QLITE_FUNCTION
136c0 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 31
136d0 2f 2a 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 /* Function Name
136e0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
136f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
13700 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 LITE_COPY
13710 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 0 /
13720 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 * No longer used
13730 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
13740 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 REF: Tracing And
13750 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 Profiling Funct
13760 69 6f 6e 73 20 7b 46 31 32 32 38 30 7d 0a 2a 2a ions {F12280}.**
13770 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
13780 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c es register call
13790 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 back functions t
137a0 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 hat can be used
137b0 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 for.** tracing a
137c0 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 nd profiling the
137d0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 execution of SQ
137e0 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a L statements..**
137f0 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b .** The callback
13800 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 function regist
13810 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f ered by sqlite3_
13820 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b trace() is invok
13830 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 ed at.** various
13840 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 times when an S
13850 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 QL statement is
13860 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 being run by [sq
13870 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a lite3_step()]..*
13880 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 * The callback r
13890 65 74 75 72 6e 73 20 61 20 55 54 46 2d 38 20 72 eturns a UTF-8 r
138a0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 endering of the
138b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 SQL statement te
138c0 78 74 0a 2a 2a 20 61 73 20 74 68 65 20 73 74 61 xt.** as the sta
138d0 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 tement first beg
138e0 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 20 20 ins executing.
138f0 41 64 64 69 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 Additional callb
13900 61 63 6b 73 20 6f 63 63 75 72 0a 2a 2a 20 61 73 acks occur.** as
13910 20 65 61 63 68 20 74 72 69 67 67 65 72 73 75 62 each triggersub
13920 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 program is enter
13930 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 ed. The callbac
13940 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a ks for triggers.
13950 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 ** contain a UTF
13960 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 -8 SQL comment t
13970 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 hat identifies t
13980 68 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 0a he trigger..** .
13990 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 ** The callback
139a0 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 function registe
139b0 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 red by sqlite3_p
139c0 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f rofile() is invo
139d0 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 ked.** as each S
139e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e QL statement fin
139f0 69 73 68 65 73 2e 20 20 54 68 65 20 70 72 6f 66 ishes. The prof
13a00 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e ile callback con
13a10 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 tains.** the ori
13a20 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 ginal statement
13a30 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 text and an esti
13a40 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f mate of wall-clo
13a50 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f ck time.** of ho
13a60 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 w long that stat
13a70 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 ement took to ru
13a80 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c n..**.** The sql
13a90 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 41 ite3_profile() A
13aa0 50 49 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 PI is currently
13ab0 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 considered exper
13ac0 69 6d 65 6e 74 61 6c 20 61 6e 64 0a 2a 2a 20 69 imental and.** i
13ad0 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 s subject to cha
13ae0 6e 67 65 20 6f 72 20 72 65 6d 6f 76 61 6c 20 69 nge or removal i
13af0 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 n a future relea
13b00 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 72 se..**.** The tr
13b10 69 67 67 65 72 20 72 65 70 6f 72 74 69 6e 67 20 igger reporting
13b20 66 65 61 74 75 72 65 20 6f 66 20 74 68 65 20 74 feature of the t
13b30 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 race callback is
13b40 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 65 considered.** e
13b50 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 xperimental and
13b60 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 is subject to ch
13b70 61 6e 67 65 20 6f 72 20 72 65 6d 6f 76 61 6c 20 ange or removal
13b80 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
13b90 65 73 2e 0a 2a 2a 20 46 75 74 75 72 65 20 76 65 es..** Future ve
13ba0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
13bb0 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 might also add
13bc0 6e 65 77 20 74 72 61 63 65 20 63 61 6c 6c 62 61 new trace callba
13bd0 63 6b 20 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f ck .** invocatio
13be0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 ns..**.** INVARI
13bf0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 ANTS:.**.** {F12
13c00 32 38 31 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 281} The callbac
13c10 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 k function regis
13c20 74 65 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65 tered by [sqlite
13c30 33 5f 74 72 61 63 65 28 29 5d 20 69 73 0a 2a 2a 3_trace()] is.**
13c40 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 65 76 whenev
13c50 65 72 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d er an SQL statem
13c60 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 ent first begins
13c70 20 74 6f 20 65 78 65 63 75 74 65 20 61 6e 64 0a to execute and.
13c80 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e ** when
13c90 65 76 65 72 20 61 20 74 72 69 67 67 65 72 20 73 ever a trigger s
13ca0 75 62 70 72 6f 67 72 61 6d 20 66 69 72 73 74 20 ubprogram first
13cb0 62 65 67 69 6e 73 20 74 6f 20 72 75 6e 2e 0a 2a begins to run..*
13cc0 2a 0a 2a 2a 20 7b 46 31 32 32 38 32 7d 20 45 61 *.** {F12282} Ea
13cd0 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 ch call to [sqli
13ce0 74 65 33 5f 74 72 61 63 65 28 29 5d 20 6f 76 65 te3_trace()] ove
13cf0 72 72 69 64 65 73 20 74 68 65 20 70 72 65 76 69 rrides the previ
13d00 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 ously.**
13d10 20 20 72 65 67 69 73 74 65 72 65 64 20 74 72 61 registered tra
13d20 63 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a ce callback..**.
13d30 2a 2a 20 7b 46 31 32 32 38 33 7d 20 41 20 4e 55 ** {F12283} A NU
13d40 4c 4c 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 LL trace callbac
13d50 6b 20 64 69 73 61 62 6c 65 73 20 74 72 61 63 69 k disables traci
13d60 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 ng..**.** {F1228
13d70 34 7d 20 54 68 65 20 66 69 72 73 74 20 61 72 67 4} The first arg
13d80 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 ument to the tra
13d90 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 ce callback is a
13da0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 copy of.**
13db0 20 20 20 20 20 74 68 65 20 70 6f 69 6e 74 65 72 the pointer
13dc0 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20 33 which was the 3
13dd0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b rd argument to [
13de0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d sqlite3_trace()]
13df0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 35 7d ..**.** {F12285}
13e00 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 The second argu
13e10 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 ment to the trac
13e20 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a e callback is a.
13e30 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f ** zero
13e40 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 38 -terminated UTF8
13e50 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 string containi
13e60 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 ng the original
13e70 74 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 text.**
13e80 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 of the SQL stat
13e90 65 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73 20 ement as it was
13ea0 70 61 73 73 65 64 20 69 6e 74 6f 20 5b 73 71 6c passed into [sql
13eb0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
13ec0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f )].** o
13ed0 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 r the equivalent
13ee0 2c 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d , or an SQL comm
13ef0 65 6e 74 20 69 6e 64 69 63 61 74 69 6e 67 20 74 ent indicating t
13f00 68 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 he beginning.**
13f10 20 20 20 20 20 20 20 20 20 6f 66 20 61 20 74 72 of a tr
13f20 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d igger subprogram
13f30 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 37 7d ..**.** {F12287}
13f40 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 The callback fu
13f50 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 nction registere
13f60 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 d by [sqlite3_pr
13f70 6f 66 69 6c 65 28 29 5d 20 69 73 20 69 6e 76 6f ofile()] is invo
13f80 6b 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ked.**
13f90 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 as each SQL stat
13fa0 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a ement finishes..
13fb0 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 38 7d 20 54 **.** {F12288} T
13fc0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
13fd0 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c er to the profil
13fe0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 e callback is a
13ff0 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 copy of.**
14000 20 20 20 20 74 68 65 20 33 72 64 20 70 61 72 61 the 3rd para
14010 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 meter to [sqlite
14020 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2e 0a 2a 2a 3_profile()]..**
14030 0a 2a 2a 20 7b 46 31 32 32 38 39 7d 20 54 68 65 .** {F12289} The
14040 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
14050 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 r to the profile
14060 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a callback is a.*
14070 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d * zero-
14080 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 terminated UTF-8
14090 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 6f 6e string that con
140a0 74 61 69 6e 73 20 74 68 65 20 63 6f 6d 70 6c 65 tains the comple
140b0 74 65 20 74 65 78 74 20 6f 66 0a 2a 2a 20 20 20 te text of.**
140c0 20 20 20 20 20 20 20 74 68 65 20 53 51 4c 20 73 the SQL s
140d0 74 61 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77 tatement as it w
140e0 61 73 20 70 72 6f 63 65 73 73 65 64 20 62 79 20 as processed by
140f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
14100 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 _v2()].**
14110 20 20 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 or the equiva
14120 6c 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 lent..**.** {F12
14130 32 39 30 7d 20 54 68 65 20 74 68 69 72 64 20 70 290} The third p
14140 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
14150 70 72 6f 66 69 6c 65 20 20 63 61 6c 6c 62 61 63 profile callbac
14160 6b 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 k is an estimate
14170 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 .** of
14180 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 the number of na
14190 6e 6f 73 65 63 6f 6e 64 73 20 6f 66 20 77 61 6c noseconds of wal
141a0 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 20 72 65 71 l-clock time req
141b0 75 69 72 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 uired to.**
141c0 20 20 20 20 20 72 75 6e 20 74 68 65 20 53 51 4c run the SQL
141d0 20 73 74 61 74 65 6d 65 6e 74 20 66 72 6f 6d 20 statement from
141e0 73 74 61 72 74 20 74 6f 20 66 69 6e 69 73 68 2e start to finish.
141f0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 .*/.void *sqlite
14200 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 3_trace(sqlite3*
14210 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 , void(*xTrace)(
14220 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 void*,const char
14230 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 *), void*);.void
14240 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c *sqlite3_profil
14250 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 e(sqlite3*,. v
14260 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 oid(*xProfile)(v
14270 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a oid*,const char*
14280 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 ,sqlite3_uint64)
14290 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a , void*);../*.**
142a0 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 CAPI3REF: Query
142b0 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 Progress Callba
142c0 63 6b 73 20 7b 46 31 32 39 31 30 7d 0a 2a 2a 0a cks {F12910}.**.
142d0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
142e0 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63 61 6c configures a cal
142f0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d lback function -
14300 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73 the.** progress
14310 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 callback - that
14320 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 is invoked peri
14330 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 odically during
14340 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 long.** running
14350 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
14360 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 3_exec()], [sqli
14370 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a te3_step()] and.
14380 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f ** [sqlite3_get_
14390 74 61 62 6c 65 28 29 5d 2e 20 20 20 41 6e 20 65 table()]. An e
143a0 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 xample use for t
143b0 68 69 73 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 his .** interfac
143c0 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 e is to keep a G
143d0 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e UI updated durin
143e0 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e g a large query.
143f0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 70 72 .**.** If the pr
14400 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 ogress callback
14410 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f returns non-zero
14420 2c 20 74 68 65 20 6f 70 65 72 74 69 6f 6e 20 69 , the opertion i
14430 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 s.** interrupted
14440 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 . This feature
14450 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 can be used to i
14460 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 mplement a.** "C
14470 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e ancel" button on
14480 20 61 20 47 55 49 20 64 69 61 6c 6f 67 20 62 6f a GUI dialog bo
14490 78 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 x..**.** INVARIA
144a0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 NTS:.**.** {F129
144b0 31 31 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 11} The callback
144c0 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 function regist
144d0 65 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 ered by [sqlite3
144e0 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 _progress_handle
144f0 72 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 r()].**
14500 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 is invoked peri
14510 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 odically during
14520 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c long running cal
14530 6c 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 ls to.**
14540 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 [sqlite3_step(
14550 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 )]..**.** {F1291
14560 32 7d 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 2} The progress
14570 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
14580 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 76 65 ked once for eve
14590 72 79 20 4e 20 76 69 72 74 75 61 6c 0a 2a 2a 20 ry N virtual.**
145a0 20 20 20 20 20 20 20 20 20 6d 61 63 68 69 6e 65 machine
145b0 20 6f 70 63 6f 64 65 73 2c 20 77 68 65 72 65 20 opcodes, where
145c0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 N is the second
145d0 61 72 67 75 6d 65 6e 74 20 74 6f 20 0a 2a 2a 20 argument to .**
145e0 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 the [sq
145f0 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 lite3_progress_h
14600 61 6e 64 6c 65 72 28 29 5d 20 63 61 6c 6c 20 74 andler()] call t
14610 68 61 74 20 72 65 67 69 73 74 65 72 65 64 0a 2a hat registered.*
14620 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63 * the c
14630 61 6c 6c 62 61 63 6b 2e 20 20 3c 74 6f 64 6f 3e allback. <todo>
14640 57 68 61 74 20 69 66 20 4e 20 69 73 20 6c 65 73 What if N is les
14650 73 20 74 68 61 6e 20 31 3f 3c 2f 74 6f 64 6f 3e s than 1?</todo>
14660 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 33 7d 20 .**.** {F12913}
14670 54 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c The progress cal
14680 6c 62 61 63 6b 20 69 74 73 65 6c 66 20 69 73 20 lback itself is
14690 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 identified by th
146a0 65 20 74 68 69 72 64 0a 2a 2a 20 20 20 20 20 20 e third.**
146b0 20 20 20 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 argument to
146c0 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 [sqlite3_progres
146d0 73 5f 68 61 6e 64 6c 65 72 28 29 5d 2e 0a 2a 2a s_handler()]..**
146e0 0a 2a 2a 20 7b 46 31 32 39 31 34 7d 20 54 68 65 .** {F12914} The
146f0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 fourth argument
14700 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 [sqlite3_progre
14710 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 20 69 73 ss_handler()] is
14720 20 61 0a 2a 2a 2a 20 20 20 20 20 20 20 20 20 76 a.*** v
14730 6f 69 64 20 70 6f 69 6e 74 65 72 20 70 61 73 73 oid pointer pass
14740 65 64 20 74 6f 20 74 68 65 20 70 72 6f 67 72 65 ed to the progre
14750 73 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 ss callback.**
14760 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e function
14770 20 65 61 63 68 20 74 69 6d 65 20 69 74 20 69 73 each time it is
14780 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 invoked..**.**
14790 7b 46 31 32 39 31 35 7d 20 49 66 20 61 20 63 61 {F12915} If a ca
147a0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ll to [sqlite3_s
147b0 74 65 70 28 29 5d 20 72 65 73 75 6c 74 73 20 69 tep()] results i
147c0 6e 20 66 65 77 65 72 20 74 68 61 6e 0a 2a 2a 20 n fewer than.**
147d0 20 20 20 20 20 20 20 20 20 4e 20 6f 70 63 6f 64 N opcod
147e0 65 73 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 es being execute
147f0 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 d,.** t
14800 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 hen the progress
14810 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 65 76 callback is nev
14820 65 72 20 69 6e 76 6f 6b 65 64 2e 20 7b 45 4e 44 er invoked. {END
14830 7d 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 32 39 31 36 }.** .** {F12916
14840 7d 20 45 76 65 72 79 20 63 61 6c 6c 20 74 6f 20 } Every call to
14850 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 [sqlite3_progres
14860 73 5f 68 61 6e 64 6c 65 72 28 29 5d 0a 2a 2a 20 s_handler()].**
14870 20 20 20 20 20 20 20 20 20 6f 76 65 72 77 72 69 overwri
14880 74 65 73 20 61 6e 79 20 70 72 65 76 69 6f 75 73 tes any previous
14890 6c 79 20 72 65 67 69 73 74 65 72 65 20 70 72 6f ly registere pro
148a0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a gress handler..*
148b0 2a 0a 2a 2a 20 7b 46 31 32 39 31 37 7d 20 49 66 *.** {F12917} If
148c0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 the progress ha
148d0 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 ndler callback i
148e0 73 20 4e 55 4c 4c 20 74 68 65 6e 20 6e 6f 20 70 s NULL then no p
148f0 72 6f 67 72 65 73 73 0a 2a 2a 20 20 20 20 20 20 rogress.**
14900 20 20 20 20 68 61 6e 64 6c 65 72 20 69 73 20 69 handler is i
14910 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 nvoked..**.** {F
14920 31 32 39 31 38 7d 20 49 66 20 74 68 65 20 70 72 12918} If the pr
14930 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 ogress callback
14940 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 returns a result
14950 20 6f 74 68 65 72 20 74 68 61 6e 20 30 2c 20 74 other than 0, t
14960 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 hen.**
14970 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 the behavior is
14980 61 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 69 6e a if [sqlite3_in
14990 74 65 72 72 75 70 74 28 29 5d 20 68 61 64 20 62 terrupt()] had b
149a0 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 een called..*/.v
149b0 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 oid sqlite3_prog
149c0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c ress_handler(sql
149d0 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 ite3*, int, int(
149e0 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a *)(void*), void*
149f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
14a00 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 EF: Opening A Ne
14a10 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 w Database Conne
14a20 63 74 69 6f 6e 20 7b 46 31 32 37 30 30 7d 0a 2a ction {F12700}.*
14a30 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
14a40 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 nes open an SQLi
14a50 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 te database file
14a60 20 77 68 6f 73 65 20 6e 61 6d 65 0a 2a 2a 20 69 whose name.** i
14a70 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 66 s given by the f
14a80 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 ilename argument
14a90 2e 0a 2a 2a 20 54 68 65 20 66 69 6c 65 6e 61 6d ..** The filenam
14aa0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e e argument is in
14ab0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 terpreted as UTF
14ac0 2d 38 0a 2a 2a 20 66 6f 72 20 5b 73 71 6c 69 74 -8.** for [sqlit
14ad0 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b e3_open()] and [
14ae0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
14af0 29 5d 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 )] and as UTF-16
14b00 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 .** in the nativ
14b10 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 e byte order for
14b20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
14b30 28 29 5d 2e 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 ()]..** An [sqli
14b40 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20 69 73 20 te3*] handle is
14b50 75 73 75 61 6c 6c 79 20 72 65 74 75 72 6e 65 64 usually returned
14b60 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 0a in *ppDb, even.
14b70 2a 2a 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f ** if an error o
14b80 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 ccurs. The only
14b90 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 69 66 exception is if
14ba0 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c SQLite is unabl
14bb0 65 0a 2a 2a 20 74 6f 20 61 6c 6c 6f 63 61 74 65 e.** to allocate
14bc0 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 memory to hold
14bd0 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 the [sqlite3] ob
14be0 6a 65 63 74 2c 20 61 20 4e 55 4c 4c 20 77 69 6c ject, a NULL wil
14bf0 6c 0a 2a 2a 20 62 65 20 77 72 69 74 74 65 6e 20 l.** be written
14c00 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 into *ppDb inste
14c10 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 ad of a pointer
14c20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d to the [sqlite3]
14c30 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 49 66 20 74 object..** If t
14c40 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
14c50 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 pened (and/or cr
14c60 65 61 74 65 64 29 0a 2a 2a 20 73 75 63 63 65 73 eated).** succes
14c70 73 66 75 6c 6c 79 2c 20 74 68 65 6e 20 5b 53 51 sfully, then [SQ
14c80 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 LITE_OK] is retu
14c90 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 rned. Otherwise
14ca0 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 an.** error cod
14cb0 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 e is returned.
14cc0 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f The.** [sqlite3_
14cd0 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 errmsg()] or [sq
14ce0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 lite3_errmsg16()
14cf0 5d 20 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 ] routines can
14d00 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 be used to obtai
14d10 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 n.** an English
14d20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 language descrip
14d30 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f tion of the erro
14d40 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 r..**.** The def
14d50 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f ault encoding fo
14d60 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77 r the database w
14d70 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a ill be UTF-8 if.
14d80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ** [sqlite3_open
14d90 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
14da0 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73 20 63 61 open_v2()] is ca
14db0 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d lled and.** UTF-
14dc0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 16 in the native
14dd0 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 5b byte order if [
14de0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
14df0 5d 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a ] is used..**.**
14e00 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 Whether or not
14e10 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 an error occurs
14e20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 when it is opene
14e30 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 d, resources.**
14e40 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
14e50 74 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 the [sqlite3*] h
14e60 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 andle should be
14e70 72 65 6c 65 61 73 65 64 20 62 79 20 70 61 73 73 released by pass
14e80 69 6e 67 20 69 74 0a 2a 2a 20 74 6f 20 5b 73 71 ing it.** to [sq
14e90 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 lite3_close()] w
14ea0 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e hen it is no lon
14eb0 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a ger required..**
14ec0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 .** The [sqlite3
14ed0 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 _open_v2()] inte
14ee0 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 rface works like
14ef0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
14f00 5d 20 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 ] .** except tha
14f10 74 20 69 74 20 61 63 63 63 65 70 74 73 20 74 77 t it acccepts tw
14f20 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 o additional par
14f30 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 ameters for addi
14f40 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a tional control.*
14f50 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 * over the new d
14f60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
14f70 6f 6e 2e 20 20 54 68 65 20 66 6c 61 67 73 20 70 on. The flags p
14f80 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 0a arameter can be.
14f90 2a 2a 20 6f 6e 65 20 6f 66 3a 0a 2a 2a 0a 2a 2a ** one of:.**.**
14fa0 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b <ol>.** <li> [
14fb0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
14fc0 4f 4e 4c 59 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b ONLY].** <li> [
14fd0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
14fe0 57 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 WRITE].** <li>
14ff0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 [SQLITE_OPEN_REA
15000 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 DWRITE] | [SQLIT
15010 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 0a 2a E_OPEN_CREATE].*
15020 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 * </ol>.**.** Th
15030 65 20 66 69 72 73 74 20 76 61 6c 75 65 20 6f 70 e first value op
15040 65 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65 ens the database
15050 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 0a 2a 2a 20 read-only. .**
15060 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 If the database
15070 64 6f 65 73 20 6e 6f 74 20 70 72 65 76 69 6f 75 does not previou
15080 73 6c 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 sly exist, an er
15090 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e ror is returned.
150a0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 6f .** The second o
150b0 70 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 74 ption opens.** t
150c0 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 he database for
150d0 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 reading and writ
150e0 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c ing if possible,
150f0 20 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 or reading only
15100 20 69 66 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 if.** if the fi
15110 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 le is write prot
15120 65 63 74 65 64 2e 20 20 49 6e 20 65 69 74 68 65 ected. In eithe
15130 72 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 r case the datab
15140 61 73 65 0a 2a 2a 20 6d 75 73 74 20 61 6c 72 65 ase.** must alre
15150 61 64 79 20 65 78 69 73 74 20 6f 72 20 61 6e 20 ady exist or an
15160 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 error is returne
15170 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 6f 70 d. The third op
15180 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 74 68 tion.** opens th
15190 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 e database for r
151a0 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 eading and writi
151b0 6e 67 20 61 6e 64 20 63 72 65 61 74 65 73 20 69 ng and creates i
151c0 74 20 69 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20 t if it does.**
151d0 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 not already exis
151e0 74 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 t..** The third
151f0 6f 70 74 69 6f 6e 73 20 69 73 20 62 65 68 61 76 options is behav
15200 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 ior that is alwa
15210 79 73 20 75 73 65 64 20 66 6f 72 20 5b 73 71 6c ys used for [sql
15220 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 ite3_open()].**
15230 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 and [sqlite3_ope
15240 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 n16()]..**.** If
15250 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 the filename is
15260 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 ":memory:", the
15270 6e 20 61 6e 20 70 72 69 76 61 74 65 0a 2a 2a 20 n an private.**
15280 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 in-memory databa
15290 73 65 20 69 73 20 63 72 65 61 74 65 64 20 66 6f se is created fo
152a0 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e r the connection
152b0 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 . This in-memor
152c0 79 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 77 69 y.** database wi
152d0 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 20 74 ll vanish when t
152e0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
152f0 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 ection is closed
15300 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 . Future.** ver
15310 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 6d sion of SQLite m
15320 69 67 68 74 20 6d 61 6b 65 20 75 73 65 20 6f 66 ight make use of
15330 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 additional spec
15340 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a ial filenames.**
15350 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 that begin with
15360 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 the ":" charact
15370 65 72 2e 20 20 49 74 20 69 73 20 72 65 63 6f 6d er. It is recom
15380 6d 65 6e 64 65 64 20 74 68 61 74 20 0a 2a 2a 20 mended that .**
15390 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 when a database
153a0 66 69 6c 65 6e 61 6d 65 20 72 65 61 6c 6c 79 20 filename really
153b0 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a does begin with.
153c0 2a 2a 20 22 3a 22 20 74 68 61 74 20 79 6f 75 20 ** ":" that you
153d0 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e prefix the filen
153e0 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e ame with a pathn
153f0 61 6d 65 20 6c 69 6b 65 20 22 2e 2f 22 20 74 6f ame like "./" to
15400 0a 2a 2a 20 61 76 6f 69 64 20 61 6d 62 69 67 75 .** avoid ambigu
15410 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ity..**.** If th
15420 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e e filename is an
15430 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 empty string, t
15440 68 65 6e 20 61 20 70 72 69 76 61 74 65 20 74 65 hen a private te
15450 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 mporary.** on-di
15460 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c sk database will
15470 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 54 68 be created. Th
15480 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 is private datab
15490 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 ase will be.** a
154a0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c utomatically del
154b0 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 eted as soon as
154c0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
154d0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 nection is close
154e0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 d..**.** The fou
154f0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f rth parameter to
15500 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
15510 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f () is the name o
15520 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 f the.** [sqlite
15530 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 3_vfs] object th
15540 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f at defines the o
15550 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 perating system
15560 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 68 .** interface th
15570 61 74 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 at the new datab
15580 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 ase connection s
15590 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 66 20 74 hould use. If t
155a0 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 he.** fourth par
155b0 61 6d 65 74 65 72 20 69 73 20 61 20 4e 55 4c 4c ameter is a NULL
155c0 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 pointer then th
155d0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 e default [sqlit
155e0 65 33 5f 76 66 73 5d 0a 2a 2a 20 6f 62 6a 65 63 e3_vfs].** objec
155f0 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a t is used..**.**
15600 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 77 69 6e 64 <b>Note to wind
15610 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 ows users:</b>
15620 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 The encoding use
15630 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 d for the filena
15640 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f me argument.** o
15650 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 f [sqlite3_open(
15660 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
15670 6f 70 65 6e 5f 76 32 28 29 5d 20 6d 75 73 74 20 open_v2()] must
15680 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 be UTF-8, not wh
15690 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 atever.** codepa
156a0 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 ge is currently
156b0 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 defined. Filena
156c0 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 mes containing i
156d0 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 nternational.**
156e0 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 characters must
156f0 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 be converted to
15700 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 UTF-8 prior to p
15710 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f assing them into
15720 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 .** [sqlite3_ope
15730 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 n()] or [sqlite3
15740 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a _open_v2()]..**.
15750 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
15760 2a 0a 2a 2a 20 7b 46 31 32 37 30 31 7d 20 54 68 *.** {F12701} Th
15770 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 e [sqlite3_open(
15780 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
15790 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 n16()], and.**
157a0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
157b0 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 _open_v2()] inte
157c0 72 66 61 63 65 73 20 63 72 65 61 74 65 20 61 20 rfaces create a
157d0 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 new.**
157e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
157f0 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 tion] associated
15800 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 with.**
15810 20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 the database f
15820 69 6c 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 ile given in the
15830 69 72 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 ir first paramet
15840 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 er..**.** {F1270
15850 32 7d 20 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 2} The filename
15860 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 argument is inte
15870 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 rpreted as UTF-8
15880 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 .** for
15890 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
158a0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f ] and [sqlite3_o
158b0 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64 20 61 73 pen_v2()] and as
158c0 20 55 54 46 2d 31 36 0a 2a 2a 20 20 20 20 20 20 UTF-16.**
158d0 20 20 20 20 69 6e 20 74 68 65 20 6e 61 74 69 76 in the nativ
158e0 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 e byte order for
158f0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
15900 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 ()]..**.** {F127
15910 30 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 03} A successful
15920 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b invocation of [
15930 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
15940 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
15950 28 29 5d 2c 20 0a 2a 2a 20 20 20 20 20 20 20 20 ()], .**
15960 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 or [sqlite3_op
15970 65 6e 5f 76 32 28 29 5d 20 77 72 69 74 65 73 20 en_v2()] writes
15980 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e a pointer to a n
15990 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b ew.** [
159a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
159b0 69 6f 6e 5d 20 69 6e 74 6f 20 2a 70 70 44 62 2e ion] into *ppDb.
159c0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 34 7d 20 .**.** {F12704}
159d0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 The [sqlite3_ope
159e0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f n()], [sqlite3_o
159f0 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a pen16()], and.**
15a00 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
15a10 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e e3_open_v2()] in
15a20 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 terfaces return
15a30 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 75 70 6f 6e [SQLITE_OK] upon
15a40 20 73 75 63 63 65 73 73 2c 0a 2a 2a 20 20 20 20 success,.**
15a50 20 20 20 20 20 20 6f 72 20 61 6e 20 61 70 70 72 or an appr
15a60 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 opriate [error c
15a70 6f 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e ode] on failure.
15a80 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 36 7d 20 .**.** {F12706}
15a90 54 68 65 20 64 65 66 61 75 6c 74 20 74 65 78 74 The default text
15aa0 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 61 20 encoding for a
15ab0 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 72 65 new database cre
15ac0 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 ated using.**
15ad0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
15ae0 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 open()] or [sqli
15af0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 te3_open_v2()] w
15b00 69 6c 6c 20 62 65 20 55 54 46 2d 38 2e 0a 2a 2a ill be UTF-8..**
15b10 0a 2a 2a 20 7b 46 31 32 37 30 37 7d 20 54 68 65 .** {F12707} The
15b20 20 64 65 66 61 75 6c 74 20 74 65 78 74 20 65 6e default text en
15b30 63 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e 65 77 coding for a new
15b40 20 64 61 74 61 62 61 73 65 20 63 72 65 61 74 65 database create
15b50 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 d using.**
15b60 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 [sqlite3_ope
15b70 6e 31 36 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 n16()] will be U
15b80 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 TF-16..**.** {F1
15b90 32 37 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 2709} The [sqlit
15ba0 65 33 5f 6f 70 65 6e 28 46 2c 44 29 5d 20 69 6e e3_open(F,D)] in
15bb0 74 65 72 66 61 63 65 20 69 73 20 65 71 75 69 76 terface is equiv
15bc0 61 6c 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 alent to.**
15bd0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 [sqlite3_op
15be0 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 30 29 5d 20 en_v2(F,D,G,0)]
15bf0 77 68 65 72 65 20 74 68 65 20 47 20 70 61 72 61 where the G para
15c00 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20 meter is.**
15c10 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 [SQLITE_OPE
15c20 4e 5f 52 45 41 44 57 52 49 54 45 5d 7c 5b 53 51 N_READWRITE]|[SQ
15c30 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
15c40 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 31 ]..**.** {F12711
15c50 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d } If the G param
15c60 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 eter to [sqlite3
15c70 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 _open_v2(F,D,G,V
15c80 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a )] contains the.
15c90 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20 ** bit
15ca0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 value [SQLITE_OP
15cb0 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 74 68 65 EN_READONLY] the
15cc0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 n the database i
15cd0 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20 s opened.**
15ce0 20 20 20 20 20 66 6f 72 20 72 65 61 64 69 6e 67 for reading
15cf0 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 only..**.** {F1
15d00 32 37 31 32 7d 20 49 66 20 74 68 65 20 47 20 70 2712} If the G p
15d10 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c arameter to [sql
15d20 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 ite3_open_v2(F,D
15d30 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 ,G,V)] contains
15d40 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
15d50 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 bit value [SQLIT
15d60 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 E_OPEN_READWRITE
15d70 5d 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 ] then the datab
15d80 61 73 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a ase is opened.**
15d90 20 20 20 20 20 20 20 20 20 20 72 65 61 64 69 6e readin
15da0 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 g and writing if
15db0 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 66 6f possible, or fo
15dc0 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 20 69 r reading only i
15dd0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 f the.**
15de0 20 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 file is write
15df0 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 protected by the
15e00 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 operating syste
15e10 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 33 m..**.** {F12713
15e20 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d } If the G param
15e30 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 eter to [sqlite3
15e40 5f 6f 70 65 6e 28 76 32 28 46 2c 44 2c 47 2c 56 _open(v2(F,D,G,V
15e50 29 5d 20 6f 6d 69 74 73 20 74 68 65 0a 2a 2a 20 )] omits the.**
15e60 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c bit val
15e70 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ue [SQLITE_OPEN_
15e80 43 52 45 41 54 45 5d 20 61 6e 64 20 74 68 65 20 CREATE] and the
15e90 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f database does no
15ea0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 t.** pr
15eb0 65 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 eviously exist,
15ec0 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 an error is retu
15ed0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 rned..**.** {F12
15ee0 37 31 34 7d 20 49 66 20 74 68 65 20 47 20 70 61 714} If the G pa
15ef0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
15f00 74 65 33 5f 6f 70 65 6e 28 76 32 28 46 2c 44 2c te3_open(v2(F,D,
15f10 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 G,V)] contains t
15f20 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 he.** b
15f30 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 it value [SQLITE
15f40 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e _OPEN_CREATE] an
15f50 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 d the database d
15f60 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 oes not.**
15f70 20 20 20 20 70 72 65 76 69 6f 75 73 6c 79 20 65 previously e
15f80 78 69 73 74 2c 20 74 68 65 6e 20 61 6e 20 61 74 xist, then an at
15f90 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f tempt is made to
15fa0 20 63 72 65 61 74 65 20 61 6e 64 0a 2a 2a 20 20 create and.**
15fb0 20 20 20 20 20 20 20 20 69 6e 69 74 69 61 6c 69 initiali
15fc0 7a 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e ze the database.
15fd0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 37 7d 20 .**.** {F12717}
15fe0 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 If the filename
15ff0 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c argument to [sql
16000 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 ite3_open()], [s
16010 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
16020 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 ,.** or
16030 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
16040 32 28 29 5d 20 69 73 20 22 3a 6d 65 6d 6f 72 79 2()] is ":memory
16050 3a 22 2c 20 74 68 65 6e 20 61 6e 20 70 72 69 76 :", then an priv
16060 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ate,.**
16070 20 65 70 68 65 6d 65 72 61 6c 2c 20 69 6e 2d 6d ephemeral, in-m
16080 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 69 emory database i
16090 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 s created for th
160a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a e connection..**
160b0 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e <todo>
160c0 49 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 Is SQLITE_OPEN_C
160d0 52 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45 REATE|SQLITE_OPE
160e0 4e 5f 52 45 41 44 57 52 49 54 45 20 72 65 71 75 N_READWRITE requ
160f0 69 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 ired.**
16100 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e in sqlite3_open
16110 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a _v2()?</todo>.**
16120 0a 2a 2a 20 7b 46 31 32 37 31 39 7d 20 49 66 20 .** {F12719} If
16130 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 the filename is
16140 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c an empty string,
16150 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c then a private,
16160 20 65 70 68 65 72 6d 65 72 61 6c 0a 2a 2a 20 20 ephermeral.**
16170 20 20 20 20 20 20 20 20 6f 6e 2d 64 69 73 6b 20 on-disk
16180 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 database will be
16190 20 63 72 65 61 74 65 64 2e 0a 2a 2a 20 20 20 20 created..**
161a0 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53 <todo>Is S
161b0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
161c0 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 E|SQLITE_OPEN_RE
161d0 41 44 57 52 49 54 45 20 72 65 71 75 69 72 65 64 ADWRITE required
161e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 .** in
161f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
16200 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 )?</todo>.**.**
16210 7b 46 31 32 37 32 31 7d 20 54 68 65 20 5b 64 61 {F12721} The [da
16220 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
16230 6e 5d 20 63 72 65 61 74 65 64 20 62 79 20 0a 2a n] created by .*
16240 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
16250 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c te3_open_v2(F,D,
16260 47 2c 56 29 5d 20 77 69 6c 6c 20 75 73 65 20 74 G,V)] will use t
16270 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b he.** [
16280 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
16290 65 63 74 20 69 64 65 6e 74 69 66 69 65 64 20 62 ect identified b
162a0 79 20 74 68 65 20 56 20 70 61 72 61 6d 65 74 65 y the V paramete
162b0 72 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 r, or.**
162c0 20 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 the default [s
162d0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
162e0 63 74 20 69 73 20 56 20 69 73 20 61 20 4e 55 4c ct is V is a NUL
162f0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 69 6e L pointer..*/.in
16300 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a t sqlite3_open(.
16310 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 const char *fi
16320 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 lename, /* Dat
16330 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 abase filename (
16340 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 UTF-8) */. sqli
16350 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 te3 **ppDb
16360 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 /* OUT: SQLi
16370 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a te db handle */.
16380 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f );.int sqlite3_o
16390 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 pen16(. const v
163a0 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 oid *filename,
163b0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c /* Database fil
163c0 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a ename (UTF-16) *
163d0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 /. sqlite3 **pp
163e0 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f Db /* O
163f0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 UT: SQLite db ha
16400 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 ndle */.);.int s
16410 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a qlite3_open_v2(.
16420 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 const char *fi
16430 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 lename, /* Dat
16440 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 abase filename (
16450 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 UTF-8) */. sqli
16460 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 te3 **ppDb,
16470 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 /* OUT: SQLi
16480 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a te db handle */.
16490 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 int flags,
164a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 /* Fla
164b0 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 gs */. const ch
164c0 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 ar *zVfs
164d0 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d /* Name of VFS m
164e0 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a odule to use */.
164f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
16500 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 EF: Error Codes
16510 41 6e 64 20 4d 65 73 73 61 67 65 73 20 7b 46 31 And Messages {F1
16520 32 38 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 2800}.**.** The
16530 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
16540 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
16550 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 0a rns the numeric.
16560 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 ** [SQLITE_OK |
16570 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 result code] or
16580 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 [SQLITE_IOERR_RE
16590 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 AD | extended re
165a0 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 66 6f sult code].** fo
165b0 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e r the most recen
165c0 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 t failed sqlite3
165d0 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f _* API call asso
165e0 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 5b ciated.** with [
165f0 73 71 6c 69 74 65 33 5d 20 68 61 6e 64 6c 65 20 sqlite3] handle
16600 27 64 62 27 2e 20 49 66 20 61 20 70 72 69 6f 72 'db'. If a prior
16610 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 API call failed
16620 20 62 75 74 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 but the.** most
16630 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c recent API call
16640 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 succeeded, the
16650 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f return value fro
16660 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 m sqlite3_errcod
16670 65 28 29 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 e().** is undefi
16680 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ned..**.** The s
16690 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 qlite3_errmsg()
166a0 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d and sqlite3_errm
166b0 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e sg16() return En
166c0 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a glish-language.*
166d0 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 * text that desc
166e0 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c ribes the error,
166f0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 38 20 as either UTF8
16700 6f 72 20 55 54 46 31 36 20 72 65 73 70 65 63 74 or UTF16 respect
16710 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 ively..** Memory
16720 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 to hold the err
16730 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e or message strin
16740 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 g is managed int
16750 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 ernally..** The
16760 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 application does
16770 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 not need to wor
16780 72 79 20 77 69 74 68 20 66 72 65 65 69 6e 67 20 ry with freeing
16790 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 the result..** H
167a0 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f owever, the erro
167b0 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 r string might b
167c0 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 e overwritten or
167d0 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 0a 2a deallocated b.*
167e0 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c * subsequent cal
167f0 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 ls to other SQLi
16800 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e te interface fun
16810 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e ctions..**.** IN
16820 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
16830 7b 46 31 32 38 30 31 7d 20 54 68 65 20 5b 73 71 {F12801} The [sq
16840 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 lite3_errcode(D)
16850 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ] interface retu
16860 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 0a rns the numeric.
16870 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c ** [SQL
16880 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 ITE_OK | result
16890 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 code] or.**
168a0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 4f 45 [SQLITE_IOE
168b0 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 RR_READ | extend
168c0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a ed result code].
168d0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 ** for
168e0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
168f0 66 61 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65 failed interface
16900 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 call associated
16910 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 .** wit
16920 68 20 5b 73 71 6c 69 74 65 33 5d 20 68 61 6e 64 h [sqlite3] hand
16930 6c 65 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 le D..**.** {U12
16940 38 30 32 7d 20 49 66 20 61 20 70 72 69 6f 72 20 802} If a prior
16950 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 20 API call failed
16960 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 but the most rec
16970 65 6e 74 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 ent API call.**
16980 20 20 20 20 20 20 20 20 20 73 75 63 63 65 65 64 succeed
16990 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 ed, the return v
169a0 61 6c 75 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 alue from [sqlit
169b0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a e3_errcode()],.*
169c0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
169d0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 te3_errmsg()], a
169e0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d nd [sqlite3_errm
169f0 73 67 31 36 28 29 5d 20 61 72 65 20 75 6e 64 65 sg16()] are unde
16a00 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 fined..**.** {F1
16a10 32 38 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 2803} The [sqlit
16a20 65 33 5f 65 72 72 6d 73 67 28 44 29 5d 20 61 6e e3_errmsg(D)] an
16a30 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 d [sqlite3_errms
16a40 67 31 36 28 44 29 5d 0a 2a 2a 20 20 20 20 20 20 g16(D)].**
16a50 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 interfaces r
16a60 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 eturn English-la
16a70 6e 67 75 61 67 65 20 74 65 78 74 20 74 68 61 74 nguage text that
16a80 20 64 65 73 63 72 69 62 65 73 0a 2a 2a 20 20 20 describes.**
16a90 20 20 20 20 20 20 20 74 68 65 20 65 72 72 6f 72 the error
16aa0 20 69 6e 20 74 68 65 20 6d 6f 73 74 6c 79 20 72 in the mostly r
16ab0 65 63 65 6e 74 6c 79 20 66 61 69 6c 65 64 20 69 ecently failed i
16ac0 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 2c 0a 2a nterface call,.*
16ad0 2a 20 20 20 20 20 20 20 20 20 20 65 6e 63 6f 64 * encod
16ae0 65 64 20 61 73 20 65 69 74 68 65 72 20 55 54 46 ed as either UTF
16af0 38 20 6f 72 20 55 54 46 31 36 20 72 65 73 70 65 8 or UTF16 respe
16b00 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b ctively..**.** {
16b10 55 31 32 38 30 34 7d 20 54 68 65 20 73 74 72 69 U12804} The stri
16b20 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 ngs returned by
16b30 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 [sqlite3_errmsg(
16b40 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
16b50 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20 errmsg16()].**
16b60 20 20 20 20 20 20 20 20 61 72 65 20 6f 6e 6c 79 are only
16b70 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 valid until the
16b80 20 6e 65 78 74 20 53 51 4c 69 74 65 20 69 6e 74 next SQLite int
16b90 65 72 66 61 63 65 20 63 61 6c 6c 2e 0a 2a 2a 0a erface call..**.
16ba0 2a 2a 20 7b 46 31 32 38 30 37 7d 20 43 61 6c 6c ** {F12807} Call
16bb0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 s to [sqlite3_er
16bc0 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 rcode()], [sqlit
16bd0 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e e3_errmsg()], an
16be0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 d.** [s
16bf0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 qlite3_errmsg16(
16c00 29 5d 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f )] themselves do
16c10 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 0a not affect the.
16c20 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75 ** resu
16c30 6c 74 73 20 6f 66 20 66 75 74 75 72 65 20 69 6e lts of future in
16c40 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 vocations of the
16c50 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a se routines..**.
16c60 2a 2a 20 7b 46 31 32 38 30 38 7d 20 43 61 6c 6c ** {F12808} Call
16c70 73 20 74 6f 20 41 50 49 20 72 6f 75 74 69 6e 65 s to API routine
16c80 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 72 65 s that do not re
16c90 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 20 63 6f turn an error co
16ca0 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 28 de.** (
16cb0 65 78 61 6d 70 6c 65 3a 20 5b 73 71 6c 69 74 65 example: [sqlite
16cc0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 29 3_data_count()])
16cd0 20 64 6f 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 do not.**
16ce0 20 20 20 20 63 68 61 6e 67 65 20 74 68 65 20 65 change the e
16cf0 72 72 6f 72 20 63 6f 64 65 20 6f 72 20 6d 65 73 rror code or mes
16d00 73 61 67 65 20 72 65 74 75 72 6e 65 64 20 62 79 sage returned by
16d10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
16d20 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d lite3_errcode()]
16d30 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 , [sqlite3_errms
16d40 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 g()], or [sqlite
16d50 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 3_errmsg16()]..*
16d60 2a 0a 2a 2a 20 7b 46 31 32 38 30 39 7d 20 49 6e *.** {F12809} In
16d70 74 65 72 66 61 63 65 73 20 74 68 61 74 20 61 72 terfaces that ar
16d80 65 20 6e 6f 74 20 61 73 73 6f 63 69 61 74 65 64 e not associated
16d90 20 77 69 74 68 20 61 20 73 70 65 63 69 66 69 63 with a specific
16da0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 .** [da
16db0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
16dc0 6e 5d 20 28 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a n] (examples:.**
16dd0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
16de0 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 6f 72 e3_mprintf()] or
16df0 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 [sqlite3_enable
16e00 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d _shared_cache()]
16e10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 6f 20 .** do
16e20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 not change the v
16e30 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 alues returned b
16e40 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 y.** [s
16e50 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 qlite3_errcode()
16e60 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d ], [sqlite3_errm
16e70 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 sg()], or [sqlit
16e80 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a e3_errmsg16()]..
16e90 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 */.int sqlite3_e
16ea0 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a rrcode(sqlite3 *
16eb0 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 db);.const char
16ec0 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 *sqlite3_errmsg(
16ed0 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 sqlite3*);.const
16ee0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 void *sqlite3_e
16ef0 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a rrmsg16(sqlite3*
16f00 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
16f10 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e EF: SQL Statemen
16f20 74 20 4f 62 6a 65 63 74 20 7b 46 31 33 30 30 30 t Object {F13000
16f30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b }.** KEYWORDS: {
16f40 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
16f50 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 nt} {prepared st
16f60 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 atements}.**.**
16f70 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 An instance of t
16f80 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 his object repre
16f90 73 65 6e 74 20 73 69 6e 67 6c 65 20 53 51 4c 20 sent single SQL
16fa0 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 54 68 69 statements. Thi
16fb0 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 73 20 76 s.** object is v
16fc0 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 ariously known a
16fd0 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74 s a "prepared st
16fe0 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 20 0a 2a atement" or a .*
16ff0 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 * "compiled SQL
17000 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 statement" or si
17010 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 mply as a "state
17020 6d 65 6e 74 22 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 ment"..** .** Th
17030 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 e life of a stat
17040 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 ement object goe
17050 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 s something like
17060 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c this:.**.** <ol
17070 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 >.** <li> Create
17080 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e the object usin
17090 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 g [sqlite3_prepa
170a0 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 re_v2()] or a re
170b0 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 lated.** fu
170c0 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 nction..** <li>
170d0 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 Bind values to h
170e0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 75 ost parameters u
170f0 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 5b 73 71 sing.** [sq
17100 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 lite3_bind_blob
17110 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a | sqlite3_bind_*
17120 20 69 6e 74 65 72 66 61 63 65 73 5d 2e 0a 2a 2a interfaces]..**
17130 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 <li> Run the SQ
17140 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 L by calling [sq
17150 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e lite3_step()] on
17160 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e e or more times.
17170 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 .** <li> Reset t
17180 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 he statement usi
17190 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ng [sqlite3_rese
171a0 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 t()] then go bac
171b0 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 k.** to ste
171c0 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 p 2. Do this ze
171d0 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 ro or more times
171e0 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f ..** <li> Destro
171f0 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 y the object usi
17200 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ng [sqlite3_fina
17210 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c lize()]..** </ol
17220 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f >.**.** Refer to
17230 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f documentation o
17240 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 n individual met
17250 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 hods above for a
17260 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 dditional.** inf
17270 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 ormation..*/.typ
17280 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
17290 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 te3_stmt sqlite3
172a0 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 _stmt;../*.** CA
172b0 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e PI3REF: Compilin
172c0 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 g An SQL Stateme
172d0 6e 74 20 7b 46 31 33 30 31 30 7d 0a 2a 2a 0a 2a nt {F13010}.**.*
172e0 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 * To execute an
172f0 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 SQL query, it mu
17300 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 st first be comp
17310 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 iled into a byte
17320 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d -code.** program
17330 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 using one of th
17340 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 20 0a 2a ese routines. .*
17350 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 *.** The first a
17360 72 67 75 6d 65 6e 74 20 22 64 62 22 20 69 73 20 rgument "db" is
17370 61 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e an [database con
17380 6e 65 63 74 69 6f 6e 5d 20 0a 2a 2a 20 6f 62 74 nection] .** obt
17390 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 ained from a pri
173a0 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 or call to [sqli
173b0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 te3_open()], [sq
173c0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d lite3_open_v2()]
173d0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f .** or [sqlite3_
173e0 6f 70 65 6e 31 36 28 29 5d 2e 20 0a 2a 2a 20 54 open16()]. .** T
173f0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
17400 6e 74 20 22 7a 53 71 6c 22 20 69 73 20 74 68 65 nt "zSql" is the
17410 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 statement to be
17420 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 compiled, encod
17430 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 ed.** as either
17440 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e UTF-8 or UTF-16.
17450 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 The sqlite3_pr
17460 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 epare() and sqli
17470 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
17480 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 .** interfaces u
17490 73 65 73 20 55 54 46 2d 38 20 61 6e 64 20 73 71 ses UTF-8 and sq
174a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
174b0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 ) and sqlite3_pr
174c0 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 epare16_v2().**
174d0 75 73 65 20 55 54 46 2d 31 36 2e 20 7b 45 4e 44 use UTF-16. {END
174e0 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e }.**.** If the n
174f0 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 Byte argument is
17500 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 7a 65 less.** than ze
17510 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 ro, then zSql is
17520 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 20 read up to the
17530 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 first zero termi
17540 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 6e 42 79 nator..** If nBy
17550 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 te is non-negati
17560 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 ve, then it is t
17570 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
17580 72 20 6f 66 20 0a 2a 2a 20 62 79 74 65 73 20 72 r of .** bytes r
17590 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 ead from zSql.
175a0 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f When nByte is no
175b0 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a n-negative, the.
175c0 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 ** zSql string e
175d0 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68 nds at either th
175e0 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f e first '\000' o
175f0 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 r '\u0000' chara
17600 63 74 65 72 20 6f 72 20 0a 2a 2a 20 75 6e 74 69 cter or .** unti
17610 6c 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 l the nByte-th b
17620 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 yte, whichever c
17630 6f 6d 65 73 20 66 69 72 73 74 2e 20 7b 45 4e 44 omes first. {END
17640 7d 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20 }.**.** *pzTail
17650 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 is made to point
17660 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 to the first by
17670 74 65 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 te past the end
17680 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 of the.** first
17690 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e SQL statement in
176a0 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f zSql. These ro
176b0 75 74 69 6e 65 73 20 6f 6e 6c 79 20 63 6f 6d 70 utines only comp
176c0 69 6c 65 73 20 74 68 65 20 66 69 72 73 74 0a 2a iles the first.*
176d0 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a * statement in z
176e0 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 Sql, so *pzTail
176f0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 is left pointing
17700 20 74 6f 20 77 68 61 74 20 72 65 6d 61 69 6e 73 to what remains
17710 0a 2a 2a 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a .** uncompiled..
17720 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69 73 **.** *ppStmt is
17730 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 left pointing t
17740 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 o a compiled [pr
17750 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
17760 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a ] that can be.**
17770 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 executed using
17780 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
17790 2e 20 20 4f 72 20 69 66 20 74 68 65 72 65 20 69 . Or if there i
177a0 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 s an error, *ppS
177b0 74 6d 74 20 6d 61 79 20 62 65 0a 2a 2a 20 73 65 tmt may be.** se
177c0 74 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74 t to NULL. If t
177d0 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f he input text co
177e0 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 ntains no SQL (i
177f0 66 20 74 68 65 20 69 6e 70 75 74 0a 2a 2a 20 69 f the input.** i
17800 73 20 61 6e 64 20 65 6d 70 74 79 20 73 74 72 69 s and empty stri
17810 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 ng or a comment)
17820 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 then *ppStmt is
17830 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a set to NULL..**
17840 20 7b 55 31 33 30 31 38 7d 20 54 68 65 20 63 61 {U13018} The ca
17850 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 lling procedure
17860 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 is responsible f
17870 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 0a or deleting the.
17880 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 ** compiled SQL
17890 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 75 73 69 statement.** usi
178a0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ng [sqlite3_fina
178b0 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 lize()] after it
178c0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 has finished wi
178d0 74 68 20 69 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 th it..**.** On
178e0 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 success, [SQLITE
178f0 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 _OK] is returned
17900 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 . Otherwise an
17910 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d .** [error code]
17920 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
17930 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
17940 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 prepare_v2() and
17950 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
17960 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 16_v2() interfac
17970 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d es are.** recomm
17980 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 ended for all ne
17990 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 w programs. The
179a0 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 two older interf
179b0 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 aces are retaine
179c0 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 d.** for backwar
179d0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ds compatibility
179e0 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 , but their use
179f0 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a is discouraged..
17a00 2a 2a 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 ** In the "v2" i
17a10 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 nterfaces, the p
17a20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
17a30 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 t.** that is ret
17a40 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 urned (the [sqli
17a50 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 te3_stmt] object
17a60 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 ) contains a cop
17a70 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6f 72 69 y of the .** ori
17a80 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 ginal SQL text.
17a90 7b 45 4e 44 7d 20 54 68 69 73 20 63 61 75 73 65 {END} This cause
17aa0 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 s the [sqlite3_s
17ab0 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 tep()] interface
17ac0 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 to.** behave a
17ad0 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 differently in t
17ae0 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c wo ways:.**.** <
17af0 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 ol>.** <li>.** I
17b00 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 f the database s
17b10 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 chema changes, i
17b20 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e nstead of return
17b30 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 ing [SQLITE_SCHE
17b40 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 MA] as it.** alw
17b50 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 ays used to do,
17b60 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
17b70 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 will automatica
17b80 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 lly recompile th
17b90 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 e SQL.** stateme
17ba0 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 nt and try to ru
17bb0 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20 n it again. If
17bc0 74 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 63 the schema has c
17bd0 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 hanged in.** a w
17be0 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 ay that makes th
17bf0 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c e statement no l
17c00 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 onger valid, [sq
17c10 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 lite3_step()] wi
17c20 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 ll still.** retu
17c30 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d rn [SQLITE_SCHEM
17c40 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 A]. But unlike
17c50 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 the legacy behav
17c60 69 6f 72 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 ior, .** [SQLITE
17c70 5f 53 43 48 45 4d 41 5d 20 69 73 20 6e 6f 77 20 _SCHEMA] is now
17c80 61 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 a fatal error.
17c90 43 61 6c 6c 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 Calling.** [sqli
17ca0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
17cb0 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 ] again will not
17cc0 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 make the.** err
17cd0 6f 72 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 or go away. Not
17ce0 65 3a 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f e: use [sqlite3_
17cf0 65 72 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e errmsg()] to fin
17d00 64 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66 d the text.** of
17d10 20 74 68 65 20 70 61 72 73 69 6e 67 20 65 72 72 the parsing err
17d20 6f 72 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 or that results
17d30 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 in an [SQLITE_SC
17d40 48 45 4d 41 5d 20 72 65 74 75 72 6e 2e 20 7b 45 HEMA] return. {E
17d50 4e 44 7d 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a ND}.** </li>.**.
17d60 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20 ** <li>.** When
17d70 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c an error occurs,
17d80 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 .** [sqlite3_st
17d90 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 ep()] will retur
17da0 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 n one of the det
17db0 61 69 6c 65 64 20 0a 2a 2a 20 5b 65 72 72 6f 72 ailed .** [error
17dc0 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 codes] or [exte
17dd0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 nded error codes
17de0 5d 2e 20 0a 2a 2a 20 54 68 65 20 6c 65 67 61 63 ]. .** The legac
17df0 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 y behavior was t
17e00 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 hat [sqlite3_ste
17e10 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 p()] would only
17e20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 return a generic
17e30 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f .** [SQLITE_ERRO
17e40 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61 R] result code a
17e50 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 nd you would hav
17e60 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f e to make a seco
17e70 6e 64 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 nd call to.** [s
17e80 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
17e90 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 in order to find
17ea0 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 the underlying
17eb0 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f cause of the pro
17ec0 62 6c 65 6d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 blem..** With th
17ed0 65 20 22 76 32 22 20 70 72 65 70 61 72 65 20 69 e "v2" prepare i
17ee0 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 nterfaces, the u
17ef0 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e nderlying reason
17f00 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 for the error i
17f10 73 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6d s.** returned im
17f20 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f mediately..** </
17f30 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a li>.** </ol>.**.
17f40 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
17f50 2a 0a 2a 2a 20 7b 46 31 33 30 31 31 7d 20 54 68 *.** {F13011} Th
17f60 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 e [sqlite3_prepa
17f70 72 65 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d re(db,zSql,...)]
17f80 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 and.**
17f90 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
17fa0 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e e_v2(db,zSql,...
17fb0 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e )] interfaces in
17fc0 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 terpret the.**
17fd0 20 20 20 20 20 20 20 20 74 65 78 74 20 69 6e 20 text in
17fe0 74 68 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d their zSql param
17ff0 65 74 65 72 20 61 73 20 55 54 46 2d 38 2e 0a 2a eter as UTF-8..*
18000 2a 0a 2a 2a 20 7b 46 31 33 30 31 32 7d 20 54 68 *.** {F13012} Th
18010 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 e [sqlite3_prepa
18020 72 65 31 36 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e re16(db,zSql,...
18030 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 )] and.**
18040 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 [sqlite3_prep
18050 61 72 65 31 36 5f 76 32 28 64 62 2c 7a 53 71 6c are16_v2(db,zSql
18060 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 ,...)] interface
18070 73 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a s interpret the.
18080 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65 78 74 ** text
18090 20 69 6e 20 74 68 65 69 72 20 7a 53 71 6c 20 70 in their zSql p
180a0 61 72 61 6d 65 74 65 72 20 61 73 20 55 54 46 2d arameter as UTF-
180b0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 16 in the native
180c0 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a byte order..**.
180d0 2a 2a 20 7b 46 31 33 30 31 33 7d 20 49 66 20 74 ** {F13013} If t
180e0 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e he nByte argumen
180f0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 t to [sqlite3_pr
18100 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c epare_v2(db,zSql
18110 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 ,nByte,...)].**
18120 20 20 20 20 20 20 20 20 20 61 6e 64 20 69 74 73 and its
18130 20 76 61 72 69 61 6e 74 73 20 69 73 20 6c 65 73 variants is les
18140 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 s than zero, the
18150 6e 20 53 51 4c 20 74 65 78 74 20 69 73 0a 2a 2a n SQL text is.**
18160 20 20 20 20 20 20 20 20 20 20 72 65 61 64 20 66 read f
18170 72 6f 6d 20 7a 53 71 6c 20 69 73 20 72 65 61 64 rom zSql is read
18180 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 up to the first
18190 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 zero terminator
181a0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 34 7d ..**.** {F13014}
181b0 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 If the nByte ar
181c0 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 gument to [sqlit
181d0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 e3_prepare_v2(db
181e0 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 ,zSql,nByte,...)
181f0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e ].** an
18200 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 69 d its variants i
18210 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 s non-negative,
18220 74 68 65 6e 20 6e 42 79 74 65 73 20 62 79 74 65 then nBytes byte
18230 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 s.** SQ
18240 4c 20 74 65 78 74 20 69 73 20 72 65 61 64 20 66 L text is read f
18250 72 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20 rom zSql..**.**
18260 7b 46 31 33 30 31 35 7d 20 49 6e 20 5b 73 71 6c {F13015} In [sql
18270 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
18280 64 62 2c 7a 53 71 6c 2c 4e 2c 50 2c 70 7a 54 61 db,zSql,N,P,pzTa
18290 69 6c 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 il)] and its var
182a0 69 61 6e 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 iants.**
182b0 20 20 69 66 20 74 68 65 20 7a 53 71 6c 20 69 6e if the zSql in
182c0 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e put text contain
182d0 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 s more than one
182e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a SQL statement.**
182f0 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 70 7a and pz
18300 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c Tail is not NULL
18310 2c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 , then *pzTail i
18320 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 s made to point
18330 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 to the.**
18340 20 20 20 66 69 72 73 74 20 62 79 74 65 20 70 61 first byte pa
18350 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 st the end of th
18360 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 e first SQL stat
18370 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 0a 2a ement in zSql..*
18380 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f * <todo
18390 3e 57 68 61 74 20 64 6f 65 73 20 2a 70 7a 54 61 >What does *pzTa
183a0 69 6c 20 70 6f 69 6e 74 20 74 6f 20 69 66 20 74 il point to if t
183b0 68 65 72 65 20 69 73 20 6f 6e 65 20 73 74 61 74 here is one stat
183c0 65 6d 65 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a ement?</todo>.**
183d0 0a 2a 2a 20 7b 46 31 33 30 31 36 7d 20 41 20 73 .** {F13016} A s
183e0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
183f0 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 o [sqlite3_prepa
18400 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c re_v2(db,zSql,N,
18410 70 70 53 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20 ppStmt,...)].**
18420 20 20 20 20 20 20 20 20 20 6f 72 20 6f 6e 65 20 or one
18430 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 of its variants
18440 77 72 69 74 65 73 20 69 6e 74 6f 20 2a 70 70 53 writes into *ppS
18450 74 6d 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f tmt a pointer to
18460 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 a new.**
18470 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 [prepared sta
18480 74 65 6d 65 6e 74 5d 20 6f 72 20 61 20 70 6f 69 tement] or a poi
18490 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 0a 2a 2a 20 nter to NULL.**
184a0 20 20 20 20 20 20 20 20 20 69 66 20 7a 53 71 6c if zSql
184b0 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 74 68 69 6e contains nothin
184c0 67 20 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69 g other than whi
184d0 74 65 73 70 61 63 65 20 6f 72 20 63 6f 6d 6d 65 tespace or comme
184e0 6e 74 73 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 nts. .**.** {F13
184f0 30 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 019} The [sqlite
18500 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
18510 69 6e 74 65 72 66 61 63 65 20 61 6e 64 20 69 74 interface and it
18520 73 20 76 61 72 69 61 6e 74 73 20 72 65 74 75 72 s variants retur
18530 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 n.** [S
18540 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 61 6e 20 QLITE_OK] or an
18550 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 appropriate [err
18560 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 20 66 61 or code] upon fa
18570 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ilure..*/.int sq
18580 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 lite3_prepare(.
18590 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
185a0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
185b0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 base handle */.
185c0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 const char *zSq
185d0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 l, /* SQL
185e0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 statement, UTF-8
185f0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e encoded */. in
18600 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 t nByte,
18610 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d /* Maximum
18620 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 length of zSql
18630 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 in bytes. */. s
18640 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 qlite3_stmt **pp
18650 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 Stmt, /* OUT: S
18660 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 tatement handle
18670 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
18680 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 **pzTail /*
18690 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 OUT: Pointer to
186a0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f unused portion o
186b0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 f zSql */.);.int
186c0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
186d0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a _v2(. sqlite3 *
186e0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f db, /
186f0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c * Database handl
18700 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
18710 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f r *zSql, /
18720 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c * SQL statement,
18730 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a UTF-8 encoded *
18740 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 /. int nByte,
18750 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d /* M
18760 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
18770 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 zSql in bytes.
18780 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d */. sqlite3_stm
18790 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 t **ppStmt, /*
187a0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 OUT: Statement h
187b0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
187c0 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 char **pzTail
187d0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 /* OUT: Point
187e0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 er to unused por
187f0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a tion of zSql */.
18800 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 );.int sqlite3_p
18810 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 repare16(. sqli
18820 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
18830 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
18840 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
18850 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 t void *zSql,
18860 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 /* SQL state
18870 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 ment, UTF-16 enc
18880 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 oded */. int nB
18890 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 yte,
188a0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e /* Maximum len
188b0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 gth of zSql in b
188c0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 ytes. */. sqlit
188d0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 e3_stmt **ppStmt
188e0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 , /* OUT: State
188f0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 ment handle */.
18900 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a const void **pz
18910 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a Tail /* OUT:
18920 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 Pointer to unus
18930 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 ed portion of zS
18940 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c ql */.);.int sql
18950 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
18960 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2(. sqlite3 *db
18970 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 , /*
18980 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 Database handle
18990 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
189a0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 *zSql, /*
189b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 SQL statement, U
189c0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f TF-16 encoded */
189d0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 . int nByte,
189e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 /* Ma
189f0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
18a00 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a zSql in bytes. *
18a10 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
18a20 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
18a30 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
18a40 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
18a50 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 void **pzTail
18a60 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
18a70 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
18a80 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
18a90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 52 45 46 ;../*.** CAPIREF
18aa0 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 : Retrieving Sta
18ab0 74 65 6d 65 6e 74 20 53 51 4c 20 7b 46 31 33 31 tement SQL {F131
18ac0 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 00}.**.** This i
18ad0 6e 74 65 72 65 66 61 63 65 20 63 61 6e 20 62 65 ntereface can be
18ae0 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 used to retriev
18af0 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f e a saved copy o
18b00 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a f the original.*
18b10 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 * SQL text used
18b20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 to create a [pre
18b30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
18b40 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
18b50 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 TS:.**.** {F1310
18b60 31 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 1} If the [prepa
18b70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 red statement] p
18b80 61 73 73 65 64 20 61 73 20 0a 2a 2a 20 20 20 20 assed as .**
18b90 20 20 20 20 20 20 74 68 65 20 61 6e 20 61 72 67 the an arg
18ba0 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 ument to [sqlite
18bb0 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 3_sql()] was com
18bc0 70 69 6c 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 piled.**
18bd0 20 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 compiled using
18be0 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 either [sqlite3
18bf0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
18c00 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 r.** [s
18c10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
18c20 5f 76 32 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 _v2()],.**
18c30 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 then [sqlite
18c40 33 5f 73 71 6c 28 29 5d 20 66 75 6e 63 74 69 6f 3_sql()] functio
18c50 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e n returns a poin
18c60 74 65 72 20 74 6f 20 61 0a 2a 2a 20 20 20 20 20 ter to a.**
18c70 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e zero-termin
18c80 61 74 65 64 20 73 74 72 69 6e 67 20 63 6f 6e 74 ated string cont
18c90 61 69 6e 69 6e 67 20 61 20 55 54 46 2d 38 20 72 aining a UTF-8 r
18ca0 65 6e 64 65 72 69 6e 67 0a 2a 2a 20 20 20 20 20 endering.**
18cb0 20 20 20 20 20 6f 66 20 74 68 65 20 6f 72 69 67 of the orig
18cc0 69 6e 61 6c 20 53 51 4c 20 73 74 61 74 65 6d 65 inal SQL stateme
18cd0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 nt..**.** {F1310
18ce0 32 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 2} If the [prepa
18cf0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 red statement] p
18d00 61 73 73 65 64 20 61 73 20 0a 2a 2a 20 20 20 20 assed as .**
18d10 20 20 20 20 20 20 74 68 65 20 61 6e 20 61 72 67 the an arg
18d20 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 ument to [sqlite
18d30 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 3_sql()] was com
18d40 70 69 6c 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 piled.**
18d50 20 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 compiled using
18d60 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 either [sqlite3
18d70 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a _prepare()] or.*
18d80 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
18d90 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d te3_prepare16()]
18da0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 ,.** th
18db0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 en [sqlite3_sql(
18dc0 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 )] function retu
18dd0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 rns a NULL point
18de0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 er..**.** {F1310
18df0 33 7d 20 54 68 65 20 73 74 72 69 6e 67 20 72 65 3} The string re
18e00 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
18e10 65 33 5f 73 71 6c 28 53 29 5d 20 69 73 20 76 61 e3_sql(S)] is va
18e20 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 0a 2a 2a lid until the.**
18e30 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 [prepa
18e40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
18e50 20 69 73 20 64 65 6c 65 74 65 64 20 75 73 69 6e is deleted usin
18e60 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c g [sqlite3_final
18e70 69 7a 65 28 53 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 ize(S)]..*/.cons
18e80 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
18e90 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 sql(sqlite3_stmt
18ea0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
18eb0 20 43 41 50 49 33 52 45 46 3a 20 20 44 79 6e 61 CAPI3REF: Dyna
18ec0 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 mically Typed Va
18ed0 6c 75 65 20 4f 62 6a 65 63 74 20 20 7b 46 31 35 lue Object {F15
18ee0 30 30 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 000}.**.** SQLit
18ef0 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 e uses the sqlit
18f00 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 e3_value object
18f10 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c to represent all
18f20 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 values.** that
18f30 61 72 65 20 6f 72 20 63 61 6e 20 62 65 20 73 74 are or can be st
18f40 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 ored in a databa
18f50 73 65 20 74 61 62 6c 65 2e 0a 2a 2a 20 53 51 4c se table..** SQL
18f60 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 ite uses dynamic
18f70 20 74 79 70 69 6e 67 20 66 6f 72 20 74 68 65 20 typing for the
18f80 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 values it stores
18f90 2e 20 20 0a 2a 2a 20 56 61 6c 75 65 73 20 73 74 . .** Values st
18fa0 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f ored in sqlite3_
18fb0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 63 61 value objects ca
18fc0 6e 20 62 65 0a 2a 2a 20 62 65 20 69 6e 74 65 67 n be.** be integ
18fd0 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f ers, floating po
18fe0 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 int values, stri
18ff0 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e ngs, BLOBs, or N
19000 55 4c 4c 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ULL..*/.typedef
19010 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 struct Mem sqlit
19020 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a e3_value;../*.**
19030 20 43 41 50 49 33 52 45 46 3a 20 20 53 51 4c 20 CAPI3REF: SQL
19040 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 Function Context
19050 20 4f 62 6a 65 63 74 20 7b 46 31 36 30 30 31 7d Object {F16001}
19060 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 .**.** The conte
19070 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 xt in which an S
19080 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 QL function exec
19090 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 utes is stored i
190a0 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f n an.** sqlite3_
190b0 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 context object.
190c0 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e A pointer to an
190d0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
190e0 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 73 20 61 6c .** object is al
190f0 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d ways first param
19100 65 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 eter to applicat
19110 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
19120 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2f 0a 74 79 functions..*/.ty
19130 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
19140 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c ite3_context sql
19150 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f ite3_context;../
19160 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 *.** CAPI3REF:
19170 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 Binding Values T
19180 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 o Prepared State
19190 6d 65 6e 74 73 20 7b 46 31 33 35 30 30 7d 0a 2a ments {F13500}.*
191a0 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 53 51 4c 20 *.** In the SQL
191b0 73 74 72 69 6e 67 73 20 69 6e 70 75 74 20 74 6f strings input to
191c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
191d0 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 0a e_v2()] and its.
191e0 2a 2a 20 76 61 72 69 61 6e 74 73 2c 20 6c 69 74 ** variants, lit
191f0 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 erals may be rep
19200 6c 61 63 65 20 62 79 20 61 20 70 61 72 61 6d 65 lace by a parame
19210 74 65 72 20 69 6e 20 6f 6e 65 0a 2a 2a 20 6f 66 ter in one.** of
19220 20 74 68 65 73 65 20 66 6f 72 6d 73 3a 0a 2a 2a these forms:.**
19230 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
19240 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e ?.** <li> ?NN
19250 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a N.** <li> :VVV.
19260 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a ** <li> @VVV.**
19270 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c <li> $VVV.** <
19280 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 /ul>.**.** In th
19290 65 20 70 61 72 61 6d 65 74 65 72 20 66 6f 72 6d e parameter form
192a0 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 4e 4e s shown above NN
192b0 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 N is an integer
192c0 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 56 56 56 20 literal,.** VVV
192d0 61 6c 70 68 61 2d 6e 75 6d 65 72 69 63 20 70 61 alpha-numeric pa
192e0 72 61 6d 65 74 65 72 20 6e 61 6d 65 2e 0a 2a 2a rameter name..**
192f0 20 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 The values of t
19300 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 20 hese parameters
19310 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f (also called "ho
19320 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d st parameter nam
19330 65 73 22 0a 2a 2a 20 6f 72 20 22 53 51 4c 20 70 es".** or "SQL p
19340 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 arameters").** c
19350 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 an be set using
19360 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 the sqlite3_bind
19370 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 _*() routines de
19380 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a fined here..**.*
19390 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 * The first argu
193a0 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 ment to the sqli
193b0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
193c0 74 69 6e 65 73 20 61 6c 77 61 79 73 0a 2a 2a 20 tines always.**
193d0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
193e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d the [sqlite3_stm
193f0 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e t] object return
19400 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 ed from.** [sqli
19410 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
19420 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 ] or its variant
19430 73 2e 20 54 68 65 20 73 65 63 6f 6e 64 0a 2a 2a s. The second.**
19440 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
19450 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 70 61 index of the pa
19460 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 rameter to be se
19470 74 2e 20 54 68 65 0a 2a 2a 20 66 69 72 73 74 20 t. The.** first
19480 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e parameter has an
19490 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 57 68 index of 1. Wh
194a0 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 en the same name
194b0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 d.** parameter i
194c0 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e s used more than
194d0 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e once, second an
194e0 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 d subsequent.**
194f0 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 occurrences have
19500 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 the same index
19510 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 as the first occ
19520 75 72 72 65 6e 63 65 2e 20 0a 2a 2a 20 54 68 65 urrence. .** The
19530 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 index for named
19540 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 parameters can
19550 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 be looked up usi
19560 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ng the.** [sqlit
19570 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
19580 72 5f 6e 61 6d 65 28 29 5d 20 41 50 49 20 69 66 r_name()] API if
19590 20 64 65 73 69 72 65 64 2e 20 20 54 68 65 20 69 desired. The i
195a0 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e ndex.** for "?NN
195b0 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 N" parameters is
195c0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e the value of NN
195d0 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 61 N..** The NNN va
195e0 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 lue must be betw
195f0 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 63 6f een 1 and the co
19600 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 70 61 mpile-time.** pa
19610 72 61 6d 65 74 65 72 20 53 51 4c 49 54 45 5f 4d rameter SQLITE_M
19620 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 AX_VARIABLE_NUMB
19630 45 52 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 ER (default valu
19640 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 e: 999)..**.** T
19650 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
19660 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 t is the value t
19670 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 o bind to the pa
19680 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 rameter..**.** I
19690 6e 20 74 68 6f 73 65 0a 2a 2a 20 72 6f 75 74 69 n those.** routi
196a0 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20 nes that have a
196b0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c fourth argument,
196c0 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 its value is th
196d0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
196e0 73 0a 2a 2a 20 69 6e 20 74 68 65 20 70 61 72 61 s.** in the para
196f0 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c meter. To be cl
19700 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 ear: the value i
19710 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
19720 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 0a 2a 2a 20 <u>bytes</u>.**
19730 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f in the value, no
19740 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 t the number of
19750 63 68 61 72 61 63 74 65 72 73 2e 20 20 20 54 68 characters. Th
19760 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 e number.** of b
19770 79 74 65 73 20 64 6f 65 73 20 6e 6f 74 20 69 6e ytes does not in
19780 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 2d 74 clude the zero-t
19790 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 erminator at the
197a0 20 65 6e 64 20 6f 66 20 73 74 72 69 6e 67 73 2e end of strings.
197b0 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 .** If the fourt
197c0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e h parameter is n
197d0 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e egative, the len
197e0 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e gth of the strin
197f0 67 20 69 73 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f g is.** number o
19800 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 f bytes up to th
19810 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 e first zero ter
19820 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 minator..**.** T
19830 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e he fifth argumen
19840 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e t to sqlite3_bin
19850 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 d_blob(), sqlite
19860 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 3_bind_text(), a
19870 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 nd.** sqlite3_bi
19880 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 nd_text16() is a
19890 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 destructor used
198a0 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 to dispose of t
198b0 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 he BLOB or.** st
198c0 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 ring after SQLit
198d0 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 e has finished w
198e0 69 74 68 20 69 74 2e 20 49 66 20 74 68 65 20 66 ith it. If the f
198f0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 ifth argument is
19900 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 .** the special
19910 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 value [SQLITE_ST
19920 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 ATIC], then SQLi
19930 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 te assumes that
19940 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 the.** informati
19950 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c on is in static,
19960 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 unmanaged space
19970 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 and does not ne
19980 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a ed to be freed..
19990 2a 2a 20 49 66 20 74 68 65 20 66 69 66 74 68 20 ** If the fifth
199a0 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 argument has the
199b0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 value [SQLITE_T
199c0 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a RANSIENT], then.
199d0 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 ** SQLite makes
199e0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 its own private
199f0 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 copy of the data
19a00 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 immediately, be
19a10 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 fore.** the sqli
19a20 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
19a30 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a tine returns..**
19a40 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
19a50 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 bind_zeroblob()
19a60 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 routine binds a
19a70 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e BLOB of length N
19a80 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c that.** is fill
19a90 65 64 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 ed with zeros.
19aa0 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 A zeroblob uses
19ab0 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f a fixed amount o
19ac0 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 f memory.** (jus
19ad0 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 t an integer to
19ae0 68 6f 6c 64 20 69 74 20 73 69 7a 65 29 20 77 68 hold it size) wh
19af0 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 ile it is being
19b00 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 processed..** Ze
19b10 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 roblobs are inte
19b20 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 nded to serve as
19b30 20 70 6c 61 63 65 2d 68 6f 6c 64 65 72 73 20 66 place-holders f
19b40 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a or BLOBs whose.*
19b50 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 * content is lat
19b60 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 er written using
19b70 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c .** [sqlite3_bl
19b80 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d ob_open | increm
19b90 65 6e 74 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f ent BLOB I/O] ro
19ba0 75 74 69 6e 65 73 2e 20 41 20 6e 65 67 61 74 69 utines. A negati
19bb0 76 65 0a 2a 2a 20 76 61 6c 75 65 20 66 6f 72 20 ve.** value for
19bc0 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 the zeroblob res
19bd0 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c ults in a zero-l
19be0 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a ength BLOB..**.*
19bf0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 * The sqlite3_bi
19c00 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 nd_*() routines
19c10 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 61 must be called a
19c20 66 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 fter.** [sqlite3
19c30 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 28 _prepare_v2()] (
19c40 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 and its variants
19c50 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ) or [sqlite3_re
19c60 73 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 set()] and.** be
19c70 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 fore [sqlite3_st
19c80 65 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e ep()]..** Bindin
19c90 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 gs are not clear
19ca0 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 ed by the [sqlit
19cb0 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 e3_reset()] rout
19cc0 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 ine..** Unbound
19cd0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 parameters are i
19ce0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 nterpreted as NU
19cf0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 LL..**.** These
19d00 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
19d10 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 [SQLITE_OK] on s
19d20 75 63 63 65 73 73 20 6f 72 20 61 6e 20 65 72 72 uccess or an err
19d30 6f 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e or code if.** an
19d40 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e ything goes wron
19d50 67 2e 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 g. [SQLITE_RANG
19d60 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 E] is returned i
19d70 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a f the parameter.
19d80 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 ** index is out
19d90 6f 66 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49 of range. [SQLI
19da0 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 TE_NOMEM] is ret
19db0 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 20 urned if malloc
19dc0 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 fails..** [SQLIT
19dd0 45 5f 4d 49 53 55 53 45 5d 20 6d 69 67 68 74 20 E_MISUSE] might
19de0 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 be returned if t
19df0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
19e00 65 20 63 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a e called on a.**
19e10 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 virtual machine
19e20 20 74 68 61 74 20 69 73 20 74 68 65 20 77 72 6f that is the wro
19e30 6e 67 20 73 74 61 74 65 20 6f 72 20 77 68 69 63 ng state or whic
19e40 68 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65 h has already be
19e50 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a en finalized..**
19e60 20 44 65 74 65 63 74 69 6f 6e 20 6f 66 20 6d 69 Detection of mi
19e70 73 75 73 65 20 69 73 20 75 6e 72 65 6c 69 61 62 suse is unreliab
19e80 6c 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e le. Application
19e90 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 64 65 70 s should not dep
19ea0 65 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 end.** on SQLITE
19eb0 5f 4d 49 53 55 53 45 20 72 65 74 75 72 6e 73 2e _MISUSE returns.
19ec0 20 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 SQLITE_MISUSE
19ed0 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 69 is intended to i
19ee0 6e 64 69 63 61 74 65 20 61 0a 2a 2a 20 61 20 6c ndicate a.** a l
19ef0 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 74 68 ogic error in th
19f00 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 e application.
19f10 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 Future versions
19f20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a of SQLite might.
19f30 2a 2a 20 70 61 6e 69 63 20 72 61 74 68 65 72 20 ** panic rather
19f40 74 68 61 6e 20 72 65 74 75 72 6e 20 53 51 4c 49 than return SQLI
19f50 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a TE_MISUSE..**.**
19f60 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
19f70 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
19f80 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 er_count()],.**
19f90 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
19fa0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c rameter_name()],
19fb0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
19fc0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
19fd0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 index()]..**.**
19fe0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
19ff0 2a 20 7b 46 31 33 35 30 36 7d 20 54 68 65 20 5b * {F13506} The [
1a000 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 sqlite3_prepare
1a010 7c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 | SQL statement
1a020 63 6f 6d 70 69 6c 65 72 5d 20 72 65 63 6f 67 6e compiler] recogn
1a030 69 7a 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 izes.**
1a040 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 20 66 tokens of the f
1a050 6f 72 6d 73 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 orms "?", "?NNN"
1a060 2c 20 22 24 56 56 56 22 2c 20 22 3a 56 56 56 22 , "$VVV", ":VVV"
1a070 2c 20 61 6e 64 20 22 40 56 56 56 22 0a 2a 2a 20 , and "@VVV".**
1a080 20 20 20 20 20 20 20 20 20 61 73 20 53 51 4c 20 as SQL
1a090 70 61 72 61 6d 65 74 65 72 73 2c 20 77 68 65 72 parameters, wher
1a0a0 65 20 4e 4e 4e 20 69 73 20 61 6e 79 20 73 65 71 e NNN is any seq
1a0b0 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20 uence of one or
1a0c0 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 more.**
1a0d0 20 64 69 67 69 74 73 20 61 6e 64 20 77 68 65 72 digits and wher
1a0e0 65 20 56 56 56 20 69 73 20 61 6e 79 20 73 65 71 e VVV is any seq
1a0f0 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20 uence of one or
1a100 6d 6f 72 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 more .**
1a110 20 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 63 alphanumeric c
1a120 68 61 72 61 63 74 65 72 73 20 6f 72 20 22 3a 3a haracters or "::
1a130 22 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c " optionally fol
1a140 6c 6f 77 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 lowed by.**
1a150 20 20 20 20 20 61 20 73 74 72 69 6e 67 20 63 6f a string co
1a160 6e 74 61 69 6e 69 6e 67 20 6e 6f 20 73 70 61 63 ntaining no spac
1a170 65 73 20 61 6e 64 20 63 6f 6e 74 61 69 6e 65 64 es and contained
1a180 20 77 69 74 68 69 6e 20 70 61 72 65 6e 74 68 65 within parenthe
1a190 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 ses..**.** {F135
1a1a0 30 39 7d 20 54 68 65 20 69 6e 69 74 69 61 6c 20 09} The initial
1a1b0 76 61 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c 20 value of an SQL
1a1c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c parameter is NUL
1a1d0 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 31 32 L..**.** {F13512
1a1e0 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 } The index of a
1a1f0 6e 20 22 3f 22 20 53 51 4c 20 70 61 72 61 6d 65 n "?" SQL parame
1a200 74 65 72 20 69 73 20 6f 6e 65 20 6c 61 72 67 65 ter is one large
1a210 72 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20 20 20 r than the.**
1a220 20 20 20 20 20 20 20 6c 61 72 67 65 73 74 20 69 largest i
1a230 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61 ndex of SQL para
1a240 6d 65 74 65 72 20 74 6f 20 74 68 65 20 6c 65 66 meter to the lef
1a250 74 2c 20 6f 72 20 31 20 69 66 0a 2a 2a 20 20 20 t, or 1 if.**
1a260 20 20 20 20 20 20 20 74 68 65 20 22 3f 22 20 69 the "?" i
1a270 73 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 s the leftmost S
1a280 51 4c 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a QL parameter..**
1a290 0a 2a 2a 20 7b 46 31 33 35 31 35 7d 20 54 68 65 .** {F13515} The
1a2a0 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 4e index of an "?N
1a2b0 4e 4e 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 NN" SQL paramete
1a2c0 72 20 69 73 20 74 68 65 20 69 6e 74 65 67 65 72 r is the integer
1a2d0 20 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 NNN..**.** {F13
1a2e0 35 31 38 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 518} The index o
1a2f0 66 20 61 6e 20 22 3a 56 56 56 22 2c 20 22 24 56 f an ":VVV", "$V
1a300 56 56 22 2c 20 6f 72 20 22 40 56 56 56 22 20 53 VV", or "@VVV" S
1a310 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a QL parameter is.
1a320 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
1a330 73 61 6d 65 20 61 73 20 74 68 65 20 69 6e 64 65 same as the inde
1a340 78 20 6f 66 20 6c 65 66 74 6d 6f 73 74 20 6f 63 x of leftmost oc
1a350 63 75 72 61 6e 63 65 73 20 6f 66 20 74 68 65 20 curances of the
1a360 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 same.**
1a370 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 6f parameter, or o
1a380 6e 65 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 65 ne more than the
1a390 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f largest index o
1a3a0 76 65 72 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 ver all.**
1a3b0 20 20 20 20 70 61 72 61 6d 65 74 65 72 73 20 74 parameters t
1a3c0 6f 20 74 68 65 20 6c 65 66 74 20 69 66 20 74 68 o the left if th
1a3d0 69 73 20 69 73 20 74 68 65 20 66 69 72 73 74 20 is is the first
1a3e0 6f 63 63 75 72 72 61 6e 63 65 0a 2a 2a 20 20 20 occurrance.**
1a3f0 20 20 20 20 20 20 20 6f 66 20 74 68 69 73 20 70 of this p
1a400 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 31 20 69 arameter, or 1 i
1a410 66 20 74 68 69 73 20 69 73 20 74 68 65 20 6c 65 f this is the le
1a420 66 74 6d 6f 73 74 20 70 61 72 61 6d 65 74 65 72 ftmost parameter
1a430 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 31 7d ..**.** {F13521}
1a440 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 The [sqlite3_pr
1a450 65 70 61 72 65 20 7c 20 53 51 4c 20 73 74 61 74 epare | SQL stat
1a460 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 ement compiler]
1a470 66 61 69 6c 20 77 69 74 68 0a 2a 2a 20 20 20 20 fail with.**
1a480 20 20 20 20 20 20 61 6e 20 5b 53 51 4c 49 54 45 an [SQLITE
1a490 5f 52 41 4e 47 45 5d 20 65 72 72 6f 72 20 69 66 _RANGE] error if
1a4a0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e the index of an
1a4b0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 0a 2a SQL parameter.*
1a4c0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6c 65 * is le
1a4d0 73 73 20 74 68 61 6e 20 31 20 6f 72 20 67 72 65 ss than 1 or gre
1a4e0 61 74 65 72 20 74 68 61 6e 20 53 51 4c 49 54 45 ater than SQLITE
1a4f0 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 _MAX_VARIABLE_NU
1a500 4d 42 45 52 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 MBER..**.** {F13
1a510 35 32 34 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 524} Calls to [s
1a520 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
1a530 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 | sqlite3_bind(
1a540 53 2c 4e 2c 56 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 S,N,V,...)].**
1a550 20 20 20 20 20 20 20 20 61 73 73 6f 63 69 61 74 associat
1a560 65 20 74 68 65 20 76 61 6c 75 65 20 56 20 77 69 e the value V wi
1a570 74 68 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d th all SQL param
1a580 65 74 65 72 73 20 68 61 76 69 6e 67 20 61 6e 0a eters having an.
1a590 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 64 65 ** inde
1a5a0 78 20 6f 66 20 4e 20 69 6e 20 74 68 65 20 5b 70 x of N in the [p
1a5b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
1a5c0 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 t] S..**.** {F13
1a5d0 35 32 37 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 527} Calls to [s
1a5e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
1a5f0 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 | sqlite3_bind(
1a600 53 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 S,N,...)].**
1a610 20 20 20 20 20 20 6f 76 65 72 72 69 64 65 20 70 override p
1a620 72 69 6f 72 20 63 61 6c 6c 73 20 77 69 74 68 20 rior calls with
1a630 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 73 20 the same values
1a640 6f 66 20 53 20 61 6e 64 20 4e 2e 0a 2a 2a 0a 2a of S and N..**.*
1a650 2a 20 7b 46 31 33 35 33 30 7d 20 42 69 6e 64 69 * {F13530} Bindi
1a660 6e 67 73 20 65 73 74 61 62 6c 69 73 68 65 64 20 ngs established
1a670 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 by [sqlite3_bind
1a680 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33 5f _text | sqlite3_
1a690 62 69 6e 64 28 53 2c 2e 2e 2e 29 5d 0a 2a 2a 20 bind(S,...)].**
1a6a0 20 20 20 20 20 20 20 20 20 70 65 72 73 69 73 74 persist
1a6b0 20 61 63 72 6f 73 73 20 63 61 6c 6c 73 20 74 6f across calls to
1a6c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
1a6d0 53 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 S)]..**.** {F135
1a6e0 33 33 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 33} In calls to
1a6f0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
1a700 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a ob(S,N,V,L,D)],.
1a710 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
1a720 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 ite3_bind_text(S
1a730 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a ,N,V,L,D)], or.*
1a740 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
1a750 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 te3_bind_text16(
1a760 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69 S,N,V,L,D)] SQLi
1a770 74 65 20 62 69 6e 64 73 20 74 68 65 20 66 69 72 te binds the fir
1a780 73 74 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 st L.**
1a790 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 62 6c bytes of the bl
1a7a0 6f 62 20 6f 72 20 73 74 72 69 6e 67 20 70 6f 69 ob or string poi
1a7b0 6e 74 65 64 20 74 6f 20 62 79 20 56 2c 20 77 68 nted to by V, wh
1a7c0 65 6e 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 en L.**
1a7d0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 is non-negative
1a7e0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 36 7d ..**.** {F13536}
1a7f0 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 In calls to [sq
1a800 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 lite3_bind_text(
1a810 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 6f 72 0a 2a S,N,V,L,D)] or.*
1a820 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
1a830 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 te3_bind_text16(
1a840 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69 S,N,V,L,D)] SQLi
1a850 74 65 20 62 69 6e 64 73 20 63 68 61 72 61 63 74 te binds charact
1a860 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ers.**
1a870 66 72 6f 6d 20 56 20 74 68 72 6f 75 67 68 20 74 from V through t
1a880 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 he first zero ch
1a890 61 72 61 63 74 65 72 20 77 68 65 6e 20 4c 20 69 aracter when L i
1a8a0 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a s negative..**.*
1a8b0 2a 20 7b 46 31 33 35 33 39 7d 20 49 6e 20 63 61 * {F13539} In ca
1a8c0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
1a8d0 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c bind_blob(S,N,V,
1a8e0 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 L,D)],.**
1a8f0 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 [sqlite3_bind
1a900 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 _text(S,N,V,L,D)
1a910 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 ], or.**
1a920 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f [sqlite3_bind_
1a930 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 text16(S,N,V,L,D
1a940 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74 68 65 )] when D is the
1a950 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20 special.**
1a960 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53 constant [S
1a970 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 53 QLITE_STATIC], S
1a980 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 QLite assumes th
1a990 61 74 20 74 68 65 20 76 61 6c 75 65 20 56 0a 2a at the value V.*
1a9a0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 68 65 * is he
1a9b0 6c 64 20 69 6e 20 73 74 61 74 69 63 20 75 6e 6d ld in static unm
1a9c0 61 6e 61 67 65 64 20 73 70 61 63 65 20 74 68 61 anaged space tha
1a9d0 74 20 77 69 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 t will not chang
1a9e0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 75 e.** du
1a9f0 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d ring the lifetim
1aa00 65 20 6f 66 20 74 68 65 20 62 69 6e 64 69 6e 67 e of the binding
1aa10 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 32 7d ..**.** {F13542}
1aa20 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 In calls to [sq
1aa30 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 lite3_bind_blob(
1aa40 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 S,N,V,L,D)],.**
1aa50 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
1aa60 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 3_bind_text(S,N,
1aa70 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 V,L,D)], or.**
1aa80 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
1aa90 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e _bind_text16(S,N
1aaa0 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 ,V,L,D)] when D
1aab0 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a 2a is the special.*
1aac0 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74 * const
1aad0 61 6e 74 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e ant [SQLITE_TRAN
1aae0 53 49 45 4e 54 5d 2c 20 74 68 65 20 72 6f 75 74 SIENT], the rout
1aaf0 69 6e 65 20 6d 61 6b 65 73 20 61 20 0a 2a 2a 20 ine makes a .**
1ab00 20 20 20 20 20 20 20 20 20 70 72 69 76 61 74 65 private
1ab10 20 63 6f 70 79 20 6f 66 20 56 20 76 61 6c 75 65 copy of V value
1ab20 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 before it retur
1ab30 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 ns..**.** {F1354
1ab40 35 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 5} In calls to [
1ab50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
1ab60 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a b(S,N,V,L,D)],.*
1ab70 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
1ab80 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c te3_bind_text(S,
1ab90 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a N,V,L,D)], or.**
1aba0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
1abb0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 e3_bind_text16(S
1abc0 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 ,N,V,L,D)] when
1abd0 44 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 D is a pointer t
1abe0 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 o.** a
1abf0 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 function, SQLite
1ac00 20 69 6e 76 6f 6b 65 73 20 74 68 61 74 20 66 75 invokes that fu
1ac10 6e 63 74 69 6f 6e 20 74 6f 20 64 65 73 74 72 6f nction to destro
1ac20 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 y the.**
1ac30 20 20 56 20 76 61 6c 75 65 20 61 66 74 65 72 20 V value after
1ac40 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 it has finished
1ac50 75 73 69 6e 67 20 74 68 65 20 56 20 76 61 6c 75 using the V valu
1ac60 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 38 e..**.** {F13548
1ac70 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 } In calls to [s
1ac80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f qlite3_bind_zero
1ac90 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 29 5d 20 74 blob(S,N,V,L)] t
1aca0 68 65 20 76 61 6c 75 65 20 62 6f 75 6e 64 0a 2a he value bound.*
1acb0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 61 20 * is a
1acc0 62 6c 6f 62 20 6f 66 20 4c 20 62 79 74 65 73 2c blob of L bytes,
1acd0 20 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 or a zero-lengt
1ace0 68 20 62 6c 6f 62 20 69 66 20 4c 20 69 73 20 6e h blob if L is n
1acf0 65 67 61 74 69 76 65 2e 0a 2a 2f 0a 69 6e 74 20 egative..*/.int
1ad00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
1ad10 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c b(sqlite3_stmt*,
1ad20 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 int, const void
1ad30 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a *, int n, void(*
1ad40 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 )(void*));.int s
1ad50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 qlite3_bind_doub
1ad60 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a le(sqlite3_stmt*
1ad70 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a , int, double);.
1ad80 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
1ad90 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d _int(sqlite3_stm
1ada0 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 t*, int, int);.i
1adb0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
1adc0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 int64(sqlite3_st
1add0 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 mt*, int, sqlite
1ade0 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 3_int64);.int sq
1adf0 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 lite3_bind_null(
1ae00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
1ae10 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 nt);.int sqlite3
1ae20 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 _bind_text(sqlit
1ae30 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 e3_stmt*, int, c
1ae40 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 onst char*, int
1ae50 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a n, void(*)(void*
1ae60 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f ));.int sqlite3_
1ae70 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 bind_text16(sqli
1ae80 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
1ae90 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
1aea0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 , void(*)(void*)
1aeb0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 );.int sqlite3_b
1aec0 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 ind_value(sqlite
1aed0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 3_stmt*, int, co
1aee0 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 nst sqlite3_valu
1aef0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 e*);.int sqlite3
1af00 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 _bind_zeroblob(s
1af10 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
1af20 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a t, int n);../*.*
1af30 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 * CAPI3REF: Numb
1af40 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 er Of SQL Parame
1af50 74 65 72 73 20 7b 46 31 33 36 30 30 7d 0a 2a 2a ters {F13600}.**
1af60 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
1af70 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
1af80 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 find the number
1af90 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 of SQL parameter
1afa0 73 0a 2a 2a 20 69 6e 20 61 20 70 72 65 70 61 72 s.** in a prepar
1afb0 65 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 ed statement. S
1afc0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 QL parameters ar
1afd0 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a e tokens of the.
1afe0 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e ** form "?", "?N
1aff0 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 NN", ":AAA", "$A
1b000 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 AA", or "@AAA" t
1b010 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 hat serve as.**
1b020 70 6c 61 63 65 2d 68 6f 6c 64 65 72 73 20 66 6f place-holders fo
1b030 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 r values that ar
1b040 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f e [sqlite3_bind_
1b050 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a blob | bound].**
1b060 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 to the paramete
1b070 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 rs at a later ti
1b080 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 me..**.** This r
1b090 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 outine actually
1b0a0 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 returns the inde
1b0b0 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 x of the largest
1b0c0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 46 parameter..** F
1b0d0 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 or all forms exc
1b0e0 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 ept ?NNN, this w
1b0f0 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 ill correspond t
1b100 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a o the number of.
1b110 2a 2a 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 ** unique parame
1b120 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 ters. If parame
1b130 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e ters of the ?NNN
1b140 20 61 72 65 20 75 73 65 64 2c 20 74 68 65 72 65 are used, there
1b150 20 6d 61 79 0a 2a 2a 20 62 65 20 67 61 70 73 20 may.** be gaps
1b160 69 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a in the list..**.
1b170 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
1b180 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c lite3_bind_blob|
1b190 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c sqlite3_bind()],
1b1a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
1b1b0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
1b1c0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
1b1d0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
1b1e0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a ter_index()]..**
1b1f0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
1b200 2a 2a 0a 2a 2a 20 7b 46 31 33 36 30 31 7d 20 54 **.** {F13601} T
1b210 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 he [sqlite3_bind
1b220 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 _parameter_count
1b230 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 (S)] interface r
1b240 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 eturns.**
1b250 20 20 20 74 68 65 20 6c 61 72 67 65 73 74 20 69 the largest i
1b260 6e 64 65 78 20 6f 66 20 61 6c 6c 20 53 51 4c 20 ndex of all SQL
1b270 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 74 68 parameters in th
1b280 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 e.** [p
1b290 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
1b2a0 74 5d 20 53 2c 20 6f 72 20 30 20 69 66 20 53 0a t] S, or 0 if S.
1b2b0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 ** cont
1b2c0 61 69 6e 73 20 6e 6f 20 53 51 4c 20 70 61 72 61 ains no SQL para
1b2d0 6d 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e 74 20 73 meters..*/.int s
1b2e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
1b2f0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 meter_count(sqli
1b300 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a te3_stmt*);../*.
1b310 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d ** CAPI3REF: Nam
1b320 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 e Of A Host Para
1b330 6d 65 74 65 72 20 7b 46 31 33 36 32 30 7d 0a 2a meter {F13620}.*
1b340 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
1b350 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e e returns a poin
1b360 74 65 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 20 ter to the name
1b370 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20 53 of the n-th.** S
1b380 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 QL parameter in
1b390 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
1b3a0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70 ement]..** SQL p
1b3b0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 arameters of the
1b3c0 20 66 6f 72 6d 20 22 3a 41 41 41 22 20 6f 72 20 form ":AAA" or
1b3d0 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 "@AAA" or "$AAA"
1b3e0 20 68 61 76 65 20 61 20 6e 61 6d 65 0a 2a 2a 20 have a name.**
1b3f0 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 which is the str
1b400 69 6e 67 20 22 3a 41 41 41 22 20 6f 72 20 22 40 ing ":AAA" or "@
1b410 41 41 41 22 20 6f 72 20 22 24 56 56 56 22 2e 20 AAA" or "$VVV".
1b420 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 .** In other wor
1b430 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 ds, the initial
1b440 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 ":" or "$" or "@
1b450 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 ".** is included
1b460 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 as part of the
1b470 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 name..** Paramet
1b480 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 ers of the form
1b490 22 3f 22 20 6f 72 20 22 3f 4e 4e 4e 22 20 68 61 "?" or "?NNN" ha
1b4a0 76 65 20 6e 6f 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a ve no name..**.*
1b4b0 2a 20 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 * The first host
1b4c0 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 parameter has a
1b4d0 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f n index of 1, no
1b4e0 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 t 0..**.** If th
1b4f0 65 20 76 61 6c 75 65 20 6e 20 69 73 20 6f 75 74 e value n is out
1b500 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 of range or if
1b510 74 68 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 the n-th paramet
1b520 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 er is.** nameles
1b530 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 s, then NULL is
1b540 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 72 returned. The r
1b550 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 eturned string i
1b560 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 74 s.** always in t
1b570 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e he UTF-8 encodin
1b580 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 g even if the na
1b590 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 med parameter wa
1b5a0 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 s.** originally
1b5b0 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 specified as UTF
1b5c0 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f -16 in [sqlite3_
1b5d0 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a prepare16()] or.
1b5e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
1b5f0 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a are16_v2()]..**.
1b600 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
1b610 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c lite3_bind_blob|
1b620 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c sqlite3_bind()],
1b630 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
1b640 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e d_parameter_coun
1b650 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 t()], and.** [sq
1b660 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
1b670 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a eter_index()]..*
1b680 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
1b690 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 32 31 7d 20 .**.** {F13621}
1b6a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e The [sqlite3_bin
1b6b0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
1b6c0 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 (S,N)] interface
1b6d0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 returns.**
1b6e0 20 20 20 20 20 61 20 55 54 46 2d 38 20 72 65 6e a UTF-8 ren
1b6f0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 6e 61 dering of the na
1b700 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 me of the SQL pa
1b710 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 20 20 rameter in.**
1b720 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 [prepared
1b730 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 statement] S ha
1b740 76 69 6e 67 20 69 6e 64 65 78 20 4e 2c 20 6f 72 ving index N, or
1b750 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 55 4c .** NUL
1b760 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f L if there is no
1b770 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 77 SQL parameter w
1b780 69 74 68 20 69 6e 64 65 78 20 4e 20 6f 72 20 69 ith index N or i
1b790 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 f the.**
1b7a0 20 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 parameter with
1b7b0 20 69 6e 64 65 78 20 4e 20 69 73 20 61 6e 20 61 index N is an a
1b7c0 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 nonymous paramet
1b7d0 65 72 20 22 3f 22 20 6f 72 0a 2a 2a 20 20 20 20 er "?" or.**
1b7e0 20 20 20 20 20 20 61 20 6e 75 6d 62 65 72 65 64 a numbered
1b7f0 20 70 61 72 61 6d 65 74 65 72 20 22 3f 4e 4e 4e parameter "?NNN
1b800 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 "..*/.const char
1b810 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 *sqlite3_bind_p
1b820 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 arameter_name(sq
1b830 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
1b840 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1b850 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 EF: Index Of A P
1b860 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 arameter With A
1b870 47 69 76 65 6e 20 4e 61 6d 65 20 7b 46 31 33 36 Given Name {F136
1b880 34 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 40}.**.** Return
1b890 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e the index of an
1b8a0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 SQL parameter g
1b8b0 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 iven its name.
1b8c0 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c The.** index val
1b8d0 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 ue returned is s
1b8e0 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 uitable for use
1b8f0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a as the second.**
1b900 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 parameter to [s
1b910 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
1b920 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d |sqlite3_bind()]
1b930 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 . A zero.** is
1b940 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d returned if no m
1b950 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 atching paramete
1b960 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 54 68 65 r is found. The
1b970 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 parameter.** na
1b980 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e me must be given
1b990 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 in UTF-8 even i
1b9a0 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 f the original s
1b9b0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 tatement.** was
1b9c0 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 prepared from UT
1b9d0 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 F-16 text using
1b9e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1b9f0 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 16_v2()]..**.**
1ba00 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
1ba10 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c e3_bind_blob|sql
1ba20 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a ite3_bind()],.**
1ba30 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
1ba40 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 arameter_count()
1ba50 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 ], and.** [sqlit
1ba60 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
1ba70 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a r_index()]..**.*
1ba80 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
1ba90 0a 2a 2a 20 7b 46 31 33 36 34 31 7d 20 54 68 65 .** {F13641} The
1baa0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
1bab0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 53 arameter_index(S
1bac0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 ,N)] interface r
1bad0 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 eturns.**
1bae0 20 20 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 the index of
1baf0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e SQL parameter in
1bb00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
1bb10 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 ment].**
1bb20 20 20 53 20 77 68 6f 73 65 20 6e 61 6d 65 20 6d S whose name m
1bb30 61 74 63 68 65 73 20 74 68 65 20 55 54 46 2d 38 atches the UTF-8
1bb40 20 73 74 72 69 6e 67 20 4e 2c 20 6f 72 20 30 20 string N, or 0
1bb50 69 66 20 74 68 65 72 65 20 69 73 0a 2a 2a 20 20 if there is.**
1bb60 20 20 20 20 20 20 20 20 6e 6f 20 6d 61 74 63 68 no match
1bb70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
1bb80 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
1bb90 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 index(sqlite3_st
1bba0 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 mt*, const char
1bbb0 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *zName);../*.**
1bbc0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 CAPI3REF: Reset
1bbd0 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 All Bindings On
1bbe0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
1bbf0 6d 65 6e 74 20 7b 46 31 33 36 36 30 7d 0a 2a 2a ment {F13660}.**
1bc00 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20 74 6f 20 .** Contrary to
1bc10 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 the intuition of
1bc20 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f many, [sqlite3_
1bc30 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f reset()] does no
1bc40 74 0a 2a 2a 20 72 65 73 65 74 20 74 68 65 20 5b t.** reset the [
1bc50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
1bc60 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e b | bindings] on
1bc70 20 61 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 a .** [prepared
1bc80 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 55 73 statement]. Us
1bc90 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 e this routine t
1bca0 6f 0a 2a 2a 20 72 65 73 65 74 20 61 6c 6c 20 68 o.** reset all h
1bcb0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 ost parameters t
1bcc0 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e o NULL..**.** IN
1bcd0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
1bce0 7b 46 31 33 36 36 31 7d 20 54 68 65 20 5b 73 71 {F13661} The [sq
1bcf0 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 lite3_clear_bind
1bd00 69 6e 67 73 28 53 29 5d 20 69 6e 74 65 72 66 61 ings(S)] interfa
1bd10 63 65 20 72 65 73 65 74 73 20 61 6c 6c 0a 2a 2a ce resets all.**
1bd20 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 70 61 SQL pa
1bd30 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 73 rameter bindings
1bd40 20 69 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74 in [prepared st
1bd50 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 atement] S.**
1bd60 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f 20 4e back to N
1bd70 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ULL..*/.int sqli
1bd80 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e te3_clear_bindin
1bd90 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a gs(sqlite3_stmt*
1bda0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1bdb0 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f EF: Number Of Co
1bdc0 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c lumns In A Resul
1bdd0 74 20 53 65 74 20 7b 46 31 33 37 31 30 7d 0a 2a t Set {F13710}.*
1bde0 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 *.** Return the
1bdf0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e number of column
1be00 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 s in the result
1be10 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 set returned by
1be20 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the .** [prepare
1be30 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68 d statement]. Th
1be40 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 is routine retur
1be50 6e 73 20 30 0a 2a 2a 20 69 66 20 70 53 74 6d 74 ns 0.** if pStmt
1be60 20 69 73 20 61 6e 20 53 51 4c 20 73 74 61 74 65 is an SQL state
1be70 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e ment that does n
1be80 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 ot return data (
1be90 66 6f 72 20 0a 2a 2a 20 65 78 61 6d 70 6c 65 20 for .** example
1bea0 61 6e 20 55 50 44 41 54 45 29 2e 0a 2a 2a 0a 2a an UPDATE)..**.*
1beb0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
1bec0 0a 2a 2a 20 7b 46 31 33 37 31 31 7d 20 54 68 65 .** {F13711} The
1bed0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
1bee0 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72 _count(S)] inter
1bef0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 face returns the
1bf00 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 number of.**
1bf10 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 73 20 69 columns i
1bf20 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 n the result set
1bf30 20 67 65 6e 65 72 61 74 65 64 20 62 79 20 74 68 generated by th
1bf40 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 e.** [p
1bf50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
1bf60 74 5d 20 53 2c 20 6f 72 20 30 20 69 66 20 53 20 t] S, or 0 if S
1bf70 64 6f 65 73 20 6e 6f 74 20 67 65 6e 65 72 61 74 does not generat
1bf80 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 e.** a
1bf90 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69 result set..*/.i
1bfa0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nt sqlite3_colum
1bfb0 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f n_count(sqlite3_
1bfc0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f stmt *pStmt);../
1bfd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
1bfe0 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 olumn Names In A
1bff0 20 52 65 73 75 6c 74 20 53 65 74 20 7b 46 31 33 Result Set {F13
1c000 37 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 720}.**.** These
1c010 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
1c020 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e the name assign
1c030 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c ed to a particul
1c040 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 ar column.** in
1c050 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f the result set o
1c060 66 20 61 20 53 45 4c 45 43 54 20 73 74 61 74 65 f a SELECT state
1c070 6d 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 ment. The sqlit
1c080 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 e3_column_name()
1c090 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 .** interface re
1c0a0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
1c0b0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e to a zero-termin
1c0c0 61 74 65 64 20 55 54 46 38 20 73 74 72 69 6e 67 ated UTF8 string
1c0d0 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f .** and sqlite3_
1c0e0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 column_name16()
1c0f0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
1c100 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d r to a zero-term
1c110 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 31 36 20 inated.** UTF16
1c120 73 74 72 69 6e 67 2e 20 20 54 68 65 20 66 69 72 string. The fir
1c130 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 st parameter is
1c140 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 the.** [prepared
1c150 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 statement] that
1c160 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 implements the
1c170 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 SELECT statement
1c180 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 ..** The second
1c190 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
1c1a0 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 column number.
1c1b0 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 The left-most c
1c1c0 6f 6c 75 6d 6e 20 69 73 0a 2a 2a 20 6e 75 6d 62 olumn is.** numb
1c1d0 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 er 0..**.** The
1c1e0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 returned string
1c1f0 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 pointer is valid
1c200 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 until either th
1c210 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 e .** [prepared
1c220 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 statement] is de
1c230 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 stroyed by [sqli
1c240 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a te3_finalize()].
1c250 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 ** or until the
1c260 6e 65 78 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 next call sqlite
1c270 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 3_column_name()
1c280 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d or sqlite3_colum
1c290 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a 2a 20 6f 6e n_name16().** on
1c2a0 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e the same column
1c2b0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74 ..**.** If sqlit
1c2c0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c e3_malloc() fail
1c2d0 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f s during the pro
1c2e0 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 cessing of eithe
1c2f0 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f r routine.** (fo
1c300 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 r example during
1c310 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 a conversion fr
1c320 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d om UTF-8 to UTF-
1c330 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 16) then a.** NU
1c340 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 LL pointer is re
1c350 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 turned..**.** Th
1c360 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 e name of a resu
1c370 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 lt column is the
1c380 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 value of the "A
1c390 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a S" clause for.**
1c3a0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 that column, if
1c3b0 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 there is an AS
1c3c0 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 clause. If ther
1c3d0 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 e is no AS claus
1c3e0 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 e.** then the na
1c3f0 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e me of the column
1c400 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 is unspecified
1c410 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 and may change f
1c420 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 rom.** one relea
1c430 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 se of SQLite to
1c440 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 the next..**.**
1c450 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
1c460 2a 20 7b 46 31 33 37 32 31 7d 20 41 20 73 75 63 * {F13721} A suc
1c470 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 cessful invocati
1c480 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 on of the [sqlit
1c490 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 e3_column_name(S
1c4a0 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 ,N)].**
1c4b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
1c4c0 6e 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 ns the name.**
1c4d0 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 4e of the N
1c4e0 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65 th column (where
1c4f0 20 30 20 69 73 20 74 68 65 20 6c 65 66 74 2d 6d 0 is the left-m
1c500 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 ost column) for
1c510 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
1c520 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 result set of [p
1c530 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
1c540 74 5d 20 53 20 61 73 20 61 0a 2a 2a 20 20 20 20 t] S as a.**
1c550 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 zero-termi
1c560 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 nated UTF-8 stri
1c570 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 ng..**.** {F1372
1c580 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 3} A successful
1c590 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 invocation of th
1c5a0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d e [sqlite3_colum
1c5b0 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 0a 2a n_name16(S,N)].*
1c5c0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 * inter
1c5d0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 face returns the
1c5e0 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 name.**
1c5f0 20 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f 6c of the Nth col
1c600 75 6d 6e 20 28 77 68 65 72 65 20 30 20 69 73 20 umn (where 0 is
1c610 74 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f the left-most co
1c620 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65 0a 2a 2a lumn) for the.**
1c630 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 result
1c640 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 set of [prepare
1c650 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 d statement] S a
1c660 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 s a.**
1c670 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
1c680 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e UTF-16 string in
1c690 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 the native byte
1c6a0 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 order..**.** {F
1c6b0 31 33 37 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 13724} The [sqli
1c6c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 te3_column_name(
1c6d0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
1c6e0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 5d column_name16()]
1c6f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 .** int
1c700 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 61 erfaces return a
1c710 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 NULL pointer if
1c720 20 74 68 65 79 20 61 72 65 20 75 6e 61 62 6c 65 they are unable
1c730 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 to.**
1c740 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 allocate memory
1c750 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 memory to hold t
1c760 68 65 72 65 20 6e 6f 72 6d 61 6c 20 72 65 74 75 here normal retu
1c770 72 6e 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 0a 2a rn strings..**.*
1c780 2a 20 7b 46 31 33 37 32 35 7d 20 49 66 20 74 68 * {F13725} If th
1c790 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f e N parameter to
1c7a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
1c7b0 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a _name(S,N)] or.*
1c7c0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
1c7d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 te3_column_name1
1c7e0 36 28 53 2c 4e 29 5d 20 69 73 20 6f 75 74 20 6f 6(S,N)] is out o
1c7f0 66 20 72 61 6e 67 65 2c 20 74 68 65 6e 20 74 68 f range, then th
1c800 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e e.** in
1c810 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 73 terfaces returns
1c820 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
1c830 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 33 37 32 36 7d .** .** {F13726}
1c840 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 The strings ret
1c850 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 urned by [sqlite
1c860 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 3_column_name(S,
1c870 4e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 N)] and.**
1c880 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c [sqlite3_col
1c890 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d umn_name16(S,N)]
1c8a0 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c are valid until
1c8b0 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 20 20 20 the next.**
1c8c0 20 20 20 20 20 20 63 61 6c 6c 20 74 6f 20 65 69 call to ei
1c8d0 74 68 65 72 20 72 6f 75 74 69 6e 65 20 77 69 74 ther routine wit
1c8e0 68 20 74 68 65 20 73 61 6d 65 20 53 20 61 6e 64 h the same S and
1c8f0 20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a N parameters.**
1c900 20 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74 or unt
1c910 69 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 il [sqlite3_fina
1c920 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c lize(S)] is call
1c930 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 ed..**.** {F1372
1c940 37 7d 20 57 68 65 6e 20 61 20 72 65 73 75 6c 74 7} When a result
1c950 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b 53 45 column of a [SE
1c960 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 LECT] statement
1c970 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 contains.**
1c980 20 20 20 20 20 61 6e 20 41 53 20 63 6c 61 75 73 an AS claus
1c990 65 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 e, the name of t
1c9a0 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 hat column is th
1c9b0 65 20 69 6e 64 65 6e 74 69 66 69 65 72 0a 2a 2a e indentifier.**
1c9c0 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 to the
1c9d0 20 72 69 67 68 74 20 6f 66 20 74 68 65 20 41 53 right of the AS
1c9e0 20 6b 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63 6f 6e keyword..*/.con
1c9f0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
1ca00 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c _column_name(sql
1ca10 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
1ca20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a N);.const void *
1ca30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e sqlite3_column_n
1ca40 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ame16(sqlite3_st
1ca50 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a mt*, int N);../*
1ca60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f .** CAPI3REF: So
1ca70 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 urce Of Data In
1ca80 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b A Query Result {
1ca90 46 31 33 37 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 F13740}.**.** Th
1caa0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f ese routines pro
1cab0 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 vide a means to
1cac0 64 65 74 65 72 6d 69 6e 65 20 77 68 61 74 20 63 determine what c
1cad0 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a olumn of what.**
1cae0 20 74 61 62 6c 65 20 69 6e 20 77 68 69 63 68 20 table in which
1caf0 64 61 74 61 62 61 73 65 20 61 20 72 65 73 75 6c database a resul
1cb00 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74 t of a SELECT st
1cb10 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 atement comes fr
1cb20 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 om..** The name
1cb30 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 of the database
1cb40 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 or table or colu
1cb50 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e mn can be return
1cb60 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 ed as.** either
1cb70 61 20 55 54 46 38 20 6f 72 20 55 54 46 31 36 20 a UTF8 or UTF16
1cb80 73 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 string. The _da
1cb90 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 tabase_ routines
1cba0 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 return.** the d
1cbb0 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 atabase name, th
1cbc0 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e e _table_ routin
1cbd0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 es return the ta
1cbe0 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a ble name, and.**
1cbf0 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 the origin_ rou
1cc00 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 tines return the
1cc10 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a column name..**
1cc20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 The returned st
1cc30 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e ring is valid un
1cc40 74 69 6c 0a 2a 2a 20 74 68 65 20 5b 70 72 65 70 til.** the [prep
1cc50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
1cc60 69 73 20 64 65 73 74 72 6f 79 65 64 20 75 73 69 is destroyed usi
1cc70 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 ng.** [sqlite3_f
1cc80 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e inalize()] or un
1cc90 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 til the same inf
1cca0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 ormation is requ
1ccb0 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 ested.** again i
1ccc0 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e n a different en
1ccd0 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 coding..**.** Th
1cce0 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 e names returned
1ccf0 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 are the origina
1cd00 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d l un-aliased nam
1cd10 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 es of the.** dat
1cd20 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e abase, table, an
1cd30 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 d column..**.**
1cd40 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
1cd50 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 nt to the follow
1cd60 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61 20 5b ing calls is a [
1cd70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1cd80 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 66 75 nt]..** These fu
1cd90 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 nctions return i
1cda0 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 nformation about
1cdb0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
1cdc0 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 returned by .**
1cdd0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 the statement, w
1cde0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 here N is the se
1cdf0 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 cond function ar
1ce00 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 gument..**.** If
1ce10 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
1ce20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 returned by the
1ce30 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 statement is an
1ce40 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 6f 72 expression.** or
1ce50 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 subquery and is
1ce60 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 not a column va
1ce70 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 lue, then all of
1ce80 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 these functions
1ce90 0a 2a 2a 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e .** return NULL.
1cea0 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 These routine
1ceb0 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 might also retur
1cec0 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f n NULL if a memo
1ced0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e ry.** allocation
1cee0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 error occurs.
1cef0 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 Otherwise, they
1cf00 72 65 74 75 72 6e 20 74 68 65 20 0a 2a 2a 20 6e return the .** n
1cf10 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 ame of the attac
1cf20 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 hed database, ta
1cf30 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74 ble and column t
1cf40 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 hat query result
1cf50 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 .** column was e
1cf60 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a xtracted from..*
1cf70 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20 61 6c 6c *.** As with all
1cf80 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 other SQLite AP
1cf90 49 73 2c 20 74 68 6f 73 65 20 70 6f 73 74 66 69 Is, those postfi
1cfa0 78 65 64 20 77 69 74 68 20 22 31 36 22 20 72 65 xed with "16" re
1cfb0 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 turn.** UTF-16 e
1cfc0 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 2c 20 ncoded strings,
1cfd0 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 the other functi
1cfe0 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 ons return UTF-8
1cff0 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 . {END}.**.** Th
1d000 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c ese APIs are onl
1d010 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 y available if t
1d020 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 he library was c
1d030 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 ompiled with the
1d040 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42 .** SQLITE_ENAB
1d050 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 LE_COLUMN_METADA
1d060 54 41 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 TA preprocessor
1d070 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a symbol defined..
1d080 2a 2a 0a 2a 2a 20 7b 55 31 33 37 35 31 7d 0a 2a **.** {U13751}.*
1d090 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 * If two or more
1d0a0 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e threads call on
1d0b0 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 e or more of the
1d0c0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 se routines agai
1d0d0 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 nst the same.**
1d0e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1d0f0 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 nt and column at
1d100 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 the same time t
1d110 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 hen the results
1d120 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 are.** undefined
1d130 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
1d140 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 34 TS:.**.** {F1374
1d150 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 1} The [sqlite3_
1d160 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f column_database_
1d170 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 name(S,N)] inter
1d180 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 face returns eit
1d190 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 her.**
1d1a0 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 the UTF-8 zero-t
1d1b0 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f erminated name o
1d1c0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 f the database f
1d1d0 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a rom which the .*
1d1e0 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 * Nth r
1d1f0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 esult column of
1d200 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
1d210 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20 ent] S .**
1d220 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65 64 is extracted
1d230 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 , or NULL if the
1d240 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
1d250 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20 of S is a.**
1d260 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78 general ex
1d270 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 pression or if u
1d280 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 nable to allocat
1d290 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 e memory.**
1d2a0 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68 to store th
1d2b0 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20 e name..**
1d2c0 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 32 7d .** {F13742}
1d2d0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f The [sqlite3_co
1d2e0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 lumn_database_na
1d2f0 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 me16(S,N)] inter
1d300 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 face returns eit
1d310 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 her.**
1d320 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 the UTF-16 nativ
1d330 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 e byte order.**
1d340 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 zero-te
1d350 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 rminated name of
1d360 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72 the database fr
1d370 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a 2a om which the .**
1d380 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 Nth re
1d390 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b sult column of [
1d3a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1d3b0 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20 20 nt] S .**
1d3c0 20 20 20 69 73 20 65 78 74 72 61 63 74 65 64 2c is extracted,
1d3d0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 or NULL if the
1d3e0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f the Nth column o
1d3f0 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 f S is a.**
1d400 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78 70 general exp
1d410 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e ression or if un
1d420 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 able to allocate
1d430 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 memory.**
1d440 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65 to store the
1d450 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20 20 name..**
1d460 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 33 7d 20 .** {F13743}
1d470 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c The [sqlite3_col
1d480 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 53 umn_table_name(S
1d490 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 ,N)] interface r
1d4a0 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a eturns either.**
1d4b0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 the UT
1d4c0 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 F-8 zero-termina
1d4d0 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 ted name of the
1d4e0 74 61 62 6c 65 20 66 72 6f 6d 20 77 68 69 63 68 table from which
1d4f0 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 the .**
1d500 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c Nth result col
1d510 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64 umn of [prepared
1d520 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a statement] S .*
1d530 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 65 78 * is ex
1d540 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c tracted, or NULL
1d550 20 69 66 20 74 68 65 20 74 68 65 20 4e 74 68 20 if the the Nth
1d560 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 column of S is a
1d570 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e .** gen
1d580 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 eral expression
1d590 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 or if unable to
1d5a0 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a allocate memory.
1d5b0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73 ** to s
1d5c0 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a tore the name..*
1d5d0 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b * .** {
1d5e0 46 31 33 37 34 34 7d 20 54 68 65 20 5b 73 71 6c F13744} The [sql
1d5f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c ite3_column_tabl
1d600 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 e_name16(S,N)] i
1d610 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
1d620 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 either.**
1d630 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e the UTF-16 n
1d640 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
1d650 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 .** zer
1d660 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d o-terminated nam
1d670 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 66 e of the table f
1d680 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a rom which the .*
1d690 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 * Nth r
1d6a0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 esult column of
1d6b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
1d6c0 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20 ent] S .**
1d6d0 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65 64 is extracted
1d6e0 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 , or NULL if the
1d6f0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
1d700 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20 of S is a.**
1d710 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78 general ex
1d720 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 pression or if u
1d730 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 nable to allocat
1d740 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 e memory.**
1d750 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68 to store th
1d760 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20 e name..**
1d770 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 35 7d .** {F13745}
1d780 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f The [sqlite3_co
1d790 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 lumn_origin_name
1d7a0 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 (S,N)] interface
1d7b0 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a returns either.
1d7c0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
1d7d0 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 UTF-8 zero-termi
1d7e0 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 nated name of th
1d7f0 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 66 e table column f
1d800 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a rom which the .*
1d810 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 * Nth r
1d820 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 esult column of
1d830 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
1d840 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20 ent] S .**
1d850 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65 64 is extracted
1d860 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 , or NULL if the
1d870 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
1d880 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20 of S is a.**
1d890 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78 general ex
1d8a0 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 pression or if u
1d8b0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 nable to allocat
1d8c0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 e memory.**
1d8d0 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68 to store th
1d8e0 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20 e name..**
1d8f0 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 36 7d .** {F13746}
1d900 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f The [sqlite3_co
1d910 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 lumn_origin_name
1d920 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 16(S,N)] interfa
1d930 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 ce returns eithe
1d940 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 r.** th
1d950 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 e UTF-16 native
1d960 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 byte order.**
1d970 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d zero-term
1d980 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 inated name of t
1d990 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 he table column
1d9a0 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a from which the .
1d9b0 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 ** Nth
1d9c0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 result column of
1d9d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
1d9e0 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 ment] S .**
1d9f0 20 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65 is extracte
1da00 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 d, or NULL if th
1da10 65 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e e the Nth column
1da20 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 of S is a.**
1da30 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65 general e
1da40 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 xpression or if
1da50 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 unable to alloca
1da60 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 te memory.**
1da70 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 to store t
1da80 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 he name..**
1da90 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 38 .** {F13748
1daa0 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c } The return val
1dab0 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 ues from.**
1dac0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f [sqlite3_co
1dad0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 lumn_database_na
1dae0 6d 65 7c 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 me|column metada
1daf0 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a ta interfaces].*
1db00 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20 76 * are v
1db10 61 6c 69 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 alid.**
1db20 20 66 6f 72 20 74 68 65 20 6c 69 66 65 74 69 6d for the lifetim
1db30 65 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 e of the [prepar
1db40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a ed statement].**
1db50 20 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74 or unt
1db60 69 6c 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 il the encoding
1db70 69 73 20 63 68 61 6e 67 65 64 20 62 79 20 61 6e is changed by an
1db80 6f 74 68 65 72 20 6d 65 74 61 64 61 74 61 0a 2a other metadata.*
1db90 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 * inter
1dba0 66 61 63 65 20 63 61 6c 6c 20 66 6f 72 20 74 68 face call for th
1dbb0 65 20 73 61 6d 65 20 70 72 65 70 61 72 65 64 20 e same prepared
1dbc0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f statement and co
1dbd0 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 lumn..**.** LIMI
1dbe0 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b TATIONS:.**.** {
1dbf0 55 31 33 37 35 31 7d 20 49 66 20 74 77 6f 20 6f U13751} If two o
1dc00 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 r more threads c
1dc10 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a all one or more.
1dc20 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
1dc30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 ite3_column_data
1dc40 62 61 73 65 5f 6e 61 6d 65 7c 63 6f 6c 75 6d 6e base_name|column
1dc50 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 metadata interf
1dc60 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 aces].**
1dc70 20 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 the same [prep
1dc80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
1dc90 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d and result colum
1dca0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 74 n.** at
1dcb0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 the same time t
1dcc0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 hen the results
1dcd0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a are undefined..*
1dce0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 /.const char *sq
1dcf0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 lite3_column_dat
1dd00 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 abase_name(sqlit
1dd10 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 e3_stmt*,int);.c
1dd20 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
1dd30 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 e3_column_databa
1dd40 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 se_name16(sqlite
1dd50 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 3_stmt*,int);.co
1dd60 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
1dd70 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 3_column_table_n
1dd80 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ame(sqlite3_stmt
1dd90 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f *,int);.const vo
1dda0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 id *sqlite3_colu
1ddb0 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 mn_table_name16(
1ddc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
1ddd0 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a t);.const char *
1dde0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f sqlite3_column_o
1ddf0 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 rigin_name(sqlit
1de00 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 e3_stmt*,int);.c
1de10 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
1de20 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e e3_column_origin
1de30 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f _name16(sqlite3_
1de40 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a stmt*,int);../*.
1de50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 ** CAPI3REF: Dec
1de60 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f lared Datatype O
1de70 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 f A Query Result
1de80 20 7b 46 31 33 37 36 30 7d 0a 2a 2a 0a 2a 2a 20 {F13760}.**.**
1de90 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 The first parame
1dea0 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 ter is a [prepar
1deb0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 0a ed statement]. .
1dec0 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 ** If this state
1ded0 6d 65 6e 74 20 69 73 20 61 20 53 45 4c 45 43 54 ment is a SELECT
1dee0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 statement and t
1def0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 he Nth column of
1df00 20 74 68 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 the .** returne
1df10 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 d result set of
1df20 74 68 61 74 20 53 45 4c 45 43 54 20 69 73 20 61 that SELECT is a
1df30 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e table column (n
1df40 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 ot an.** express
1df50 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 ion or subquery)
1df60 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 then the declar
1df70 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 ed type of the t
1df80 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 able.** column i
1df90 73 20 72 65 74 75 72 6e 65 64 2e 20 20 49 66 20 s returned. If
1dfa0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f the Nth column o
1dfb0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 f the result set
1dfc0 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 is an.** expres
1dfd0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 sion or subquery
1dfe0 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f , then a NULL po
1dff0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 inter is returne
1e000 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e d..** The return
1e010 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 ed string is alw
1e020 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 ays UTF-8 encode
1e030 64 2e 20 20 7b 45 4e 44 7d 20 0a 2a 2a 20 46 6f d. {END} .** Fo
1e040 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 74 68 r example, in th
1e050 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d e database schem
1e060 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 a:.**.** CREATE
1e070 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 TABLE t1(c1 VARI
1e080 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 41 6e 64 20 ANT);.**.** And
1e090 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 the following st
1e0a0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 64 atement compiled
1e0b0 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 :.**.** SELECT c
1e0c0 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 1 + 1, c1 FROM t
1e0d0 31 3b 0a 2a 2a 0a 2a 2a 20 54 68 65 6e 20 74 68 1;.**.** Then th
1e0e0 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 is routine would
1e0f0 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 return the stri
1e100 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 ng "VARIANT" for
1e110 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 72 the second.** r
1e120 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d esult column (i=
1e130 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 =1), and a NULL
1e140 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 pointer for the
1e150 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c first result col
1e160 75 6d 6e 0a 2a 2a 20 28 69 3d 3d 30 29 2e 0a 2a umn.** (i==0)..*
1e170 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 *.** SQLite uses
1e180 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d dynamic run-tim
1e190 65 20 74 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75 e typing. So ju
1e1a0 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c st because a col
1e1b0 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 umn.** is declar
1e1c0 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 ed to contain a
1e1d0 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 particular type
1e1e0 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 does not mean th
1e1f0 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 at the.** data s
1e200 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f tored in that co
1e210 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 lumn is of the d
1e220 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 eclared type. S
1e230 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f QLite is.** stro
1e240 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 ngly typed, but
1e250 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 the typing is dy
1e260 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 namic not static
1e270 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 . Type.** is as
1e280 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e sociated with in
1e290 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c dividual values,
1e2a0 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f not with the co
1e2b0 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 ntainers.** used
1e2c0 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 to hold those v
1e2d0 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 alues..**.** INV
1e2e0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
1e2f0 46 31 33 37 36 31 7d 20 20 41 20 73 75 63 63 65 F13761} A succe
1e300 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 ssful call to [s
1e310 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 qlite3_column_de
1e320 63 6c 74 79 70 65 28 53 2c 4e 29 5d 0a 2a 2a 20 cltype(S,N)].**
1e330 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e return
1e340 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 s a zero-termina
1e350 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 ted UTF-8 string
1e360 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a containing the.
1e370 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65 ** the
1e380 20 64 65 63 6c 61 72 65 64 20 64 61 74 61 74 79 declared dataty
1e390 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 pe of the table
1e3a0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 70 65 column that appe
1e3b0 61 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ars.**
1e3c0 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 as the Nth colu
1e3d0 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20 66 72 6f mn (numbered fro
1e3e0 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65 73 75 m 0) of the resu
1e3f0 6c 74 20 73 65 74 20 74 6f 20 74 68 65 0a 2a 2a lt set to the.**
1e400 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 [prep
1e410 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
1e420 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36 32 S..**.** {F13762
1e430 7d 20 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 } A successful
1e440 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
1e450 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 _column_decltype
1e460 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 16(S,N)].**
1e470 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 returns a
1e480 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
1e490 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 UTF-16 native by
1e4a0 74 65 20 6f 72 64 65 72 20 73 74 72 69 6e 67 0a te order string.
1e4b0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f 6e ** con
1e4c0 74 61 69 6e 69 6e 67 20 74 68 65 20 64 65 63 6c taining the decl
1e4d0 61 72 65 64 20 64 61 74 61 74 79 70 65 20 6f 66 ared datatype of
1e4e0 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d the table colum
1e4f0 6e 20 74 68 61 74 20 61 70 70 65 61 72 73 0a 2a n that appears.*
1e500 2a 20 20 20 20 20 20 20 20 20 20 20 61 73 20 74 * as t
1e510 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e he Nth column (n
1e520 75 6d 62 65 72 65 64 20 66 72 6f 6d 20 30 29 20 umbered from 0)
1e530 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 of the result se
1e540 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 t to the.**
1e550 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 [prepared
1e560 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a statement] S..**
1e570 0a 2a 2a 20 7b 46 31 33 37 36 33 7d 20 20 49 66 .** {F13763} If
1e580 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 N is less than
1e590 30 20 6f 72 20 4e 20 69 73 20 67 72 65 61 74 65 0 or N is greate
1e5a0 72 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 r than or equal
1e5b0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 to.**
1e5c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f the number of co
1e5d0 6c 75 6d 6e 73 20 69 6e 20 5b 70 72 65 70 61 72 lumns in [prepar
1e5e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a ed statement] S.
1e5f0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 72 20 ** or
1e600 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d if the Nth colum
1e610 6e 20 6f 66 20 53 20 69 73 20 61 6e 20 65 78 70 n of S is an exp
1e620 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 ression or subqu
1e630 65 72 79 20 72 61 74 68 65 72 0a 2a 2a 20 20 20 ery rather.**
1e640 20 20 20 20 20 20 20 20 74 68 61 6e 20 61 20 74 than a t
1e650 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 6f 72 20 69 able column or i
1e660 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 f a memory alloc
1e670 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 0a 2a 2a ation failure.**
1e680 20 20 20 20 20 20 20 20 20 20 20 6f 63 63 75 72 occur
1e690 73 20 64 75 72 69 6e 67 20 65 6e 63 6f 64 69 6e s during encodin
1e6a0 67 20 63 6f 6e 76 65 72 73 69 6f 6e 73 2c 20 74 g conversions, t
1e6b0 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 hen.**
1e6c0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
1e6d0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 e3_column_declty
1e6e0 70 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 pe(S,N)] or.**
1e6f0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
1e700 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 3_column_decltyp
1e710 65 31 36 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e e16(S,N)] return
1e720 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 NULL..*/.const
1e730 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
1e740 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 lumn_decltype(sq
1e750 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
1e760 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 ;.const void *sq
1e770 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 lite3_column_dec
1e780 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f ltype16(sqlite3_
1e790 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 20 stmt*,int);../*
1e7a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 .** CAPI3REF: E
1e7b0 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 valuate An SQL S
1e7c0 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 32 30 30 tatement {F13200
1e7d0 7d 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 6e }.**.** After an
1e7e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
1e7f0 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 ment] has been p
1e800 72 65 70 61 72 65 64 20 77 69 74 68 20 61 20 63 repared with a c
1e810 61 6c 6c 0a 2a 2a 20 74 6f 20 65 69 74 68 65 72 all.** to either
1e820 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1e830 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 e_v2()] or [sqli
1e840 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
1e850 28 29 5d 20 6f 72 20 74 6f 20 6f 6e 65 20 6f 66 ()] or to one of
1e860 0a 2a 2a 20 74 68 65 20 6c 65 67 61 63 79 20 69 .** the legacy i
1e870 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 nterfaces [sqlit
1e880 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 e3_prepare()] or
1e890 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1e8a0 65 31 36 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 e16()],.** then
1e8b0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 75 this function mu
1e8c0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 st be called one
1e8d0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 or more times t
1e8e0 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 0a o evaluate the .
1e8f0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a ** statement..**
1e900 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 .** The details
1e910 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 of the behavior
1e920 6f 66 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f of this sqlite3_
1e930 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 step() interface
1e940 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 depend.** on wh
1e950 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d ether the statem
1e960 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 ent was prepared
1e970 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 using the newer
1e980 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a "v2" interface.
1e990 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
1e9a0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 are_v2()] and [s
1e9b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
1e9c0 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c _v2()] or the ol
1e9d0 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e der legacy.** in
1e9e0 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 terface [sqlite3
1e9f0 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 _prepare()] and
1ea00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1ea10 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 16()]. The use
1ea20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 of the.** new "v
1ea30 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 2" interface is
1ea40 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 recommended for
1ea50 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 new applications
1ea60 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a but the legacy.
1ea70 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c ** interface wil
1ea80 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 l continue to be
1ea90 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a supported..**.*
1eaa0 2a 20 49 6e 20 74 68 65 20 6c 61 67 61 63 79 20 * In the lagacy
1eab0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 interface, the r
1eac0 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c eturn value will
1ead0 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 be either [SQLI
1eae0 54 45 5f 42 55 53 59 5d 2c 20 0a 2a 2a 20 5b 53 TE_BUSY], .** [S
1eaf0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 QLITE_DONE], [SQ
1eb00 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 LITE_ROW], [SQLI
1eb10 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 TE_ERROR], or [S
1eb20 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a QLITE_MISUSE]..*
1eb30 2a 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 * With the "v2"
1eb40 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f interface, any o
1eb50 66 20 74 68 65 20 6f 74 68 65 72 20 5b 53 51 4c f the other [SQL
1eb60 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 ITE_OK | result
1eb70 63 6f 64 65 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c code].** or [SQL
1eb80 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c ITE_IOERR_READ |
1eb90 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 extended result
1eba0 20 63 6f 64 65 5d 20 6d 69 67 68 74 20 62 65 20 code] might be
1ebb0 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 77 returned as.** w
1ebc0 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 ell..**.** [SQLI
1ebd0 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 TE_BUSY] means t
1ebe0 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 hat the database
1ebf0 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 engine was unab
1ec00 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 le to acquire th
1ec10 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f e.** database lo
1ec20 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 cks it needs to
1ec30 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 do its job. If
1ec40 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 the statement is
1ec50 20 61 20 43 4f 4d 4d 49 54 0a 2a 2a 20 6f 72 20 a COMMIT.** or
1ec60 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f occurs outside o
1ec70 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 f an explicit tr
1ec80 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 ansaction, then
1ec90 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 you can retry th
1eca0 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 e.** statement.
1ecb0 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e If the statemen
1ecc0 74 20 69 73 20 6e 6f 74 20 61 20 43 4f 4d 4d 49 t is not a COMMI
1ecd0 54 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 T and occurs wit
1ece0 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 hin a.** explici
1ecf0 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 t transaction th
1ed00 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f en you should ro
1ed10 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 llback the trans
1ed20 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a action before.**
1ed30 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a continuing..**.
1ed40 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d ** [SQLITE_DONE]
1ed50 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 means that the
1ed60 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 statement has fi
1ed70 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 nished executing
1ed80 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 .** successfully
1ed90 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 . sqlite3_step(
1eda0 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 ) should not be
1edb0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 called again on
1edc0 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 this virtual.**
1edd0 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 machine without
1ede0 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 first calling [s
1edf0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
1ee00 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 to reset the vir
1ee10 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 tual.** machine
1ee20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 back to its init
1ee30 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a ial state..**.**
1ee40 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 If the SQL stat
1ee50 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 ement being exec
1ee60 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 uted returns any
1ee70 20 64 61 74 61 2c 20 74 68 65 6e 20 0a 2a 2a 20 data, then .**
1ee80 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 69 73 20 [SQLITE_ROW] is
1ee90 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 returned each ti
1eea0 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 me a new row of
1eeb0 64 61 74 61 20 69 73 20 72 65 61 64 79 0a 2a 2a data is ready.**
1eec0 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 for processing
1eed0 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 54 by the caller. T
1eee0 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 he values may be
1eef0 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 0a accessed using.
1ef00 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f ** the [sqlite3_
1ef10 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 63 6f 6c column_int | col
1ef20 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 umn access funct
1ef30 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 ions]..** sqlite
1ef40 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 3_step() is call
1ef50 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 ed again to retr
1ef60 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f ieve the next ro
1ef70 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 20 0a 2a w of data..** .*
1ef80 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d * [SQLITE_ERROR]
1ef90 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 means that a ru
1efa0 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 n-time error (su
1efb0 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 ch as a constrai
1efc0 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 nt.** violation)
1efd0 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 has occurred.
1efe0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 sqlite3_step() s
1eff0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c hould not be cal
1f000 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 led again on.**
1f010 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 the VM. More inf
1f020 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 ormation may be
1f030 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 found by calling
1f040 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
1f050 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 ()]..** With the
1f060 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 legacy interfac
1f070 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 e, a more specif
1f080 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 65 ic error code (e
1f090 78 61 6d 70 6c 65 3a 0a 2a 2a 20 5b 53 51 4c 49 xample:.** [SQLI
1f0a0 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b TE_INTERRUPT], [
1f0b0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 SQLITE_SCHEMA],
1f0c0 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d [SQLITE_CORRUPT]
1f0d0 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a , and so forth).
1f0e0 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e ** can be obtain
1f0f0 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 ed by calling [s
1f100 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
1f110 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 on the.** [prepa
1f120 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 red statement].
1f130 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 In the "v2" int
1f140 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d erface,.** the m
1f150 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 ore specific err
1f160 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 or code is retur
1f170 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 ned directly by
1f180 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a sqlite3_step()..
1f190 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 **.** [SQLITE_MI
1f1a0 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 SUSE] means that
1f1b0 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e the this routin
1f1c0 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 e was called ina
1f1d0 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a ppropriately..**
1f1e0 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 Perhaps it was
1f1f0 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 called on a [pre
1f200 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
1f210 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 that has.** alr
1f220 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 eady been [sqlit
1f230 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 e3_finalize | fi
1f240 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f nalized] or on o
1f250 6e 65 20 74 68 61 74 20 68 61 64 20 0a 2a 2a 20 ne that had .**
1f260 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 previously retur
1f270 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f ned [SQLITE_ERRO
1f280 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f R] or [SQLITE_DO
1f290 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c NE]. Or it coul
1f2a0 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 d.** be the case
1f2b0 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 that the same d
1f2c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1f2d0 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 on is being used
1f2e0 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f by two or.** mo
1f2f0 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 re threads at th
1f300 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e e same moment in
1f310 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e time..**.** <b>
1f320 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 Goofy Interface
1f330 41 6c 65 72 74 3a 3c 2f 62 3e 0a 2a 2a 20 49 6e Alert:</b>.** In
1f340 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 the legacy inte
1f350 72 66 61 63 65 2c 20 0a 2a 2a 20 74 68 65 20 73 rface, .** the s
1f360 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 41 50 qlite3_step() AP
1f370 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 I always returns
1f380 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 a generic error
1f390 20 63 6f 64 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 code,.** [SQLIT
1f3a0 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 E_ERROR], follow
1f3b0 69 6e 67 20 61 6e 79 20 65 72 72 6f 72 20 6f 74 ing any error ot
1f3c0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
1f3d0 5f 42 55 53 59 5d 0a 2a 2a 20 61 6e 64 20 5b 53 _BUSY].** and [S
1f3e0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 QLITE_MISUSE].
1f3f0 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 20 5b 73 You must call [s
1f400 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
1f410 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 or.** [sqlite3_f
1f420 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 inalize()] in or
1f430 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 der to find one
1f440 6f 66 20 74 68 65 20 73 70 65 63 69 66 69 63 0a of the specific.
1f450 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d ** [error codes]
1f460 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 that better des
1f470 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 cribes the error
1f480 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 ..** We admit th
1f490 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f at this is a goo
1f4a0 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 fy design. The
1f4b0 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e problem has been
1f4c0 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 fixed.** with t
1f4d0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 he "v2" interfac
1f4e0 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 e. If you prepa
1f4f0 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 re all of your S
1f500 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a QL statements.**
1f510 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 using either [s
1f520 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1f530 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 2()] or [sqlite3
1f540 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
1f550 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 instead.** of t
1f560 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 he legacy [sqlit
1f570 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e e3_prepare()] an
1f580 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 d [sqlite3_prepa
1f590 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20 74 68 re16()], then th
1f5a0 65 20 0a 2a 2a 20 6d 6f 72 65 20 73 70 65 63 69 e .** more speci
1f5b0 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 fic [error codes
1f5c0 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 ] are returned d
1f5d0 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 irectly.** by sq
1f5e0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 lite3_step(). T
1f5f0 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 he use of the "v
1f600 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 2" interface is
1f610 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a recommended..**.
1f620 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
1f630 2a 0a 2a 2a 20 7b 46 31 33 32 30 32 7d 20 20 49 *.** {F13202} I
1f640 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 f [prepared stat
1f650 65 6d 65 6e 74 5d 20 53 20 69 73 20 72 65 61 64 ement] S is read
1f660 79 20 74 6f 20 62 65 0a 2a 2a 20 20 20 20 20 20 y to be.**
1f670 20 20 20 20 20 72 75 6e 2c 20 74 68 65 6e 20 5b run, then [
1f680 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d sqlite3_step(S)]
1f690 20 61 64 76 61 6e 63 65 73 20 74 68 61 74 20 70 advances that p
1f6a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
1f6b0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 75 t.** u
1f6c0 6e 74 69 6c 20 74 6f 20 63 6f 6d 70 6c 65 74 69 ntil to completi
1f6d0 6f 6e 20 6f 72 20 75 6e 74 69 6c 20 69 74 20 69 on or until it i
1f6e0 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 s ready to retur
1f6f0 6e 20 61 6e 6f 74 68 65 72 0a 2a 2a 20 20 20 20 n another.**
1f700 20 20 20 20 20 20 20 72 6f 77 20 6f 66 20 74 68 row of th
1f710 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 72 20 e result set or
1f720 61 6e 20 69 6e 74 65 72 72 75 70 74 20 6f 72 20 an interrupt or
1f730 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 6f run-time error o
1f740 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 ccurs..**.** {F1
1f750 35 33 30 34 7d 20 20 57 68 65 6e 20 61 20 63 61 5304} When a ca
1f760 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ll to [sqlite3_s
1f770 74 65 70 28 53 29 5d 20 63 61 75 73 65 73 20 74 tep(S)] causes t
1f780 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 he .**
1f790 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
1f7a0 6d 65 6e 74 5d 20 53 20 74 6f 20 72 75 6e 20 74 ment] S to run t
1f7b0 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2c 0a 2a 2a o completion,.**
1f7c0 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20 66 the f
1f7d0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
1f7e0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a [SQLITE_DONE]..*
1f7f0 2a 0a 2a 2a 20 7b 46 31 35 33 30 36 7d 20 20 57 *.** {F15306} W
1f800 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 hen a call to [s
1f810 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 qlite3_step(S)]
1f820 73 74 6f 70 73 20 62 65 63 61 75 73 65 20 69 74 stops because it
1f830 20 69 73 20 72 65 61 64 79 0a 2a 2a 20 20 20 20 is ready.**
1f840 20 20 20 20 20 20 20 74 6f 20 72 65 74 75 72 6e to return
1f850 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66 20 another row of
1f860 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 2c 20 the result set,
1f870 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 it returns.**
1f880 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f [SQLITE_
1f890 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 ROW]..**.** {F15
1f8a0 33 30 38 7d 20 20 49 66 20 61 20 63 61 6c 6c 20 308} If a call
1f8b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 to [sqlite3_step
1f8c0 28 53 29 5d 20 65 6e 63 6f 75 6e 74 65 72 73 20 (S)] encounters
1f8d0 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 an.**
1f8e0 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 [sqlite3_interru
1f8f0 70 74 7c 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 pt|interrupt] or
1f900 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f a run-time erro
1f910 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 r,.**
1f920 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 it returns an ap
1f930 70 72 6f 70 72 61 69 74 65 20 65 72 72 6f 72 20 propraite error
1f940 63 6f 64 65 20 74 68 61 74 20 69 73 20 6e 6f 74 code that is not
1f950 20 6f 6e 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 one of.**
1f960 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d [SQLITE_OK]
1f970 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 , [SQLITE_ROW],
1f980 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d or [SQLITE_DONE]
1f990 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33 31 30 7d ..**.** {F15310}
1f9a0 20 20 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 If an [sqlite3
1f9b0 5f 69 6e 74 65 72 72 75 70 74 7c 69 6e 74 65 72 _interrupt|inter
1f9c0 72 75 70 74 5d 20 6f 72 20 72 75 6e 2d 74 69 6d rupt] or run-tim
1f9d0 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20 e error.**
1f9e0 20 20 20 20 20 6f 63 63 75 72 73 20 64 75 72 69 occurs duri
1f9f0 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 ng a call to [sq
1fa00 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 0a 2a lite3_step(S)].*
1fa10 2a 20 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 * for
1fa20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
1fa30 65 6d 65 6e 74 5d 20 53 20 63 72 65 61 74 65 64 ement] S created
1fa40 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 using.**
1fa50 20 20 20 20 6c 65 67 61 63 79 20 69 6e 74 65 72 legacy inter
1fa60 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 faces [sqlite3_p
1fa70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 repare()] or.**
1fa80 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
1fa90 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 e3_prepare16()]
1faa0 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f then the functio
1fab0 6e 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 n returns either
1fac0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53 .** [S
1fad0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 5b 53 QLITE_ERROR], [S
1fae0 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 6f 72 20 QLITE_BUSY], or
1faf0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e [SQLITE_MISUSE].
1fb00 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
1fb10 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d step(sqlite3_stm
1fb20 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
1fb30 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 3REF: Number of
1fb40 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 columns in a res
1fb50 75 6c 74 20 73 65 74 20 7b 46 31 33 37 37 30 7d ult set {F13770}
1fb60 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 .**.** Return th
1fb70 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c 75 e number of valu
1fb80 65 73 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e es in the curren
1fb90 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 t row of the res
1fba0 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 ult set..**.** I
1fbb0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
1fbc0 20 7b 46 31 33 37 37 31 7d 20 20 41 66 74 65 72 {F13771} After
1fbd0 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 a call to [sqli
1fbe0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 74 68 61 te3_step(S)] tha
1fbf0 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 t returns.**
1fc00 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 52 [SQLITE_R
1fc10 4f 57 5d 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 OW], the [sqlite
1fc20 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 3_data_count(S)]
1fc30 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 20 20 20 20 routine.**
1fc40 20 20 20 20 20 20 77 69 6c 6c 20 72 65 74 75 72 will retur
1fc50 6e 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 n the same value
1fc60 20 61 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 as the.**
1fc70 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f [sqlite3_co
1fc80 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 66 lumn_count(S)] f
1fc90 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b unction..**.** {
1fca0 46 31 33 37 37 32 7d 20 20 41 66 74 65 72 20 5b F13772} After [
1fcb0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d sqlite3_step(S)]
1fcc0 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 61 6e has returned an
1fcd0 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 y value other th
1fce0 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 an.**
1fcf0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 [SQLITE_ROW] or
1fd00 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f before [sqlite3_
1fd10 73 74 65 70 28 53 29 5d 20 68 61 73 20 62 65 65 step(S)] has bee
1fd20 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 n .**
1fd30 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 5b 70 called on the [p
1fd40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
1fd50 74 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 t] for.**
1fd60 20 20 20 20 74 68 65 20 66 69 72 73 74 20 74 69 the first ti
1fd70 6d 65 20 73 69 6e 63 65 20 69 74 20 77 61 73 20 me since it was
1fd80 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1fd90 7c 70 72 65 70 61 72 65 64 5d 0a 2a 2a 20 20 20 |prepared].**
1fda0 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 or [sqli
1fdb0 74 65 33 5f 72 65 73 65 74 7c 72 65 73 65 74 5d te3_reset|reset]
1fdc0 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 , the [sqlite3_d
1fdd0 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 0a 2a 2a ata_count(S)].**
1fde0 20 20 20 20 20 20 20 20 20 20 20 72 6f 75 74 69 routi
1fdf0 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e ne returns zero.
1fe00 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
1fe10 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 data_count(sqlit
1fe20 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b e3_stmt *pStmt);
1fe30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1fe40 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 : Fundamental Da
1fe50 74 61 74 79 70 65 73 20 7b 46 31 30 32 36 35 7d tatypes {F10265}
1fe60 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 .** KEYWORDS: SQ
1fe70 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 LITE_TEXT.**.**
1fe80 7b 46 31 30 32 36 36 7d 45 76 65 72 79 20 76 61 {F10266}Every va
1fe90 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 lue in SQLite ha
1fea0 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 s one of five fu
1feb0 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 ndamental dataty
1fec0 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a pes:.**.** <ul>.
1fed0 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 ** <li> 64-bit s
1fee0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a igned integer.**
1fef0 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 <li> 64-bit IEE
1ff00 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 E floating point
1ff10 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 number.** <li>
1ff20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 string.** <li> B
1ff30 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c LOB.** <li> NULL
1ff40 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a .** </ul> {END}.
1ff50 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
1ff60 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 tants are codes
1ff70 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 for each of thos
1ff80 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e e types..**.** N
1ff90 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c ote that the SQL
1ffa0 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e ITE_TEXT constan
1ffb0 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 t was also used
1ffc0 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f in SQLite versio
1ffd0 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d n 2.** for a com
1ffe0 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e pletely differen
1fff0 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 t meaning. Soft
20000 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 ware that links
20010 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 against both.**
20020 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 SQLite version 2
20030 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 and SQLite vers
20040 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 ion 3 should use
20050 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 6e 6f SQLITE3_TEXT no
20060 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 t.** SQLITE_TEXT
20070 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
20080 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 ITE_INTEGER 1.#
20090 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c define SQLITE_FL
200a0 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 OAT 2.#define
200b0 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 SQLITE_BLOB
200c0 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 4.#define SQLIT
200d0 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 E_NULL 5.#if
200e0 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a def SQLITE_TEXT.
200f0 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 # undef SQLITE_T
20100 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 EXT.#else.# defi
20110 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 ne SQLITE_TEXT
20120 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 3.#endif.#def
20130 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 ine SQLITE3_TEXT
20140 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 3../*.** CA
20150 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 73 20 PI3REF: Results
20160 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 Values From A Qu
20170 65 72 79 20 7b 46 31 33 38 30 30 7d 0a 2a 2a 0a ery {F13800}.**.
20180 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
20190 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 s form the "resu
201a0 6c 74 20 73 65 74 20 71 75 65 72 79 22 20 69 6e lt set query" in
201b0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 terface..**.** T
201c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 hese routines re
201d0 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e turn information
201e0 20 61 62 6f 75 74 0a 2a 2a 20 61 20 73 69 6e 67 about.** a sing
201f0 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 le column of the
20200 20 63 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20 current result
20210 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 row of a query.
20220 20 49 6e 20 65 76 65 72 79 0a 2a 2a 20 63 61 73 In every.** cas
20230 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 e the first argu
20240 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 ment is a pointe
20250 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 70 72 r to the .** [pr
20260 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
20270 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 0a ] that is being.
20280 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 ** evaluated (th
20290 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a e [sqlite3_stmt*
202a0 5d 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 ] that was retur
202b0 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 ned from .** [sq
202c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
202d0 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 ()] or one of it
202e0 73 20 76 61 72 69 61 6e 74 73 29 20 61 6e 64 0a s variants) and.
202f0 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 ** the second ar
20300 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e gument is the in
20310 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d dex of the colum
20320 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f n for which info
20330 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20 73 68 6f 75 rmation .** shou
20340 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 ld be returned.
20350 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 The left-most c
20360 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 olumn of the res
20370 75 6c 74 20 73 65 74 0a 2a 2a 20 68 61 73 20 61 ult set.** has a
20380 6e 20 69 6e 64 65 78 20 6f 66 20 30 2e 0a 2a 2a n index of 0..**
20390 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 .** If the SQL s
203a0 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 tatement is not
203b0 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 currently point
203c0 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 to a valid row,
203d0 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 74 68 65 or if the.** the
203e0 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 column index is
203f0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 out of range, t
20400 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 he result is und
20410 65 66 69 6e 65 64 2e 20 0a 2a 2a 20 54 68 65 73 efined. .** Thes
20420 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f e routines may o
20430 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 nly be called wh
20440 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 en the most rece
20450 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 nt call to.** [s
20460 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 qlite3_step()] h
20470 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c as returned [SQL
20480 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 ITE_ROW] and nei
20490 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ther.** [sqlite3
204a0 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 _reset()] nor [s
204b0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
204c0 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c )] has been call
204d0 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a subsequently..*
204e0 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 * If any of thes
204f0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 e routines are c
20500 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c alled after [sql
20510 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 ite3_reset()] or
20520 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e .** [sqlite3_fin
20530 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 alize()] or afte
20540 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 r [sqlite3_step(
20550 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a )] has returned.
20560 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 ** something oth
20570 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
20580 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 ROW], the result
20590 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e s are undefined.
205a0 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f .** If [sqlite3_
205b0 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 step()] or [sqli
205c0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 te3_reset()] or
205d0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
205e0 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c e()].** are call
205f0 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 ed from a differ
20600 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 ent thread while
20610 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f any of these ro
20620 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 utines.** are pe
20630 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 nding, then the
20640 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 results are unde
20650 66 69 6e 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 fined. .**.** T
20660 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d he sqlite3_colum
20670 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 n_type() routine
20680 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 returns .** [SQ
20690 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 LITE_INTEGER | d
206a0 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f atatype code] fo
206b0 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 r the initial da
206c0 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 ta type.** of th
206d0 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e e result column.
206e0 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 The returned v
206f0 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b alue is one of [
20700 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c SQLITE_INTEGER],
20710 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 .** [SQLITE_FLOA
20720 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 T], [SQLITE_TEXT
20730 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d ], [SQLITE_BLOB]
20740 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c , or [SQLITE_NUL
20750 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a L]. The value.*
20760 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 * returned by sq
20770 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 lite3_column_typ
20780 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e e() is only mean
20790 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 ingful if no typ
207a0 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 e.** conversions
207b0 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 have occurred a
207c0 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f s described belo
207d0 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65 w. After a type
207e0 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 conversion,.**
207f0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
20800 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f ed by sqlite3_co
20810 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 lumn_type() is u
20820 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 ndefined. Futur
20830 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 e.** versions of
20840 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e SQLite may chan
20850 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 ge the behavior
20860 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d of sqlite3_colum
20870 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c n_type().** foll
20880 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e owing a type con
20890 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 version..**.** I
208a0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
208b0 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 a BLOB or UTF-8
208c0 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 string then the
208d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
208e0 79 74 65 73 28 29 20 0a 2a 2a 20 72 6f 75 74 69 ytes() .** routi
208f0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e ne returns the n
20900 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 umber of bytes i
20910 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 n that BLOB or s
20920 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 65 tring..** If the
20930 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 result is a UTF
20940 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e -16 string, then
20950 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
20960 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 bytes() converts
20970 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 .** the string t
20980 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e o UTF-8 and then
20990 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
209a0 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a ber of bytes..**
209b0 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 If the result i
209c0 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 s a numeric valu
209d0 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 e then sqlite3_c
209e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 olumn_bytes() us
209f0 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 es.** [sqlite3_s
20a00 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f nprintf()] to co
20a10 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 nvert that value
20a20 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 to a UTF-8 stri
20a30 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a ng and returns.*
20a40 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 * the number of
20a50 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 bytes in that st
20a60 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 76 61 6c ring..** The val
20a70 75 65 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 ue returned does
20a80 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 not include the
20a90 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 zero terminator
20aa0 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f at the end.** o
20ab0 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 46 f the string. F
20ac0 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 or clarity: the
20ad0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 value returned i
20ae0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a s the number of.
20af0 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 ** bytes in the
20b00 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 string, not the
20b10 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 number of charac
20b20 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69 ters..**.** Stri
20b30 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 ngs returned by
20b40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
20b50 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 ext() and sqlite
20b60 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
20b70 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 ),.** even empty
20b80 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c strings, are al
20b90 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e ways zero termin
20ba0 61 74 65 64 2e 20 20 54 68 65 20 72 65 74 75 72 ated. The retur
20bb0 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 n.** value from
20bc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
20bd0 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f lob() for a zero
20be0 2d 6c 65 6e 67 74 68 20 62 6c 6f 62 20 69 73 20 -length blob is
20bf0 61 6e 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 an arbitrary.**
20c00 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c pointer, possibl
20c10 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f y even a NULL po
20c20 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 inter..**.** The
20c30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
20c40 62 79 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e bytes16() routin
20c50 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 e is similar to
20c60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
20c70 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 ytes().** but le
20c80 61 76 65 73 20 74 68 65 20 72 65 73 75 6c 74 20 aves the result
20c90 69 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 in UTF-16 in nat
20ca0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 ive byte order i
20cb0 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e nstead of UTF-8.
20cc0 20 20 0a 2a 2a 20 54 68 65 20 7a 65 72 6f 20 74 .** The zero t
20cd0 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74 erminator is not
20ce0 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 69 included in thi
20cf0 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 s count..**.** T
20d00 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 hese routines at
20d10 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 tempt to convert
20d20 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 the value where
20d30 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 46 appropriate. F
20d40 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 or.** example, i
20d50 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 f the internal r
20d60 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 epresentation is
20d70 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 FLOAT and a tex
20d80 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 t result.** is r
20d90 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 equested, [sqlit
20da0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 e3_snprintf()] i
20db0 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c s used internall
20dc0 79 20 74 6f 20 64 6f 20 74 68 65 20 63 6f 6e 76 y to do the conv
20dd0 65 72 73 69 6f 6e 0a 2a 2a 20 61 75 74 6f 6d 61 ersion.** automa
20de0 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f tically. The fo
20df0 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 llowing table de
20e00 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 tails the conver
20e10 73 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 61 72 sions that.** ar
20e20 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a e applied:.**.**
20e30 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a <blockquote>.**
20e40 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 <table border="
20e50 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 1">.** <tr><th>
20e60 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 Internal<br>Type
20e70 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c <th> Requested<
20e80 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f br>Type <th> Co
20e90 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c nversion.**.** <
20ea0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 tr><td> NULL
20eb0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 <td> INTEGER
20ec0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 <td> Result is 0
20ed0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 .** <tr><td> NU
20ee0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 LL <td> FLOA
20ef0 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 T <td> Result
20f00 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c is 0.0.** <tr><
20f10 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 td> NULL <td
20f20 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e > TEXT <td>
20f30 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 Result is NULL
20f40 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c pointer.** <tr><
20f50 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 td> NULL <td
20f60 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e > BLOB <td>
20f70 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 Result is NULL
20f80 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c pointer.** <tr><
20f90 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 td> INTEGER <td
20fa0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e > FLOAT <td>
20fb0 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e Convert from in
20fc0 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a teger to float.*
20fd0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 * <tr><td> INTEG
20fe0 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 ER <td> TEXT
20ff0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 <td> ASCII re
21000 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 ndering of the i
21010 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 nteger.** <tr><t
21020 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e d> INTEGER <td>
21030 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 BLOB <td>
21040 53 61 6d 65 20 61 73 20 66 6f 72 20 49 4e 54 45 Same as for INTE
21050 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 GER->TEXT.** <tr
21060 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c ><td> FLOAT <
21070 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 td> INTEGER <t
21080 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 d> Convert from
21090 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 float to integer
210a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c .** <tr><td> FL
210b0 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 OAT <td> TEX
210c0 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 T <td> ASCII
210d0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 rendering of the
210e0 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 float.** <tr><t
210f0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e d> FLOAT <td>
21100 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 BLOB <td>
21110 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 Same as FLOAT->T
21120 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 EXT.** <tr><td>
21130 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e TEXT <td> IN
21140 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 TEGER <td> Use
21150 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c atoi().** <tr><
21160 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 td> TEXT <td
21170 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e > FLOAT <td>
21180 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c Use atof().** <
21190 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 tr><td> TEXT
211a0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 <td> BLOB
211b0 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a <td> No change.*
211c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 * <tr><td> BLOB
211d0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 <td> INTEGER
211e0 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 <td> Convert
211f0 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 to TEXT then use
21200 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c atoi().** <tr><
21210 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 td> BLOB <td
21220 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e > FLOAT <td>
21230 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 Convert to TEXT
21240 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 then use atof()
21250 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c .** <tr><td> BL
21260 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 OB <td> TEX
21270 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 T <td> Add a
21280 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 zero terminator
21290 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 if needed.** </t
212a0 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b able>.** </block
212b0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 quote>.**.** The
212c0 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b table above mak
212d0 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 es reference to
212e0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 standard C libra
212f0 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f ry functions ato
21300 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 i().** and atof(
21310 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 ). SQLite does
21320 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 not really use t
21330 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 hese functions.
21340 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f It has its.** o
21350 6e 20 65 71 75 61 76 61 6c 65 6e 74 20 69 6e 74 n equavalent int
21360 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 ernal routines.
21370 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 The atoi() and
21380 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 atof() names are
21390 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 .** used in the
213a0 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 table for brevit
213b0 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 y and because th
213c0 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 ey are familiar
213d0 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f to most.** C pro
213e0 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 grammers..**.**
213f0 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 Note that when t
21400 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 ype conversions
21410 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 occur, pointers
21420 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f returned by prio
21430 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 r.** calls to sq
21440 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
21450 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c b(), sqlite3_col
21460 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f umn_text(), and/
21470 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f or.** sqlite3_co
21480 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 lumn_text16() ma
21490 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 y be invalidated
214a0 2e 20 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 . .** Type conve
214b0 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 rsions and point
214c0 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 er invalidations
214d0 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 might occur.**
214e0 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 in the following
214f0 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 cases:.**.** <u
21500 6c 3e 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 l>.** <li><p> T
21510 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 he initial conte
21520 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 nt is a BLOB and
21530 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
21540 74 65 78 74 28 29 20 0a 2a 2a 20 20 20 20 20 20 text() .**
21550 20 20 20 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 or sqlite3_c
21560 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 olumn_text16() i
21570 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 s called. A zer
21580 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 o-terminator mig
21590 68 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e ht.** n
215a0 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 eed to be added
215b0 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f to the string.</
215c0 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c p></li>.**.** <l
215d0 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69 74 69 i><p> The initi
215e0 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 al content is UT
215f0 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c F-8 text and sql
21600 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
21610 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 s16() or.**
21620 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c sqlite3_col
21630 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 umn_text16() is
21640 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e called. The con
21650 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e tent must be con
21660 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 verted.**
21670 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 70 to UTF-16.</p
21680 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 ></li>.**.** <li
21690 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61 ><p> The initia
216a0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 l content is UTF
216b0 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c -16 text and sql
216c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
216d0 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 s() or.**
216e0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d sqlite3_colum
216f0 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c n_text() is call
21700 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 ed. The content
21710 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 must be convert
21720 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 ed.** t
21730 6f 20 55 54 46 2d 38 2e 3c 2f 70 3e 3c 2f 6c 69 o UTF-8.</p></li
21740 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a >.** </ul>.**.**
21750 20 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 Conversions bet
21760 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e ween UTF-16be an
21770 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 d UTF-16le are a
21780 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c lways done in pl
21790 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f ace and do.** no
217a0 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 t invalidate a p
217b0 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 rior pointer, th
217c0 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 ough of course t
217d0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 he content of th
217e0 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 e buffer.** that
217f0 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 the prior point
21800 65 72 20 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c er points to wil
21810 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 l have been modi
21820 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e fied. Other kin
21830 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 ds.** of convers
21840 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 ion are done in
21850 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 place when it is
21860 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 possible, but s
21870 6f 6d 65 74 69 6d 65 20 69 74 20 69 73 0a 2a 2a ometime it is.**
21880 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e not possible an
21890 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 d in those cases
218a0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 prior pointers
218b0 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e are invalidated.
218c0 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 .**.** The saf
218d0 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 est and easiest
218e0 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 to remember poli
218f0 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 cy is to invoke
21900 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a these routines.*
21910 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 * in one of the
21920 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a following ways:.
21930 2a 2a 0a 2a 2a 20 20 3c 75 6c 3e 0a 2a 2a 20 20 **.** <ul>.**
21940 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 <li>sqlite3_colu
21950 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 mn_text() follow
21960 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f ed by sqlite3_co
21970 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 lumn_bytes()</li
21980 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 >.** <li>sqlite
21990 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 3_column_blob()
219a0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 followed by sqli
219b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
219c0 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e ()</li>.** <li>
219d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
219e0 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 ext16() followed
219f0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by sqlite3_colu
21a00 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 mn_bytes16()</li
21a10 3e 0a 2a 2a 20 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a >.** </ul>.**.*
21a20 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 * In other words
21a30 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c , you should cal
21a40 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e l sqlite3_column
21a50 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 _text(), sqlite3
21a60 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 0a _column_blob(),.
21a70 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f ** or sqlite3_co
21a80 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 lumn_text16() fi
21a90 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 rst to force the
21aa0 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 74 68 65 result into the
21ab0 20 64 65 73 69 72 65 64 0a 2a 2a 20 66 6f 72 6d desired.** form
21ac0 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 at, then invoke
21ad0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
21ae0 79 74 65 73 28 29 20 6f 72 20 73 71 6c 69 74 65 ytes() or sqlite
21af0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
21b00 28 29 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 74 68 () to.** find th
21b10 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 e size of the re
21b20 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 sult. Do not mi
21b30 78 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 x call to sqlite
21b40 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 3_column_text()
21b50 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f or.** sqlite3_co
21b60 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 lumn_blob() with
21b70 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 calls to sqlite
21b80 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
21b90 28 29 2e 20 20 41 6e 64 20 64 6f 20 6e 6f 74 0a (). And do not.
21ba0 2a 2a 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 ** mix calls to
21bb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
21bc0 65 78 74 31 36 28 29 20 77 69 74 68 20 63 61 6c ext16() with cal
21bd0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ls to sqlite3_co
21be0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a lumn_bytes()..**
21bf0 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 73 .** The pointers
21c00 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 returned are va
21c10 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 lid until a type
21c20 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 conversion occu
21c30 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 rs as.** describ
21c40 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 ed above, or unt
21c50 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 il [sqlite3_step
21c60 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
21c70 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b reset()] or.** [
21c80 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
21c90 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 ()] is called.
21ca0 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 The memory space
21cb0 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 used to hold st
21cc0 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 62 6c 6f rings.** and blo
21cd0 62 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f bs is freed auto
21ce0 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c matically. Do <
21cf0 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 b>not</b> pass t
21d00 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 he pointers retu
21d10 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 rned.** [sqlite3
21d20 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c _column_blob()],
21d30 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
21d40 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 _text()], etc. i
21d50 6e 74 6f 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 nto .** [sqlite3
21d60 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 _free()]..**.**
21d70 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f If a memory allo
21d80 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 cation error occ
21d90 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 urs during the e
21da0 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 valuation of any
21db0 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 .** of these rou
21dc0 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 tines, a default
21dd0 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e value is return
21de0 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 ed. The default
21df0 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 value.** is eit
21e00 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 her the integer
21e10 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 0, the floating
21e20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 point number 0.0
21e30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 , or a NULL.** p
21e40 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 ointer. Subsequ
21e50 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 ent calls to [sq
21e60 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d lite3_errcode()]
21e70 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 will return.**
21e80 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a [SQLITE_NOMEM]..
21e90 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
21ea0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30 33 7d :.**.** {F13803}
21eb0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f The [sqlite3_co
21ec0 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 lumn_blob(S,N)]
21ed0 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 interface conver
21ee0 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 ts the.**
21ef0 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e Nth column in
21f00 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 the current row
21f10 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 of the result s
21f20 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 et for.**
21f30 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 [prepared sta
21f40 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 tement] S into a
21f50 20 62 6c 6f 62 20 61 6e 64 20 74 68 65 6e 20 72 blob and then r
21f60 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 eturns a.**
21f70 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 pointer to
21f80 74 68 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61 the converted va
21f90 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 lue..**.** {F138
21fa0 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 06} The [sqlite3
21fb0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 53 2c _column_bytes(S,
21fc0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 N)] interface re
21fd0 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 turns the.**
21fe0 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 number of
21ff0 62 79 74 65 73 20 69 6e 20 74 68 65 20 62 6c 6f bytes in the blo
22000 62 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63 b or string (exc
22010 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a lusive of the.**
22020 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 zero t
22030 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 erminator on the
22040 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 string) that wa
22050 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 s returned by th
22060 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f e.** mo
22070 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 st recent call t
22080 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d o [sqlite3_colum
22090 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a n_blob(S,N)] or.
220a0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
220b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
220c0 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 (S,N)]..**.** {F
220d0 31 33 38 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 13809} The [sqli
220e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
220f0 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 16(S,N)] interfa
22100 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a ce returns the.*
22110 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 * numbe
22120 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
22130 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 e string (exclus
22140 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 ive of the.**
22150 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d zero term
22160 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 inator on the st
22170 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 ring) that was r
22180 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a eturned by the.*
22190 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 * most
221a0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b recent call to [
221b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
221c0 65 78 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a ext16(S,N)]..**.
221d0 2a 2a 20 7b 46 31 33 38 31 32 7d 20 54 68 65 20 ** {F13812} The
221e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
221f0 64 6f 75 62 6c 65 28 53 2c 4e 29 5d 20 69 6e 74 double(S,N)] int
22200 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 erface converts
22210 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
22220 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 Nth column in th
22230 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 e current row of
22240 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 the result set
22250 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 for.**
22260 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
22270 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 66 6c ent] S into a fl
22280 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c oating point val
22290 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 ue and.**
222a0 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 returns a cop
222b0 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e y of that value.
222c0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31 35 7d 20 .**.** {F13815}
222d0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c The [sqlite3_col
222e0 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29 5d 20 69 6e umn_int(S,N)] in
222f0 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 terface converts
22300 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
22310 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 Nth column in t
22320 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f he current row o
22330 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 f the result set
22340 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 for.**
22350 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
22360 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 33 ment] S into a 3
22370 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 2-bit signed int
22380 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 eger and.**
22390 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 returns a c
223a0 6f 70 79 20 6f 66 20 74 68 61 74 20 69 6e 74 65 opy of that inte
223b0 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 ger..**.** {F138
223c0 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 18} The [sqlite3
223d0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 53 2c _column_int64(S,
223e0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f N)] interface co
223f0 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 nverts the.**
22400 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d Nth colum
22410 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 n in the current
22420 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 row of the resu
22430 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 lt set for.**
22440 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 [prepared
22450 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e statement] S in
22460 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e to a 64-bit sign
22470 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a ed integer and.*
22480 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 * retur
22490 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 ns a copy of tha
224a0 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a t integer..**.**
224b0 20 7b 46 31 33 38 32 31 7d 20 54 68 65 20 5b 73 {F13821} The [s
224c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
224d0 78 74 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 xt(S,N)] interfa
224e0 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a ce converts the.
224f0 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 ** Nth
22500 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 column in the cu
22510 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 rrent row of the
22520 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a result set for.
22530 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 ** [pre
22540 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
22550 20 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 S into a zero-t
22560 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 erminated UTF-8
22570 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 .** str
22580 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 ing and returns
22590 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 a pointer to tha
225a0 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 t string..**.**
225b0 7b 46 31 33 38 32 34 7d 20 54 68 65 20 5b 73 71 {F13824} The [sq
225c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
225d0 74 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 t16(S,N)] interf
225e0 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 ace converts the
225f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 .** Nth
22600 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 column in the c
22610 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 urrent row of th
22620 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 e result set for
22630 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 .** [pr
22640 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
22650 5d 20 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d ] S into a zero-
22660 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 terminated 2-byt
22670 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c e.** al
22680 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74 igned UTF-16 nat
22690 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a ive byte order.*
226a0 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e * strin
226b0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 g and returns a
226c0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 pointer to that
226d0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 string..**.** {F
226e0 31 33 38 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 13827} The [sqli
226f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
22700 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 S,N)] interface
22710 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 returns.**
22720 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 one of [SQLI
22730 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 TE_NULL], [SQLIT
22740 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c E_INTEGER], [SQL
22750 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 ITE_FLOAT],.**
22760 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f [SQLITE_
22770 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 TEXT], or [SQLIT
22780 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f E_BLOB] as appro
22790 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 priate for.**
227a0 20 20 20 20 20 20 20 74 68 65 20 4e 74 68 20 63 the Nth c
227b0 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 olumn in the cur
227c0 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 rent row of the
227d0 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a result set for.*
227e0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 * [prep
227f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
22800 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 33 30 S..**.** {F13830
22810 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 } The [sqlite3_c
22820 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 53 2c 4e 29 olumn_value(S,N)
22830 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ] interface retu
22840 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 rns a.**
22850 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 pointer to the
22860 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d [sqlite3_value]
22870 20 6f 62 6a 65 63 74 20 74 68 61 74 20 66 6f 72 object that for
22880 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
22890 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 Nth column in t
228a0 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f he current row o
228b0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 f the result set
228c0 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 for.**
228d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
228e0 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 ment] S..*/.cons
228f0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
22900 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 column_blob(sqli
22910 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
22920 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 Col);.int sqlite
22930 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 3_column_bytes(s
22940 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
22950 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c t iCol);.int sql
22960 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
22970 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 s16(sqlite3_stmt
22980 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f *, int iCol);.do
22990 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c uble sqlite3_col
229a0 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 umn_double(sqlit
229b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
229c0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ol);.int sqlite3
229d0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 _column_int(sqli
229e0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
229f0 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e Col);.sqlite3_in
22a00 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 t64 sqlite3_colu
22a10 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 mn_int64(sqlite3
22a20 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
22a30 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 );.const unsigne
22a40 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f d char *sqlite3_
22a50 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 column_text(sqli
22a60 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
22a70 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 Col);.const void
22a80 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
22a90 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f _text16(sqlite3_
22aa0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
22ab0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f ;.int sqlite3_co
22ac0 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 lumn_type(sqlite
22ad0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
22ae0 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 l);.sqlite3_valu
22af0 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d e *sqlite3_colum
22b00 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f n_value(sqlite3_
22b10 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
22b20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
22b30 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 F: Destroy A Pre
22b40 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 pared Statement
22b50 4f 62 6a 65 63 74 20 7b 46 31 33 33 30 30 7d 0a Object {F13300}.
22b60 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
22b70 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 3_finalize() fun
22b80 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 ction is called
22b90 74 6f 20 64 65 6c 65 74 65 20 61 20 0a 2a 2a 20 to delete a .**
22ba0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
22bb0 65 6e 74 5d 2e 20 49 66 20 74 68 65 20 73 74 61 ent]. If the sta
22bc0 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 65 78 tement was.** ex
22bd0 65 63 75 74 65 64 20 73 75 63 63 65 73 73 66 75 ecuted successfu
22be0 6c 6c 79 2c 20 6f 72 20 6e 6f 74 20 65 78 65 63 lly, or not exec
22bf0 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 uted at all, the
22c00 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 n SQLITE_OK is r
22c10 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 65 eturned..** If e
22c20 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 xecution of the
22c30 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 statement failed
22c40 20 74 68 65 6e 20 61 6e 20 0a 2a 2a 20 5b 65 72 then an .** [er
22c50 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 ror code] or [ex
22c60 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 tended error cod
22c70 65 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 e].** is returne
22c80 64 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 d. .**.** This r
22c90 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 outine can be ca
22ca0 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e lled at any poin
22cb0 74 20 64 75 72 69 6e 67 20 74 68 65 20 65 78 65 t during the exe
22cc0 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a cution of the.**
22cd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
22ce0 6d 65 6e 74 5d 2e 20 20 49 66 20 74 68 65 20 76 ment]. If the v
22cf0 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 irtual machine h
22d00 61 73 20 6e 6f 74 20 0a 2a 2a 20 63 6f 6d 70 6c as not .** compl
22d10 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77 eted execution w
22d20 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 hen this routine
22d30 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 is called, that
22d40 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f is like.** enco
22d50 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f untering an erro
22d60 72 20 6f 72 20 61 6e 20 69 6e 74 65 72 72 75 70 r or an interrup
22d70 74 2e 20 20 28 53 65 65 20 5b 73 71 6c 69 74 65 t. (See [sqlite
22d80 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 2e 29 3_interrupt()].)
22d90 20 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20 .** Incomplete
22da0 75 70 64 61 74 65 73 20 6d 61 79 20 62 65 20 72 updates may be r
22db0 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74 olled back and t
22dc0 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 ransactions canc
22dd0 65 6c 6c 65 64 2c 20 20 0a 2a 2a 20 64 65 70 65 elled, .** depe
22de0 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 nding on the cir
22df0 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 cumstances, and
22e00 74 68 65 20 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 the .** [error c
22e10 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20 77 69 ode] returned wi
22e20 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 ll be [SQLITE_AB
22e30 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 ORT]..**.** INVA
22e40 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 RIANTS:.**.** {F
22e50 31 31 33 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 11302} The [sqli
22e60 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d te3_finalize(S)]
22e70 20 69 6e 74 65 72 66 61 63 65 20 64 65 73 74 72 interface destr
22e80 6f 79 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 oys the.**
22e90 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 [prepared st
22ea0 61 74 65 6d 65 6e 74 5d 20 53 20 61 6e 64 20 72 atement] S and r
22eb0 65 6c 65 61 73 65 73 20 61 6c 6c 0a 2a 2a 20 20 eleases all.**
22ec0 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 61 memory a
22ed0 6e 64 20 66 69 6c 65 20 72 65 73 6f 75 72 63 65 nd file resource
22ee0 73 20 68 65 6c 64 20 62 79 20 74 68 61 74 20 6f s held by that o
22ef0 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 bject..**.** {F1
22f00 31 33 30 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 1304} If the mos
22f10 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f t recent call to
22f20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 [sqlite3_step(S
22f30 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 )] for the.**
22f40 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 [prepared
22f50 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 statement] S re
22f60 74 75 72 6e 65 64 20 61 6e 20 65 72 72 6f 72 2c turned an error,
22f70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
22f80 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c n [sqlite3_final
22f90 69 7a 65 28 53 29 5d 20 72 65 74 75 72 6e 73 20 ize(S)] returns
22fa0 74 68 61 74 20 73 61 6d 65 20 65 72 72 6f 72 2e that same error.
22fb0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
22fc0 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 finalize(sqlite3
22fd0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a _stmt *pStmt);..
22fe0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
22ff0 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 Reset A Prepared
23000 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 Statement Objec
23010 74 20 7b 46 31 33 33 33 30 7d 0a 2a 2a 0a 2a 2a t {F13330}.**.**
23020 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 The sqlite3_res
23030 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 et() function is
23040 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 called to reset
23050 20 61 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 a .** [prepared
23060 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 statement] obje
23070 63 74 2e 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 69 ct..** back to i
23080 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 ts initial state
23090 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 , ready to be re
230a0 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e -executed..** An
230b0 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 y SQL statement
230c0 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 variables that h
230d0 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 ad values bound
230e0 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a to them using.**
230f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 the [sqlite3_bi
23100 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 nd_blob | sqlite
23110 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 3_bind_*() API]
23120 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c retain their val
23130 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c ues..** Use [sql
23140 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 ite3_clear_bindi
23150 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 ngs()] to reset
23160 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a the bindings..**
23170 0a 2a 2a 20 7b 46 31 31 33 33 32 7d 20 54 68 65 .** {F11332} The
23180 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
23190 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 S)] interface re
231a0 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 sets the [prepar
231b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a ed statement] S.
231c0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 61 63 6b ** back
231d0 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e to the beginnin
231e0 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d g of its program
231f0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 34 7d ..**.** {F11334}
23200 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 If the most rec
23210 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ent call to [sql
23220 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f ite3_step(S)] fo
23230 72 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b r .** [
23240 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
23250 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b nt] S returned [
23260 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b SQLITE_ROW] or [
23270 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a SQLITE_DONE],.**
23280 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 or if
23290 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
232a0 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f ] has never befo
232b0 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f re been called o
232c0 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 n S,.**
232d0 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 then [sqlite3_r
232e0 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 eset(S)] returns
232f0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a [SQLITE_OK]..**
23300 0a 2a 2a 20 7b 46 31 31 33 33 36 7d 20 49 66 20 .** {F11336} If
23310 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
23320 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
23330 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 0a 2a 2a _step(S)] for.**
23340 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 [prepa
23350 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
23360 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 indicated an er
23370 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 ror, then.**
23380 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 [sqlite3_r
23390 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 eset(S)] returns
233a0 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 an appropriate
233b0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a [error code]..**
233c0 0a 2a 2a 20 7b 46 31 31 33 33 38 7d 20 54 68 65 .** {F11338} The
233d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
233e0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f S)] interface do
233f0 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 es not change th
23400 65 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 e values.**
23410 20 20 20 20 20 6f 66 20 61 6e 79 20 5b 73 71 6c of any [sql
23420 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 ite3_bind_blob|b
23430 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 5b 70 72 65 indings] on [pre
23440 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
23450 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 S..*/.int sqlit
23460 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 e3_reset(sqlite3
23470 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a _stmt *pStmt);..
23480 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
23490 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 Create Or Redefi
234a0 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 ne SQL Functions
234b0 20 7b 46 31 36 31 30 30 7d 0a 2a 2a 20 4b 45 59 {F16100}.** KEY
234c0 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e WORDS: {function
234d0 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e creation routin
234e0 65 73 7d 20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 es} .**.** These
234f0 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 two functions (
23500 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f collectively kno
23510 77 6e 20 61 73 0a 2a 2a 20 22 66 75 6e 63 74 69 wn as.** "functi
23520 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 on creation rout
23530 69 6e 65 73 22 29 20 61 72 65 20 75 73 65 64 20 ines") are used
23540 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 to add SQL funct
23550 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 ions or aggregat
23560 65 73 0a 2a 2a 20 6f 72 20 74 6f 20 72 65 64 65 es.** or to rede
23570 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f fine the behavio
23580 72 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 r of existing SQ
23590 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 L functions or a
235a0 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 0a ggregates. The.
235b0 2a 2a 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e ** difference on
235c0 6c 79 20 62 65 74 77 65 65 6e 20 74 68 65 20 74 ly between the t
235d0 77 6f 20 69 73 20 74 68 61 74 20 74 68 65 20 73 wo is that the s
235e0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c econd parameter,
235f0 20 74 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 the.** name of
23600 74 68 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e the (scalar) fun
23610 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 ction or aggrega
23620 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69 te, is encoded i
23630 6e 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 n UTF-8 for.** s
23640 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
23650 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 nction() and UTF
23660 2d 31 36 20 66 6f 72 20 73 71 6c 69 74 65 33 5f -16 for sqlite3_
23670 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
23680 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6()..**.** The f
23690 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 irst argument is
236a0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
236b0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 onnection] that
236c0 68 6f 6c 64 73 20 74 68 65 0a 2a 2a 20 53 51 4c holds the.** SQL
236d0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 function or agg
236e0 72 65 67 61 74 65 20 69 73 20 74 6f 20 62 65 20 regate is to be
236f0 61 64 64 65 64 20 6f 72 20 72 65 64 65 66 69 6e added or redefin
23700 65 64 2e 20 49 66 20 61 20 73 69 6e 67 6c 65 0a ed. If a single.
23710 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 ** program uses
23720 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 more than one da
23730 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 69 6e tabase handle in
23740 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 ternally, then S
23750 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 QL.** functions
23760 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6d 75 or aggregates mu
23770 73 74 20 62 65 20 61 64 64 65 64 20 69 6e 64 69 st be added indi
23780 76 69 64 75 61 6c 6c 79 20 74 6f 20 65 61 63 68 vidually to each
23790 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 68 61 6e database.** han
237a0 64 6c 65 20 77 69 74 68 20 77 68 69 63 68 20 74 dle with which t
237b0 68 65 79 20 77 69 6c 6c 20 62 65 20 75 73 65 64 hey will be used
237c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f ..**.** The seco
237d0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
237e0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
237f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 SQL function to
23800 62 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 6f 72 be created.** or
23810 20 72 65 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 redefined..** T
23820 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 he length of the
23830 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 name is limited
23840 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65 to 255 bytes, e
23850 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 xclusive of the
23860 0a 2a 2a 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 .** zero-termina
23870 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 tor. Note that
23880 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 the name length
23890 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 limit is in byte
238a0 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 s, not.** charac
238b0 74 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d ters. Any attem
238c0 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 pt to create a f
238d0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c unction with a l
238e0 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 onger name.** wi
238f0 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 ll result in an
23900 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 65 72 72 SQLITE_ERROR err
23910 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 or..**.** The th
23920 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ird parameter is
23930 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 the number of a
23940 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 rguments that th
23950 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f e SQL function o
23960 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 r.** aggregate t
23970 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70 61 akes. If this pa
23980 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 rameter is negat
23990 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 53 51 ive, then the SQ
239a0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a L function or.**
239b0 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 aggregate may t
239c0 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f ake any number o
239d0 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a f arguments..**.
239e0 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 ** The fourth pa
239f0 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 rameter, eTextRe
23a00 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 p, specifies wha
23a10 74 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 t .** [SQLITE_UT
23a20 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 F8 | text encodi
23a30 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e ng] this SQL fun
23a40 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f ction prefers fo
23a50 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 r.** its paramet
23a60 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 ers. Any SQL fu
23a70 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 nction implement
23a80 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 ation should be
23a90 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 able to work.**
23aa0 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c work with UTF-8,
23ab0 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 UTF-16le, or UT
23ac0 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d F-16be. But som
23ad0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
23ae0 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 s may be.** more
23af0 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 efficient with
23b00 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 one encoding tha
23b10 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 20 69 n another. It i
23b20 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 s allowed to.**
23b30 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 invoke sqlite3_c
23b40 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
23b50 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 or sqlite3_crea
23b60 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 te_function16()
23b70 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 multiple.** time
23b80 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 s with the same
23b90 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 function but wit
23ba0 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 h different valu
23bb0 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a es of eTextRep..
23bc0 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 ** When multiple
23bd0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
23be0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e of the same fun
23bf0 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 ction are availa
23c00 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 ble, SQLite.** w
23c10 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 ill pick the one
23c20 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 that involves t
23c30 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 he least amount
23c40 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 of data conversi
23c50 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 on..** If there
23c60 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 is only a single
23c70 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
23c80 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 which does not c
23c90 61 72 65 20 77 68 61 74 0a 2a 2a 20 74 65 78 74 are what.** text
23ca0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 encoding is use
23cb0 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 d, then the four
23cc0 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 th argument shou
23cd0 6c 64 20 62 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 ld be.** [SQLITE
23ce0 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 _ANY]..**.** The
23cf0 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 fifth parameter
23d00 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 is an arbitrary
23d10 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 pointer. The i
23d20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a mplementation.**
23d30 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e of the function
23d40 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 can gain access
23d50 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 to this pointer
23d60 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 using.** [sqlit
23d70 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e e3_user_data()].
23d80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e .**.** The seven
23d90 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20 6e th, eighth and n
23da0 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c inth parameters,
23db0 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e xFunc, xStep an
23dc0 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a d xFinal, are.**
23dd0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c pointers to C-l
23de0 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e anguage function
23df0 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 s that implement
23e00 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 the SQL.** func
23e10 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 tion or aggregat
23e20 65 2e 20 41 20 73 63 61 6c 61 72 20 53 51 4c 20 e. A scalar SQL
23e30 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 function require
23e40 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 s an implementat
23e50 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46 ion of.** the xF
23e60 75 6e 63 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c unc callback onl
23e70 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 y, NULL pointers
23e80 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 should be passe
23e90 64 20 61 73 20 74 68 65 20 78 53 74 65 70 0a 2a d as the xStep.*
23ea0 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 70 61 72 * and xFinal par
23eb0 61 6d 65 74 65 72 73 2e 20 41 6e 20 61 67 67 72 ameters. An aggr
23ec0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 egate SQL functi
23ed0 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 on requires an i
23ee0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a mplementation.**
23ef0 20 6f 66 20 78 53 74 65 70 20 61 6e 64 20 78 46 of xStep and xF
23f00 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 68 inal and NULL sh
23f10 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 66 ould be passed f
23f20 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20 64 65 6c or xFunc. To del
23f30 65 74 65 20 61 6e 0a 2a 2a 20 65 78 69 73 74 69 ete an.** existi
23f40 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 ng SQL function
23f50 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 or aggregate, pa
23f60 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 ss NULL for all
23f70 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a three function.*
23f80 2a 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a * callback..**.*
23f90 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 * It is permitte
23fa0 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 d to register mu
23fb0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 ltiple implement
23fc0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 ations of the sa
23fd0 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 me.** functions
23fe0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 with the same na
23ff0 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 me but with eith
24000 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d er differing num
24010 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d bers of.** argum
24020 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e ents or differin
24030 67 20 70 65 72 66 65 72 72 65 64 20 74 65 78 74 g perferred text
24040 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51 4c encodings. SQL
24050 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 ite will use.**
24060 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 the implementati
24070 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 on most closely
24080 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 matches the way
24090 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 in which the.**
240a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 SQL function is
240b0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 used..**.** INVA
240c0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 RIANTS:.**.** {F
240d0 31 36 31 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 16103} The [sqli
240e0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
240f0 69 6f 6e 31 36 28 29 5d 20 69 6e 74 65 72 66 61 ion16()] interfa
24100 63 65 20 62 65 68 61 76 65 73 20 65 78 61 63 74 ce behaves exact
24110 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c ly.** l
24120 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 ike [sqlite3_cre
24130 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 ate_function()]
24140 69 6e 20 65 76 65 72 79 20 77 61 79 20 65 78 63 in every way exc
24150 65 70 74 20 74 68 61 74 20 69 74 0a 2a 2a 20 20 ept that it.**
24160 20 20 20 20 20 20 20 20 69 6e 74 65 72 70 72 65 interpre
24170 74 73 20 74 68 65 20 7a 46 75 6e 63 74 69 6f 6e ts the zFunction
24180 4e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 61 73 Name argument as
24190 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 .** zer
241a0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 o-terminated UTF
241b0 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 -16 native byte
241c0 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66 order instead of
241d0 20 61 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 as a.**
241e0 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 zero-terminate
241f0 64 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b d UTF-8..**.** {
24200 46 31 36 31 30 36 7d 20 0a 2a 2f 0a 69 6e 74 20 F16106} .*/.int
24210 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
24220 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 unction(. sqlit
24230 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 e3 *db,. const
24240 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e char *zFunctionN
24250 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c ame,. int nArg,
24260 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c . int eTextRep,
24270 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 . void *pApp,.
24280 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 void (*xFunc)(s
24290 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
242a0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 int,sqlite3_valu
242b0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 e**),. void (*x
242c0 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f Step)(sqlite3_co
242d0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 ntext*,int,sqlit
242e0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 e3_value**),. v
242f0 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 oid (*xFinal)(sq
24300 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a lite3_context*).
24310 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 );.int sqlite3_c
24320 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
24330 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
24340 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a . const void *z
24350 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 FunctionName,.
24360 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 int nArg,. int
24370 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 eTextRep,. void
24380 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 *pApp,. void (
24390 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f *xFunc)(sqlite3_
243a0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c context*,int,sql
243b0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 ite3_value**),.
243c0 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 void (*xStep)(s
243d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
243e0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 int,sqlite3_valu
243f0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 e**),. void (*x
24400 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 Final)(sqlite3_c
24410 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a ontext*).);../*.
24420 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 ** CAPI3REF: Tex
24430 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b 46 31 30 t Encodings {F10
24440 32 36 37 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 267}.**.** These
24450 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 constant define
24460 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 integer codes t
24470 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 hat represent th
24480 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 e various.** tex
24490 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 t encodings supp
244a0 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e orted by SQLite.
244b0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
244c0 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 TE_UTF8
244d0 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 1.#define SQLI
244e0 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 TE_UTF16LE
244f0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 2.#define SQLI
24500 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 TE_UTF16BE
24510 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 3.#define SQLI
24520 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 TE_UTF16
24530 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 4 /* Use na
24540 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 tive byte order
24550 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
24560 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 E_ANY
24570 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5 /* sqlite3
24580 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
24590 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 only */.#define
245a0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c SQLITE_UTF16_AL
245b0 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 IGNED 8 /* s
245c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
245d0 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a llation only */.
245e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
245f0 20 4f 62 73 6f 6c 65 74 65 20 46 75 6e 63 74 69 Obsolete Functi
24600 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ons.**.** These
24610 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 61 6c functions are al
24620 6c 20 6e 6f 77 20 6f 62 73 6f 6c 65 74 65 2e 20 l now obsolete.
24630 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 In order to mai
24640 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 ntain.** backwar
24650 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ds compatibility
24660 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 with older code
24670 2c 20 77 65 20 63 6f 6e 74 69 6e 75 65 20 74 6f , we continue to
24680 20 73 75 70 70 6f 72 74 0a 2a 2a 20 74 68 65 73 support.** thes
24690 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 48 6f e functions. Ho
246a0 77 65 76 65 72 2c 20 6e 65 77 20 64 65 76 65 6c wever, new devel
246b0 6f 70 6d 65 6e 74 20 70 72 6f 6a 65 63 74 73 20 opment projects
246c0 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 should avoid.**
246d0 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 the use of these
246e0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 functions. To
246f0 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 help encourage p
24700 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a eople to avoid.*
24710 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 * using these fu
24720 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 nctions, we are
24730 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c not going to tel
24740 6c 20 79 6f 75 20 77 61 6e 74 20 74 68 65 79 20 l you want they
24750 64 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 do..*/.int sqlit
24760 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 e3_aggregate_cou
24770 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 nt(sqlite3_conte
24780 78 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 xt*);.int sqlite
24790 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 3_expired(sqlite
247a0 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 3_stmt*);.int sq
247b0 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 lite3_transfer_b
247c0 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f indings(sqlite3_
247d0 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 stmt*, sqlite3_s
247e0 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 tmt*);.int sqlit
247f0 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 e3_global_recove
24800 72 28 76 6f 69 64 29 3b 0a 76 6f 69 64 20 73 71 r(void);.void sq
24810 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 lite3_thread_cle
24820 61 6e 75 70 28 76 6f 69 64 29 3b 0a 69 6e 74 20 anup(void);.int
24830 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 sqlite3_memory_a
24840 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 larm(void(*)(voi
24850 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 d*,sqlite3_int64
24860 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 ,int),void*,sqli
24870 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a te3_int64);../*.
24880 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 ** CAPI3REF: Obt
24890 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 aining SQL Funct
248a0 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 ion Parameter Va
248b0 6c 75 65 73 20 7b 46 31 35 31 30 30 7d 0a 2a 2a lues {F15100}.**
248c0 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 .** The C-langua
248d0 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ge implementatio
248e0 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f n of SQL functio
248f0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 ns and aggregate
24900 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 s uses.** this s
24910 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 et of interface
24920 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 routines to acce
24930 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 ss the parameter
24940 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 values on.** th
24950 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 e function or ag
24960 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 gregate..**.** T
24970 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 he xFunc (for sc
24980 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 alar functions)
24990 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 or xStep (for ag
249a0 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 gregates) parame
249b0 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 ters.** to [sqli
249c0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
249d0 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 ion()] and [sqli
249e0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
249f0 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 ion16()].** defi
24a00 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 ne callbacks tha
24a10 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 t implement the
24a20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e SQL functions an
24a30 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a d aggregates..**
24a40 20 54 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 The 4th paramet
24a50 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c er to these call
24a60 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 backs is an arra
24a70 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f y of pointers to
24a80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c .** [sqlite3_val
24a90 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 ue] objects. Th
24aa0 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 ere is one [sqli
24ab0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
24ac0 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 t for.** each pa
24ad0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 rameter to the S
24ae0 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 QL function. Th
24af0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
24b00 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 used to.** extr
24b10 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 act values from
24b20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c the [sqlite3_val
24b30 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a ue] objects..**.
24b40 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
24b50 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 s work just like
24b60 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 the correspondi
24b70 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ng .** [sqlite3_
24b80 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 20 7c 20 73 71 column_blob | sq
24b90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 20 72 lite3_column_* r
24ba0 6f 75 74 69 6e 65 73 5d 20 65 78 63 65 70 74 20 outines] except
24bb0 74 68 61 74 20 0a 2a 2a 20 74 68 65 73 65 20 72 that .** these r
24bc0 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 outines take a s
24bd0 69 6e 67 6c 65 20 5b 73 71 6c 69 74 65 33 5f 76 ingle [sqlite3_v
24be0 61 6c 75 65 2a 5d 20 70 6f 69 6e 74 65 72 20 69 alue*] pointer i
24bf0 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 6e 20 nstead.** of an
24c00 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 [sqlite3_stmt*]
24c10 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 pointer and an i
24c20 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 nteger column nu
24c30 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 mber..**.** The
24c40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
24c50 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 xt16() interface
24c60 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 31 extracts a UTF1
24c70 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 6 string.** in t
24c80 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f he native byte-o
24c90 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 rder of the host
24ca0 20 6d 61 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a machine. The.*
24cb0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f * sqlite3_value_
24cc0 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 text16be() and s
24cd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
24ce0 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 t16le() interfac
24cf0 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 es.** extract UT
24d00 46 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 F16 strings as b
24d10 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 ig-endian and li
24d20 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 ttle-endian resp
24d30 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ectively..**.**
24d40 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 The sqlite3_valu
24d50 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 e_numeric_type()
24d60 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d interface attem
24d70 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 pts to apply.**
24d80 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 numeric affinity
24d90 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 to the value.
24da0 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 This means that
24db0 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a an attempt is.**
24dc0 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 made to convert
24dd0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e the value to an
24de0 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 integer or floa
24df0 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a ting point. If.
24e00 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 ** such a conver
24e10 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 sion is possible
24e20 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 without loss of
24e30 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e information (in
24e40 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 20 other.** words
24e50 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 if the value is
24e60 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f a string that lo
24e70 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 oks like a numbe
24e80 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 r).** then the c
24e90 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 64 6f 6e onversion is don
24ea0 65 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f e. Otherwise no
24eb0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 conversion occu
24ec0 72 73 2e 20 20 54 68 65 20 0a 2a 2a 20 5b 53 51 rs. The .** [SQ
24ed0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 LITE_INTEGER | d
24ee0 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 atatype] after c
24ef0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 onversion is ret
24f00 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 urned..**.** Ple
24f10 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c ase pay particul
24f20 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 ar attention to
24f30 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 the fact that th
24f40 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a e pointer that.*
24f50 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 66 72 * is returned fr
24f60 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 om [sqlite3_valu
24f70 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 e_blob()], [sqli
24f80 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 te3_value_text()
24f90 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 ], or.** [sqlite
24fa0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 3_value_text16()
24fb0 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 ] can be invalid
24fc0 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 ated by a subseq
24fd0 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 uent call to.**
24fe0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 [sqlite3_value_b
24ff0 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 ytes()], [sqlite
25000 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 3_value_bytes16(
25010 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c )], [sqlite3_val
25020 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f ue_text()],.** o
25030 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 r [sqlite3_value
25040 5f 74 65 78 74 31 36 28 29 5d 2e 20 20 0a 2a 2a _text16()]. .**
25050 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
25060 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 es must be calle
25070 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 d from the same
25080 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 thread as.** the
25090 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 SQL function th
250a0 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 at supplied the
250b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 20 70 sqlite3_value* p
250c0 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 20 4f 72 arameters..** Or
250d0 2c 20 69 66 20 74 68 65 20 73 71 6c 69 74 65 33 , if the sqlite3
250e0 5f 76 61 6c 75 65 2a 20 61 72 67 75 6d 65 6e 74 _value* argument
250f0 20 63 6f 6d 65 73 20 66 72 6f 6d 20 74 68 65 20 comes from the
25100 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
25110 76 61 6c 75 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 value()].** inte
25120 72 66 61 63 65 2c 20 74 68 65 6e 20 74 68 65 73 rface, then thes
25130 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c e routines shoul
25140 64 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d d be called from
25150 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 the same thread
25160 0a 2a 2a 20 74 68 61 74 20 72 61 6e 20 5b 73 71 .** that ran [sq
25170 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c lite3_column_val
25180 75 65 28 29 5d 2e 0a 2a 2a 0a 2a 2f 0a 63 6f 6e ue()]..**.*/.con
25190 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
251a0 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 _value_blob(sqli
251b0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 te3_value*);.int
251c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 sqlite3_value_b
251d0 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c ytes(sqlite3_val
251e0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 ue*);.int sqlite
251f0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 3_value_bytes16(
25200 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
25210 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f .double sqlite3_
25220 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c value_double(sql
25230 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e ite3_value*);.in
25240 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f t sqlite3_value_
25250 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 int(sqlite3_valu
25260 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 e*);.sqlite3_int
25270 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 64 sqlite3_value
25280 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 _int64(sqlite3_v
25290 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e alue*);.const un
252a0 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c signed char *sql
252b0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 ite3_value_text(
252c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
252d0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
252e0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
252f0 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 6(sqlite3_value*
25300 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
25310 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
25320 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 t16le(sqlite3_va
25330 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 lue*);.const voi
25340 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 d *sqlite3_value
25350 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 _text16be(sqlite
25360 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 3_value*);.int s
25370 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 qlite3_value_typ
25380 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a e(sqlite3_value*
25390 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 );.int sqlite3_v
253a0 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 alue_numeric_typ
253b0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a e(sqlite3_value*
253c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
253d0 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 EF: Obtain Aggre
253e0 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f gate Function Co
253f0 6e 74 65 78 74 20 7b 46 31 36 32 31 30 7d 0a 2a ntext {F16210}.*
25400 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 *.** The impleme
25410 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 ntation of aggre
25420 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f gate SQL functio
25430 6e 73 20 75 73 65 20 74 68 69 73 20 72 6f 75 74 ns use this rout
25440 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a ine to allocate.
25450 2a 2a 20 61 20 73 74 72 75 63 74 75 72 65 20 66 ** a structure f
25460 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 or storing their
25470 20 73 74 61 74 65 2e 20 20 0a 2a 2a 20 7b 46 31 state. .** {F1
25480 36 32 31 31 7d 20 54 68 65 20 66 69 72 73 74 20 6211} The first
25490 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 time the sqlite3
254a0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
254b0 78 74 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a xt() routine is.
254c0 2a 2a 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 ** is called for
254d0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 a particular ag
254e0 67 72 65 67 61 74 65 2c 20 53 51 4c 69 74 65 20 gregate, SQLite
254f0 61 6c 6c 6f 63 61 74 65 73 20 6e 42 79 74 65 73 allocates nBytes
25500 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 7a 65 of memory.** ze
25510 72 6f 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c ros that memory,
25520 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 and returns a p
25530 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 0a 2a 2a ointer to it..**
25540 20 7b 46 31 36 32 31 32 7d 20 4f 6e 20 73 65 63 {F16212} On sec
25550 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 ond and subseque
25560 6e 74 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 nt calls to sqli
25570 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
25580 6e 74 65 78 74 28 29 0a 2a 2a 20 66 6f 72 20 74 ntext().** for t
25590 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 he same aggregat
255a0 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64 65 78 e function index
255b0 2c 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 , the same buffe
255c0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 7b r is returned. {
255d0 45 4e 44 7d 0a 2a 2a 20 54 68 65 20 69 6d 70 6c END}.** The impl
255e0 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 ementation.** of
255f0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 63 the aggregate c
25600 61 6e 20 75 73 65 20 74 68 65 20 72 65 74 75 72 an use the retur
25610 6e 65 64 20 62 75 66 66 65 72 20 74 6f 20 61 63 ned buffer to ac
25620 63 75 6d 75 6c 61 74 65 20 64 61 74 61 2e 0a 2a cumulate data..*
25630 2a 0a 2a 2a 20 7b 46 31 36 32 31 33 7d 20 53 51 *.** {F16213} SQ
25640 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c Lite automatical
25650 6c 79 20 66 72 65 65 73 20 74 68 65 20 61 6c 6c ly frees the all
25660 6f 63 61 74 65 64 20 62 75 66 66 65 72 20 77 68 ocated buffer wh
25670 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 en the aggregate
25680 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 .** query conclu
25690 64 65 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a des. {END}.**.**
256a0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d The first param
256b0 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61 eter should be a
256c0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 0a 2a 2a copy of the .**
256d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 [sqlite3_contex
256e0 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e t | SQL function
256f0 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 context] that i
25700 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 s the first.** p
25710 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
25720 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 callback routine
25730 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 that implements
25740 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a the aggregate.*
25750 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a * function..**.*
25760 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d * This routine m
25770 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 ust be called fr
25780 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 om the same thre
25790 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 ad in which.** t
257a0 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c he aggregate SQL
257b0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e function is run
257c0 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 ning..*/.void *s
257d0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
257e0 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 _context(sqlite3
257f0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e _context*, int n
25800 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 Bytes);../*.** C
25810 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 API3REF: User Da
25820 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 ta For Functions
25830 20 7b 46 31 36 32 34 30 7d 0a 2a 2a 0a 2a 2a 20 {F16240}.**.**
25840 7b 46 31 36 32 34 31 7d 20 54 68 65 20 73 71 6c {F16241} The sql
25850 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 ite3_user_data()
25860 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
25870 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 ns a copy of.**
25880 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 the pointer that
25890 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61 was the pUserDa
258a0 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 ta parameter (th
258b0 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 e 5th parameter)
258c0 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68 65 20 5b .** of the the [
258d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
258e0 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e unction()].** an
258f0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 d [sqlite3_creat
25900 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 e_function16()]
25910 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 routines that or
25920 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 iginally.** regi
25930 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 stered the appli
25940 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 cation defined f
25950 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a unction. {END}.*
25960 2a 0a 2a 2a 20 7b 55 31 36 32 34 33 7d 20 54 68 *.** {U16243} Th
25970 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 is routine must
25980 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 be called from t
25990 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 he same thread i
259a0 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 n which.** the a
259b0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
259c0 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 ed function is r
259d0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 unning..*/.void
259e0 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 *sqlite3_user_da
259f0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ta(sqlite3_conte
25a00 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 xt*);../*.** CAP
25a10 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 I3REF: Function
25a20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 20 7b Auxiliary Data {
25a30 46 31 36 32 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 F16270}.**.** Th
25a40 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 e following two
25a50 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 functions may be
25a60 20 75 73 65 64 20 62 79 20 73 63 61 6c 61 72 20 used by scalar
25a70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f SQL functions to
25a80 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 .** associate me
25a90 74 61 2d 64 61 74 61 20 77 69 74 68 20 61 72 67 ta-data with arg
25aa0 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 ument values. If
25ab0 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 the same value
25ac0 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 is passed to.**
25ad0 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 multiple invocat
25ae0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 ions of the same
25af0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 SQL function du
25b00 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 ring query execu
25b10 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 tion, under.** s
25b20 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 ome circumstance
25b30 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 s the associated
25b40 20 6d 65 74 61 2d 64 61 74 61 20 6d 61 79 20 62 meta-data may b
25b50 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 e preserved. Thi
25b60 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 s may.** be used
25b70 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 , for example, t
25b80 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d o add a regular-
25b90 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 expression match
25ba0 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 ing scalar.** fu
25bb0 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 nction. The comp
25bc0 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 iled version of
25bd0 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 the regular expr
25be0 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 ession is stored
25bf0 20 61 73 0a 2a 2a 20 6d 65 74 61 2d 64 61 74 61 as.** meta-data
25c00 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
25c10 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 the SQL value p
25c20 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67 assed as the reg
25c30 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a ular expression.
25c40 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 ** pattern. The
25c50 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 compiled regula
25c60 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e r expression can
25c70 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 be reused on mu
25c80 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 ltiple.** invoca
25c90 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d tions of the sam
25ca0 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 e function so th
25cb0 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 at the original
25cc0 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a pattern string.*
25cd0 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 * does not need
25ce0 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 to be recompiled
25cf0 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 on each invocat
25d00 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 ion..**.** {F162
25d10 37 31 7d 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 71}.** The sqlit
25d20 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 e3_get_auxdata()
25d30 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
25d40 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
25d50 74 68 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a 2a the meta-data.**
25d60 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 associated by t
25d70 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 he sqlite3_set_a
25d80 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f uxdata() functio
25d90 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 n with the Nth a
25da0 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 rgument.** value
25db0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 to the applicat
25dc0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
25dd0 74 69 6f 6e 2e 0a 2a 2a 20 7b 46 31 36 32 37 32 tion..** {F16272
25de0 7d 20 49 66 20 6e 6f 20 6d 65 74 61 2d 64 61 74 } If no meta-dat
25df0 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 20 a has been ever
25e00 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 been set for the
25e10 20 4e 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 Nth.** argument
25e20 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e of the function
25e30 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f 6f 72 , or if the coor
25e40 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 esponding functi
25e50 6f 6e 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 on parameter.**
25e60 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 has changed sinc
25e70 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 e the meta-data
25e80 77 61 73 20 73 65 74 2c 20 74 68 65 6e 20 73 71 was set, then sq
25e90 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 lite3_get_auxdat
25ea0 61 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 a().** returns a
25eb0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a NULL pointer..*
25ec0 2a 0a 2a 2a 20 7b 46 31 36 32 37 35 7d 20 54 68 *.** {F16275} Th
25ed0 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 e sqlite3_set_au
25ee0 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 xdata() interfac
25ef0 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 e saves the meta
25f00 2d 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 -data.** pointed
25f10 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 to by its 3rd p
25f20 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 arameter as the
25f30 6d 65 74 61 2d 64 61 74 61 20 66 6f 72 20 74 68 meta-data for th
25f40 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 e N-th.** argume
25f50 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 nt of the applic
25f60 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
25f70 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 20 53 75 nction. {END} Su
25f80 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c bsequent.** call
25f90 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 s to sqlite3_get
25fa0 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 _auxdata() might
25fb0 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 return this dat
25fc0 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 a, if it has.**
25fd0 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 not been destroy
25fe0 65 64 2e 20 0a 2a 2a 20 7b 46 31 36 32 37 37 7d ed. .** {F16277}
25ff0 20 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 If it is not NU
26000 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 LL, SQLite will
26010 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 invoke the destr
26020 75 63 74 6f 72 20 0a 2a 2a 20 66 75 6e 63 74 69 uctor .** functi
26030 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 on given by the
26040 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 4th parameter to
26050 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 sqlite3_set_aux
26060 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 data() on.** the
26070 20 6d 65 74 61 2d 64 61 74 61 20 77 68 65 6e 20 meta-data when
26080 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
26090 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d g function param
260a0 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 eter changes.**
260b0 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 or when the SQL
260c0 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 statement comple
260d0 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 tes, whichever c
260e0 6f 6d 65 73 20 66 69 72 73 74 2e 20 7b 45 4e 44 omes first. {END
260f0 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 74 }.**.** In pract
26100 69 63 65 2c 20 6d 65 74 61 2d 64 61 74 61 20 69 ice, meta-data i
26110 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 s preserved betw
26120 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c een function cal
26130 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 ls for.** expres
26140 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 sions that are c
26150 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 onstant at compi
26160 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e le time. This in
26170 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a cludes literal.*
26180 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 53 51 4c * values and SQL
26190 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a variables..**.*
261a0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
261b0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 must be called
261c0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 from the same th
261d0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a read in which.**
261e0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
261f0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f n is running..*/
26200 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 .void *sqlite3_g
26210 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 et_auxdata(sqlit
26220 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 e3_context*, int
26230 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 N);.void sqlite
26240 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 3_set_auxdata(sq
26250 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
26260 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f int N, void*, vo
26270 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a id (*)(void*));.
26280 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
26290 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 : Constants Defi
262a0 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 ning Special Des
262b0 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 tructor Behavior
262c0 20 7b 46 31 30 32 38 30 7d 0a 2a 2a 0a 2a 2a 20 {F10280}.**.**
262d0 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 These are specia
262e0 6c 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 l value for the
262f0 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 destructor that
26300 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 is passed in as
26310 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 the.** final arg
26320 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 ument to routine
26330 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f s like [sqlite3_
26340 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 result_blob()].
26350 20 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 If the destruct
26360 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 or.** argument i
26370 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c s SQLITE_STATIC,
26380 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 it means that t
26390 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 he content point
263a0 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a er is constant.*
263b0 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 * and will never
263c0 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 change. It doe
263d0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 s not need to be
263e0 20 64 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65 destroyed. The
263f0 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e .** SQLITE_TRAN
26400 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e SIENT value mean
26410 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 s that the conte
26420 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 nt will likely c
26430 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 hange in.** the
26440 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 near future and
26450 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 that SQLite shou
26460 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 ld make its own
26470 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a private copy of.
26480 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 ** the content b
26490 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e efore returning.
264a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 .**.** The typed
264b0 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 ef is necessary
264c0 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 to work around p
264d0 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 roblems in certa
264e0 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c in.** C++ compil
264f0 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 ers. See ticket
26500 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 #2191..*/.typed
26510 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 ef void (*sqlite
26520 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 3_destructor_typ
26530 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 e)(void*);.#defi
26540 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 ne SQLITE_STATIC
26550 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f ((sqlite3_
26560 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 destructor_type)
26570 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 0).#define SQLIT
26580 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 E_TRANSIENT ((
26590 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 sqlite3_destruct
265a0 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a or_type)-1)../*.
265b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 ** CAPI3REF: Set
265c0 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 ting The Result
265d0 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 Of An SQL Functi
265e0 6f 6e 20 7b 46 31 36 34 30 30 7d 0a 2a 2a 0a 2a on {F16400}.**.*
265f0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
26600 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 are used by the
26610 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c xFunc or xFinal
26620 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a callbacks that.
26630 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c ** implement SQL
26640 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 functions and a
26650 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a ggregates. See.
26660 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 ** [sqlite3_crea
26670 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 te_function()] a
26680 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 nd [sqlite3_crea
26690 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d te_function16()]
266a0 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e .** for addition
266b0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a al information..
266c0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 **.** These func
266d0 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 tions work very
266e0 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 0a 2a much like the .*
266f0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
26700 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 blob | sqlite3_b
26710 69 6e 64 5f 2a 5d 20 66 61 6d 69 6c 79 20 6f 66 ind_*] family of
26720 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 0a functions used.
26730 2a 2a 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 ** to bind value
26740 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 s to host parame
26750 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 ters in prepared
26760 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 statements..**
26770 52 65 66 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 Refer to the.**
26780 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
26790 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e ob | sqlite3_bin
267a0 64 5f 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f d_* documentatio
267b0 6e 5d 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 n] for.** additi
267c0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
267d0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 32 7d ..**.** {F16402}
267e0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 The sqlite3_res
267f0 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 ult_blob() inter
26800 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 face sets the re
26810 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 sult from.** an
26820 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 application defi
26830 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ned function to
26840 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 be the BLOB whos
26850 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 e content is poi
26860 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 nted.** to by th
26870 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
26880 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 er and which is
26890 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 N bytes long whe
268a0 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 re N is the.** t
268b0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 hird parameter.
268c0 0a 2a 2a 20 7b 46 31 36 34 30 33 7d 20 54 68 65 .** {F16403} The
268d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
268e0 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 65 72 66 zeroblob() inerf
268f0 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 aces set the res
26900 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 ult of.** the ap
26910 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 plication define
26920 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 d function to be
26930 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 a BLOB containi
26940 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 ng all zero.** b
26950 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 ytes and N bytes
26960 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 in size, where
26970 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f N is the value o
26980 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 f the 2nd parame
26990 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 ter..**.** {F164
269a0 30 37 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 07} The sqlite3_
269b0 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 result_double()
269c0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 interface sets t
269d0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a he result from.*
269e0 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e * an application
269f0 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f defined functio
26a00 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 n to be a floati
26a10 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 ng point value s
26a20 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 pecified.** by i
26a30 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e ts 2nd argument.
26a40 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 39 7d 20 .**.** {F16409}
26a50 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
26a60 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 lt_error() and s
26a70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
26a80 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e ror16() function
26a90 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 s.** cause the i
26aa0 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 mplemented SQL f
26ab0 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 unction to throw
26ac0 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a an exception..*
26ad0 2a 20 7b 46 31 36 34 31 31 7d 20 53 51 4c 69 74 * {F16411} SQLit
26ae0 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e e uses the strin
26af0 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 g pointed to by
26b00 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d the.** 2nd param
26b10 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f eter of sqlite3_
26b20 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f result_error() o
26b30 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 r sqlite3_result
26b40 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 _error16().** as
26b50 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 the text of an
26b60 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 7b error message. {
26b70 46 31 36 34 31 32 7d 20 53 51 4c 69 74 65 20 69 F16412} SQLite i
26b80 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 nterprets the er
26b90 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 ror.** message s
26ba0 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 tring from sqlit
26bb0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
26bc0 29 20 61 73 20 55 54 46 38 2e 20 20 7b 46 31 36 ) as UTF8. {F16
26bd0 34 31 33 7d 20 53 51 4c 69 74 65 0a 2a 2a 20 69 413} SQLite.** i
26be0 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74 nterprets the st
26bf0 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 ring from sqlite
26c00 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
26c10 28 29 20 61 73 20 55 54 46 31 36 20 69 6e 20 6e () as UTF16 in n
26c20 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 ative.** byte or
26c30 64 65 72 2e 20 20 7b 46 31 36 34 31 34 7d 20 49 der. {F16414} I
26c40 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 f the third para
26c50 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
26c60 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a _result_error().
26c70 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 ** or sqlite3_re
26c80 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 sult_error16() i
26c90 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 s negative then
26ca0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 SQLite takes as
26cb0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 the error.** mes
26cc0 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 sage all text up
26cd0 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 through the fir
26ce0 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 st zero characte
26cf0 72 2e 0a 2a 2a 20 7b 46 31 36 34 31 35 7d 20 49 r..** {F16415} I
26d00 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 f the third para
26d10 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
26d20 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 _result_error()
26d30 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 or.** sqlite3_re
26d40 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 sult_error16() i
26d50 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 s non-negative t
26d60 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 hen SQLite takes
26d70 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 that many.** by
26d80 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 tes (not charact
26d90 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e ers) from the 2n
26da0 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 d parameter as t
26db0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 he error message
26dc0 2e 0a 2a 2a 20 7b 46 31 36 34 31 37 7d 20 54 68 ..** {F16417} Th
26dd0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
26de0 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c _error() and sql
26df0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
26e00 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 r16().** routine
26e10 73 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 70 72 s make a copy pr
26e20 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 ivate copy of th
26e30 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 e error message
26e40 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 text before.** t
26e50 68 65 79 20 72 65 74 75 72 6e 2e 20 20 7b 45 4e hey return. {EN
26e60 44 7d 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 D} Hence, the ca
26e70 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 lling function c
26e80 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 an deallocate or
26e90 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 .** modify the t
26ea0 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 ext after they r
26eb0 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 eturn without ha
26ec0 72 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 32 rm..**.** {F1642
26ed0 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 1} The sqlite3_r
26ee0 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 esult_toobig() i
26ef0 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 nterface causes
26f00 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 74 68 72 SQLite.** to thr
26f10 6f 77 20 61 6e 20 65 72 72 6f 72 20 69 6e 64 69 ow an error indi
26f20 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 cating that a st
26f30 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 ring or BLOB is
26f40 74 6f 20 6c 6f 6e 67 0a 2a 2a 20 74 6f 20 72 65 to long.** to re
26f50 70 72 65 73 65 6e 74 2e 20 20 7b 46 31 36 34 32 present. {F1642
26f60 32 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 2} The sqlite3_r
26f70 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e esult_nomem() in
26f80 74 65 72 66 61 63 65 0a 2a 2a 20 63 61 75 73 65 terface.** cause
26f90 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f s SQLite to thro
26fa0 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 69 w an exception i
26fb0 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 ndicating that t
26fc0 68 65 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 he a.** memory a
26fd0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 llocation failed
26fe0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 31 7d ..**.** {F16431}
26ff0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 The sqlite3_res
27000 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 ult_int() interf
27010 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 ace sets the ret
27020 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 urn value.** of
27030 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
27040 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
27050 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 to be the 32-bi
27060 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 t signed integer
27070 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 .** value given
27080 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d in the 2nd argum
27090 65 6e 74 2e 0a 2a 2a 20 7b 46 31 36 34 33 32 7d ent..** {F16432}
270a0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 The sqlite3_res
270b0 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 ult_int64() inte
270c0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 rface sets the r
270d0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f eturn value.** o
270e0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
270f0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
27100 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d on to be the 64-
27110 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 bit signed integ
27120 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 er.** value give
27130 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 n in the 2nd arg
27140 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 ument..**.** {F1
27150 36 34 33 37 7d 20 54 68 65 20 73 71 6c 69 74 65 6437} The sqlite
27160 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 3_result_null()
27170 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 interface sets t
27180 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a he return value.
27190 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 ** of the applic
271a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
271b0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c nction to be NUL
271c0 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 34 31 L..**.** {F16441
271d0 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 } The sqlite3_re
271e0 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c sult_text(), sql
271f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
27200 31 36 28 29 2c 20 0a 2a 2a 20 73 71 6c 69 74 65 16(), .** sqlite
27210 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 3_result_text16l
27220 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 e(), and sqlite3
27230 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 _result_text16be
27240 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a () interfaces.**
27250 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 set the return
27260 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 value of the app
27270 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
27280 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a function to be.
27290 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 ** a text string
272a0 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73 which is repres
272b0 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 ented as UTF-8,
272c0 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 UTF-16 native by
272d0 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 te order,.** UTF
272e0 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 -16 little endia
272f0 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 n, or UTF-16 big
27300 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 endian, respect
27310 69 76 65 6c 79 2e 0a 2a 2a 20 7b 46 31 36 34 34 ively..** {F1644
27320 32 7d 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 2} SQLite takes
27330 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 the text result
27340 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 from the applica
27350 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 tion from.** the
27360 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 2nd parameter o
27370 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 f the sqlite3_re
27380 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 sult_text* inter
27390 66 61 63 65 73 2e 0a 2a 2a 20 7b 46 31 36 34 34 faces..** {F1644
273a0 34 7d 20 49 66 20 74 68 65 20 33 72 64 20 70 61 4} If the 3rd pa
273b0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 rameter to the s
273c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
273d0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a xt* interfaces.*
273e0 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 * is negative, t
273f0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 hen SQLite takes
27400 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f result text fro
27410 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 m the 2nd parame
27420 74 65 72 20 0a 2a 2a 20 74 68 72 6f 75 67 68 20 ter .** through
27430 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 the first zero c
27440 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 7b 46 31 haracter..** {F1
27450 36 34 34 37 7d 20 49 66 20 74 68 65 20 33 72 64 6447} If the 3rd
27460 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
27470 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
27480 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 _text* interface
27490 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 s.** is non-nega
274a0 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 tive, then as ma
274b0 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 ny bytes (not ch
274c0 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 aracters) of the
274d0 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 text.** pointed
274e0 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 to by the 2nd p
274f0 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b arameter are tak
27500 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 en as the applic
27510 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a ation-defined.**
27520 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 function result
27530 2e 0a 2a 2a 20 7b 46 31 36 34 35 31 7d 20 49 66 ..** {F16451} If
27540 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 the 4th paramet
27550 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 er to the sqlite
27560 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 3_result_text* i
27570 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 nterfaces.** or
27580 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 sqlite3_result_b
27590 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c lob is a non-NUL
275a0 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 L pointer, then
275b0 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 SQLite calls tha
275c0 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 t.** function as
275d0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 the destructor
275e0 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 62 on the text or b
275f0 6c 6f 62 20 72 65 73 75 6c 74 20 77 68 65 6e 20 lob result when
27600 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 it has.** finish
27610 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 ed using that re
27620 73 75 6c 74 2e 0a 2a 2a 20 7b 46 31 36 34 35 33 sult..** {F16453
27630 7d 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72 } If the 4th par
27640 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
27650 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
27660 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a t* interfaces.**
27670 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 or sqlite3_resu
27680 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 lt_blob is the s
27690 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 pecial constant
276a0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 SQLITE_STATIC, t
276b0 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 73 hen.** SQLite as
276c0 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 sumes that the t
276d0 65 78 74 20 6f 72 20 62 6c 6f 62 20 72 65 73 75 ext or blob resu
276e0 6c 74 20 69 73 20 63 6f 6e 73 74 61 6e 74 20 73 lt is constant s
276f0 70 61 63 65 20 61 6e 64 0a 2a 2a 20 64 6f 65 73 pace and.** does
27700 20 6e 6f 74 20 63 6f 70 79 20 74 68 65 20 73 70 not copy the sp
27710 61 63 65 20 6f 72 20 63 61 6c 6c 20 61 20 64 65 ace or call a de
27720 73 74 72 75 63 74 6f 72 20 77 68 65 6e 20 69 74 structor when it
27730 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 has.** finished
27740 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 using that resu
27750 6c 74 2e 0a 2a 2a 20 7b 46 31 36 34 35 34 7d 20 lt..** {F16454}
27760 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d If the 4th param
27770 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 eter to the sqli
27780 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a te3_result_text*
27790 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f interfaces.** o
277a0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 r sqlite3_result
277b0 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 _blob is the spe
277c0 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 cial constant SQ
277d0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a LITE_TRANSIENT.*
277e0 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 * then SQLite ma
277f0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 kes a copy of th
27800 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 e result into sp
27810 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f ace obtained fro
27820 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 m.** from [sqlit
27830 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 e3_malloc()] bef
27840 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a ore it returns..
27850 2a 2a 0a 2a 2a 20 7b 46 31 36 34 36 31 7d 20 54 **.** {F16461} T
27860 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
27870 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 t_value() interf
27880 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 ace sets the res
27890 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 ult of.** the ap
278a0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
278b0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 d function to be
278c0 20 61 20 63 6f 70 79 20 74 68 65 20 5b 73 71 6c a copy the [sql
278d0 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f ite3_value].** o
278e0 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20 bject specified
278f0 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d by the 2nd param
27900 65 74 65 72 2e 20 20 7b 46 31 36 34 36 33 7d 20 eter. {F16463}
27910 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 The.** sqlite3_r
27920 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e esult_value() in
27930 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 terface makes a
27940 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c copy of the [sql
27950 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 ite3_value].** s
27960 6f 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f o that [sqlite3_
27970 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 value] specified
27980 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 in the paramete
27990 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a r may change or.
279a0 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 ** be deallocate
279b0 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f d after sqlite3_
279c0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 result_value() r
279d0 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 eturns without h
279e0 61 72 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 36 34 arm..**.** {U164
279f0 39 31 7d 20 54 68 65 73 65 20 72 6f 75 74 69 6e 91} These routin
27a00 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 es are called fr
27a10 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 om within the di
27a20 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 0a fferent thread .
27a30 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 ** than the one
27a40 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 containing the a
27a50 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
27a60 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 ed function that
27a70 20 72 65 63 69 65 76 65 64 0a 2a 2a 20 74 68 65 recieved.** the
27a80 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 [sqlite3_contex
27a90 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 t] pointer, the
27aa0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 results are unde
27ab0 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 fined..*/.void s
27ac0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
27ad0 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ob(sqlite3_conte
27ae0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a xt*, const void*
27af0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 , int, void(*)(v
27b00 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c oid*));.void sql
27b10 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 ite3_result_doub
27b20 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 le(sqlite3_conte
27b30 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f xt*, double);.vo
27b40 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
27b50 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f t_error(sqlite3_
27b60 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
27b70 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 char*, int);.voi
27b80 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
27b90 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 _error16(sqlite3
27ba0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 _context*, const
27bb0 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f void*, int);.vo
27bc0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
27bd0 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 t_error_toobig(s
27be0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
27bf0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
27c00 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 esult_error_nome
27c10 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 m(sqlite3_contex
27c20 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 t*);.void sqlite
27c30 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 3_result_int(sql
27c40 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 ite3_context*, i
27c50 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 nt);.void sqlite
27c60 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 3_result_int64(s
27c70 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
27c80 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b sqlite3_int64);
27c90 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
27ca0 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 sult_null(sqlite
27cb0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 3_context*);.voi
27cc0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
27cd0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f _text(sqlite3_co
27ce0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 ntext*, const ch
27cf0 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a ar*, int, void(*
27d00 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 )(void*));.void
27d10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
27d20 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f ext16(sqlite3_co
27d30 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f ntext*, const vo
27d40 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a id*, int, void(*
27d50 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 )(void*));.void
27d60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
27d70 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f ext16le(sqlite3_
27d80 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
27d90 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 void*, int,void(
27da0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 *)(void*));.void
27db0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
27dc0 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 text16be(sqlite3
27dd0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 _context*, const
27de0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 void*, int,void
27df0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 (*)(void*));.voi
27e00 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
27e10 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 _value(sqlite3_c
27e20 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 ontext*, sqlite3
27e30 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 _value*);.void s
27e40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 qlite3_result_ze
27e50 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 roblob(sqlite3_c
27e60 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b ontext*, int n);
27e70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
27e80 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c : Define New Col
27e90 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 lating Sequences
27ea0 20 7b 46 31 36 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 {F16600}.**.**
27eb0 7b 46 31 36 36 30 31 7d 0a 2a 2a 20 54 68 65 73 {F16601}.** Thes
27ec0 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 e functions are
27ed0 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20 used to add new
27ee0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e collation sequen
27ef0 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 73 ces to the.** [s
27f00 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20 qlite3*] handle
27f10 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65 specified as the
27f20 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e first argument.
27f30 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 32 7d .**.** {F16602}
27f40 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 .** The name of
27f50 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f the new collatio
27f60 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 73 70 n sequence is sp
27f70 65 63 69 66 69 65 64 20 61 73 20 61 20 55 54 46 ecified as a UTF
27f80 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 -8 string.** for
27f90 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
27fa0 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 collation() and
27fb0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
27fc0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a ollation_v2().**
27fd0 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 and a UTF-16 st
27fe0 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33 ring for sqlite3
27ff0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
28000 6e 31 36 28 29 2e 20 7b 46 31 36 36 30 33 7d 20 n16(). {F16603}
28010 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 In all cases.**
28020 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73 the name is pass
28030 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 ed as the second
28040 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 function argume
28050 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 nt..**.** {F1660
28060 34 7d 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 4}.** The third
28070 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 argument may be
28080 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 one of the const
28090 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46 ants [SQLITE_UTF
280a0 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 8],.** [SQLITE_U
280b0 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53 51 4c 49 TF16LE] or [SQLI
280c0 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64 TE_UTF16BE], ind
280d0 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 68 65 icating that the
280e0 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a user-supplied.*
280f0 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 * routine expect
28100 73 20 74 6f 20 62 65 20 70 61 73 73 65 64 20 70 s to be passed p
28110 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e ointers to strin
28120 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 gs encoded using
28130 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 UTF-8,.** UTF-1
28140 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 6 little-endian
28150 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e or UTF-16 big-en
28160 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c dian respectivel
28170 79 2e 20 7b 46 31 36 36 30 35 7d 20 54 68 65 0a y. {F16605} The.
28180 2a 2a 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e ** third argumen
28190 74 20 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20 t might also be
281a0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c [SQLITE_UTF16_AL
281b0 49 47 4e 45 44 5d 20 74 6f 20 69 6e 64 69 63 61 IGNED] to indica
281c0 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 72 te that.** the r
281d0 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 70 outine expects p
281e0 6f 69 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 69 ointers to 16-bi
281f0 74 20 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 73 t word aligned s
28200 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46 trings.** of UTF
28210 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 16 in the native
28220 20 62 79 74 65 20 6f 72 64 65 72 20 6f 66 20 74 byte order of t
28230 68 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 he host computer
28240 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 37 7d ..**.** {F16607}
28250 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f .** A pointer to
28260 20 74 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 the user suppli
28270 65 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 ed routine must
28280 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 be passed as the
28290 20 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 fifth.** argume
282a0 6e 74 2e 20 7b 46 31 36 36 30 39 7d 20 49 66 20 nt. {F16609} If
282b0 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73 it is NULL, this
282c0 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 is the same as
282d0 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c deleting the col
282e0 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e lation.** sequen
282f0 63 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69 ce (so that SQLi
28300 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 te cannot call i
28310 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 7b t anymore)..** {
28320 46 31 36 36 31 31 7d 20 45 61 63 68 20 74 69 6d F16611} Each tim
28330 65 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f e the applicatio
28340 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 66 75 n.** supplied fu
28350 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 nction is invoke
28360 64 2c 20 69 74 20 69 73 20 70 61 73 73 65 64 20 d, it is passed
28370 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f a copy of the vo
28380 69 64 2a 20 70 61 73 73 65 64 20 61 73 0a 2a 2a id* passed as.**
28390 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 the fourth argu
283a0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f ment to sqlite3_
283b0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
283c0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 () or.** sqlite3
283d0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
283e0 6e 31 36 28 29 20 61 73 20 69 74 73 20 66 69 72 n16() as its fir
283f0 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a st parameter..**
28400 0a 2a 2a 20 7b 46 31 36 36 31 32 7d 0a 2a 2a 20 .** {F16612}.**
28410 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 The remaining ar
28420 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 61 guments to the a
28430 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c pplication-suppl
28440 69 65 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 ied routine are
28450 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 two strings,.**
28460 65 61 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 each represented
28470 20 62 79 20 61 20 28 6c 65 6e 67 74 68 2c 20 64 by a (length, d
28480 61 74 61 29 20 70 61 69 72 20 61 6e 64 20 65 6e ata) pair and en
28490 63 6f 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 coded in the enc
284a0 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 oding.** that wa
284b0 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 s passed as the
284c0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 third argument w
284d0 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f hen the collatio
284e0 6e 20 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a n sequence was.*
284f0 2a 20 72 65 67 69 73 74 65 72 65 64 2e 20 7b 45 * registered. {E
28500 4e 44 7d 20 54 68 65 20 61 70 70 6c 69 63 61 74 ND} The applicat
28510 69 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c ion defined coll
28520 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 ation routine sh
28530 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e ould.** return n
28540 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 egative, zero or
28550 20 70 6f 73 69 74 69 76 65 20 69 66 0a 2a 2a 20 positive if.**
28560 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 the first string
28570 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 is less than, e
28580 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 qual to, or grea
28590 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 ter than the sec
285a0 6f 6e 64 0a 2a 2a 20 73 74 72 69 6e 67 2e 20 69 ond.** string. i
285b0 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53 .e. (STRING1 - S
285c0 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 7b TRING2)..**.** {
285d0 46 31 36 36 31 35 7d 0a 2a 2a 20 54 68 65 20 73 F16615}.** The s
285e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
285f0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 llation_v2() wor
28600 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f ks like sqlite3_
28610 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
28620 28 29 0a 2a 2a 20 65 78 63 61 70 74 20 74 68 61 ().** excapt tha
28630 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78 t it takes an ex
28640 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69 tra argument whi
28650 63 68 20 69 73 20 61 20 64 65 73 74 72 75 63 74 ch is a destruct
28660 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f or for.** the co
28670 6c 6c 61 74 69 6f 6e 2e 20 20 7b 46 31 36 36 31 llation. {F1661
28680 37 7d 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 7} The destructo
28690 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e r is called when
286a0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 the collation i
286b0 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64 20 61 s.** destroyed a
286c0 6e 64 20 69 73 20 70 61 73 73 65 64 20 61 20 63 nd is passed a c
286d0 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75 72 74 opy of the fourt
286e0 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f 69 64 h parameter void
286f0 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 * pointer.** of
28700 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 the sqlite3_crea
28710 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 te_collation_v2(
28720 29 2e 0a 2a 2a 20 7b 46 31 36 36 31 38 7d 20 20 )..** {F16618}
28730 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 Collations are d
28740 65 73 74 72 6f 79 65 64 20 77 68 65 6e 0a 2a 2a estroyed when.**
28750 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 they are overri
28760 64 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61 dden by later ca
28770 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 lls to the colla
28780 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 tion creation fu
28790 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6f 72 20 77 68 nctions.** or wh
287a0 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a en the [sqlite3*
287b0 5d 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c ] database handl
287c0 65 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e e is closed usin
287d0 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 g [sqlite3_close
287e0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ()]..*/.int sqli
287f0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
28800 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a tion(. sqlite3*
28810 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 , . const char
28820 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 *zName, . int e
28830 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 TextRep, . void
28840 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 *,. int(*xCompa
28850 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f re)(void*,int,co
28860 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f nst void*,int,co
28870 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e nst void*).);.in
28880 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
28890 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 _collation_v2(.
288a0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f sqlite3*, . co
288b0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
288c0 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 . int eTextRep
288d0 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e , . void*,. in
288e0 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 t(*xCompare)(voi
288f0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 d*,int,const voi
28900 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 d*,int,const voi
28910 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 d*),. void(*xDe
28920 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b stroy)(void*).);
28930 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 .int sqlite3_cre
28940 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 ate_collation16(
28950 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 . sqlite3*, .
28960 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
28970 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 e, . int eTextR
28980 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 ep, . void*,.
28990 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 int(*xCompare)(v
289a0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 oid*,int,const v
289b0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 oid*,int,const v
289c0 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 oid*).);../*.**
289d0 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 CAPI3REF: Collat
289e0 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 ion Needed Callb
289f0 61 63 6b 73 20 7b 46 31 36 37 30 30 7d 0a 2a 2a acks {F16700}.**
28a00 0a 2a 2a 20 7b 46 31 36 37 30 31 7d 0a 2a 2a 20 .** {F16701}.**
28a10 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 To avoid having
28a20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 to register all
28a30 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e collation sequen
28a40 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 ces before a dat
28a50 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 abase.** can be
28a60 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 used, a single c
28a70 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
28a80 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 may be register
28a90 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 64 ed with the.** d
28aa0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74 atabase handle t
28ab0 6f 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e o be called when
28ac0 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 ever an undefine
28ad0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 d collation sequ
28ae0 65 6e 63 65 20 69 73 0a 2a 2a 20 72 65 71 75 69 ence is.** requi
28af0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37 red..**.** {F167
28b00 30 32 7d 0a 2a 2a 20 49 66 20 74 68 65 20 66 75 02}.** If the fu
28b10 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 nction is regist
28b20 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 ered using the s
28b30 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
28b40 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a _needed() API,.*
28b50 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 * then it is pas
28b60 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 sed the names of
28b70 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 undefined colla
28b80 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 tion sequences a
28b90 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 s strings.** enc
28ba0 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 7b oded in UTF-8. {
28bb0 46 31 36 37 30 33 7d 20 49 66 20 73 71 6c 69 74 F16703} If sqlit
28bc0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 e3_collation_nee
28bd0 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c ded16() is used,
28be0 20 74 68 65 20 6e 61 6d 65 73 0a 2a 2a 20 61 72 the names.** ar
28bf0 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d e passed as UTF-
28c00 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 16 in machine na
28c10 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e tive byte order.
28c20 20 7b 46 31 36 37 30 34 7d 20 41 20 63 61 6c 6c {F16704} A call
28c30 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 66 75 to either.** fu
28c40 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 nction replaces
28c50 61 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c any existing cal
28c60 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 lback..**.** {F1
28c70 36 37 30 35 7d 20 57 68 65 6e 20 74 68 65 20 63 6705} When the c
28c80 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
28c90 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 ed, the first ar
28ca0 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 gument passed is
28cb0 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 a copy.** of th
28cc0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
28cd0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c t to sqlite3_col
28ce0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 lation_needed()
28cf0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f or.** sqlite3_co
28d00 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 llation_needed16
28d10 28 29 2e 20 7b 46 31 36 37 30 36 7d 20 54 68 65 (). {F16706} The
28d20 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
28d30 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 is the database
28d40 0a 2a 2a 20 68 61 6e 64 6c 65 2e 20 20 7b 46 31 .** handle. {F1
28d50 36 37 30 37 7d 20 54 68 65 20 74 68 69 72 64 20 6707} The third
28d60 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 argument is one
28d70 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d of [SQLITE_UTF8]
28d80 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 ,.** [SQLITE_UTF
28d90 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 16BE], or [SQLIT
28da0 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 E_UTF16LE], indi
28db0 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 0a cating the most.
28dc0 2a 2a 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 ** desirable for
28dd0 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 m of the collati
28de0 6f 6e 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 on sequence func
28df0 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 0a 2a tion required..*
28e00 2a 20 7b 46 31 36 37 30 38 7d 20 54 68 65 20 66 * {F16708} The f
28e10 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
28e20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 is the name of t
28e30 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 he.** required c
28e40 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 ollation sequenc
28e50 65 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 e. {END}.**.** T
28e60 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 he callback func
28e70 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 tion should regi
28e80 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64 ster the desired
28e90 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 collation using
28ea0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 .** [sqlite3_cre
28eb0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d ate_collation()]
28ec0 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 , [sqlite3_creat
28ed0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d e_collation16()]
28ee0 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 , or.** [sqlite3
28ef0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
28f00 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 n_v2()]..*/.int
28f10 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
28f20 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 n_needed(. sqli
28f30 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 te3*, . void*,
28f40 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a . void(*)(void*
28f50 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 ,sqlite3*,int eT
28f60 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 extRep,const cha
28f70 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 r*).);.int sqlit
28f80 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 e3_collation_nee
28f90 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 ded16(. sqlite3
28fa0 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 *, . void*,. v
28fb0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c oid(*)(void*,sql
28fc0 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 ite3*,int eTextR
28fd0 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a ep,const void*).
28fe0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 );../*.** Specif
28ff0 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e y the key for an
29000 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 encrypted datab
29010 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 ase. This routi
29020 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 ne should be.**
29030 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 called right aft
29040 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 er sqlite3_open(
29050 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 )..**.** The cod
29060 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 e to implement t
29070 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 his API is not a
29080 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 vailable in the
29090 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a public release.*
290a0 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a * of SQLite..*/.
290b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 int sqlite3_key(
290c0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
290d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
290e0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f /* Database to
290f0 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 be rekeyed */.
29100 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 const void *pKe
29110 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 y, int nKey
29120 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b /* The key */.);
29130 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 ../*.** Change t
29140 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 he key on an ope
29150 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 n database. If
29160 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 the current data
29170 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 base is not.** e
29180 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 ncrypted, this r
29190 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 outine will encr
291a0 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 ypt it. If pNew
291b0 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 ==0 or nNew==0,
291c0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 the.** database
291d0 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a is decrypted..**
291e0 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 .** The code to
291f0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 implement this A
29200 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 PI is not availa
29210 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 ble in the publi
29220 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 c release.** of
29230 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 SQLite..*/.int s
29240 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 qlite3_rekey(.
29250 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
29260 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
29270 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 * Database to be
29280 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f rekeyed */. co
29290 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 nst void *pKey,
292a0 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 int nKey /*
292b0 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 The new key */.)
292c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
292d0 46 3a 20 20 53 75 73 70 65 6e 64 20 45 78 65 63 F: Suspend Exec
292e0 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 ution For A Shor
292f0 74 20 54 69 6d 65 20 7b 46 31 30 35 33 30 7d 0a t Time {F10530}.
29300 2a 2a 0a 2a 2a 20 7b 46 31 30 35 33 31 7d 20 54 **.** {F10531} T
29310 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 he sqlite3_sleep
29320 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 () function.** c
29330 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e auses the curren
29340 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 t thread to susp
29350 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a end execution.**
29360 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 for at least a
29370 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 number of millis
29380 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 econds specified
29390 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 in its paramete
293a0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 33 32 r..**.** {F10532
293b0 7d 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 } If the operati
293c0 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e ng system does n
293d0 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 ot support sleep
293e0 20 72 65 71 75 65 73 74 73 20 77 69 74 68 20 0a requests with .
293f0 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 ** millisecond t
29400 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 ime resolution,
29410 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 then the time wi
29420 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 ll be rounded up
29430 20 74 6f 20 0a 2a 2a 20 74 68 65 20 6e 65 61 72 to .** the near
29440 65 73 74 20 73 65 63 6f 6e 64 2e 20 7b 46 31 30 est second. {F10
29450 35 33 33 7d 20 54 68 65 20 6e 75 6d 62 65 72 20 533} The number
29460 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 of milliseconds
29470 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c of sleep actuall
29480 79 20 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 y .** requested
29490 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 from the operati
294a0 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 ng system is ret
294b0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 urned..**.** {F1
294c0 30 35 33 34 7d 20 53 51 4c 69 74 65 20 69 6d 70 0534} SQLite imp
294d0 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 lements this int
294e0 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e erface by callin
294f0 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a g the xSleep().*
29500 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 * method of the
29510 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 default [sqlite3
29520 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 7b 45 _vfs] object. {E
29530 4e 44 7d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ND}.*/.int sqlit
29540 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a e3_sleep(int);..
29550 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
29560 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c Name Of The Fol
29570 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 der Holding Temp
29580 6f 72 61 72 79 20 46 69 6c 65 73 20 7b 46 31 30 orary Files {F10
29590 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 310}.**.** If th
295a0 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 is global variab
295b0 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f le is made to po
295c0 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 int to a string
295d0 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 which is.** the
295e0 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 name of a folder
295f0 20 28 61 2e 6b 61 2e 20 64 69 72 65 63 74 6f 72 (a.ka. director
29600 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d y), then all tem
29610 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 porary files.**
29620 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 created by SQLit
29630 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 e will be placed
29640 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f in that directo
29650 72 79 2e 20 20 49 66 20 74 68 69 73 20 76 61 72 ry. If this var
29660 69 61 62 6c 65 0a 2a 2a 20 69 73 20 4e 55 4c 4c iable.** is NULL
29670 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 pointer, then S
29680 51 4c 69 74 65 20 64 6f 65 73 20 61 20 73 65 61 QLite does a sea
29690 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f rch for an appro
296a0 70 72 69 61 74 65 20 74 65 6d 70 6f 72 61 72 79 priate temporary
296b0 0a 2a 2a 20 66 69 6c 65 20 64 69 72 65 63 74 6f .** file directo
296c0 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 ry..**.** It is
296d0 6e 6f 74 20 73 61 66 65 20 74 6f 20 6d 6f 64 69 not safe to modi
296e0 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 fy this variable
296f0 20 6f 6e 63 65 20 61 20 64 61 74 61 62 61 73 65 once a database
29700 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 68 connection.** h
29710 61 73 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 as been opened.
29720 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 It is intended
29730 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 that this variab
29740 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a le be set once.*
29750 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f * as part of pro
29760 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 cess initializat
29770 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 ion and before a
29780 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 ny SQLite interf
29790 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 ace.** routines
297a0 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 20 61 have been call a
297b0 6e 64 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e nd remain unchan
297c0 67 65 64 20 74 68 65 72 65 61 66 74 65 72 2e 0a ged thereafter..
297d0 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e */.SQLITE_EXTERN
297e0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 char *sqlite3_t
297f0 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a emp_directory;..
29800 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
29810 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 Test To See If
29820 54 68 65 20 44 61 74 61 62 61 73 65 20 49 73 20 The Database Is
29830 49 6e 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d In Auto-Commit M
29840 6f 64 65 20 7b 46 31 32 39 33 30 7d 0a 2a 2a 0a ode {F12930}.**.
29850 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 ** The sqlite3_g
29860 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 et_autocommit()
29870 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72 interfaces retur
29880 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a ns non-zero or.*
29890 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 * zero if the gi
298a0 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e ven database con
298b0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 nection is or is
298c0 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d not in autocomm
298d0 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 it mode,.** resp
298e0 65 63 74 69 76 65 6c 79 2e 20 20 20 41 75 74 6f ectively. Auto
298f0 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f commit mode is o
29900 6e 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2e n.** by default.
29910 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 Autocommit mod
29920 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 e is disabled by
29930 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 a [BEGIN] state
29940 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d ment..** Autocom
29950 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 65 6e mit mode is reen
29960 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d abled by a [COMM
29970 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b IT] or [ROLLBACK
29980 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 ]..**.** If cert
29990 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 ain kinds of err
299a0 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 ors occur on a s
299b0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 tatement within
299c0 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e a multi-statemen
299d0 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e t.** transaction
299e0 73 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 s (errors includ
299f0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c ing [SQLITE_FULL
29a00 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 ], [SQLITE_IOERR
29a10 5d 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e ], .** [SQLITE_N
29a20 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 OMEM], [SQLITE_B
29a30 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 USY], and [SQLIT
29a40 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68 E_INTERRUPT]) th
29a50 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 en the.** transa
29a60 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 ction might be r
29a70 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d olled back autom
29a80 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f atically. The o
29a90 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 nly way to.** fi
29aa0 6e 64 20 6f 75 74 20 69 66 20 53 51 4c 69 74 65 nd out if SQLite
29ab0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 automatically r
29ac0 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74 olled back the t
29ad0 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72 ransaction after
29ae0 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20 .** an error is
29af0 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63 to use this func
29b00 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 tion..**.** INVA
29b10 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 RIANTS:.**.** {F
29b20 31 32 39 33 31 7d 20 54 68 65 20 5b 73 71 6c 69 12931} The [sqli
29b30 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d te3_get_autocomm
29b40 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 it()] interface
29b50 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f returns non-zero
29b60 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 or.**
29b70 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 zero if the give
29b80 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 n database conne
29b90 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e ction is or is n
29ba0 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 ot in autocommit
29bb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 64 .** mod
29bc0 65 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e e, respectively.
29bd0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 32 7d 20 .**.** {F12932}
29be0 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 Autocommit mode
29bf0 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 is on by default
29c00 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 33 7d ..**.** {F12933}
29c10 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 Autocommit mode
29c20 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 is disabled by
29c30 61 20 73 75 63 63 65 73 73 66 75 6c 20 5b 42 45 a successful [BE
29c40 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a GIN] statement..
29c50 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 34 7d 20 41 **.** {F12934} A
29c60 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 utocommit mode i
29c70 73 20 65 6e 61 62 6c 65 64 20 62 79 20 61 20 73 s enabled by a s
29c80 75 63 63 65 73 73 66 75 6c 20 5b 43 4f 4d 4d 49 uccessful [COMMI
29c90 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d T] or [ROLLBACK]
29ca0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 61 .** sta
29cb0 74 65 6d 65 6e 74 2e 0a 2a 2a 20 0a 2a 2a 0a 2a tement..** .**.*
29cc0 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a * LIMITATIONS:.*
29cd0 2a 2a 0a 2a 2a 20 7b 55 31 32 39 33 36 7d 20 49 **.** {U12936} I
29ce0 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 f another thread
29cf0 20 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 changes the aut
29d00 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f ocommit status o
29d10 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a f the database.*
29d20 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 6e 65 * conne
29d30 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 ction while this
29d40 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e routine is runn
29d50 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 ing, then the re
29d60 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 20 20 turn value.**
29d70 20 20 20 20 20 20 20 69 73 20 75 6e 64 65 66 69 is undefi
29d80 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ned..*/.int sqli
29d90 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d te3_get_autocomm
29da0 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f it(sqlite3*);../
29db0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 *.** CAPI3REF:
29dc0 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73 Find The Databas
29dd0 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 e Handle Of A Pr
29de0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
29df0 20 7b 46 31 33 31 32 30 7d 0a 2a 2a 0a 2a 2a 20 {F13120}.**.**
29e00 7b 46 31 33 31 32 31 7d 20 54 68 65 20 73 71 6c {F13121} The sql
29e10 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 ite3_db_handle i
29e20 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 nterface.** retu
29e30 72 6e 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 rns the [sqlite3
29e40 2a 5d 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 *] database hand
29e50 6c 65 20 74 6f 20 77 68 69 63 68 20 61 0a 2a 2a le to which a.**
29e60 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
29e70 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 0a 2a ment] belongs..*
29e80 2a 20 7b 46 31 33 31 32 32 7d 20 74 68 65 20 64 * {F13122} the d
29e90 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 72 atabase handle r
29ea0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
29eb0 65 33 5f 64 62 5f 68 61 6e 64 6c 65 0a 2a 2a 20 e3_db_handle.**
29ec0 69 73 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 is the same data
29ed0 62 61 73 65 20 68 61 6e 64 6c 65 20 74 68 61 74 base handle that
29ee0 20 77 61 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 was.** the firs
29ef0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 t argument to th
29f00 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 e [sqlite3_prepa
29f10 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 re_v2()] or its
29f20 76 61 72 69 61 6e 74 73 0a 2a 2a 20 74 68 61 74 variants.** that
29f30 20 77 61 73 20 75 73 65 64 20 74 6f 20 63 72 65 was used to cre
29f40 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e ate the statemen
29f50 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 t in the first p
29f60 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 lace..*/.sqlite3
29f70 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e *sqlite3_db_han
29f80 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 dle(sqlite3_stmt
29f90 2a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 *);.../*.** CAPI
29fa0 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 3REF: Commit And
29fb0 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 Rollback Notifi
29fc0 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 cation Callbacks
29fd0 20 7b 46 31 32 39 35 30 7d 0a 2a 2a 0a 2a 2a 20 {F12950}.**.**
29fe0 7b 46 31 32 39 35 31 7d 20 54 68 65 20 73 71 6c {F12951} The sql
29ff0 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b ite3_commit_hook
2a000 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 () interface reg
2a010 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 isters a callbac
2a020 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f k.** function to
2a030 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e be invoked when
2a040 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 ever a transacti
2a050 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e on is committed.
2a060 0a 2a 2a 20 7b 46 31 32 39 35 32 7d 20 41 6e 79 .** {F12952} Any
2a070 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 callback set by
2a080 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c a previous call
2a090 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d to sqlite3_comm
2a0a0 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 it_hook().** for
2a0b0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
2a0c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
2a0d0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 overridden..**
2a0e0 7b 46 31 32 39 35 33 7d 20 54 68 65 20 73 71 6c {F12953} The sql
2a0f0 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f ite3_rollback_ho
2a100 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 ok() interface r
2a110 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 egisters a callb
2a120 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ack.** function
2a130 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 to be invoked wh
2a140 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 enever a transac
2a150 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 tion is committe
2a160 64 2e 0a 2a 2a 20 7b 46 31 32 39 35 34 7d 20 41 d..** {F12954} A
2a170 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 ny callback set
2a180 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 by a previous ca
2a190 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ll to sqlite3_co
2a1a0 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 mmit_hook().** f
2a1b0 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 or the same data
2a1c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
2a1d0 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a is overridden..*
2a1e0 2a 20 7b 46 31 32 39 35 36 7d 20 54 68 65 20 70 * {F12956} The p
2a1f0 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 Arg argument is
2a200 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 0a 2a passed through.*
2a210 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 * to the callbac
2a220 6b 2e 20 20 7b 46 31 32 39 35 37 7d 20 49 66 20 k. {F12957} If
2a230 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 the callback on
2a240 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 a commit hook fu
2a250 6e 63 74 69 6f 6e 20 0a 2a 2a 20 72 65 74 75 72 nction .** retur
2a260 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 ns non-zero, the
2a270 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 n the commit is
2a280 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 converted into a
2a290 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a rollback..**.**
2a2a0 20 7b 46 31 32 39 35 38 7d 20 49 66 20 61 6e 6f {F12958} If ano
2a2b0 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 ther function wa
2a2c0 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 s previously reg
2a2d0 69 73 74 65 72 65 64 2c 20 69 74 73 0a 2a 2a 20 istered, its.**
2a2e0 70 41 72 67 20 76 61 6c 75 65 20 69 73 20 72 65 pArg value is re
2a2f0 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 turned. Otherwi
2a300 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 se NULL is retur
2a310 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 ned..**.** {F129
2a320 35 39 7d 20 52 65 67 69 73 74 65 72 69 6e 67 20 59} Registering
2a330 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 a NULL function
2a340 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c disables the cal
2a350 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 lback..**.** {F1
2a360 32 39 36 31 7d 20 46 6f 72 20 74 68 65 20 70 75 2961} For the pu
2a370 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 rposes of this A
2a380 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f PI, a transactio
2a390 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 n is said to hav
2a3a0 65 20 62 65 65 6e 20 0a 2a 2a 20 72 6f 6c 6c 65 e been .** rolle
2a3b0 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 d back if an exp
2a3c0 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 licit "ROLLBACK"
2a3d0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 statement is ex
2a3e0 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e ecuted, or.** an
2a3f0 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 error or constr
2a400 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 aint causes an i
2a410 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b mplicit rollback
2a420 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 7b 46 to occur..** {F
2a430 31 32 39 36 32 7d 20 54 68 65 20 72 6f 6c 6c 62 12962} The rollb
2a440 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ack callback is
2a450 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 not invoked if a
2a460 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a transaction is.
2a470 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ** automatically
2a480 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 rolled back bec
2a490 61 75 73 65 20 74 68 65 20 64 61 74 61 62 61 73 ause the databas
2a4a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
2a4b0 63 6c 6f 73 65 64 2e 0a 2a 2a 20 7b 46 31 32 39 closed..** {F129
2a4c0 36 34 7d 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 64} The rollback
2a4d0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 callback is not
2a4e0 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 invoked if a tr
2a4f0 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 ansaction is.**
2a500 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 rolled back beca
2a510 75 73 65 20 61 20 63 6f 6d 6d 69 74 20 63 61 6c use a commit cal
2a520 6c 62 61 63 6b 20 72 65 74 75 72 6e 65 64 20 6e lback returned n
2a530 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 on-zero..** <tod
2a540 6f 3e 20 43 68 65 63 6b 20 6f 6e 20 74 68 69 73 o> Check on this
2a550 20 3c 2f 74 6f 64 6f 3e 20 7b 45 4e 44 7d 0a 2a </todo> {END}.*
2a560 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 65 *.** These are e
2a570 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 xperimental inte
2a580 72 66 61 63 65 73 20 61 6e 64 20 61 72 65 20 73 rfaces and are s
2a590 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 ubject to change
2a5a0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 ..*/.void *sqlit
2a5b0 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 e3_commit_hook(s
2a5c0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 qlite3*, int(*)(
2a5d0 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a void*), void*);.
2a5e0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f void *sqlite3_ro
2a5f0 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 llback_hook(sqli
2a600 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f te3*, void(*)(vo
2a610 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a id *), void*);..
2a620 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2a630 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 Data Change Noti
2a640 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 fication Callbac
2a650 6b 73 20 7b 46 31 32 39 37 30 7d 0a 2a 2a 0a 2a ks {F12970}.**.*
2a660 2a 20 7b 46 31 32 39 37 31 7d 20 54 68 65 20 73 * {F12971} The s
2a670 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f qlite3_update_ho
2a680 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a ok() interface.*
2a690 2a 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 * registers a ca
2a6a0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
2a6b0 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73 with the databas
2a6c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 65 e connection ide
2a6d0 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 0a ntified by the .
2a6e0 2a 2a 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e ** first argumen
2a6f0 74 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 t to be invoked
2a700 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 whenever a row i
2a710 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 s updated, inser
2a720 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a ted or deleted..
2a730 2a 2a 20 7b 46 31 32 39 37 32 7d 20 41 6e 79 20 ** {F12972} Any
2a740 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 callback set by
2a750 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 a previous call
2a760 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e to this function
2a770 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 0a 2a for the same .*
2a780 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
2a790 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 ction is overrid
2a7a0 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 den..**.** {F129
2a7b0 37 34 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 61 74} The second a
2a7c0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 rgument is a poi
2a7d0 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 nter to the func
2a7e0 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 tion to invoke w
2a7f0 68 65 6e 20 61 20 0a 2a 2a 20 72 6f 77 20 69 73 hen a .** row is
2a800 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 updated, insert
2a810 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 20 0a ed or deleted. .
2a820 2a 2a 20 7b 46 31 32 39 37 36 7d 20 54 68 65 20 ** {F12976} The
2a830 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
2a840 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 o the callback i
2a850 73 0a 2a 2a 20 61 20 63 6f 70 79 20 6f 66 20 74 s.** a copy of t
2a860 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
2a870 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 t to sqlite3_upd
2a880 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 7b ate_hook()..** {
2a890 46 31 32 39 37 37 7d 20 54 68 65 20 73 65 63 6f F12977} The seco
2a8a0 6e 64 20 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a 20 nd callback .**
2a8b0 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 argument is one
2a8c0 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 of [SQLITE_INSER
2a8d0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 T], [SQLITE_DELE
2a8e0 54 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 TE] or [SQLITE_U
2a8f0 50 44 41 54 45 5d 2c 0a 2a 2a 20 64 65 70 65 6e PDATE],.** depen
2a900 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 ding on the oper
2a910 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 ation that cause
2a920 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 74 d the callback t
2a930 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a o be invoked..**
2a940 20 7b 46 31 32 39 37 38 7d 20 54 68 65 20 74 68 {F12978} The th
2a950 69 72 64 20 61 6e 64 20 0a 2a 2a 20 66 6f 75 72 ird and .** four
2a960 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 th arguments to
2a970 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e the callback con
2a980 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f tain pointers to
2a990 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e the database an
2a9a0 64 20 0a 2a 2a 20 74 61 62 6c 65 20 6e 61 6d 65 d .** table name
2a9b0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 containing the
2a9c0 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a affected row..**
2a9d0 20 7b 46 31 32 39 37 39 7d 20 54 68 65 20 66 69 {F12979} The fi
2a9e0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 nal callback par
2a9f0 61 6d 65 74 65 72 20 69 73 20 0a 2a 2a 20 74 68 ameter is .** th
2aa00 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 72 e rowid of the r
2aa10 6f 77 2e 0a 2a 2a 20 7b 46 31 32 39 38 31 7d 20 ow..** {F12981}
2aa20 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 In the case of a
2aa30 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 n update, this i
2aa40 73 20 74 68 65 20 72 6f 77 69 64 20 61 66 74 65 s the rowid afte
2aa50 72 20 0a 2a 2a 20 74 68 65 20 75 70 64 61 74 65 r .** the update
2aa60 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a takes place..**
2aa70 0a 2a 2a 20 7b 46 31 32 39 38 33 7d 20 54 68 65 .** {F12983} The
2aa80 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 update hook is
2aa90 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e not invoked when
2aaa0 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d internal system
2aab0 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d tables are.** m
2aac0 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71 odified (i.e. sq
2aad0 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 lite_master and
2aae0 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29 sqlite_sequence)
2aaf0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 38 34 7d ..**.** {F12984}
2ab00 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 If another func
2ab10 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 tion was previou
2ab20 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 sly registered,
2ab30 69 74 73 20 70 41 72 67 20 76 61 6c 75 65 0a 2a its pArg value.*
2ab40 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 * is returned.
2ab50 7b 46 31 32 39 38 35 7d 20 4f 74 68 65 72 77 69 {F12985} Otherwi
2ab60 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 se NULL is retur
2ab70 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 ned..*/.void *sq
2ab80 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f lite3_update_hoo
2ab90 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a k(. sqlite3*, .
2aba0 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a void(*)(void *
2abb0 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 ,int ,char const
2abc0 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c *,char const *,
2abd0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a sqlite3_int64),.
2abe0 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a void*.);../*.*
2abf0 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 6e 61 * CAPI3REF: Ena
2ac00 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 ble Or Disable S
2ac10 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63 68 hared Pager Cach
2ac20 65 20 7b 46 31 30 33 33 30 7d 0a 2a 2a 0a 2a 2a e {F10330}.**.**
2ac30 20 7b 46 31 30 33 33 31 7d 0a 2a 2a 20 54 68 69 {F10331}.** Thi
2ac40 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 s routine enable
2ac50 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 s or disables th
2ac60 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74 68 65 e sharing of the
2ac70 20 64 61 74 61 62 61 73 65 20 63 61 63 68 65 0a database cache.
2ac80 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 64 61 ** and schema da
2ac90 74 61 20 73 74 72 75 63 74 75 72 65 73 20 62 65 ta structures be
2aca0 74 77 65 65 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e tween connection
2acb0 73 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 s to the same da
2acc0 74 61 62 61 73 65 2e 0a 2a 2a 20 7b 46 31 30 33 tabase..** {F103
2acd0 33 32 7d 0a 2a 2a 20 53 68 61 72 69 6e 67 20 69 32}.** Sharing i
2ace0 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 s enabled if the
2acf0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 argument is tru
2ad00 65 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69 e and disabled i
2ad10 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a f the argument.*
2ad20 2a 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a * is false..**.*
2ad30 2a 20 7b 46 31 30 33 33 33 7d 20 43 61 63 68 65 * {F10333} Cache
2ad40 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 sharing is enab
2ad50 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64 led and disabled
2ad60 0a 2a 2a 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 .** for an entir
2ad70 65 20 70 72 6f 63 65 73 73 2e 20 7b 45 4e 44 7d e process. {END}
2ad80 20 54 68 69 73 20 69 73 20 61 20 63 68 61 6e 67 This is a chang
2ad90 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20 76 e as of SQLite v
2ada0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 0a 2a 2a ersion 3.5.0..**
2adb0 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f In prior versio
2adc0 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 20 73 68 ns of SQLite, sh
2add0 61 72 69 6e 67 20 77 61 73 0a 2a 2a 20 65 6e 61 aring was.** ena
2ade0 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 bled or disabled
2adf0 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 for each thread
2ae00 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a separately..**.
2ae10 2a 2a 20 7b 46 31 30 33 33 34 7d 0a 2a 2a 20 54 ** {F10334}.** T
2ae20 68 65 20 63 61 63 68 65 20 73 68 61 72 69 6e 67 he cache sharing
2ae30 20 6d 6f 64 65 20 73 65 74 20 62 79 20 74 68 69 mode set by thi
2ae40 73 20 69 6e 74 65 72 66 61 63 65 20 65 66 66 65 s interface effe
2ae50 63 74 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65 cts all subseque
2ae60 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b nt.** calls to [
2ae70 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
2ae80 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
2ae90 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 2()], and [sqlit
2aea0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a e3_open16()]..**
2aeb0 20 7b 46 31 30 33 33 35 7d 20 45 78 69 73 74 69 {F10335} Existi
2aec0 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ng database conn
2aed0 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 ections continue
2aee0 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 use the sharing
2aef0 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 mode.** that wa
2af00 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 s in effect at t
2af10 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 he time they wer
2af20 65 20 6f 70 65 6e 65 64 2e 20 7b 45 4e 44 7d 0a e opened. {END}.
2af30 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 **.** Virtual ta
2af40 62 6c 65 73 20 63 61 6e 6e 6f 74 20 62 65 20 75 bles cannot be u
2af50 73 65 64 20 77 69 74 68 20 61 20 73 68 61 72 65 sed with a share
2af60 64 20 63 61 63 68 65 2e 20 20 7b 46 31 30 33 33 d cache. {F1033
2af70 36 7d 20 57 68 65 6e 20 73 68 61 72 65 64 0a 2a 6} When shared.*
2af80 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c * cache is enabl
2af90 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 ed, the [sqlite3
2afa0 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 _create_module()
2afb0 5d 20 41 50 49 20 75 73 65 64 20 74 6f 20 72 65 ] API used to re
2afc0 67 69 73 74 65 72 0a 2a 2a 20 76 69 72 74 75 61 gister.** virtua
2afd0 6c 20 74 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c l tables will al
2afe0 77 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65 ways return an e
2aff0 72 72 6f 72 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a rror. {END}.**.*
2b000 2a 20 7b 46 31 30 33 33 37 7d 20 54 68 69 73 20 * {F10337} This
2b010 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
2b020 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 [SQLITE_OK] if s
2b030 68 61 72 65 64 20 63 61 63 68 65 20 77 61 73 0a hared cache was.
2b040 2a 2a 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 ** enabled or di
2b050 73 61 62 6c 65 64 20 73 75 63 63 65 73 73 66 75 sabled successfu
2b060 6c 6c 79 2e 20 20 7b 46 31 30 33 33 38 7d 20 41 lly. {F10338} A
2b070 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a n [error code].*
2b080 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74 * is returned ot
2b090 68 65 72 77 69 73 65 2e 20 7b 45 4e 44 7d 0a 2a herwise. {END}.*
2b0a0 2a 0a 2a 2a 20 7b 46 31 30 33 33 39 7d 20 53 68 *.** {F10339} Sh
2b0b0 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69 ared cache is di
2b0c0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c sabled by defaul
2b0d0 74 2e 20 7b 45 4e 44 7d 20 42 75 74 20 74 68 69 t. {END} But thi
2b0e0 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 s might change i
2b0f0 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65 n.** future rele
2b100 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 ases of SQLite.
2b110 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 Applications th
2b120 61 74 20 63 61 72 65 20 61 62 6f 75 74 20 73 68 at care about sh
2b130 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 ared.** cache se
2b140 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 tting should set
2b150 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a it explicitly..
2b160 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 */.int sqlite3_e
2b170 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 nable_shared_cac
2b180 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 he(int);../*.**
2b190 43 41 50 49 33 52 45 46 3a 20 20 41 74 74 65 6d CAPI3REF: Attem
2b1a0 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 pt To Free Heap
2b1b0 4d 65 6d 6f 72 79 20 7b 46 31 37 33 34 30 7d 0a Memory {F17340}.
2b1c0 2a 2a 0a 2a 2a 20 7b 46 31 37 33 34 31 7d 20 54 **.** {F17341} T
2b1d0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 he sqlite3_relea
2b1e0 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 se_memory() inte
2b1f0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 rface attempts t
2b200 6f 0a 2a 2a 20 66 72 65 65 20 4e 20 62 79 74 65 o.** free N byte
2b210 73 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 s of heap memory
2b220 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 by deallocating
2b230 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d non-essential m
2b240 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 emory.** allocat
2b250 69 6f 6e 73 20 68 65 6c 64 20 62 79 20 74 68 65 ions held by the
2b260 20 64 61 74 61 62 61 73 65 20 6c 61 62 72 61 72 database labrar
2b270 79 2e 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72 79 y. {END} Memory
2b280 20 75 73 65 64 0a 2a 2a 20 74 6f 20 63 61 63 68 used.** to cach
2b290 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 73 e database pages
2b2a0 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 to improve perf
2b2b0 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 ormance is an ex
2b2c0 61 6d 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6f 6e 2d ample of.** non-
2b2d0 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 essential memory
2b2e0 2e 20 20 7b 46 31 36 33 34 32 7d 20 73 71 6c 69 . {F16342} sqli
2b2f0 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f te3_release_memo
2b300 72 79 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 ry() returns.**
2b310 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
2b320 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 tes actually fre
2b330 65 64 2c 20 77 68 69 63 68 20 6d 69 67 68 74 20 ed, which might
2b340 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 0a be more or less.
2b350 2a 2a 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 ** than the amou
2b360 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2f nt requested..*/
2b370 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c .int sqlite3_rel
2b380 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 ease_memory(int)
2b390 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2b3a0 46 3a 20 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d F: Impose A Lim
2b3b0 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 20 it On Heap Size
2b3c0 7b 46 31 37 33 35 30 7d 0a 2a 2a 0a 2a 2a 20 7b {F17350}.**.** {
2b3d0 46 31 36 33 35 31 7d 20 54 68 65 20 73 71 6c 69 F16351} The sqli
2b3e0 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 te3_soft_heap_li
2b3f0 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 0a mit() interface.
2b400 2a 2a 20 70 6c 61 63 65 73 20 61 20 22 73 6f 66 ** places a "sof
2b410 74 22 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 t" limit on the
2b420 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d amount of heap m
2b430 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 emory that may b
2b440 65 20 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20 62 e allocated.** b
2b450 79 20 53 51 4c 69 74 65 2e 20 7b 46 31 36 33 35 y SQLite. {F1635
2b460 32 7d 20 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 2} If an interna
2b470 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 l allocation is
2b480 72 65 71 75 65 73 74 65 64 20 0a 2a 2a 20 74 68 requested .** th
2b490 61 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20 at would exceed
2b4a0 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 the soft heap li
2b4b0 6d 69 74 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 mit, [sqlite3_re
2b4c0 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 lease_memory()]
2b4d0 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 6f 6e is.** invoked on
2b4e0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 e or more times
2b4f0 74 6f 20 66 72 65 65 20 75 70 20 73 6f 6d 65 20 to free up some
2b500 73 70 61 63 65 20 62 65 66 6f 72 65 20 74 68 65 space before the
2b510 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 allocation.** i
2b520 73 20 6d 61 64 65 2e 20 7b 45 4e 44 7d 0a 2a 2a s made. {END}.**
2b530 0a 2a 2a 20 7b 46 31 36 33 35 33 7d 20 54 68 65 .** {F16353} The
2b540 20 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 limit is called
2b550 20 22 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65 "soft", because
2b560 20 69 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f if.** [sqlite3_
2b570 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 release_memory()
2b580 5d 20 63 61 6e 6e 6f 74 0a 2a 2a 20 66 72 65 65 ] cannot.** free
2b590 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f sufficient memo
2b5a0 72 79 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 ry to prevent th
2b5b0 65 20 6c 69 6d 69 74 20 66 72 6f 6d 20 62 65 69 e limit from bei
2b5c0 6e 67 20 65 78 63 65 65 64 65 64 2c 0a 2a 2a 20 ng exceeded,.**
2b5d0 74 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c the memory is al
2b5e0 6c 6f 63 61 74 65 64 20 61 6e 79 77 61 79 20 61 located anyway a
2b5f0 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 6f nd the current o
2b600 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 peration proceed
2b610 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 34 s..**.** {F16354
2b620 7d 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20 }.** A negative
2b630 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f or zero value fo
2b640 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74 r N means that t
2b650 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 here is no soft
2b660 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a heap limit and.*
2b670 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 * [sqlite3_relea
2b680 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c se_memory()] wil
2b690 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 l only be called
2b6a0 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 when memory is
2b6b0 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 7b 46 exhausted..** {F
2b6c0 31 36 33 35 35 7d 20 54 68 65 20 64 65 66 61 75 16355} The defau
2b6d0 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 lt value for the
2b6e0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 soft heap limit
2b6f0 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 is zero..**.**
2b700 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 62 SQLite makes a b
2b710 65 73 74 20 65 66 66 6f 72 74 20 74 6f 20 68 6f est effort to ho
2b720 6e 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 nor the soft hea
2b730 70 20 6c 69 6d 69 74 2e 20 20 0a 2a 2a 20 7b 46 p limit. .** {F
2b740 31 36 33 35 36 7d 20 42 75 74 20 69 66 20 74 68 16356} But if th
2b750 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 e soft heap limi
2b760 74 20 63 61 6e 6e 6f 74 20 68 6f 6e 6f 72 65 64 t cannot honored
2b770 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c , execution will
2b780 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 .** continue wit
2b790 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f hout error or no
2b7a0 74 69 66 69 63 61 74 69 6f 6e 2e 20 7b 45 4e 44 tification. {END
2b7b0 7d 20 20 54 68 69 73 20 69 73 20 77 68 79 20 74 } This is why t
2b7c0 68 65 20 6c 69 6d 69 74 20 69 73 20 0a 2a 2a 20 he limit is .**
2b7d0 63 61 6c 6c 65 64 20 61 20 22 73 6f 66 74 22 20 called a "soft"
2b7e0 6c 69 6d 69 74 2e 20 20 49 74 20 69 73 20 61 64 limit. It is ad
2b7f0 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a visory only..**.
2b800 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 ** Prior to SQLi
2b810 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 te version 3.5.0
2b820 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6f , this routine o
2b830 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65 64 20 nly constrained
2b840 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c the memory.** al
2b850 6c 6f 63 61 74 65 64 20 62 79 20 61 20 73 69 6e located by a sin
2b860 67 6c 65 20 74 68 72 65 61 64 20 2d 20 74 68 65 gle thread - the
2b870 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 same thread in
2b880 77 68 69 63 68 20 74 68 69 73 20 72 6f 75 74 69 which this routi
2b890 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 65 67 ne.** runs. Beg
2b8a0 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69 inning with SQLi
2b8b0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 te version 3.5.0
2b8c0 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 , the soft heap
2b8d0 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70 70 6c limit is.** appl
2b8e0 69 65 64 20 74 6f 20 61 6c 6c 20 74 68 72 65 61 ied to all threa
2b8f0 64 73 2e 20 7b 46 31 36 33 35 37 7d 20 54 68 65 ds. {F16357} The
2b900 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 value specified
2b910 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 for the soft he
2b920 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61 ap limit.** is a
2b930 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e n upper bound on
2b940 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 the total memor
2b950 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 y allocation for
2b960 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 7b 45 all threads. {E
2b970 4e 44 7d 20 20 49 6e 0a 2a 2a 20 76 65 72 73 69 ND} In.** versi
2b980 6f 6e 20 33 2e 35 2e 30 20 74 68 65 72 65 20 69 on 3.5.0 there i
2b990 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20 66 s no mechanism f
2b9a0 6f 72 20 6c 69 6d 69 74 69 6e 67 20 74 68 65 20 or limiting the
2b9b0 68 65 61 70 20 75 73 61 67 65 20 66 6f 72 0a 2a heap usage for.*
2b9c0 2a 20 69 6e 64 69 76 69 64 75 61 6c 20 74 68 72 * individual thr
2b9d0 65 61 64 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 eads..*/.void sq
2b9e0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f lite3_soft_heap_
2b9f0 6c 69 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a limit(int);../*.
2ba00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 78 ** CAPI3REF: Ex
2ba10 74 72 61 63 74 20 4d 65 74 61 64 61 74 61 20 41 tract Metadata A
2ba20 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 bout A Column Of
2ba30 20 41 20 54 61 62 6c 65 20 7b 46 31 32 38 35 30 A Table {F12850
2ba40 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 }.**.** This rou
2ba50 74 69 6e 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 tine.** returns
2ba60 6d 65 74 61 2d 64 61 74 61 20 61 62 6f 75 74 20 meta-data about
2ba70 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d a specific colum
2ba80 6e 20 6f 66 20 61 20 73 70 65 63 69 66 69 63 20 n of a specific
2ba90 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c database.** tabl
2baa0 65 20 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 e accessible usi
2bab0 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f ng the connectio
2bac0 6e 20 68 61 6e 64 6c 65 20 70 61 73 73 65 64 20 n handle passed
2bad0 61 73 20 74 68 65 20 66 69 72 73 74 20 66 75 6e as the first fun
2bae0 63 74 69 6f 6e 20 0a 2a 2a 20 61 72 67 75 6d 65 ction .** argume
2baf0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f nt..**.** The co
2bb00 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69 lumn is identifi
2bb10 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 ed by the second
2bb20 2c 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 , third and four
2bb30 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f th parameters to
2bb40 20 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 .** this functi
2bb50 6f 6e 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 on. The second p
2bb60 61 72 61 6d 65 74 65 72 20 69 73 20 65 69 74 68 arameter is eith
2bb70 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 er the name of t
2bb80 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28 he database.** (
2bb90 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65 i.e. "main", "te
2bba0 6d 70 22 20 6f 72 20 61 6e 20 61 74 74 61 63 68 mp" or an attach
2bbb0 65 64 20 64 61 74 61 62 61 73 65 29 20 63 6f 6e ed database) con
2bbc0 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65 63 taining the spec
2bbd0 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f ified.** table o
2bbe0 72 20 4e 55 4c 4c 2e 20 49 66 20 69 74 20 69 73 r NULL. If it is
2bbf0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 NULL, then all
2bc00 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 attached databas
2bc10 65 73 20 61 72 65 20 73 65 61 72 63 68 65 64 0a es are searched.
2bc20 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c 65 ** for the table
2bc30 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 using the same
2bc40 61 6c 67 6f 72 69 74 68 6d 20 61 73 20 74 68 65 algorithm as the
2bc50 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 database engine
2bc60 20 75 73 65 73 20 74 6f 20 0a 2a 2a 20 72 65 73 uses to .** res
2bc70 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64 olve unqualified
2bc80 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65 table reference
2bc90 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 s..**.** The thi
2bca0 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 rd and fourth pa
2bcb0 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 rameters to this
2bcc0 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 68 function are th
2bcd0 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 e table and colu
2bce0 6d 6e 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 mn .** name of t
2bcf0 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d he desired colum
2bd00 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e n, respectively.
2bd10 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 Neither of thes
2bd20 65 20 70 61 72 61 6d 65 74 65 72 73 20 0a 2a 2a e parameters .**
2bd30 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a may be NULL..**
2bd40 0a 2a 2a 20 4d 65 74 61 20 69 6e 66 6f 72 6d 61 .** Meta informa
2bd50 74 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 tion is returned
2bd60 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74 by writing to t
2bd70 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 he memory locati
2bd80 6f 6e 73 20 70 61 73 73 65 64 20 61 73 0a 2a 2a ons passed as.**
2bd90 20 74 68 65 20 35 74 68 20 61 6e 64 20 73 75 62 the 5th and sub
2bda0 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65 sequent paramete
2bdb0 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 rs to this funct
2bdc0 69 6f 6e 2e 20 41 6e 79 20 6f 66 20 74 68 65 73 ion. Any of thes
2bdd0 65 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 e .** arguments
2bde0 6d 61 79 20 62 65 20 4e 55 4c 4c 2c 20 69 6e 20 may be NULL, in
2bdf0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 63 which case the c
2be00 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 orresponding ele
2be10 6d 65 6e 74 20 6f 66 20 6d 65 74 61 20 0a 2a 2a ment of meta .**
2be20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 information is
2be30 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 ommitted..**.**
2be40 3c 70 72 65 3e 0a 2a 2a 20 50 61 72 61 6d 65 74 <pre>.** Paramet
2be50 65 72 20 20 20 20 20 4f 75 74 70 75 74 20 54 79 er Output Ty
2be60 70 65 20 20 20 20 20 20 44 65 73 63 72 69 70 74 pe Descript
2be70 69 6f 6e 0a 2a 2a 20 2d 2d 2d 2d 2d 2d 2d 2d 2d ion.** ---------
2be80 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
2be90 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 0a 2a 2a ----------.**.**
2bea0 20 20 20 35 74 68 20 20 20 20 20 20 20 20 20 63 5th c
2beb0 6f 6e 73 74 20 63 68 61 72 2a 20 20 20 20 20 20 onst char*
2bec0 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 20 20 36 Data type.** 6
2bed0 74 68 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74 th const
2bee0 20 63 68 61 72 2a 20 20 20 20 20 20 4e 61 6d 65 char* Name
2bef0 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 of the default
2bf00 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e collation sequen
2bf10 63 65 20 0a 2a 2a 20 20 20 37 74 68 20 20 20 20 ce .** 7th
2bf20 20 20 20 20 20 69 6e 74 20 20 20 20 20 20 20 20 int
2bf30 20 20 20 20 20 20 54 72 75 65 20 69 66 20 74 68 True if th
2bf40 65 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e e column has a N
2bf50 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 OT NULL constrai
2bf60 6e 74 0a 2a 2a 20 20 20 38 74 68 20 20 20 20 20 nt.** 8th
2bf70 20 20 20 20 69 6e 74 20 20 20 20 20 20 20 20 20 int
2bf80 20 20 20 20 20 54 72 75 65 20 69 66 20 74 68 65 True if the
2bf90 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 column is part
2bfa0 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b of the PRIMARY K
2bfb0 45 59 0a 2a 2a 20 20 20 39 74 68 20 20 20 20 20 EY.** 9th
2bfc0 20 20 20 20 69 6e 74 20 20 20 20 20 20 20 20 20 int
2bfd0 20 20 20 20 20 54 72 75 65 20 69 66 20 74 68 65 True if the
2bfe0 20 63 6f 6c 75 6d 6e 20 69 73 20 41 55 54 4f 49 column is AUTOI
2bff0 4e 43 52 45 4d 45 4e 54 0a 2a 2a 20 3c 2f 70 72 NCREMENT.** </pr
2c000 65 3e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 e>.**.**.** The
2c010 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 memory pointed t
2c020 6f 20 62 79 20 74 68 65 20 63 68 61 72 61 63 74 o by the charact
2c030 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 er pointers retu
2c040 72 6e 65 64 20 66 6f 72 20 74 68 65 20 0a 2a 2a rned for the .**
2c050 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 declaration typ
2c060 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 e and collation
2c070 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69 sequence is vali
2c080 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 d only until the
2c090 20 6e 65 78 74 20 0a 2a 2a 20 63 61 6c 6c 20 74 next .** call t
2c0a0 6f 20 61 6e 79 20 73 71 6c 69 74 65 20 41 50 49 o any sqlite API
2c0b0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a function..**.**
2c0c0 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65 If the specifie
2c0d0 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75 61 d table is actua
2c0e0 6c 6c 79 20 61 20 76 69 65 77 2c 20 74 68 65 6e lly a view, then
2c0f0 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 an error is ret
2c100 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 urned..**.** If
2c110 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63 6f the specified co
2c120 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c lumn is "rowid",
2c130 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69 "oid" or "_rowi
2c140 64 5f 22 20 61 6e 64 20 61 6e 20 0a 2a 2a 20 49 d_" and an .** I
2c150 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b NTEGER PRIMARY K
2c160 45 59 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65 EY column has be
2c170 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 en explicitly de
2c180 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68 65 clared, then the
2c190 20 6f 75 74 70 75 74 20 0a 2a 2a 20 70 61 72 61 output .** para
2c1a0 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 66 meters are set f
2c1b0 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c or the explicitl
2c1c0 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d y declared colum
2c1d0 6e 2e 20 49 66 20 74 68 65 72 65 20 69 73 20 6e n. If there is n
2c1e0 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79 20 o.** explicitly
2c1f0 64 65 63 6c 61 72 65 64 20 49 50 4b 20 63 6f 6c declared IPK col
2c200 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 umn, then the ou
2c210 74 70 75 74 20 70 61 72 61 6d 65 74 65 72 73 20 tput parameters
2c220 61 72 65 20 73 65 74 20 61 73 20 0a 2a 2a 20 66 are set as .** f
2c230 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 ollows:.**.** <p
2c240 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 20 re>.** data
2c250 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a type: "INTEGER".
2c260 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e ** collation
2c270 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49 4e 41 sequence: "BINA
2c280 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e RY".** not n
2c290 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72 ull: 0.** pr
2c2a0 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 imary key: 1.**
2c2b0 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65 6d 65 auto increme
2c2c0 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 0a nt: 0.** </pre>.
2c2d0 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 **.** This funct
2c2e0 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 ion may load one
2c2f0 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 or more schemas
2c300 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20 66 from database f
2c310 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 iles. If an.** e
2c320 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 rror occurs duri
2c330 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73 73 2c ng this process,
2c340 20 6f 72 20 69 66 20 74 68 65 20 72 65 71 75 65 or if the reque
2c350 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20 63 6f sted table or co
2c360 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 lumn.** cannot b
2c370 65 20 66 6f 75 6e 64 2c 20 61 6e 20 53 51 4c 49 e found, an SQLI
2c380 54 45 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 TE error code is
2c390 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e returned and an
2c3a0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a error message.*
2c3b0 2a 20 6c 65 66 74 20 69 6e 20 74 68 65 20 64 61 * left in the da
2c3c0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 28 74 tabase handle (t
2c3d0 6f 20 62 65 20 72 65 74 72 69 65 76 65 64 20 75 o be retrieved u
2c3e0 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72 sing sqlite3_err
2c3f0 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 msg())..**.** Th
2c400 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 is API is only a
2c410 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 vailable if the
2c420 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 library was comp
2c430 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a iled with the.**
2c440 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 SQLITE_ENABLE_C
2c450 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 20 70 OLUMN_METADATA p
2c460 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 reprocessor symb
2c470 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 ol defined..*/.i
2c480 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 nt sqlite3_table
2c490 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 _column_metadata
2c4a0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
2c4b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2c4c0 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 /* Connection ha
2c4d0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
2c4e0 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 char *zDbName,
2c4f0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 /* Databas
2c500 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a e name or NULL *
2c510 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
2c520 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 zTableName,
2c530 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f /* Table name */
2c540 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
2c550 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f ColumnName, /
2c560 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f * Column name */
2c570 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a . char const **
2c580 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f pzDataType, /
2c590 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72 * OUTPUT: Declar
2c5a0 65 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a ed data type */.
2c5b0 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 char const **p
2c5c0 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a zCollSeq, /*
2c5d0 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 OUTPUT: Collati
2c5e0 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 on sequence name
2c5f0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e */. int *pNotN
2c600 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 ull,
2c610 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 /* OUTPUT: Tru
2c620 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f e if NOT NULL co
2c630 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20 nstraint exists
2c640 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 */. int *pPrima
2c650 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20 ryKey,
2c660 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 /* OUTPUT: True
2c670 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 if column part
2c680 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a of PK */. int *
2c690 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20 pAutoinc
2c6a0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 /* OUTPUT
2c6b0 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e : True if column
2c6c0 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 is auto-increme
2c6d0 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 nt */.);../*.**
2c6e0 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 CAPI3REF: Load A
2c6f0 6e 20 45 78 74 65 6e 73 69 6f 6e 20 7b 46 31 32 n Extension {F12
2c700 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 600}.**.** {F126
2c710 30 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 01} The sqlite3_
2c720 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 load_extension()
2c730 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 61 74 interface.** at
2c740 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61 tempts to load a
2c750 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 n SQLite extensi
2c760 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 on library conta
2c770 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65 ined in the file
2c780 0a 2a 2a 20 7a 46 69 6c 65 2e 20 7b 46 31 32 36 .** zFile. {F126
2c790 30 32 7d 20 54 68 65 20 65 6e 74 72 79 20 70 6f 02} The entry po
2c7a0 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 20 7b 46 int is zProc. {F
2c7b0 31 32 36 30 33 7d 20 7a 50 72 6f 63 20 6d 61 79 12603} zProc may
2c7c0 20 62 65 20 30 0a 2a 2a 20 69 6e 20 77 68 69 63 be 0.** in whic
2c7d0 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20 h case the name
2c7e0 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 of the entry poi
2c7f0 6e 74 20 64 65 66 61 75 6c 74 73 0a 2a 2a 20 74 nt defaults.** t
2c800 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e o "sqlite3_exten
2c810 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 0a 2a sion_init"..**.*
2c820 2a 20 7b 46 31 32 36 30 34 7d 20 54 68 65 20 73 * {F12604} The s
2c830 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 qlite3_load_exte
2c840 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 nsion() interfac
2c850 65 20 73 68 61 6c 6c 0a 2a 2a 20 72 65 74 75 72 e shall.** retur
2c860 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e n [SQLITE_OK] on
2c870 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 success and [SQ
2c880 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 LITE_ERROR] if s
2c890 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 omething goes wr
2c8a0 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 ong..**.** {F126
2c8b0 30 35 7d 0a 2a 2a 20 49 66 20 61 6e 20 65 72 72 05}.** If an err
2c8c0 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70 7a or occurs and pz
2c8d0 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c ErrMsg is not 0,
2c8e0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 73 71 6c then the.** sql
2c8f0 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 ite3_load_extens
2c900 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 ion() interface
2c910 73 68 61 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f shall attempt to
2c920 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20 fill *pzErrMsg
2c930 77 69 74 68 20 0a 2a 2a 20 65 72 72 6f 72 20 6d with .** error m
2c940 65 73 73 61 67 65 20 74 65 78 74 20 73 74 6f 72 essage text stor
2c950 65 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 ed in memory obt
2c960 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
2c970 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a te3_malloc()]..*
2c980 2a 20 7b 45 4e 44 7d 20 20 54 68 65 20 63 61 6c * {END} The cal
2c990 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68 ling function sh
2c9a0 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d ould free this m
2c9b0 65 6d 6f 72 79 0a 2a 2a 20 62 79 20 63 61 6c 6c emory.** by call
2c9c0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 ing [sqlite3_fre
2c9d0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 e()]..**.** {F12
2c9e0 36 30 36 7d 0a 2a 2a 20 45 78 74 65 6e 73 69 6f 606}.** Extensio
2c9f0 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 n loading must b
2ca00 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 e enabled using
2ca10 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f [sqlite3_enable_
2ca20 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 load_extension()
2ca30 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 ].** prior to ca
2ca40 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 20 6f lling this API o
2ca50 72 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 r an error will
2ca60 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a be returned..*/.
2ca70 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 int sqlite3_load
2ca80 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 _extension(. sq
2ca90 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
2caa0 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 /* Load the
2cab0 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 extension into t
2cac0 68 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e his database con
2cad0 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e nection */. con
2cae0 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 st char *zFile,
2caf0 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 /* Name of th
2cb00 65 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79 e shared library
2cb10 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 containing exte
2cb20 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 nsion */. const
2cb30 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 char *zProc,
2cb40 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e /* Entry point.
2cb50 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a Derived from z
2cb60 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 File if 0 */. c
2cb70 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 har **pzErrMsg
2cb80 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f /* Put erro
2cb90 72 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69 r message here i
2cba0 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f f not 0 */.);../
2cbb0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 *.** CAPI3REF:
2cbc0 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c Enable Or Disabl
2cbd0 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 e Extension Load
2cbe0 69 6e 67 20 7b 46 31 32 36 32 30 7d 0a 2a 2a 0a ing {F12620}.**.
2cbf0 2a 2a 20 53 6f 20 61 73 20 6e 6f 74 20 74 6f 20 ** So as not to
2cc00 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20 68 6f open security ho
2cc10 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61 70 70 les in older app
2cc20 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 61 lications that a
2cc30 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72 65 64 re.** unprepared
2cc40 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 65 78 to deal with ex
2cc50 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c tension loading,
2cc60 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e 73 20 and as a means
2cc70 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 of disabling.**
2cc80 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e extension loadin
2cc90 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 g while evaluati
2cca0 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 ng user-entered
2ccb0 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 SQL, the followi
2ccc0 6e 67 0a 2a 2a 20 41 50 49 20 69 73 20 70 72 6f ng.** API is pro
2ccd0 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20 74 68 vided to turn th
2cce0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f e [sqlite3_load_
2ccf0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 extension()] mec
2cd00 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 0a 2a 2a hanism on and.**
2cd10 20 6f 66 66 2e 20 20 7b 46 31 32 36 32 32 7d 20 off. {F12622}
2cd20 49 74 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 It is off by def
2cd30 61 75 6c 74 2e 20 7b 45 4e 44 7d 20 53 65 65 20 ault. {END} See
2cd40 74 69 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a ticket #1863..**
2cd50 0a 2a 2a 20 7b 46 31 32 36 32 31 7d 20 43 61 6c .** {F12621} Cal
2cd60 6c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e l the sqlite3_en
2cd70 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 able_load_extens
2cd80 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a ion() routine.**
2cd90 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 20 74 with onoff==1 t
2cda0 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e o turn extension
2cdb0 20 6c 6f 61 64 69 6e 67 20 6f 6e 0a 2a 2a 20 61 loading on.** a
2cdc0 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20 nd call it with
2cdd0 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e onoff==0 to turn
2cde0 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 it back off aga
2cdf0 69 6e 2e 20 7b 45 4e 44 7d 0a 2a 2f 0a 69 6e 74 in. {END}.*/.int
2ce00 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f sqlite3_enable_
2ce10 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73 load_extension(s
2ce20 71 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e 74 20 qlite3 *db, int
2ce30 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 onoff);../*.** C
2ce40 41 50 49 33 52 45 46 3a 20 4d 61 6b 65 20 41 72 API3REF: Make Ar
2ce50 72 61 6e 67 65 6d 65 6e 74 73 20 54 6f 20 41 75 rangements To Au
2ce60 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64 tomatically Load
2ce70 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 20 7b 46 An Extension {F
2ce80 31 32 36 34 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 12640}.**.** {F1
2ce90 32 36 34 31 7d 20 54 68 69 73 20 66 75 6e 63 74 2641} This funct
2cea0 69 6f 6e 0a 2a 2a 20 72 65 67 69 73 74 65 72 73 ion.** registers
2ceb0 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e an extension en
2cec0 74 72 79 20 70 6f 69 6e 74 20 74 68 61 74 20 69 try point that i
2ced0 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 s automatically
2cee0 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 65 invoked.** whene
2cef0 76 65 72 20 61 20 6e 65 77 20 64 61 74 61 62 61 ver a new databa
2cf00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
2cf10 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 0a 2a 2a opened using.**
2cf20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
2cf30 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ], [sqlite3_open
2cf40 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 16()], or [sqlit
2cf50 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 7b e3_open_v2()]. {
2cf60 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 END}.**.** This
2cf70 41 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b API can be invok
2cf80 65 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73 74 ed at program st
2cf90 61 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20 74 artup in order t
2cfa0 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e o register.** on
2cfb0 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69 63 e or more static
2cfc0 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74 65 ally linked exte
2cfd0 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c nsions that will
2cfe0 20 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a be available.**
2cff0 20 74 6f 20 61 6c 6c 20 6e 65 77 20 64 61 74 61 to all new data
2d000 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
2d010 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34 32 7d ..**.** {F12642}
2d020 20 44 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e Duplicate exten
2d030 73 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74 sions are detect
2d040 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68 ed so calling th
2d050 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 6c 74 69 is routine multi
2d060 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 ple.** times wit
2d070 68 20 74 68 65 20 73 61 6d 65 20 65 78 74 65 6e h the same exten
2d080 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73 73 sion is harmless
2d090 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34 33 7d ..**.** {F12643}
2d0a0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 This routine st
2d0b0 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 ores a pointer t
2d0c0 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 o the extension
2d0d0 69 6e 20 61 6e 20 61 72 72 61 79 0a 2a 2a 20 74 in an array.** t
2d0e0 68 61 74 20 69 73 20 6f 62 74 61 69 6e 65 64 20 hat is obtained
2d0f0 66 72 6f 6d 20 73 71 6c 69 74 65 5f 6d 61 6c 6c from sqlite_mall
2d100 6f 63 28 29 2e 20 7b 45 4e 44 7d 20 49 66 20 79 oc(). {END} If y
2d110 6f 75 20 72 75 6e 20 61 20 6d 65 6d 6f 72 79 20 ou run a memory
2d120 6c 65 61 6b 0a 2a 2a 20 63 68 65 63 6b 65 72 20 leak.** checker
2d130 6f 6e 20 79 6f 75 72 20 70 72 6f 67 72 61 6d 20 on your program
2d140 61 6e 64 20 69 74 20 72 65 70 6f 72 74 73 20 61 and it reports a
2d150 20 6c 65 61 6b 20 62 65 63 61 75 73 65 20 6f 66 leak because of
2d160 20 74 68 69 73 0a 2a 2a 20 61 72 72 61 79 2c 20 this.** array,
2d170 74 68 65 6e 20 69 6e 76 6f 6b 65 20 5b 73 71 6c then invoke [sql
2d180 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f ite3_reset_auto_
2d190 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 extension()] pri
2d1a0 6f 72 0a 2a 2a 20 74 6f 20 73 68 75 74 64 6f 77 or.** to shutdow
2d1b0 6e 20 74 6f 20 66 72 65 65 20 74 68 65 20 6d 65 n to free the me
2d1c0 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 mory..**.** {F12
2d1d0 36 34 34 7d 20 41 75 74 6f 6d 61 74 69 63 20 65 644} Automatic e
2d1e0 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 xtensions apply
2d1f0 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 across all threa
2d200 64 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 ds. {END}.**.**
2d210 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 This interface i
2d220 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 s experimental a
2d230 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f nd is subject to
2d240 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 change or.** re
2d250 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20 moval in future
2d260 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 releases of SQLi
2d270 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 te..*/.int sqlit
2d280 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f e3_auto_extensio
2d290 6e 28 76 6f 69 64 20 2a 78 45 6e 74 72 79 50 6f n(void *xEntryPo
2d2a0 69 6e 74 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 int);.../*.** CA
2d2b0 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 75 PI3REF: Reset Au
2d2c0 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73 69 6f tomatic Extensio
2d2d0 6e 20 4c 6f 61 64 69 6e 67 20 7b 46 31 32 36 36 n Loading {F1266
2d2e0 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 36 31 0}.**.** {F12661
2d2f0 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 } This function
2d300 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 70 72 65 disables all pre
2d310 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 viously register
2d320 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 20 ed.** automatic
2d330 65 78 74 65 6e 73 69 6f 6e 73 2e 20 7b 45 4e 44 extensions. {END
2d340 7d 20 20 54 68 69 73 0a 2a 2a 20 72 6f 75 74 69 } This.** routi
2d350 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 ne undoes the ef
2d360 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f fect of all prio
2d370 72 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f r [sqlite3_auto_
2d380 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 extension()].**
2d390 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 calls..**.** {F1
2d3a0 32 36 36 32 7d 20 54 68 69 73 20 63 61 6c 6c 20 2662} This call
2d3b0 64 69 73 61 62 6c 65 64 20 61 75 74 6f 6d 61 74 disabled automat
2d3c0 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e ic extensions in
2d3d0 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 7b 45 all threads. {E
2d3e0 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 ND}.**.** This i
2d3f0 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65 nterface is expe
2d400 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 rimental and is
2d410 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 subject to chang
2d420 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 e or.** removal
2d430 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
2d440 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f es of SQLite..*/
2d450 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
2d460 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 set_auto_extensi
2d470 6f 6e 28 76 6f 69 64 29 3b 0a 0a 0a 2f 2a 0a 2a on(void);.../*.*
2d480 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 ***** EXPERIMENT
2d490 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 AL - subject to
2d4a0 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e change without n
2d4b0 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a otice **********
2d4c0 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 ****.**.** The i
2d4d0 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 nterface to the
2d4e0 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 virtual-table me
2d4f0 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 chanism is curre
2d500 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a ntly considered.
2d510 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d ** to be experim
2d520 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 ental. The inte
2d530 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e rface might chan
2d540 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 ge in incompatib
2d550 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 le ways..** If t
2d560 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d his is a problem
2d570 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 for you, do not
2d580 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 use the interfa
2d590 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e ce at this time.
2d5a0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 .**.** When the
2d5b0 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 virtual-table me
2d5c0 63 68 61 6e 69 73 6d 20 73 74 61 62 6c 69 7a 65 chanism stablize
2d5d0 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 s, we will decla
2d5e0 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 re the.** interf
2d5f0 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f ace fixed, suppo
2d600 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 rt it indefinite
2d610 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 ly, and remove t
2d620 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a his comment..*/.
2d630 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 ./*.** Structure
2d640 73 20 75 73 65 64 20 62 79 20 74 68 65 20 76 69 s used by the vi
2d650 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 rtual table inte
2d660 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 rface.*/.typedef
2d670 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
2d680 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 vtab sqlite3_vta
2d690 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 b;.typedef struc
2d6a0 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f t sqlite3_index_
2d6b0 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 info sqlite3_ind
2d6c0 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 ex_info;.typedef
2d6d0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
2d6e0 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 vtab_cursor sqli
2d6f0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b te3_vtab_cursor;
2d700 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
2d710 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 sqlite3_module s
2d720 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a qlite3_module;..
2d730 2f 2a 0a 2a 2a 20 41 20 6d 6f 64 75 6c 65 20 69 /*.** A module i
2d740 73 20 61 20 63 6c 61 73 73 20 6f 66 20 76 69 72 s a class of vir
2d750 74 75 61 6c 20 74 61 62 6c 65 73 2e 20 20 45 61 tual tables. Ea
2d760 63 68 20 6d 6f 64 75 6c 65 20 69 73 20 64 65 66 ch module is def
2d770 69 6e 65 64 0a 2a 2a 20 62 79 20 61 6e 20 69 6e ined.** by an in
2d780 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 66 6f stance of the fo
2d790 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 llowing structur
2d7a0 65 2e 20 20 54 68 69 73 20 73 74 72 75 63 74 75 e. This structu
2d7b0 72 65 20 63 6f 6e 73 69 73 74 73 0a 2a 2a 20 6d re consists.** m
2d7c0 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 ostly of methods
2d7d0 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e for the module.
2d7e0 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 .*/.struct sqlit
2d7f0 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e e3_module {. in
2d800 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e t iVersion;. in
2d810 74 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c t (*xCreate)(sql
2d820 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 ite3*, void *pAu
2d830 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 x,.
2d840 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 int argc, cons
2d850 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 t char *const*ar
2d860 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 gv,.
2d870 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 sqlite3_vtab
2d880 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a **ppVTab, char**
2d890 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e );. int (*xConn
2d8a0 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 ect)(sqlite3*, v
2d8b0 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 oid *pAux,.
2d8c0 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 int ar
2d8d0 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a gc, const char *
2d8e0 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 const*argv,.
2d8f0 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 sqlit
2d900 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 e3_vtab **ppVTab
2d910 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 , char**);. int
2d920 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 (*xBestIndex)(s
2d930 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
2d940 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 ab, sqlite3_inde
2d950 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 x_info*);. int
2d960 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 (*xDisconnect)(s
2d970 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
2d980 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 ab);. int (*xDe
2d990 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 stroy)(sqlite3_v
2d9a0 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 tab *pVTab);. i
2d9b0 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 nt (*xOpen)(sqli
2d9c0 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c te3_vtab *pVTab,
2d9d0 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 sqlite3_vtab_cu
2d9e0 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 rsor **ppCursor)
2d9f0 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 ;. int (*xClose
2da00 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 )(sqlite3_vtab_c
2da10 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 ursor*);. int (
2da20 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 *xFilter)(sqlite
2da30 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 3_vtab_cursor*,
2da40 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 int idxNum, cons
2da50 74 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a t char *idxStr,.
2da60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2da70 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 int argc, sqlite
2da80 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 3_value **argv);
2da90 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 . int (*xNext)(
2daa0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 sqlite3_vtab_cur
2dab0 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 sor*);. int (*x
2dac0 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 Eof)(sqlite3_vta
2dad0 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e b_cursor*);. in
2dae0 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c t (*xColumn)(sql
2daf0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 ite3_vtab_cursor
2db00 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 *, sqlite3_conte
2db10 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 xt*, int);. int
2db20 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 (*xRowid)(sqlit
2db30 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c e3_vtab_cursor*,
2db40 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a sqlite3_int64 *
2db50 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 pRowid);. int (
2db60 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 *xUpdate)(sqlite
2db70 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 3_vtab *, int, s
2db80 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c qlite3_value **,
2db90 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a sqlite3_int64 *
2dba0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 );. int (*xBegi
2dbb0 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 n)(sqlite3_vtab
2dbc0 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 *pVTab);. int (
2dbd0 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f *xSync)(sqlite3_
2dbe0 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 vtab *pVTab);.
2dbf0 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 int (*xCommit)(s
2dc00 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
2dc10 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f ab);. int (*xRo
2dc20 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f llback)(sqlite3_
2dc30 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 vtab *pVTab);.
2dc40 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 int (*xFindFunct
2dc50 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 ion)(sqlite3_vta
2dc60 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 b *pVtab, int nA
2dc70 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a rg, const char *
2dc80 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 zName,.
2dc90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f vo
2dca0 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 id (**pxFunc)(sq
2dcb0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
2dcc0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
2dcd0 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 **),.
2dce0 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 void
2dcf0 20 2a 2a 70 70 41 72 67 29 3b 0a 0a 20 20 69 6e **ppArg);.. in
2dd00 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c t (*xRename)(sql
2dd10 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 ite3_vtab *pVtab
2dd20 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
2dd30 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 54 ew);.};../*.** T
2dd40 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 he sqlite3_index
2dd50 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20 _info structure
2dd60 61 6e 64 20 69 74 73 20 73 75 62 73 74 72 75 63 and its substruc
2dd70 74 75 72 65 73 20 69 73 20 75 73 65 64 20 74 6f tures is used to
2dd80 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 .** pass informa
2dd90 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 tion into and re
2dda0 63 65 69 76 65 20 74 68 65 20 72 65 70 6c 79 20 ceive the reply
2ddb0 66 72 6f 6d 20 74 68 65 20 78 42 65 73 74 49 6e from the xBestIn
2ddc0 64 65 78 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 dex.** method of
2ddd0 20 61 6e 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 an sqlite3_modu
2dde0 6c 65 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20 le. The fields
2ddf0 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a under **Inputs**
2de00 20 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 are the.** inpu
2de10 74 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78 ts to xBestIndex
2de20 20 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e and are read-on
2de30 6c 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20 ly. xBestIndex
2de40 69 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 inserts its.** r
2de50 65 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 esults into the
2de60 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c **Outputs** fiel
2de70 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43 ds..**.** The aC
2de80 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 onstraint[] arra
2de90 79 20 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 y records WHERE
2dea0 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e clause constrain
2deb0 74 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 ts of the.** for
2dec0 6d 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 20 20 20 20 m:.**.**
2ded0 20 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 0a column OP expr.
2dee0 2a 2a 0a 2a 2a 20 57 68 65 72 65 20 4f 50 20 69 **.** Where OP i
2def0 73 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d s =, <, <=
2df00 2c 20 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d , >, or >=
2df10 2e 20 20 0a 2a 2a 20 54 68 65 20 70 61 72 74 69 . .** The parti
2df20 63 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69 cular operator i
2df30 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 s stored.** in a
2df40 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e Constraint[].op.
2df50 20 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74 The index of t
2df60 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f he column is sto
2df70 72 65 64 20 69 6e 20 0a 2a 2a 20 61 43 6f 6e 73 red in .** aCons
2df80 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e traint[].iColumn
2df90 2e 20 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d . aConstraint[]
2dfa0 2e 75 73 61 62 6c 65 20 69 73 20 54 52 55 45 20 .usable is TRUE
2dfb0 69 66 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f if the.** expr o
2dfc0 6e 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 n the right-hand
2dfd0 20 73 69 64 65 20 63 61 6e 20 62 65 20 65 76 61 side can be eva
2dfe0 6c 75 61 74 65 64 20 28 61 6e 64 20 74 68 75 73 luated (and thus
2dff0 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a the constraint.
2e000 2a 2a 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e ** is usable) an
2e010 64 20 66 61 6c 73 65 20 69 66 20 69 74 20 63 61 d false if it ca
2e020 6e 6e 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 nnot..**.** The
2e030 6f 70 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 optimizer automa
2e040 74 69 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 tically inverts
2e050 74 65 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 terms of the for
2e060 6d 20 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d m "expr OP colum
2e070 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 n".** and makes
2e080 6f 74 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61 other simplifica
2e090 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 57 48 45 tions to the WHE
2e0a0 52 45 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 RE clause in an
2e0b0 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 attempt to.** ge
2e0c0 74 20 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20 t as many WHERE
2e0d0 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74 clause terms int
2e0e0 6f 20 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e o the form shown
2e0f0 20 61 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62 above as possib
2e100 6c 65 2e 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73 le..** The aCons
2e110 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f traint[] array o
2e120 6e 6c 79 20 72 65 70 6f 72 74 73 20 57 48 45 52 nly reports WHER
2e130 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 E clause terms i
2e140 6e 20 74 68 65 20 63 6f 72 72 65 63 74 0a 2a 2a n the correct.**
2e150 20 66 6f 72 6d 20 74 68 61 74 20 72 65 66 65 72 form that refer
2e160 20 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c to the particul
2e170 61 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 ar virtual table
2e180 20 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a being queried..
2e190 2a 2a 0a 2a 2a 20 49 6e 66 6f 72 6d 61 74 69 6f **.** Informatio
2e1a0 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 n about the ORDE
2e1b0 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 R BY clause is s
2e1c0 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 tored in aOrderB
2e1d0 79 5b 5d 2e 0a 2a 2a 20 45 61 63 68 20 74 65 72 y[]..** Each ter
2e1e0 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65 m of aOrderBy re
2e1f0 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f cords a column o
2e200 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 f the ORDER BY c
2e210 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 lause..**.** The
2e220 20 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 xBestIndex meth
2e230 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f od must fill aCo
2e240 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 nstraintUsage[]
2e250 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e with information
2e260 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70 .** about what p
2e270 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73 arameters to pas
2e280 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 49 s to xFilter. I
2e290 66 20 61 72 67 76 49 6e 64 65 78 3e 30 20 74 68 f argvIndex>0 th
2e2a0 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 2d en.** the right-
2e2b0 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65 hand side of the
2e2c0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 corresponding a
2e2d0 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 Constraint[] is
2e2e0 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 evaluated.** and
2e2f0 20 62 65 63 6f 6d 65 73 20 74 68 65 20 61 72 67 becomes the arg
2e300 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 20 vIndex-th entry
2e310 69 6e 20 61 72 67 76 2e 20 20 49 66 20 61 43 6f in argv. If aCo
2e320 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e nstraintUsage[].
2e330 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c omit.** is true,
2e340 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 then the constr
2e350 61 69 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20 aint is assumed
2e360 74 6f 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 to be fully hand
2e370 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 led by the.** vi
2e380 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 rtual table and
2e390 69 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 is not checked a
2e3a0 67 61 69 6e 20 62 79 20 53 51 4c 69 74 65 2e 0a gain by SQLite..
2e3b0 2a 2a 0a 2a 2a 20 54 68 65 20 69 64 78 4e 75 6d **.** The idxNum
2e3c0 20 61 6e 64 20 69 64 78 50 74 72 20 76 61 6c 75 and idxPtr valu
2e3d0 65 73 20 61 72 65 20 72 65 63 6f 72 64 65 64 20 es are recorded
2e3e0 61 6e 64 20 70 61 73 73 65 64 20 69 6e 74 6f 20 and passed into
2e3f0 78 46 69 6c 74 65 72 2e 0a 2a 2a 20 73 71 6c 69 xFilter..** sqli
2e400 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 75 73 te3_free() is us
2e410 65 64 20 74 6f 20 66 72 65 65 20 69 64 78 50 74 ed to free idxPt
2e420 72 20 69 66 20 6e 65 65 64 54 6f 46 72 65 65 49 r if needToFreeI
2e430 64 78 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a dxPtr is true..*
2e440 2a 0a 2a 2a 20 54 68 65 20 6f 72 64 65 72 42 79 *.** The orderBy
2e450 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 Consumed means t
2e460 68 61 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 hat output from
2e470 78 46 69 6c 74 65 72 20 77 69 6c 6c 20 6f 63 63 xFilter will occ
2e480 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 ur in.** the cor
2e490 72 65 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61 rect order to sa
2e4a0 74 69 73 66 79 20 74 68 65 20 4f 52 44 45 52 20 tisfy the ORDER
2e4b0 42 59 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61 BY clause so tha
2e4c0 74 20 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a t no separate.**
2e4d0 20 73 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73 sorting step is
2e4e0 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a required..**.**
2e4f0 20 54 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f The estimatedCo
2e500 73 74 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65 st value is an e
2e510 73 74 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63 stimate of the c
2e520 6f 73 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 ost of doing the
2e530 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c .** particular l
2e540 6f 6f 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 ookup. A full s
2e550 63 61 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77 can of a table w
2e560 69 74 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68 ith N entries sh
2e570 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 ould have.** a c
2e580 6f 73 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e ost of N. A bin
2e590 61 72 79 20 73 65 61 72 63 68 20 6f 66 20 61 20 ary search of a
2e5a0 74 61 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 table of N entri
2e5b0 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61 es should have a
2e5c0 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72 .** cost of appr
2e5d0 6f 78 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 oximately log(N)
2e5e0 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 ..*/.struct sqli
2e5f0 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b te3_index_info {
2e600 0a 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a . /* Inputs */.
2e610 20 20 69 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e int nConstrain
2e620 74 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 t; /*
2e630 4e 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65 Number of entrie
2e640 73 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 s in aConstraint
2e650 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c */. struct sql
2e660 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 ite3_index_const
2e670 72 61 69 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74 raint {. int
2e680 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 iColumn;
2e690 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e /* Column
2e6a0 20 6f 6e 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 on left-hand si
2e6b0 64 65 20 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74 de of constraint
2e6c0 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 */. unsigne
2e6d0 64 20 63 68 61 72 20 6f 70 3b 20 20 20 20 20 20 d char op;
2e6e0 20 20 20 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74 /* Constraint
2e6f0 20 6f 70 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20 operator */.
2e700 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 unsigned char
2e710 75 73 61 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54 usable; /* T
2e720 72 75 65 20 69 66 20 74 68 69 73 20 63 6f 6e 73 rue if this cons
2e730 74 72 61 69 6e 74 20 69 73 20 75 73 61 62 6c 65 traint is usable
2e740 20 2a 2f 0a 20 20 20 20 20 69 6e 74 20 69 54 65 */. int iTe
2e750 72 6d 4f 66 66 73 65 74 3b 20 20 20 20 20 20 20 rmOffset;
2e760 20 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 /* Used inter
2e770 6e 61 6c 6c 79 20 2d 20 78 42 65 73 74 49 6e 64 nally - xBestInd
2e780 65 78 20 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65 ex should ignore
2e790 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 */. } *aConstr
2e7a0 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20 aint;
2e7b0 20 2f 2a 20 54 61 62 6c 65 20 6f 66 20 57 48 45 /* Table of WHE
2e7c0 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 RE clause constr
2e7d0 61 69 6e 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e aints */. int n
2e7e0 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 OrderBy;
2e7f0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 /* Number
2e800 6f 66 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 of terms in the
2e810 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 ORDER BY clause
2e820 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 */. struct sqli
2e830 74 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62 te3_index_orderb
2e840 79 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f y {. int iCo
2e850 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 lumn;
2e860 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d /* Column num
2e870 62 65 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 ber */. unsi
2e880 67 6e 65 64 20 63 68 61 72 20 64 65 73 63 3b 20 gned char desc;
2e890 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20 66 6f /* True fo
2e8a0 72 20 44 45 53 43 2e 20 20 46 61 6c 73 65 20 66 r DESC. False f
2e8b0 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a or ASC. */. } *
2e8c0 61 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 aOrderBy;
2e8d0 20 20 20 20 20 20 20 20 2f 2a 20 54 68 65 20 4f /* The O
2e8e0 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a RDER BY clause *
2e8f0 2f 0a 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73 20 /.. /* Outputs
2e900 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 */. struct sqli
2e910 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 te3_index_constr
2e920 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20 20 aint_usage {.
2e930 20 69 6e 74 20 61 72 67 76 49 6e 64 65 78 3b 20 int argvIndex;
2e940 20 20 20 20 20 20 20 20 20 20 2f 2a 20 69 66 20 /* if
2e950 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 >0, constraint i
2e960 73 20 70 61 72 74 20 6f 66 20 61 72 67 76 20 74 s part of argv t
2e970 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20 o xFilter */.
2e980 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f unsigned char o
2e990 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20 mit; /* Do
2e9a0 6e 6f 74 20 63 6f 64 65 20 61 20 74 65 73 74 20 not code a test
2e9b0 66 6f 72 20 74 68 69 73 20 63 6f 6e 73 74 72 61 for this constra
2e9c0 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e int */. } *aCon
2e9d0 73 74 72 61 69 6e 74 55 73 61 67 65 3b 0a 20 20 straintUsage;.
2e9e0 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20 20 20 20 int idxNum;
2e9f0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 /* Nu
2ea00 6d 62 65 72 20 75 73 65 64 20 74 6f 20 69 64 65 mber used to ide
2ea10 6e 74 69 66 79 20 74 68 65 20 69 6e 64 65 78 20 ntify the index
2ea20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64 78 53 74 */. char *idxSt
2ea30 72 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 r;
2ea40 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73 73 69 /* String, possi
2ea50 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f bly obtained fro
2ea60 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 m sqlite3_malloc
2ea70 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f */. int needTo
2ea80 46 72 65 65 49 64 78 53 74 72 3b 20 20 20 20 20 FreeIdxStr;
2ea90 20 2f 2a 20 46 72 65 65 20 69 64 78 53 74 72 20 /* Free idxStr
2eaa0 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 using sqlite3_fr
2eab0 65 65 28 29 20 69 66 20 74 72 75 65 20 2a 2f 0a ee() if true */.
2eac0 20 20 69 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e int orderByCon
2ead0 73 75 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a 20 sumed; /*
2eae0 54 72 75 65 20 69 66 20 6f 75 74 70 75 74 20 69 True if output i
2eaf0 73 20 61 6c 72 65 61 64 79 20 6f 72 64 65 72 65 s already ordere
2eb00 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73 d */. double es
2eb10 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 20 20 20 timatedCost;
2eb20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 63 /* Estimated c
2eb30 6f 73 74 20 6f 66 20 75 73 69 6e 67 20 74 68 69 ost of using thi
2eb40 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 23 64 s index */.};.#d
2eb50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 efine SQLITE_IND
2eb60 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 EX_CONSTRAINT_EQ
2eb70 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 2.#define SQ
2eb80 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 LITE_INDEX_CONST
2eb90 52 41 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 RAINT_GT 4.#d
2eba0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 efine SQLITE_IND
2ebb0 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 EX_CONSTRAINT_LE
2ebc0 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 8.#define SQ
2ebd0 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 LITE_INDEX_CONST
2ebe0 52 41 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 RAINT_LT 16.#
2ebf0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
2ec00 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 DEX_CONSTRAINT_G
2ec10 45 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20 E 32.#define
2ec20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e SQLITE_INDEX_CON
2ec30 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 STRAINT_MATCH 64
2ec40 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 ../*.** This rou
2ec50 74 69 6e 65 20 69 73 20 75 73 65 64 20 74 6f 20 tine is used to
2ec60 72 65 67 69 73 74 65 72 20 61 20 6e 65 77 20 6d register a new m
2ec70 6f 64 75 6c 65 20 6e 61 6d 65 20 77 69 74 68 20 odule name with
2ec80 61 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 6e an SQLite.** con
2ec90 6e 65 63 74 69 6f 6e 2e 20 20 4d 6f 64 75 6c 65 nection. Module
2eca0 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20 72 names must be r
2ecb0 65 67 69 73 74 65 72 65 64 20 62 65 66 6f 72 65 egistered before
2ecc0 20 63 72 65 61 74 69 6e 67 20 6e 65 77 0a 2a 2a creating new.**
2ecd0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 virtual tables
2ece0 6f 6e 20 74 68 65 20 6d 6f 64 75 6c 65 2c 20 6f on the module, o
2ecf0 72 20 62 65 66 6f 72 65 20 75 73 69 6e 67 20 70 r before using p
2ed00 72 65 65 78 69 73 74 69 6e 67 20 76 69 72 74 75 reexisting virtu
2ed10 61 6c 0a 2a 2a 20 74 61 62 6c 65 73 20 6f 66 20 al.** tables of
2ed20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a 69 the module..*/.i
2ed30 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 nt sqlite3_creat
2ed40 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 e_module(. sqli
2ed50 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
2ed60 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 /* SQLite
2ed70 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 connection to r
2ed80 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 egister module w
2ed90 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 ith */. const c
2eda0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 har *zName,
2edb0 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 /* Name of t
2edc0 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 he module */. c
2edd0 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 onst sqlite3_mod
2ede0 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 ule *, /* Met
2edf0 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 hods for the mod
2ee00 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 20 ule */. void *
2ee10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2ee20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 /* Client da
2ee30 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 ta for xCreate/x
2ee40 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a 2f Connect */.);../
2ee50 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
2ee60 65 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 e is identical t
2ee70 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 o the sqlite3_cr
2ee80 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 20 6d 65 eate_module() me
2ee90 74 68 6f 64 20 61 62 6f 76 65 2c 0a 2a 2a 20 65 thod above,.** e
2eea0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c xcept that it al
2eeb0 6c 6f 77 73 20 61 20 64 65 73 74 72 75 63 74 6f lows a destructo
2eec0 72 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 r function to be
2eed0 20 73 70 65 63 69 66 69 65 64 2e 20 49 74 20 69 specified. It i
2eee0 73 0a 2a 2a 20 65 76 65 6e 20 6d 6f 72 65 20 65 s.** even more e
2eef0 78 70 65 72 69 6d 65 6e 74 61 6c 20 74 68 61 6e xperimental than
2ef00 20 74 68 65 20 72 65 73 74 20 6f 66 20 74 68 65 the rest of the
2ef10 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 virtual tables
2ef20 41 50 49 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 API..*/.int sqli
2ef30 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c te3_create_modul
2ef40 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 e_v2(. sqlite3
2ef50 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
2ef60 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e /* SQLite con
2ef70 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 nection to regis
2ef80 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 ter module with
2ef90 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
2efa0 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 *zName,
2efb0 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d /* Name of the m
2efc0 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 odule */. const
2efd0 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 sqlite3_module
2efe0 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 *, /* Methods
2eff0 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 for the module
2f000 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 */. void *,
2f010 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2f020 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 /* Client data f
2f030 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e or xCreate/xConn
2f040 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 ect */. void(*x
2f050 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 Destroy)(void*)
2f060 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 /* Module de
2f070 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f structor functio
2f080 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 45 n */.);../*.** E
2f090 76 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c very module impl
2f0a0 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 ementation uses
2f0b0 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 a subclass of th
2f0c0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 e following stru
2f0d0 63 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63 cture.** to desc
2f0e0 72 69 62 65 20 61 20 70 61 72 74 69 63 75 6c 61 ribe a particula
2f0f0 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 r instance of th
2f100 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 e module. Each
2f110 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a subclass will.**
2f120 20 62 65 20 74 61 69 6c 6f 72 65 64 20 74 6f 20 be tailored to
2f130 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 the specific nee
2f140 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 ds of the module
2f150 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e implementation.
2f160 20 20 20 54 68 65 0a 2a 2a 20 70 75 72 70 6f 73 The.** purpos
2f170 65 20 6f 66 20 74 68 69 73 20 73 75 70 65 72 63 e of this superc
2f180 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66 69 6e lass is to defin
2f190 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73 e certain fields
2f1a0 20 74 68 61 74 20 61 72 65 20 63 6f 6d 6d 6f 6e that are common
2f1b0 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c .** to all modul
2f1c0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
2f1d0 73 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c s..**.** Virtual
2f1e0 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 20 tables methods
2f1f0 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f 72 can set an error
2f200 20 6d 65 73 73 61 67 65 20 62 79 20 61 73 73 69 message by assi
2f210 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e gning a.** strin
2f220 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 g obtained from
2f230 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
2f240 29 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 ) to zErrMsg. T
2f250 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 he method should
2f260 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 74 68 .** take care th
2f270 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73 74 72 at any prior str
2f280 69 6e 67 20 69 73 20 66 72 65 65 64 20 62 79 20 ing is freed by
2f290 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 a call to sqlite
2f2a0 33 5f 66 72 65 65 28 29 0a 2a 2a 20 70 72 69 6f 3_free().** prio
2f2b0 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61 r to assigning a
2f2c0 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a new string to z
2f2d0 45 72 72 4d 73 67 2e 20 20 41 66 74 65 72 20 74 ErrMsg. After t
2f2e0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 he error message
2f2f0 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64 .** is delivered
2f300 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e up to the clien
2f310 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 t application, t
2f320 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 he string will b
2f330 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a e automatically.
2f340 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c 69 ** freed by sqli
2f350 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74 te3_free() and t
2f360 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 he zErrMsg field
2f370 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e will be zeroed.
2f380 20 20 4e 6f 74 65 0a 2a 2a 20 74 68 61 74 20 73 Note.** that s
2f390 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 qlite3_mprintf()
2f3a0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 66 72 65 and sqlite3_fre
2f3b0 65 28 29 20 61 72 65 20 75 73 65 64 20 6f 6e 20 e() are used on
2f3c0 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c the zErrMsg fiel
2f3d0 64 0a 2a 2a 20 73 69 6e 63 65 20 76 69 72 74 75 d.** since virtu
2f3e0 61 6c 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f al tables are co
2f3f0 6d 6d 6f 6e 6c 79 20 69 6d 70 6c 65 6d 65 6e 74 mmonly implement
2f400 65 64 20 69 6e 20 6c 6f 61 64 61 62 6c 65 20 65 ed in loadable e
2f410 78 74 65 6e 73 69 6f 6e 73 20 77 68 69 63 68 0a xtensions which.
2f420 2a 2a 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 61 ** do not have a
2f430 63 63 65 73 73 20 74 6f 20 73 71 6c 69 74 65 33 ccess to sqlite3
2f440 4d 50 72 69 6e 74 66 28 29 20 6f 72 20 73 71 6c MPrintf() or sql
2f450 69 74 65 33 46 72 65 65 28 29 2e 0a 2a 2f 0a 73 ite3Free()..*/.s
2f460 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 truct sqlite3_vt
2f470 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c ab {. const sql
2f480 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f ite3_module *pMo
2f490 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f dule; /* The mo
2f4a0 64 75 6c 65 20 66 6f 72 20 74 68 69 73 20 76 69 dule for this vi
2f4b0 72 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 rtual table */.
2f4c0 20 69 6e 74 20 6e 52 65 66 3b 20 20 20 20 20 20 int nRef;
2f4d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2f4e0 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61 /* Used interna
2f4f0 6c 6c 79 20 2a 2f 0a 20 20 63 68 61 72 20 2a 7a lly */. char *z
2f500 45 72 72 4d 73 67 3b 20 20 20 20 20 20 20 20 20 ErrMsg;
2f510 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f /* Erro
2f520 72 20 6d 65 73 73 61 67 65 20 66 72 6f 6d 20 73 r message from s
2f530 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 qlite3_mprintf()
2f540 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c */. /* Virtual
2f550 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 table implement
2f560 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 ations will typi
2f570 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 cally add additi
2f580 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d onal fields */.}
2f590 3b 0a 0a 2f 2a 20 45 76 65 72 79 20 6d 6f 64 75 ;../* Every modu
2f5a0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
2f5b0 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 n uses a subclas
2f5c0 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 s of the followi
2f5d0 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 ng structure.**
2f5e0 74 6f 20 64 65 73 63 72 69 62 65 20 63 75 72 73 to describe curs
2f5f0 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74 20 69 ors that point i
2f600 6e 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 20 nto the virtual
2f610 74 61 62 6c 65 20 61 6e 64 20 61 72 65 20 75 73 table and are us
2f620 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68 ed.** to loop th
2f630 72 6f 75 67 68 20 74 68 65 20 76 69 72 74 75 61 rough the virtua
2f640 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73 6f 72 l table. Cursor
2f650 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 s are created us
2f660 69 6e 67 20 74 68 65 0a 2a 2a 20 78 4f 70 65 6e ing the.** xOpen
2f670 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 6d method of the m
2f680 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64 odule. Each mod
2f690 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ule implementati
2f6a0 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a on will define.*
2f6b0 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 * the content of
2f6c0 20 61 20 63 75 72 73 6f 72 20 73 74 72 75 63 74 a cursor struct
2f6d0 75 72 65 20 74 6f 20 73 75 69 74 20 69 74 73 20 ure to suit its
2f6e0 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a own needs..**.**
2f6f0 20 54 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 This superclass
2f700 20 65 78 69 73 74 73 20 69 6e 20 6f 72 64 65 72 exists in order
2f710 20 74 6f 20 64 65 66 69 6e 65 20 66 69 65 6c 64 to define field
2f720 73 20 6f 66 20 74 68 65 20 63 75 72 73 6f 72 20 s of the cursor
2f730 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d that.** are comm
2f740 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d on to all implem
2f750 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 entations..*/.st
2f760 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 ruct sqlite3_vta
2f770 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c b_cursor {. sql
2f780 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 ite3_vtab *pVtab
2f790 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74 75 61 ; /* Virtua
2f7a0 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69 73 20 l table of this
2f7b0 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 cursor */. /* V
2f7c0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 irtual table imp
2f7d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c lementations wil
2f7e0 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 l typically add
2f7f0 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 additional field
2f800 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 54 s */.};../*.** T
2f810 68 65 20 78 43 72 65 61 74 65 20 61 6e 64 20 78 he xCreate and x
2f820 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 73 20 Connect methods
2f830 6f 66 20 61 20 6d 6f 64 75 6c 65 20 75 73 65 20 of a module use
2f840 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 the following AP
2f850 49 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65 20 I.** to declare
2f860 74 68 65 20 66 6f 72 6d 61 74 20 28 74 68 65 20 the format (the
2f870 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61 74 79 names and dataty
2f880 70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d pes of the colum
2f890 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76 69 ns) of.** the vi
2f8a0 72 74 75 61 6c 20 74 61 62 6c 65 73 20 74 68 65 rtual tables the
2f8b0 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a y implement..*/.
2f8c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c int sqlite3_decl
2f8d0 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33 are_vtab(sqlite3
2f8e0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
2f8f0 43 72 65 61 74 65 54 61 62 6c 65 29 3b 0a 0a 2f CreateTable);../
2f900 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 *.** Virtual tab
2f910 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65 20 les can provide
2f920 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c alternative impl
2f930 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66 ementations of f
2f940 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e unctions.** usin
2f950 67 20 74 68 65 20 78 46 69 6e 64 46 75 6e 63 74 g the xFindFunct
2f960 69 6f 6e 20 6d 65 74 68 6f 64 2e 20 20 42 75 74 ion method. But
2f970 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73 global versions
2f980 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63 74 69 of those functi
2f990 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73 ons.** must exis
2f9a0 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 65 t in order to be
2f9b0 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a overloaded..**.
2f9c0 2a 2a 20 54 68 69 73 20 41 50 49 20 6d 61 6b 65 ** This API make
2f9d0 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c 20 s sure a global
2f9e0 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75 6e version of a fun
2f9f0 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61 72 ction with a par
2fa00 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20 ticular.** name
2fa10 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 and number of pa
2fa20 72 61 6d 65 74 65 72 73 20 65 78 69 73 74 73 2e rameters exists.
2fa30 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75 6e If no such fun
2fa40 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a 20 ction exists.**
2fa50 62 65 66 6f 72 65 20 74 68 69 73 20 41 50 49 20 before this API
2fa60 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65 77 is called, a new
2fa70 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72 65 function is cre
2fa80 61 74 65 64 2e 20 20 54 68 65 20 69 6d 70 6c 65 ated. The imple
2fa90 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 mentation.** of
2faa0 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e the new function
2fab0 20 61 6c 77 61 79 73 20 63 61 75 73 65 73 20 61 always causes a
2fac0 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f 20 62 n exception to b
2fad0 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a e thrown. So.**
2fae0 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f the new functio
2faf0 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66 6f n is not good fo
2fb00 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20 69 74 r anything by it
2fb10 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79 0a self. Its only.
2fb20 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20 74 6f ** purpose is to
2fb30 20 62 65 20 61 20 70 6c 61 63 65 2d 68 6f 6c 64 be a place-hold
2fb40 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 er function that
2fb50 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64 can be overload
2fb60 65 64 0a 2a 2a 20 62 79 20 76 69 72 74 75 61 6c ed.** by virtual
2fb70 20 74 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 tables..**.** T
2fb80 68 69 73 20 41 50 49 20 73 68 6f 75 6c 64 20 62 his API should b
2fb90 65 20 63 6f 6e 73 69 64 65 72 65 64 20 70 61 72 e considered par
2fba0 74 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c t of the virtual
2fbb0 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61 63 65 table interface
2fbc0 2c 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 65 78 ,.** which is ex
2fbd0 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 73 perimental and s
2fbe0 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 ubject to change
2fbf0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
2fc00 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 _overload_functi
2fc10 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e on(sqlite3*, con
2fc20 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 st char *zFuncNa
2fc30 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a me, int nArg);..
2fc40 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 /*.** The interf
2fc50 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 ace to the virtu
2fc60 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 al-table mechani
2fc70 73 6d 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65 sm defined above
2fc80 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 (back up.** to
2fc90 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b a comment remark
2fca0 61 62 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 ably similar to
2fcb0 74 68 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72 this one) is cur
2fcc0 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 rently considere
2fcd0 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 d.** to be exper
2fce0 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e imental. The in
2fcf0 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 terface might ch
2fd00 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 ange in incompat
2fd10 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 ible ways..** If
2fd20 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c this is a probl
2fd30 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e em for you, do n
2fd40 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 ot use the inter
2fd50 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d face at this tim
2fd60 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 e..**.** When th
2fd70 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 e virtual-table
2fd80 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c mechanism stabil
2fd90 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 izes, we will de
2fda0 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 clare the.** int
2fdb0 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 erface fixed, su
2fdc0 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e pport it indefin
2fdd0 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 itely, and remov
2fde0 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a e this comment..
2fdf0 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 **.****** EXPERI
2fe00 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 MENTAL - subject
2fe10 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f to change witho
2fe20 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a ut notice ******
2fe30 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a ********.*/../*.
2fe40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 20 48 ** CAPI3REF: A H
2fe50 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e andle To An Open
2fe60 20 42 4c 4f 42 20 7b 46 31 37 38 30 30 7d 0a 2a BLOB {F17800}.*
2fe70 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 *.** An instance
2fe80 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e of the followin
2fe90 67 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 g opaque structu
2fea0 72 65 20 69 73 20 75 73 65 64 20 74 6f 20 0a 2a re is used to .*
2feb0 2a 20 72 65 70 72 65 73 65 6e 74 20 61 6e 20 62 * represent an b
2fec0 6c 6f 62 2d 68 61 6e 64 6c 65 2e 20 20 41 20 62 lob-handle. A b
2fed0 6c 6f 62 2d 68 61 6e 64 6c 65 20 69 73 20 63 72 lob-handle is cr
2fee0 65 61 74 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c eated by.** [sql
2fef0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 ite3_blob_open()
2ff00 5d 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20 ] and destroyed
2ff10 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 by [sqlite3_blob
2ff20 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54 68 _close()]..** Th
2ff30 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f e [sqlite3_blob_
2ff40 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c read()] and [sql
2ff50 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 ite3_blob_write(
2ff60 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a )] interfaces.**
2ff70 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
2ff80 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d read or write sm
2ff90 61 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20 all subsections
2ffa0 6f 66 20 74 68 65 20 62 6c 6f 62 2e 0a 2a 2a 20 of the blob..**
2ffb0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f The [sqlite3_blo
2ffc0 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 b_bytes()] inter
2ffd0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 face returns the
2ffe0 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 size of the.**
2fff0 62 6c 6f 62 20 69 6e 20 62 79 74 65 73 2e 0a 2a blob in bytes..*
30000 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
30010 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 sqlite3_blob sq
30020 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a lite3_blob;../*.
30030 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 ** CAPI3REF: Ope
30040 6e 20 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 n A BLOB For Inc
30050 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 20 7b 46 31 remental I/O {F1
30060 37 38 31 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 7810}.**.** {F17
30070 38 31 31 7d 20 54 68 69 73 20 69 6e 74 65 72 66 811} This interf
30080 61 63 65 73 20 6f 70 65 6e 73 20 61 20 68 61 6e aces opens a han
30090 64 6c 65 20 74 6f 20 74 68 65 20 62 6c 6f 62 20 dle to the blob
300a0 6c 6f 63 61 74 65 64 0a 2a 2a 20 69 6e 20 72 6f located.** in ro
300b0 77 20 69 52 6f 77 2c 2c 20 63 6f 6c 75 6d 6e 20 w iRow,, column
300c0 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 20 7a zColumn, table z
300d0 54 61 62 6c 65 20 69 6e 20 64 61 74 61 62 61 73 Table in databas
300e0 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68 e zDb;.** in oth
300f0 65 72 20 77 6f 72 64 73 2c 20 20 74 68 65 20 73 er words, the s
30100 61 6d 65 20 62 6c 6f 62 20 74 68 61 74 20 77 6f ame blob that wo
30110 75 6c 64 20 62 65 20 73 65 6c 65 63 74 65 64 20 uld be selected
30120 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a by:.**.** <pre>.
30130 2a 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a 43 ** SELECT zC
30140 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a olumn FROM zDb.z
30150 54 61 62 6c 65 20 57 48 45 52 45 20 72 6f 77 69 Table WHERE rowi
30160 64 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 d = iRow;.** </p
30170 72 65 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 re> {END}.**.**
30180 7b 46 31 37 38 31 32 7d 20 49 66 20 74 68 65 20 {F17812} If the
30190 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 flags parameter
301a0 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 is non-zero, the
301b0 20 62 6c 6f 62 20 69 73 20 6f 70 65 6e 65 64 20 blob is opened
301c0 66 6f 72 20 0a 2a 2a 20 72 65 61 64 20 61 6e 64 for .** read and
301d0 20 77 72 69 74 65 20 61 63 63 65 73 73 2e 20 49 write access. I
301e0 66 20 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 f it is zero, th
301f0 65 20 62 6c 6f 62 20 69 73 20 6f 70 65 6e 65 64 e blob is opened
30200 20 66 6f 72 20 72 65 61 64 20 0a 2a 2a 20 61 63 for read .** ac
30210 63 65 73 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a cess. {END}.**.*
30220 2a 20 7b 46 31 37 38 31 33 7d 20 4f 6e 20 73 75 * {F17813} On su
30230 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f ccess, [SQLITE_O
30240 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 K] is returned a
30250 6e 64 20 74 68 65 20 6e 65 77 20 0a 2a 2a 20 5b nd the new .** [
30260 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 sqlite3_blob | b
30270 6c 6f 62 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 lob handle] is w
30280 72 69 74 74 65 6e 20 74 6f 20 2a 70 70 42 6c 6f ritten to *ppBlo
30290 62 2e 20 0a 2a 2a 20 7b 46 31 37 38 31 34 7d 20 b. .** {F17814}
302a0 4f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 Otherwise an err
302b0 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 or code is retur
302c0 6e 65 64 20 61 6e 64 20 0a 2a 2a 20 61 6e 79 20 ned and .** any
302d0 76 61 6c 75 65 20 77 72 69 74 74 65 6e 20 74 6f value written to
302e0 20 2a 70 70 42 6c 6f 62 20 73 68 6f 75 6c 64 20 *ppBlob should
302f0 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 74 not be used by t
30300 68 65 20 63 61 6c 6c 65 72 2e 0a 2a 2a 20 7b 46 he caller..** {F
30310 31 37 38 31 35 7d 20 54 68 69 73 20 66 75 6e 63 17815} This func
30320 74 69 6f 6e 20 73 65 74 73 20 74 68 65 20 64 61 tion sets the da
30330 74 61 62 61 73 65 2d 68 61 6e 64 6c 65 20 65 72 tabase-handle er
30340 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 ror code and mes
30350 73 61 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 sage.** accessib
30360 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f le via [sqlite3_
30370 65 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b errcode()] and [
30380 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
30390 5d 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 57 65 20 73 ]..** <todo>We s
303a0 68 6f 75 6c 64 20 67 6f 20 74 68 72 6f 75 67 68 hould go through
303b0 20 61 6e 64 20 6d 61 72 6b 20 61 6c 6c 20 69 6e and mark all in
303c0 74 65 72 66 61 63 65 73 20 74 68 61 74 20 62 65 terfaces that be
303d0 68 61 76 65 20 74 68 69 73 0a 2a 2a 20 77 61 79 have this.** way
303e0 20 77 69 74 68 20 61 20 73 69 6d 69 6c 61 72 20 with a similar
303f0 73 74 61 74 65 6d 65 6e 74 3c 2f 74 6f 64 6f 3e statement</todo>
30400 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
30410 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c blob_open(. sql
30420 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 ite3*,. const c
30430 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 har *zDb,. cons
30440 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a t char *zTable,.
30450 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 const char *zC
30460 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33 olumn,. sqlite3
30470 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20 69 _int64 iRow,. i
30480 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69 nt flags,. sqli
30490 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f te3_blob **ppBlo
304a0 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 b.);../*.** CAPI
304b0 33 52 45 46 3a 20 20 43 6c 6f 73 65 20 41 20 42 3REF: Close A B
304c0 4c 4f 42 20 48 61 6e 64 6c 65 20 7b 46 31 37 38 LOB Handle {F178
304d0 33 30 7d 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 20 30}.**.** Close
304e0 61 6e 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 an open [sqlite3
304f0 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61 6e _blob | blob han
30500 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 dle]..**.** {F17
30510 38 33 31 7d 20 43 6c 6f 73 69 6e 67 20 61 20 42 831} Closing a B
30520 4c 4f 42 20 73 68 61 6c 6c 20 63 61 75 73 65 20 LOB shall cause
30530 74 68 65 20 63 75 72 72 65 6e 74 20 74 72 61 6e the current tran
30540 73 61 63 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 saction to commi
30550 74 0a 2a 2a 20 69 66 20 74 68 65 72 65 20 61 72 t.** if there ar
30560 65 20 6e 6f 20 6f 74 68 65 72 20 42 4c 4f 42 73 e no other BLOBs
30570 2c 20 6e 6f 20 70 65 6e 64 69 6e 67 20 70 72 65 , no pending pre
30580 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
30590 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74 , and the.** dat
305a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
305b0 20 69 73 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 is in autocommi
305c0 74 20 6d 6f 64 65 2e 0a 2a 2a 20 7b 46 31 37 38 t mode..** {F178
305d0 33 32 7d 20 49 66 20 61 6e 79 20 77 72 69 74 65 32} If any write
305e0 73 20 77 65 72 65 20 6d 61 64 65 20 74 6f 20 74 s were made to t
305f0 68 65 20 42 4c 4f 42 2c 20 74 68 65 79 20 6d 69 he BLOB, they mi
30600 67 68 74 20 62 65 20 68 65 6c 64 20 69 6e 20 63 ght be held in c
30610 61 63 68 65 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 ache.** until th
30620 65 20 63 6c 6f 73 65 20 6f 70 65 72 61 74 69 6f e close operatio
30630 6e 20 69 66 20 74 68 65 79 20 77 69 6c 6c 20 66 n if they will f
30640 69 74 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 43 6c 6f it. {END}.** Clo
30650 73 69 6e 67 20 74 68 65 20 42 4c 4f 42 20 6f 66 sing the BLOB of
30660 74 65 6e 20 66 6f 72 63 65 73 20 74 68 65 20 63 ten forces the c
30670 68 61 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f hanges.** out to
30680 20 64 69 73 6b 20 61 6e 64 20 73 6f 20 69 66 20 disk and so if
30690 61 6e 79 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f any I/O errors o
306a0 63 63 75 72 2c 20 74 68 65 79 20 77 69 6c 6c 20 ccur, they will
306b0 6c 69 6b 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 likely occur.**
306c0 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e at the time when
306d0 20 74 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f the BLOB is clo
306e0 73 65 64 2e 20 20 7b 46 31 37 38 33 33 7d 20 41 sed. {F17833} A
306f0 6e 79 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f ny errors that o
30700 63 63 75 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63 ccur during.** c
30710 6c 6f 73 69 6e 67 20 61 72 65 20 72 65 70 6f 72 losing are repor
30720 74 65 64 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 ted as a non-zer
30730 6f 20 72 65 74 75 72 6e 20 76 61 6c 75 65 2e 0a o return value..
30740 2a 2a 0a 2a 2a 20 7b 46 31 37 38 33 39 7d 20 54 **.** {F17839} T
30750 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 he BLOB is close
30760 64 20 75 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c d unconditionall
30770 79 2e 20 20 45 76 65 6e 20 69 66 20 74 68 69 73 y. Even if this
30780 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
30790 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 .** an error cod
307a0 65 2c 20 74 68 65 20 42 4c 4f 42 20 69 73 20 73 e, the BLOB is s
307b0 74 69 6c 6c 20 63 6c 6f 73 65 64 2e 0a 2a 2f 0a till closed..*/.
307c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 int sqlite3_blob
307d0 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 5f 62 _close(sqlite3_b
307e0 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 lob *);../*.** C
307f0 41 50 49 33 52 45 46 3a 20 20 52 65 74 75 72 6e API3REF: Return
30800 20 54 68 65 20 53 69 7a 65 20 4f 66 20 41 6e 20 The Size Of An
30810 4f 70 65 6e 20 42 4c 4f 42 20 7b 46 31 37 38 30 Open BLOB {F1780
30820 35 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 38 30 36 5}.**.** {F16806
30830 7d 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a } Return the siz
30840 65 20 69 6e 20 62 79 74 65 73 20 6f 66 20 74 68 e in bytes of th
30850 65 20 62 6c 6f 62 20 61 63 63 65 73 73 69 62 6c e blob accessibl
30860 65 20 76 69 61 20 74 68 65 20 6f 70 65 6e 20 0a e via the open .
30870 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 ** [sqlite3_blob
30880 20 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 | blob-handle]
30890 70 61 73 73 65 64 20 61 73 20 61 6e 20 61 72 67 passed as an arg
308a0 75 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ument..*/.int sq
308b0 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 lite3_blob_bytes
308c0 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 (sqlite3_blob *)
308d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
308e0 46 3a 20 20 52 65 61 64 20 44 61 74 61 20 46 72 F: Read Data Fr
308f0 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d om A BLOB Increm
30900 65 6e 74 61 6c 6c 79 20 7b 46 31 37 38 35 30 7d entally {F17850}
30910 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 .**.** This func
30920 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 tion is used to
30930 72 65 61 64 20 64 61 74 61 20 66 72 6f 6d 20 61 read data from a
30940 6e 20 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 n open .** [sqli
30950 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d te3_blob | blob-
30960 68 61 6e 64 6c 65 5d 20 69 6e 74 6f 20 61 20 63 handle] into a c
30970 61 6c 6c 65 72 20 73 75 70 70 6c 69 65 64 20 62 aller supplied b
30980 75 66 66 65 72 2e 0a 2a 2a 20 7b 46 31 37 38 35 uffer..** {F1785
30990 31 7d 20 6e 20 62 79 74 65 73 20 6f 66 20 64 61 1} n bytes of da
309a0 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e ta are copied in
309b0 74 6f 20 62 75 66 66 65 72 0a 2a 2a 20 7a 20 66 to buffer.** z f
309c0 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20 62 6c 6f rom the open blo
309d0 62 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f b, starting at o
309e0 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a ffset iOffset..*
309f0 2a 0a 2a 2a 20 7b 46 31 37 38 35 32 7d 20 49 66 *.** {F17852} If
30a00 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 20 offset iOffset
30a10 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6e 20 62 is less than n b
30a20 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e ytes from the en
30a30 64 20 6f 66 20 74 68 65 20 62 6c 6f 62 2c 20 0a d of the blob, .
30a40 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ** [SQLITE_ERROR
30a50 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e ] is returned an
30a60 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61 d no data is rea
30a70 64 2e 20 20 7b 46 31 37 38 35 33 7d 20 49 66 20 d. {F17853} If
30a80 6e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 n is.** less tha
30a90 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45 n zero [SQLITE_E
30aa0 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 RROR] is returne
30ab0 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 d and no data is
30ac0 20 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 read..**.** {F1
30ad0 37 38 35 34 7d 20 4f 6e 20 73 75 63 63 65 73 73 7854} On success
30ae0 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 , SQLITE_OK is r
30af0 65 74 75 72 6e 65 64 2e 20 4f 74 68 65 72 77 69 eturned. Otherwi
30b00 73 65 2c 20 61 6e 20 0a 2a 2a 20 5b 65 72 72 6f se, an .** [erro
30b10 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 r code] or an [e
30b20 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f xtended error co
30b30 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e de] is returned.
30b40 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
30b50 62 6c 6f 62 5f 72 65 61 64 28 73 71 6c 69 74 65 blob_read(sqlite
30b60 33 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 3_blob *, void *
30b70 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f z, int n, int iO
30b80 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ffset);../*.** C
30b90 41 50 49 33 52 45 46 3a 20 20 57 72 69 74 65 20 API3REF: Write
30ba0 44 61 74 61 20 49 6e 74 6f 20 41 20 42 4c 4f 42 Data Into A BLOB
30bb0 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b Incrementally {
30bc0 46 31 37 38 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 F17870}.**.** Th
30bd0 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 is function is u
30be0 73 65 64 20 74 6f 20 77 72 69 74 65 20 64 61 74 sed to write dat
30bf0 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 0a a into an open .
30c00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 ** [sqlite3_blob
30c10 20 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 | blob-handle]
30c20 66 72 6f 6d 20 61 20 75 73 65 72 20 73 75 70 70 from a user supp
30c30 6c 69 65 64 20 62 75 66 66 65 72 2e 0a 2a 2a 20 lied buffer..**
30c40 7b 46 31 37 38 37 31 7d 20 6e 20 62 79 74 65 73 {F17871} n bytes
30c50 20 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70 of data are cop
30c60 69 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 66 ied from the buf
30c70 66 65 72 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 fer.** pointed t
30c80 6f 20 62 79 20 7a 20 69 6e 74 6f 20 74 68 65 20 o by z into the
30c90 6f 70 65 6e 20 62 6c 6f 62 2c 20 73 74 61 72 74 open blob, start
30ca0 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f ing at offset iO
30cb0 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 ffset..**.** {F1
30cc0 37 38 37 32 7d 20 49 66 20 74 68 65 20 5b 73 71 7872} If the [sq
30cd0 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f lite3_blob | blo
30ce0 62 2d 68 61 6e 64 6c 65 5d 20 70 61 73 73 65 64 b-handle] passed
30cf0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 as the first ar
30d00 67 75 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 6e 6f gument.** was no
30d10 74 20 6f 70 65 6e 65 64 20 66 6f 72 20 77 72 69 t opened for wri
30d20 74 69 6e 67 20 28 74 68 65 20 66 6c 61 67 73 20 ting (the flags
30d30 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
30d40 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 lite3_blob_open(
30d50 29 5d 0a 2a 2a 2a 20 77 61 73 20 7a 65 72 6f 29 )].*** was zero)
30d60 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 , this function
30d70 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
30d80 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a READONLY]..**.**
30d90 20 7b 46 31 37 38 37 33 7d 20 54 68 69 73 20 66 {F17873} This f
30da0 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79 unction may only
30db0 20 6d 6f 64 69 66 79 20 74 68 65 20 63 6f 6e 74 modify the cont
30dc0 65 6e 74 73 20 6f 66 20 74 68 65 20 62 6c 6f 62 ents of the blob
30dd0 3b 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 ; it is.** not p
30de0 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 63 72 65 ossible to incre
30df0 61 73 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 ase the size of
30e00 61 20 62 6c 6f 62 20 75 73 69 6e 67 20 74 68 69 a blob using thi
30e10 73 20 41 50 49 2e 0a 2a 2a 20 7b 46 31 37 38 37 s API..** {F1787
30e20 34 7d 20 49 66 20 6f 66 66 73 65 74 20 69 4f 66 4} If offset iOf
30e30 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 fset is less tha
30e40 6e 20 6e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 n n bytes from t
30e50 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 62 6c he end of the bl
30e60 6f 62 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ob, .** [SQLITE_
30e70 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e ERROR] is return
30e80 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 ed and no data i
30e90 73 20 77 72 69 74 74 65 6e 2e 20 20 7b 46 31 37 s written. {F17
30ea0 38 37 35 7d 20 49 66 20 6e 20 69 73 0a 2a 2a 20 875} If n is.**
30eb0 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 20 5b less than zero [
30ec0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 SQLITE_ERROR] is
30ed0 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f returned and no
30ee0 20 64 61 74 61 20 69 73 20 77 72 69 74 74 65 6e data is written
30ef0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 37 36 7d ..**.** {F17876}
30f00 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 53 51 4c On success, SQL
30f10 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e ITE_OK is return
30f20 65 64 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 61 ed. Otherwise, a
30f30 6e 20 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 n .** [error cod
30f40 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 e] or an [extend
30f50 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 ed error code] i
30f60 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 s returned..*/.i
30f70 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f nt sqlite3_blob_
30f80 77 72 69 74 65 28 73 71 6c 69 74 65 33 5f 62 6c write(sqlite3_bl
30f90 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 ob *, const void
30fa0 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 *z, int n, int
30fb0 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a iOffset);../*.**
30fc0 20 43 41 50 49 33 52 45 46 3a 20 20 56 69 72 74 CAPI3REF: Virt
30fd0 75 61 6c 20 46 69 6c 65 20 53 79 73 74 65 6d 20 ual File System
30fe0 4f 62 6a 65 63 74 73 20 7b 46 31 31 32 30 30 7d Objects {F11200}
30ff0 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c .**.** A virtual
31000 20 66 69 6c 65 73 79 73 74 65 6d 20 28 56 46 53 filesystem (VFS
31010 29 20 69 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 ) is an [sqlite3
31020 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 _vfs] object.**
31030 74 68 61 74 20 53 51 4c 69 74 65 20 75 73 65 73 that SQLite uses
31040 20 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a 2a 20 to interact.**
31050 77 69 74 68 20 74 68 65 20 75 6e 64 65 72 6c 79 with the underly
31060 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 ing operating sy
31070 73 74 65 6d 2e 20 20 4d 6f 73 74 20 62 75 69 6c stem. Most buil
31080 64 73 20 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a ds come with a.*
31090 2a 20 73 69 6e 67 6c 65 20 64 65 66 61 75 6c 74 * single default
310a0 20 56 46 53 20 74 68 61 74 20 69 73 20 61 70 70 VFS that is app
310b0 72 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 ropriate for the
310c0 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a host computer..
310d0 2a 2a 20 4e 65 77 20 56 46 53 65 73 20 63 61 6e ** New VFSes can
310e0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 61 be registered a
310f0 6e 64 20 65 78 69 73 74 69 6e 67 20 56 46 53 65 nd existing VFSe
31100 73 20 63 61 6e 20 62 65 20 75 6e 72 65 67 69 73 s can be unregis
31110 74 65 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f tered..** The fo
31120 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 llowing interfac
31130 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 2e es are provided.
31140 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 32 30 31 7d 20 .**.** {F11201}
31150 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f The sqlite3_vfs_
31160 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61 63 65 find() interface
31170 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
31180 65 72 20 74 6f 20 0a 2a 2a 20 61 20 56 46 53 20 er to .** a VFS
31190 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 given its name.
311a0 20 7b 46 31 31 32 30 32 7d 20 4e 61 6d 65 73 20 {F11202} Names
311b0 61 72 65 20 63 61 73 65 20 73 65 6e 73 69 74 69 are case sensiti
311c0 76 65 2e 0a 2a 2a 20 7b 46 31 31 32 30 33 7d 20 ve..** {F11203}
311d0 4e 61 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d 74 Names are zero-t
311e0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 erminated UTF-8
311f0 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 7b 46 31 31 strings..** {F11
31200 32 30 34 7d 20 49 66 20 74 68 65 72 65 20 69 73 204} If there is
31210 20 6e 6f 20 6d 61 74 63 68 2c 20 61 20 4e 55 4c no match, a NUL
31220 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 L.** pointer is
31230 72 65 74 75 72 6e 65 64 2e 20 7b 46 31 31 32 30 returned. {F1120
31240 35 7d 20 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 5} If zVfsName i
31250 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 s NULL then the
31260 64 65 66 61 75 6c 74 20 0a 2a 2a 20 56 46 53 20 default .** VFS
31270 69 73 20 72 65 74 75 72 6e 65 64 2e 20 7b 45 4e is returned. {EN
31280 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 32 31 30 D}.**.** {F11210
31290 7d 20 4e 65 77 20 56 46 53 65 73 20 61 72 65 20 } New VFSes are
312a0 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 registered with
312b0 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 sqlite3_vfs_regi
312c0 73 74 65 72 28 29 2e 0a 2a 2a 20 7b 46 31 31 32 ster()..** {F112
312d0 31 31 7d 20 45 61 63 68 20 6e 65 77 20 56 46 53 11} Each new VFS
312e0 20 62 65 63 6f 6d 65 73 20 74 68 65 20 64 65 66 becomes the def
312f0 61 75 6c 74 20 56 46 53 20 69 66 20 74 68 65 20 ault VFS if the
31300 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 69 73 makeDflt flag is
31310 20 73 65 74 2e 0a 2a 2a 20 7b 46 31 31 32 31 32 set..** {F11212
31320 7d 20 54 68 65 20 73 61 6d 65 20 56 46 53 20 63 } The same VFS c
31330 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 an be registered
31340 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 multiple times
31350 77 69 74 68 6f 75 74 20 69 6e 6a 75 72 79 2e 0a without injury..
31360 2a 2a 20 7b 46 31 31 32 31 33 7d 20 54 6f 20 6d ** {F11213} To m
31370 61 6b 65 20 61 6e 20 65 78 69 73 74 69 6e 67 20 ake an existing
31380 56 46 53 20 69 6e 74 6f 20 74 68 65 20 64 65 66 VFS into the def
31390 61 75 6c 74 20 56 46 53 2c 20 72 65 67 69 73 74 ault VFS, regist
313a0 65 72 20 69 74 20 61 67 61 69 6e 0a 2a 2a 20 77 er it again.** w
313b0 69 74 68 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 ith the makeDflt
313c0 20 66 6c 61 67 20 73 65 74 2e 20 7b 55 31 31 32 flag set. {U112
313d0 31 34 7d 20 49 66 20 74 77 6f 20 64 69 66 66 65 14} If two diffe
313e0 72 65 6e 74 20 56 46 53 65 73 20 77 69 74 68 20 rent VFSes with
313f0 74 68 65 0a 2a 2a 20 73 61 6d 65 20 6e 61 6d 65 the.** same name
31400 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64 2c are registered,
31410 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
31420 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 7b 55 31 undefined. {U1
31430 31 32 31 35 7d 20 49 66 20 61 0a 2a 2a 20 56 46 1215} If a.** VF
31440 53 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 S is registered
31450 77 69 74 68 20 61 20 6e 61 6d 65 20 74 68 61 74 with a name that
31460 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 is NULL or an e
31470 6d 70 74 79 20 73 74 72 69 6e 67 2c 0a 2a 2a 20 mpty string,.**
31480 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f then the behavio
31490 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a r is undefined..
314a0 2a 2a 20 0a 2a 2a 20 7b 46 31 31 32 32 30 7d 20 ** .** {F11220}
314b0 55 6e 72 65 67 69 73 74 65 72 20 61 20 56 46 53 Unregister a VFS
314c0 20 77 69 74 68 20 74 68 65 20 73 71 6c 69 74 65 with the sqlite
314d0 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 3_vfs_unregister
314e0 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a () interface..**
314f0 20 7b 46 31 31 32 32 31 7d 20 49 66 20 74 68 65 {F11221} If the
31500 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 default VFS is
31510 75 6e 72 65 67 69 73 74 65 72 65 64 2c 20 61 6e unregistered, an
31520 6f 74 68 65 72 20 56 46 53 20 69 73 20 63 68 6f other VFS is cho
31530 73 65 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64 65 sen as.** the de
31540 66 61 75 6c 74 2e 20 20 54 68 65 20 63 68 6f 69 fault. The choi
31550 63 65 20 66 6f 72 20 74 68 65 20 6e 65 77 20 56 ce for the new V
31560 46 53 20 69 73 20 61 72 62 69 74 72 61 72 79 2e FS is arbitrary.
31570 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 66 73 20 .*/.sqlite3_vfs
31580 2a 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e *sqlite3_vfs_fin
31590 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 d(const char *zV
315a0 66 73 4e 61 6d 65 29 3b 0a 69 6e 74 20 73 71 6c fsName);.int sql
315b0 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 ite3_vfs_registe
315c0 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 r(sqlite3_vfs*,
315d0 69 6e 74 20 6d 61 6b 65 44 66 6c 74 29 3b 0a 69 int makeDflt);.i
315e0 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 nt sqlite3_vfs_u
315f0 6e 72 65 67 69 73 74 65 72 28 73 71 6c 69 74 65 nregister(sqlite
31600 33 5f 76 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 3_vfs*);../*.**
31610 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 65 CAPI3REF: Mutexe
31620 73 20 7b 46 31 37 30 30 30 7d 0a 2a 2a 0a 2a 2a s {F17000}.**.**
31630 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 The SQLite core
31640 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 uses these rout
31650 69 6e 65 73 20 66 6f 72 20 74 68 72 65 61 64 0a ines for thread.
31660 2a 2a 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69 ** synchronizati
31670 6f 6e 2e 20 20 54 68 6f 75 67 68 20 74 68 65 79 on. Though they
31680 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f are intended fo
31690 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 r internal.** us
316a0 65 20 62 79 20 53 51 4c 69 74 65 2c 20 63 6f 64 e by SQLite, cod
316b0 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 e that links aga
316c0 69 6e 73 74 20 53 51 4c 69 74 65 20 69 73 0a 2a inst SQLite is.*
316d0 2a 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 75 * permitted to u
316e0 73 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 se any of these
316f0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 routines..**.**
31700 54 68 65 20 53 51 4c 69 74 65 20 73 6f 75 72 63 The SQLite sourc
31710 65 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 e code contains
31720 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 multiple impleme
31730 6e 74 61 74 69 6f 6e 73 20 0a 2a 2a 20 6f 66 20 ntations .** of
31740 74 68 65 73 65 20 6d 75 74 65 78 20 72 6f 75 74 these mutex rout
31750 69 6e 65 73 2e 20 20 41 6e 20 61 70 70 72 6f 70 ines. An approp
31760 72 69 61 74 65 20 69 6d 70 6c 65 6d 65 6e 74 61 riate implementa
31770 74 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c 65 63 tion.** is selec
31780 74 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c ted automaticall
31790 79 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d y at compile-tim
317a0 65 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e e. The followin
317b0 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 g.** implementat
317c0 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62 ions are availab
317d0 6c 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 le in the SQLite
317e0 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c core:.**.** <ul
317f0 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 >.** <li> SQLI
31800 54 45 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 TE_MUTEX_OS2.**
31810 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 <li> SQLITE_MU
31820 54 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a 20 3c TEX_PTHREAD.** <
31830 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 li> SQLITE_MUT
31840 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 EX_W32.** <li>
31850 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f SQLITE_MUTEX_NO
31860 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a OP.** </ul>.**.*
31870 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 * The SQLITE_MUT
31880 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e EX_NOOP implemen
31890 74 61 74 69 6f 6e 20 69 73 20 61 20 73 65 74 20 tation is a set
318a0 6f 66 20 72 6f 75 74 69 6e 65 73 20 0a 2a 2a 20 of routines .**
318b0 74 68 61 74 20 64 6f 65 73 20 6e 6f 20 72 65 61 that does no rea
318c0 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73 l locking and is
318d0 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 appropriate for
318e0 20 75 73 65 20 69 6e 20 0a 2a 2a 20 61 20 73 69 use in .** a si
318f0 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 20 61 70 ngle-threaded ap
31900 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 plication. The
31910 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 SQLITE_MUTEX_OS2
31920 2c 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 ,.** SQLITE_MUTE
31930 58 5f 50 54 48 52 45 41 44 2c 20 61 6e 64 20 53 X_PTHREAD, and S
31940 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 20 QLITE_MUTEX_W32
31950 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a implementations.
31960 2a 2a 20 61 72 65 20 61 70 70 72 6f 70 72 69 61 ** are appropria
31970 74 65 20 66 6f 72 20 75 73 65 20 6f 6e 20 6f 73 te for use on os
31980 2f 32 2c 20 75 6e 69 78 2c 20 61 6e 64 20 77 69 /2, unix, and wi
31990 6e 64 6f 77 73 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 ndows..** .** If
319a0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
319b0 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c led with the SQL
319c0 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 ITE_MUTEX_APPDEF
319d0 20 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a preprocessor.**
319e0 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20 28 macro defined (
319f0 77 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d with "-DSQLITE_M
31a00 55 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29 2c UTEX_APPDEF=1"),
31a10 20 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a then no mutex.*
31a20 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
31a30 20 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69 74 is included wit
31a40 68 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20 20 h the library.
31a50 54 68 65 0a 2a 2a 20 6d 75 74 65 78 20 69 6e 74 The.** mutex int
31a60 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 erface routines
31a70 64 65 66 69 6e 65 64 20 68 65 72 65 20 62 65 63 defined here bec
31a80 6f 6d 65 20 65 78 74 65 72 6e 61 6c 0a 2a 2a 20 ome external.**
31a90 72 65 66 65 72 65 6e 63 65 73 20 69 6e 20 74 68 references in th
31aa0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 e SQLite library
31ab0 20 66 6f 72 20 77 68 69 63 68 20 69 6d 70 6c 65 for which imple
31ac0 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6d 75 mentations.** mu
31ad0 73 74 20 62 65 20 70 72 6f 76 69 64 65 64 20 62 st be provided b
31ae0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f y the applicatio
31af0 6e 2e 20 20 54 68 69 73 20 66 61 63 69 6c 69 74 n. This facilit
31b00 79 20 61 6c 6c 6f 77 73 20 61 6e 0a 2a 2a 20 61 y allows an.** a
31b10 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 pplication that
31b20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 51 links against SQ
31b30 4c 69 74 65 20 74 6f 20 70 72 6f 76 69 64 65 20 Lite to provide
31b40 69 74 73 20 6f 77 6e 20 6d 75 74 65 78 0a 2a 2a its own mutex.**
31b50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
31b60 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 without having t
31b70 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c o modify the SQL
31b80 69 74 65 20 63 6f 72 65 2e 0a 2a 2a 0a 2a 2a 20 ite core..**.**
31b90 7b 46 31 37 30 31 31 7d 20 54 68 65 20 73 71 6c {F17011} The sql
31ba0 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 ite3_mutex_alloc
31bb0 28 29 20 72 6f 75 74 69 6e 65 20 61 6c 6c 6f 63 () routine alloc
31bc0 61 74 65 73 20 61 20 6e 65 77 0a 2a 2a 20 6d 75 ates a new.** mu
31bd0 74 65 78 20 61 6e 64 20 72 65 74 75 72 6e 73 20 tex and returns
31be0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e a pointer to it.
31bf0 20 7b 46 31 37 30 31 32 7d 20 49 66 20 69 74 20 {F17012} If it
31c00 72 65 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 returns NULL.**
31c10 74 68 61 74 20 6d 65 61 6e 73 20 74 68 61 74 20 that means that
31c20 61 20 6d 75 74 65 78 20 63 6f 75 6c 64 20 6e 6f a mutex could no
31c30 74 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 2e 20 t be allocated.
31c40 7b 46 31 37 30 31 33 7d 20 53 51 4c 69 74 65 0a {F17013} SQLite.
31c50 2a 2a 20 77 69 6c 6c 20 75 6e 77 69 6e 64 20 69 ** will unwind i
31c60 74 73 20 73 74 61 63 6b 20 61 6e 64 20 72 65 74 ts stack and ret
31c70 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 20 7b 46 urn an error. {F
31c80 31 37 30 31 34 7d 20 54 68 65 20 61 72 67 75 6d 17014} The argum
31c90 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 ent.** to sqlite
31ca0 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 3_mutex_alloc()
31cb0 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 is one of these
31cc0 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 integer constant
31cd0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a s:.**.** <ul>.**
31ce0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 <li> SQLITE_MU
31cf0 54 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e TEX_FAST.** <li>
31d00 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 SQLITE_MUTEX_R
31d10 45 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e ECURSIVE.** <li>
31d20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 SQLITE_MUTEX_S
31d30 54 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20 TATIC_MASTER.**
31d40 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 <li> SQLITE_MUT
31d50 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a EX_STATIC_MEM.**
31d60 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 <li> SQLITE_MU
31d70 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a TEX_STATIC_MEM2.
31d80 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f ** <li> SQLITE_
31d90 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e MUTEX_STATIC_PRN
31da0 47 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 G.** <li> SQLIT
31db0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c E_MUTEX_STATIC_L
31dc0 52 55 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 RU.** </ul> {END
31dd0 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 30 31 35 7d }.**.** {F17015}
31de0 20 54 68 65 20 66 69 72 73 74 20 74 77 6f 20 63 The first two c
31df0 6f 6e 73 74 61 6e 74 73 20 63 61 75 73 65 20 73 onstants cause s
31e00 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c qlite3_mutex_all
31e10 6f 63 28 29 20 74 6f 20 63 72 65 61 74 65 0a 2a oc() to create.*
31e20 2a 20 61 20 6e 65 77 20 6d 75 74 65 78 2e 20 20 * a new mutex.
31e30 54 68 65 20 6e 65 77 20 6d 75 74 65 78 20 69 73 The new mutex is
31e40 20 72 65 63 75 72 73 69 76 65 20 77 68 65 6e 20 recursive when
31e50 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 SQLITE_MUTEX_REC
31e60 55 52 53 49 56 45 0a 2a 2a 20 69 73 20 75 73 65 URSIVE.** is use
31e70 64 20 62 75 74 20 6e 6f 74 20 6e 65 63 65 73 73 d but not necess
31e80 61 72 69 6c 79 20 73 6f 20 77 68 65 6e 20 53 51 arily so when SQ
31e90 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 LITE_MUTEX_FAST
31ea0 69 73 20 75 73 65 64 2e 20 7b 45 4e 44 7d 0a 2a is used. {END}.*
31eb0 2a 20 54 68 65 20 6d 75 74 65 78 20 69 6d 70 6c * The mutex impl
31ec0 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 ementation does
31ed0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d 61 6b 65 not need to make
31ee0 20 61 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a a distinction.*
31ef0 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 * between SQLITE
31f00 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 _MUTEX_RECURSIVE
31f10 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 and SQLITE_MUTE
31f20 58 5f 46 41 53 54 20 69 66 20 69 74 20 64 6f 65 X_FAST if it doe
31f30 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 6f s.** not want to
31f40 2e 20 20 7b 46 31 37 30 31 36 7d 20 42 75 74 20 . {F17016} But
31f50 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 SQLite will only
31f60 20 72 65 71 75 65 73 74 20 61 20 72 65 63 75 72 request a recur
31f70 73 69 76 65 20 6d 75 74 65 78 20 69 6e 0a 2a 2a sive mutex in.**
31f80 20 63 61 73 65 73 20 77 68 65 72 65 20 69 74 20 cases where it
31f90 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f 6e 65 really needs one
31fa0 2e 20 20 7b 45 4e 44 7d 20 49 66 20 61 20 66 61 . {END} If a fa
31fb0 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72 73 69 ster non-recursi
31fc0 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c ve mutex.** impl
31fd0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 76 ementation is av
31fe0 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65 20 68 ailable on the h
31ff0 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20 74 68 ost platform, th
32000 65 20 6d 75 74 65 78 20 73 75 62 73 79 73 74 65 e mutex subsyste
32010 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74 75 72 m.** might retur
32020 6e 20 73 75 63 68 20 61 20 6d 75 74 65 78 20 69 n such a mutex i
32030 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 53 51 n response to SQ
32040 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 2e LITE_MUTEX_FAST.
32050 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 30 31 37 7d 20 .**.** {F17017}
32060 54 68 65 20 6f 74 68 65 72 20 61 6c 6c 6f 77 65 The other allowe
32070 64 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 d parameters to
32080 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c sqlite3_mutex_al
32090 6c 6f 63 28 29 20 65 61 63 68 20 72 65 74 75 72 loc() each retur
320a0 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 n.** a pointer t
320b0 6f 20 61 20 73 74 61 74 69 63 20 70 72 65 65 78 o a static preex
320c0 69 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 7b 45 isting mutex. {E
320d0 4e 44 7d 20 20 46 6f 75 72 20 73 74 61 74 69 63 ND} Four static
320e0 20 6d 75 74 65 78 65 73 20 61 72 65 0a 2a 2a 20 mutexes are.**
320f0 75 73 65 64 20 62 79 20 74 68 65 20 63 75 72 72 used by the curr
32100 65 6e 74 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 ent version of S
32110 51 4c 69 74 65 2e 20 20 46 75 74 75 72 65 20 76 QLite. Future v
32120 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
32130 65 0a 2a 2a 20 6d 61 79 20 61 64 64 20 61 64 64 e.** may add add
32140 69 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d itional static m
32150 75 74 65 78 65 73 2e 20 20 53 74 61 74 69 63 20 utexes. Static
32160 6d 75 74 65 78 65 73 20 61 72 65 20 66 6f 72 20 mutexes are for
32170 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 internal.** use
32180 62 79 20 53 51 4c 69 74 65 20 6f 6e 6c 79 2e 20 by SQLite only.
32190 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 Applications th
321a0 61 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d 75 at use SQLite mu
321b0 74 65 78 65 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 texes should.**
321c0 75 73 65 20 6f 6e 6c 79 20 74 68 65 20 64 79 6e use only the dyn
321d0 61 6d 69 63 20 6d 75 74 65 78 65 73 20 72 65 74 amic mutexes ret
321e0 75 72 6e 65 64 20 62 79 20 53 51 4c 49 54 45 5f urned by SQLITE_
321f0 4d 55 54 45 58 5f 46 41 53 54 20 6f 72 0a 2a 2a MUTEX_FAST or.**
32200 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 SQLITE_MUTEX_RE
32210 43 55 52 53 49 56 45 2e 0a 2a 2a 0a 2a 2a 20 7b CURSIVE..**.** {
32220 46 31 37 30 31 38 7d 20 4e 6f 74 65 20 74 68 61 F17018} Note tha
32230 74 20 69 66 20 6f 6e 65 20 6f 66 20 74 68 65 20 t if one of the
32240 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 70 61 dynamic mutex pa
32250 72 61 6d 65 74 65 72 73 20 28 53 51 4c 49 54 45 rameters (SQLITE
32260 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 6f _MUTEX_FAST.** o
32270 72 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 r SQLITE_MUTEX_R
32280 45 43 55 52 53 49 56 45 29 20 69 73 20 75 73 65 ECURSIVE) is use
32290 64 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d d then sqlite3_m
322a0 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20 utex_alloc().**
322b0 72 65 74 75 72 6e 73 20 61 20 64 69 66 66 65 72 returns a differ
322c0 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65 76 65 ent mutex on eve
322d0 72 79 20 63 61 6c 6c 2e 20 20 7b 46 31 37 30 33 ry call. {F1703
322e0 34 7d 20 42 75 74 20 66 6f 72 20 74 68 65 20 73 4} But for the s
322f0 74 61 74 69 63 20 0a 2a 2a 20 6d 75 74 65 78 20 tatic .** mutex
32300 74 79 70 65 73 2c 20 74 68 65 20 73 61 6d 65 20 types, the same
32310 6d 75 74 65 78 20 69 73 20 72 65 74 75 72 6e 65 mutex is returne
32320 64 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 20 d on every call
32330 74 68 61 74 20 68 61 73 0a 2a 2a 20 74 68 65 20 that has.** the
32340 73 61 6d 65 20 74 79 70 65 20 6e 75 6d 62 65 72 same type number
32350 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 . {END}.**.** {F
32360 31 37 30 31 39 7d 20 54 68 65 20 73 71 6c 69 74 17019} The sqlit
32370 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 20 e3_mutex_free()
32380 72 6f 75 74 69 6e 65 20 64 65 61 6c 6c 6f 63 61 routine dealloca
32390 74 65 73 20 61 20 70 72 65 76 69 6f 75 73 6c 79 tes a previously
323a0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 64 79 .** allocated dy
323b0 6e 61 6d 69 63 20 6d 75 74 65 78 2e 20 7b 46 31 namic mutex. {F1
323c0 37 30 32 30 7d 20 53 51 4c 69 74 65 20 69 73 20 7020} SQLite is
323d0 63 61 72 65 66 75 6c 20 74 6f 20 64 65 61 6c 6c careful to deall
323e0 6f 63 61 74 65 20 65 76 65 72 79 0a 2a 2a 20 64 ocate every.** d
323f0 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 74 68 61 ynamic mutex tha
32400 74 20 69 74 20 61 6c 6c 6f 63 61 74 65 73 2e 20 t it allocates.
32410 7b 55 31 37 30 32 31 7d 20 54 68 65 20 64 79 6e {U17021} The dyn
32420 61 6d 69 63 20 6d 75 74 65 78 65 73 20 6d 75 73 amic mutexes mus
32430 74 20 6e 6f 74 20 62 65 20 69 6e 20 0a 2a 2a 20 t not be in .**
32440 75 73 65 20 77 68 65 6e 20 74 68 65 79 20 61 72 use when they ar
32450 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 20 7b e deallocated. {
32460 55 31 37 30 32 32 7d 20 41 74 74 65 6d 70 74 69 U17022} Attempti
32470 6e 67 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 ng to deallocate
32480 20 61 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 a static.** mut
32490 65 78 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e ex results in un
324a0 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 defined behavior
324b0 2e 20 7b 46 31 37 30 32 33 7d 20 53 51 4c 69 74 . {F17023} SQLit
324c0 65 20 6e 65 76 65 72 20 64 65 61 6c 6c 6f 63 61 e never dealloca
324d0 74 65 73 0a 2a 2a 20 61 20 73 74 61 74 69 63 20 tes.** a static
324e0 6d 75 74 65 78 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a mutex. {END}.**.
324f0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d ** The sqlite3_m
32500 75 74 65 78 5f 65 6e 74 65 72 28 29 20 61 6e 64 utex_enter() and
32510 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 sqlite3_mutex_t
32520 72 79 28 29 20 72 6f 75 74 69 6e 65 73 20 61 74 ry() routines at
32530 74 65 6d 70 74 0a 2a 2a 20 74 6f 20 65 6e 74 65 tempt.** to ente
32540 72 20 61 20 6d 75 74 65 78 2e 20 7b 46 31 37 30 r a mutex. {F170
32550 32 34 7d 20 49 66 20 61 6e 6f 74 68 65 72 20 74 24} If another t
32560 68 72 65 61 64 20 69 73 20 61 6c 72 65 61 64 79 hread is already
32570 20 77 69 74 68 69 6e 20 74 68 65 20 6d 75 74 65 within the mute
32580 78 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 x,.** sqlite3_mu
32590 74 65 78 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c tex_enter() will
325a0 20 62 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 block and sqlit
325b0 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 77 e3_mutex_try() w
325c0 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 ill return.** SQ
325d0 4c 49 54 45 5f 42 55 53 59 2e 20 7b 46 31 37 30 LITE_BUSY. {F170
325e0 32 35 7d 20 20 54 68 65 20 73 71 6c 69 74 65 33 25} The sqlite3
325f0 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 69 6e 74 _mutex_try() int
32600 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 53 erface returns S
32610 51 4c 49 54 45 5f 4f 4b 0a 2a 2a 20 75 70 6f 6e QLITE_OK.** upon
32620 20 73 75 63 63 65 73 73 66 75 6c 20 65 6e 74 72 successful entr
32630 79 2e 20 20 7b 46 31 37 30 32 36 7d 20 4d 75 74 y. {F17026} Mut
32640 65 78 65 73 20 63 72 65 61 74 65 64 20 75 73 69 exes created usi
32650 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 ng.** SQLITE_MUT
32660 45 58 5f 52 45 43 55 52 53 49 56 45 20 63 61 6e EX_RECURSIVE can
32670 20 62 65 20 65 6e 74 65 72 65 64 20 6d 75 6c 74 be entered mult
32680 69 70 6c 65 20 74 69 6d 65 73 20 62 79 20 74 68 iple times by th
32690 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e 0a 2a e same thread..*
326a0 2a 20 7b 46 31 37 30 32 37 7d 20 49 6e 20 73 75 * {F17027} In su
326b0 63 68 20 63 61 73 65 73 20 74 68 65 2c 0a 2a 2a ch cases the,.**
326c0 20 6d 75 74 65 78 20 6d 75 73 74 20 62 65 20 65 mutex must be e
326d0 78 69 74 65 64 20 61 6e 20 65 71 75 61 6c 20 6e xited an equal n
326e0 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 62 umber of times b
326f0 65 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 74 68 efore another th
32700 72 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74 65 read.** can ente
32710 72 2e 20 20 7b 55 31 37 30 32 38 7d 20 49 66 20 r. {U17028} If
32720 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 the same thread
32730 74 72 69 65 73 20 74 6f 20 65 6e 74 65 72 20 61 tries to enter a
32740 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 ny other.** kind
32750 20 6f 66 20 6d 75 74 65 78 20 6d 6f 72 65 20 74 of mutex more t
32760 68 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20 62 65 han once, the be
32770 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 havior is undefi
32780 6e 65 64 2e 0a 2a 2a 20 7b 46 31 37 30 32 39 7d ned..** {F17029}
32790 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 SQLite will nev
327a0 65 72 20 65 78 68 69 62 69 74 0a 2a 2a 20 73 75 er exhibit.** su
327b0 63 68 20 62 65 68 61 76 69 6f 72 20 69 6e 20 69 ch behavior in i
327c0 74 73 20 6f 77 6e 20 75 73 65 20 6f 66 20 6d 75 ts own use of mu
327d0 74 65 78 65 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a texes. {END}.**.
327e0 2a 2a 20 53 6f 6d 65 20 73 79 73 74 65 6d 73 20 ** Some systems
327f0 28 65 78 3a 20 77 69 6e 64 6f 77 73 39 35 29 20 (ex: windows95)
32800 64 6f 20 6e 6f 74 20 74 68 65 20 6f 70 65 72 61 do not the opera
32810 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 65 64 tion implemented
32820 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d by.** sqlite3_m
32830 75 74 65 78 5f 74 72 79 28 29 2e 20 20 4f 6e 20 utex_try(). On
32840 74 68 6f 73 65 20 73 79 73 74 65 6d 73 2c 20 73 those systems, s
32850 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 qlite3_mutex_try
32860 28 29 20 77 69 6c 6c 0a 2a 2a 20 61 6c 77 61 79 () will.** alway
32870 73 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f s return SQLITE_
32880 42 55 53 59 2e 20 20 7b 46 31 37 30 33 30 7d 20 BUSY. {F17030}
32890 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 The SQLite core
328a0 6f 6e 6c 79 20 65 76 65 72 20 75 73 65 73 0a 2a only ever uses.*
328b0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f * sqlite3_mutex_
328c0 74 72 79 28 29 20 61 73 20 61 6e 20 6f 70 74 69 try() as an opti
328d0 6d 69 7a 61 74 69 6f 6e 20 73 6f 20 74 68 69 73 mization so this
328e0 20 69 73 20 61 63 63 65 70 74 61 62 6c 65 20 62 is acceptable b
328f0 65 68 61 76 69 6f 72 2e 20 7b 45 4e 44 7d 0a 2a ehavior. {END}.*
32900 2a 0a 2a 2a 20 7b 46 31 37 30 33 31 7d 20 54 68 *.** {F17031} Th
32910 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f e sqlite3_mutex_
32920 6c 65 61 76 65 28 29 20 72 6f 75 74 69 6e 65 20 leave() routine
32930 65 78 69 74 73 20 61 20 6d 75 74 65 78 20 74 68 exits a mutex th
32940 61 74 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f at was.** previo
32950 75 73 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20 usly entered by
32960 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e the same thread.
32970 20 20 7b 55 31 37 30 33 32 7d 20 54 68 65 20 62 {U17032} The b
32980 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e ehavior.** is un
32990 64 65 66 69 6e 65 64 20 69 66 20 74 68 65 20 6d defined if the m
329a0 75 74 65 78 20 69 73 20 6e 6f 74 20 63 75 72 72 utex is not curr
329b0 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 62 79 ently entered by
329c0 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 the.** calling
329d0 74 68 72 65 61 64 20 6f 72 20 69 73 20 6e 6f 74 thread or is not
329e0 20 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f 63 currently alloc
329f0 61 74 65 64 2e 20 20 7b 46 31 37 30 33 33 7d 20 ated. {F17033}
32a00 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e SQLite will.** n
32a10 65 76 65 72 20 64 6f 20 65 69 74 68 65 72 2e 20 ever do either.
32a20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53 65 65 20 {END}.**.** See
32a30 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6d also: [sqlite3_m
32a40 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 61 6e 64 utex_held()] and
32a50 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
32a60 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a 2f 0a 73 notheld()]..*/.s
32a70 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73 71 qlite3_mutex *sq
32a80 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f lite3_mutex_allo
32a90 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c c(int);.void sql
32aa0 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 ite3_mutex_free(
32ab0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b sqlite3_mutex*);
32ac0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 .void sqlite3_mu
32ad0 74 65 78 5f 65 6e 74 65 72 28 73 71 6c 69 74 65 tex_enter(sqlite
32ae0 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 3_mutex*);.int s
32af0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 qlite3_mutex_try
32b00 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 (sqlite3_mutex*)
32b10 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d ;.void sqlite3_m
32b20 75 74 65 78 5f 6c 65 61 76 65 28 73 71 6c 69 74 utex_leave(sqlit
32b30 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a e3_mutex*);../*.
32b40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 ** CAPI3REF: Mut
32b50 65 78 20 56 65 72 69 66 63 61 74 69 6f 6e 20 52 ex Verifcation R
32b60 6f 75 74 69 6e 65 73 20 7b 46 31 37 30 38 30 7d outines {F17080}
32b70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
32b80 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 e3_mutex_held()
32b90 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 and sqlite3_mute
32ba0 78 5f 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75 74 x_notheld() rout
32bb0 69 6e 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74 65 ines.** are inte
32bc0 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 nded for use ins
32bd0 69 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61 ide assert() sta
32be0 74 65 6d 65 6e 74 73 2e 20 7b 46 31 37 30 38 31 tements. {F17081
32bf0 7d 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 } The SQLite cor
32c00 65 0a 2a 2a 20 6e 65 76 65 72 20 75 73 65 73 20 e.** never uses
32c10 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 65 these routines e
32c20 78 63 65 70 74 20 69 6e 73 69 64 65 20 61 6e 20 xcept inside an
32c30 61 73 73 65 72 74 28 29 20 61 6e 64 20 61 70 70 assert() and app
32c40 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 lications.** are
32c50 20 61 64 76 69 73 65 64 20 74 6f 20 66 6f 6c 6c advised to foll
32c60 6f 77 20 74 68 65 20 6c 65 61 64 20 6f 66 20 74 ow the lead of t
32c70 68 65 20 63 6f 72 65 2e 20 20 7b 46 31 37 30 38 he core. {F1708
32c80 32 7d 20 54 68 65 20 63 6f 72 65 20 6f 6e 6c 79 2} The core only
32c90 0a 2a 2a 20 70 72 6f 76 69 64 65 73 20 69 6d 70 .** provides imp
32ca0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 lementations for
32cb0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
32cc0 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 when it is compi
32cd0 6c 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 led.** with the
32ce0 53 51 4c 49 54 45 5f 44 45 42 55 47 20 66 6c 61 SQLITE_DEBUG fla
32cf0 67 2e 20 20 7b 55 31 37 30 38 37 7d 20 45 78 74 g. {U17087} Ext
32d00 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 6d 70 6c ernal mutex impl
32d10 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 ementations.** a
32d20 72 65 20 6f 6e 6c 79 20 72 65 71 75 69 72 65 64 re only required
32d30 20 74 6f 20 70 72 6f 76 69 64 65 20 74 68 65 73 to provide thes
32d40 65 20 72 6f 75 74 69 6e 65 73 20 69 66 20 53 51 e routines if SQ
32d50 4c 49 54 45 5f 44 45 42 55 47 20 69 73 0a 2a 2a LITE_DEBUG is.**
32d60 20 64 65 66 69 6e 65 64 20 61 6e 64 20 69 66 20 defined and if
32d70 4e 44 45 42 55 47 20 69 73 20 6e 6f 74 20 64 65 NDEBUG is not de
32d80 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 fined..**.** {F1
32d90 37 30 38 33 7d 20 54 68 65 73 65 20 72 6f 75 74 7083} These rout
32da0 69 6e 65 73 20 73 68 6f 75 6c 64 20 72 65 74 75 ines should retu
32db0 72 6e 20 74 72 75 65 20 69 66 20 74 68 65 20 6d rn true if the m
32dc0 75 74 65 78 20 69 6e 20 74 68 65 69 72 20 61 72 utex in their ar
32dd0 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 68 65 6c gument.** is hel
32de0 64 20 6f 72 20 6e 6f 74 20 68 65 6c 64 2c 20 72 d or not held, r
32df0 65 73 70 65 63 74 69 76 65 6c 79 2c 20 62 79 20 espectively, by
32e00 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 the calling thre
32e10 61 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 ad. {END}.**.**
32e20 7b 58 31 37 30 38 34 7d 20 54 68 65 20 69 6d 70 {X17084} The imp
32e30 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e lementation is n
32e40 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 ot required to p
32e50 72 6f 76 69 64 65 64 20 76 65 72 73 69 6f 6e 73 rovided versions
32e60 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 72 6f 75 of these.** rou
32e70 74 69 6e 65 73 20 74 68 61 74 20 61 63 74 75 61 tines that actua
32e80 6c 6c 79 20 77 6f 72 6b 2e 0a 2a 2a 20 49 66 20 lly work..** If
32e90 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 the implementati
32ea0 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 on does not prov
32eb0 69 64 65 20 77 6f 72 6b 69 6e 67 0a 2a 2a 20 76 ide working.** v
32ec0 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 ersions of these
32ed0 20 72 6f 75 74 69 6e 65 73 2c 20 69 74 20 73 68 routines, it sh
32ee0 6f 75 6c 64 20 61 74 20 6c 65 61 73 74 20 70 72 ould at least pr
32ef0 6f 76 69 64 65 20 73 74 75 62 73 0a 2a 2a 20 74 ovide stubs.** t
32f00 68 61 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 hat always retur
32f10 6e 20 74 72 75 65 20 73 6f 20 74 68 61 74 20 6f n true so that o
32f20 6e 65 20 64 6f 65 73 20 6e 6f 74 20 67 65 74 20 ne does not get
32f30 73 70 75 72 69 6f 75 73 0a 2a 2a 20 61 73 73 65 spurious.** asse
32f40 72 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 2e 20 rtion failures.
32f50 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 {END}.**.** {F17
32f60 30 38 35 7d 20 49 66 20 74 68 65 20 61 72 67 75 085} If the argu
32f70 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f ment to sqlite3_
32f80 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 69 73 20 mutex_held() is
32f90 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 a NULL pointer t
32fa0 68 65 6e 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 hen.** the routi
32fb0 6e 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e ne should return
32fc0 20 31 2e 20 20 7b 45 4e 44 7d 20 54 68 69 73 20 1. {END} This
32fd0 73 65 65 6d 73 20 63 6f 75 6e 74 65 72 2d 69 6e seems counter-in
32fe0 74 75 69 74 69 76 65 20 73 69 6e 63 65 0a 2a 2a tuitive since.**
32ff0 20 63 6c 65 61 72 6c 79 20 74 68 65 20 6d 75 74 clearly the mut
33000 65 78 20 63 61 6e 6e 6f 74 20 62 65 20 68 65 6c ex cannot be hel
33010 64 20 69 66 20 69 74 20 64 6f 65 73 20 6e 6f 74 d if it does not
33020 20 65 78 69 73 74 2e 20 20 42 75 74 20 74 68 65 exist. But the
33030 0a 2a 2a 20 74 68 65 20 72 65 61 73 6f 6e 20 74 .** the reason t
33040 68 65 20 6d 75 74 65 78 20 64 6f 65 73 20 6e 6f he mutex does no
33050 74 20 65 78 69 73 74 20 69 73 20 62 65 63 61 75 t exist is becau
33060 73 65 20 74 68 65 20 62 75 69 6c 64 20 69 73 20 se the build is
33070 6e 6f 74 0a 2a 2a 20 75 73 69 6e 67 20 6d 75 74 not.** using mut
33080 65 78 65 73 2e 20 20 41 6e 64 20 77 65 20 64 6f exes. And we do
33090 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 61 73 not want the as
330a0 73 65 72 74 28 29 20 63 6f 6e 74 61 69 6e 69 6e sert() containin
330b0 67 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 20 74 6f g the.** call to
330c0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 sqlite3_mutex_h
330d0 65 6c 64 28 29 20 74 6f 20 66 61 69 6c 2c 20 73 eld() to fail, s
330e0 6f 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 o a non-zero ret
330f0 75 72 6e 20 69 73 0a 2a 2a 20 74 68 65 20 61 70 urn is.** the ap
33100 70 72 6f 70 72 69 61 74 65 20 74 68 69 6e 67 20 propriate thing
33110 74 6f 20 64 6f 2e 20 20 7b 46 31 37 30 38 36 7d to do. {F17086}
33120 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 The sqlite3_mut
33130 65 78 5f 6e 6f 74 68 65 6c 64 28 29 20 0a 2a 2a ex_notheld() .**
33140 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f 75 6c interface shoul
33150 64 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 31 20 d also return 1
33160 77 68 65 6e 20 67 69 76 65 6e 20 61 20 4e 55 4c when given a NUL
33170 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 69 6e L pointer..*/.in
33180 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f t sqlite3_mutex_
33190 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 held(sqlite3_mut
331a0 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 ex*);.int sqlite
331b0 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 3_mutex_notheld(
331c0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b sqlite3_mutex*);
331d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
331e0 3a 20 4d 75 74 65 78 20 54 79 70 65 73 20 7b 46 : Mutex Types {F
331f0 31 37 30 30 31 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 17001}.**.** {F1
33200 37 30 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 7002} The [sqlit
33210 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 e3_mutex_alloc()
33220 5d 20 69 6e 74 65 72 66 61 63 65 20 74 61 6b 65 ] interface take
33230 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
33240 65 6e 74 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 ent.** which is
33250 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 one of these int
33260 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 2e 20 eger constants.
33270 7b 45 4e 44 7d 0a 2a 2f 0a 23 64 65 66 69 6e 65 {END}.*/.#define
33280 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 SQLITE_MUTEX_FA
33290 53 54 20 20 20 20 20 20 20 20 20 20 20 20 20 30 ST 0
332a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
332b0 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 MUTEX_RECURSIVE
332c0 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 1.#define
332d0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 SQLITE_MUTEX_ST
332e0 41 54 49 43 5f 4d 41 53 54 45 52 20 20 20 20 32 ATIC_MASTER 2
332f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
33300 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d MUTEX_STATIC_MEM
33310 20 20 20 20 20 20 20 33 20 20 2f 2a 20 73 71 6c 3 /* sql
33320 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 2a 2f ite3_malloc() */
33330 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
33340 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d MUTEX_STATIC_MEM
33350 32 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 2 4 /* sql
33360 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d ite3_release_mem
33370 6f 72 79 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 ory() */.#define
33380 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 SQLITE_MUTEX_ST
33390 41 54 49 43 5f 50 52 4e 47 20 20 20 20 20 20 35 ATIC_PRNG 5
333a0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 72 61 6e /* sqlite3_ran
333b0 64 6f 6d 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 dom() */.#define
333c0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 SQLITE_MUTEX_ST
333d0 41 54 49 43 5f 4c 52 55 20 20 20 20 20 20 20 36 ATIC_LRU 6
333e0 20 20 2f 2a 20 6c 72 75 20 70 61 67 65 20 6c 69 /* lru page li
333f0 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 st */../*.** CAP
33400 49 33 52 45 46 3a 20 4c 6f 77 2d 4c 65 76 65 6c I3REF: Low-Level
33410 20 43 6f 6e 74 72 6f 6c 20 4f 66 20 44 61 74 61 Control Of Data
33420 62 61 73 65 20 46 69 6c 65 73 20 7b 46 31 31 33 base Files {F113
33430 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 30 00}.**.** {F1130
33440 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 1} The [sqlite3_
33450 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 file_control()]
33460 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 interface makes
33470 61 20 64 69 72 65 63 74 20 63 61 6c 6c 20 74 6f a direct call to
33480 20 74 68 65 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e the.** xFileCon
33490 74 72 6f 6c 20 6d 65 74 68 6f 64 20 66 6f 72 20 trol method for
334a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f the [sqlite3_io_
334b0 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 methods] object
334c0 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 associated.** wi
334d0 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 th a particular
334e0 64 61 74 61 62 61 73 65 20 69 64 65 6e 74 69 66 database identif
334f0 69 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e ied by the secon
33500 64 20 61 72 67 75 6d 65 6e 74 2e 20 7b 46 31 31 d argument. {F11
33510 33 30 32 7d 20 54 68 65 0a 2a 2a 20 6e 61 6d 65 302} The.** name
33520 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
33530 20 69 73 20 74 68 65 20 6e 61 6d 65 20 61 73 73 is the name ass
33540 69 67 6e 65 64 20 74 6f 20 74 68 65 20 64 61 74 igned to the dat
33550 61 62 61 73 65 20 62 79 20 74 68 65 0a 2a 2a 20 abase by the.**
33560 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f 61 74 <a href="lang_at
33570 74 61 63 68 2e 68 74 6d 6c 22 3e 41 54 54 41 43 tach.html">ATTAC
33580 48 3c 2f 61 3e 20 53 51 4c 20 63 6f 6d 6d 61 6e H</a> SQL comman
33590 64 20 74 68 61 74 20 6f 70 65 6e 65 64 20 74 68 d that opened th
335a0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 7b e.** database. {
335b0 46 31 31 33 30 33 7d 20 54 6f 20 63 6f 6e 74 72 F11303} To contr
335c0 6f 6c 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 ol the main data
335d0 62 61 73 65 20 66 69 6c 65 2c 20 75 73 65 20 74 base file, use t
335e0 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 0a 2a he name "main".*
335f0 2a 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e * or a NULL poin
33600 74 65 72 2e 20 7b 46 31 31 33 30 34 7d 20 54 68 ter. {F11304} Th
33610 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 e third and four
33620 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f th parameters to
33630 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a this routine.**
33640 20 61 72 65 20 70 61 73 73 65 64 20 64 69 72 65 are passed dire
33650 63 74 6c 79 20 74 68 72 6f 75 67 68 20 74 6f 20 ctly through to
33660 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 the second and t
33670 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 73 20 hird parameters
33680 6f 66 0a 2a 2a 20 74 68 65 20 78 46 69 6c 65 43 of.** the xFileC
33690 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 20 ontrol method.
336a0 7b 46 31 31 33 30 35 7d 20 54 68 65 20 72 65 74 {F11305} The ret
336b0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 urn value of the
336c0 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 0a 2a 2a xFileControl.**
336d0 20 6d 65 74 68 6f 64 20 62 65 63 6f 6d 65 73 20 method becomes
336e0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
336f0 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 of this routine
33700 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 30 36 7d ..**.** {F11306}
33710 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 If the second p
33720 61 72 61 6d 65 74 65 72 20 28 7a 44 62 4e 61 6d arameter (zDbNam
33730 65 29 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 e) does not matc
33740 68 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 6e h the name of an
33750 79 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62 61 y.** open databa
33760 73 65 20 66 69 6c 65 2c 20 74 68 65 6e 20 53 51 se file, then SQ
33770 4c 49 54 45 5f 45 52 52 4f 52 20 69 73 20 72 65 LITE_ERROR is re
33780 74 75 72 6e 65 64 2e 20 7b 46 31 31 33 30 37 7d turned. {F11307}
33790 20 54 68 69 73 20 65 72 72 6f 72 0a 2a 2a 20 63 This error.** c
337a0 6f 64 65 20 69 73 20 6e 6f 74 20 72 65 6d 65 6d ode is not remem
337b0 62 65 72 65 64 20 61 6e 64 20 77 69 6c 6c 20 6e bered and will n
337c0 6f 74 20 62 65 20 72 65 63 61 6c 6c 65 64 20 62 ot be recalled b
337d0 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f y [sqlite3_errco
337e0 64 65 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c de()].** or [sql
337f0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 20 ite3_errmsg()].
33800 7b 55 31 31 33 30 38 7d 20 54 68 65 20 75 6e 64 {U11308} The und
33810 65 72 6c 79 69 6e 67 20 78 46 69 6c 65 43 6f 6e erlying xFileCon
33820 74 72 6f 6c 20 6d 65 74 68 6f 64 20 6d 69 67 68 trol method migh
33830 74 0a 2a 2a 20 61 6c 73 6f 20 72 65 74 75 72 6e t.** also return
33840 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 SQLITE_ERROR.
33850 7b 55 31 31 33 30 39 7d 20 54 68 65 72 65 20 69 {U11309} There i
33860 73 20 6e 6f 20 77 61 79 20 74 6f 20 64 69 73 74 s no way to dist
33870 69 6e 67 75 69 73 68 20 62 65 74 77 65 65 6e 0a inguish between.
33880 2a 2a 20 61 6e 20 69 6e 63 6f 72 72 65 63 74 20 ** an incorrect
33890 7a 44 62 4e 61 6d 65 20 61 6e 64 20 61 6e 20 53 zDbName and an S
338a0 51 4c 49 54 45 5f 45 52 52 4f 52 20 72 65 74 75 QLITE_ERROR retu
338b0 72 6e 20 66 72 6f 6d 20 74 68 65 20 75 6e 64 65 rn from the unde
338c0 72 6c 79 69 6e 67 0a 2a 2a 20 78 46 69 6c 65 43 rlying.** xFileC
338d0 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 7b ontrol method. {
338e0 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 END}.**.** See a
338f0 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 46 43 4e lso: [SQLITE_FCN
33900 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 0a 2a 2f TL_LOCKSTATE].*/
33910 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6c .int sqlite3_fil
33920 65 5f 63 6f 6e 74 72 6f 6c 28 73 71 6c 69 74 65 e_control(sqlite
33930 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 3*, const char *
33940 7a 44 62 4e 61 6d 65 2c 20 69 6e 74 20 6f 70 2c zDbName, int op,
33950 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 void*);../*.**
33960 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 69 6e CAPI3REF: Testin
33970 67 20 49 6e 74 65 72 66 61 63 65 20 7b 46 31 31 g Interface {F11
33980 34 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 400}.**.** The s
33990 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 qlite3_test_cont
339a0 72 6f 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 rol() interface
339b0 69 73 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 is used to read
339c0 6f 75 74 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 out internal.**
339d0 73 74 61 74 65 20 6f 66 20 53 51 4c 69 74 65 20 state of SQLite
339e0 61 6e 64 20 74 6f 20 69 6e 6a 65 63 74 20 66 61 and to inject fa
339f0 75 6c 74 73 20 69 6e 74 6f 20 53 51 4c 69 74 65 ults into SQLite
33a00 20 66 6f 72 20 74 65 73 74 69 6e 67 0a 2a 2a 20 for testing.**
33a10 70 75 72 70 6f 73 65 73 2e 20 20 54 68 65 20 66 purposes. The f
33a20 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 61 irst parameter a
33a30 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 65 20 operation code
33a40 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a that determines.
33a50 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 2c 20 6d ** the number, m
33a60 65 61 6e 69 6e 67 2c 20 61 6e 64 20 6f 70 65 72 eaning, and oper
33a70 61 74 69 6f 6e 20 6f 66 20 61 6c 6c 20 73 75 62 ation of all sub
33a80 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65 sequent paramete
33a90 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 rs..**.** This i
33aa0 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 nterface is not
33ab0 66 6f 72 20 75 73 65 20 62 79 20 61 70 70 6c 69 for use by appli
33ac0 63 61 74 69 6f 6e 73 2e 20 20 49 74 20 65 78 69 cations. It exi
33ad0 73 74 73 20 73 6f 6c 65 6c 79 0a 2a 2a 20 66 6f sts solely.** fo
33ae0 72 20 76 65 72 69 66 79 69 6e 67 20 74 68 65 20 r verifying the
33af0 63 6f 72 72 65 63 74 20 6f 70 65 72 61 74 69 6f correct operatio
33b00 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 n of the SQLite
33b10 6c 69 62 72 61 72 79 2e 20 20 44 65 70 65 6e 64 library. Depend
33b20 69 6e 67 0a 2a 2a 20 6f 6e 20 68 6f 77 20 74 68 ing.** on how th
33b30 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 e SQLite library
33b40 20 69 73 20 63 6f 6d 70 69 6c 65 64 2c 20 74 68 is compiled, th
33b50 69 73 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 is interface mig
33b60 68 74 20 6e 6f 74 20 65 78 69 73 74 2e 0a 2a 2a ht not exist..**
33b70 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 .** The details
33b80 6f 66 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e of the operation
33b90 20 63 6f 64 65 73 2c 20 74 68 65 69 72 20 6d 65 codes, their me
33ba0 61 6e 69 6e 67 73 2c 20 74 68 65 20 70 61 72 61 anings, the para
33bb0 6d 65 74 65 72 73 0a 2a 2a 20 74 68 65 79 20 74 meters.** they t
33bc0 61 6b 65 2c 20 61 6e 64 20 77 68 61 74 20 74 68 ake, and what th
33bd0 65 79 20 64 6f 20 61 72 65 20 61 6c 6c 20 73 75 ey do are all su
33be0 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 bject to change
33bf0 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 2e 0a without notice..
33c00 2a 2a 20 55 6e 6c 69 6b 65 20 6d 6f 73 74 20 6f ** Unlike most o
33c10 66 20 74 68 65 20 53 51 4c 69 74 65 20 41 50 49 f the SQLite API
33c20 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 , this function
33c30 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 is not guarantee
33c40 64 20 74 6f 0a 2a 2a 20 6f 70 65 72 61 74 65 20 d to.** operate
33c50 63 6f 6e 73 69 73 74 65 6e 74 6c 79 20 66 72 6f consistently fro
33c60 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f m one release to
33c70 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 69 6e the next..*/.in
33c80 74 20 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 t sqlite3_test_c
33c90 6f 6e 74 72 6f 6c 28 69 6e 74 20 6f 70 2c 20 2e ontrol(int op, .
33ca0 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ..);../*.** CAPI
33cb0 33 52 45 46 3a 20 54 65 73 74 69 6e 67 20 49 6e 3REF: Testing In
33cc0 74 65 72 66 61 63 65 20 4f 70 65 72 61 74 69 6f terface Operatio
33cd0 6e 20 43 6f 64 65 73 20 7b 46 31 31 34 31 30 7d n Codes {F11410}
33ce0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e .**.** These con
33cf0 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 76 stants are the v
33d00 61 6c 69 64 20 6f 70 65 72 61 74 69 6f 6e 20 63 alid operation c
33d10 6f 64 65 20 70 61 72 61 6d 65 74 65 72 73 20 75 ode parameters u
33d20 73 65 64 0a 2a 2a 20 61 73 20 74 68 65 20 66 69 sed.** as the fi
33d30 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
33d40 5b 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f [sqlite3_test_co
33d50 6e 74 72 6f 6c 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 ntrol()]..**.**
33d60 54 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 These parameters
33d70 20 61 6e 64 20 74 68 65 69 72 20 6d 65 61 6e 73 and their means
33d80 69 6e 67 20 61 72 65 20 73 75 62 6a 65 63 74 20 ing are subject
33d90 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 77 69 74 to change.** wit
33da0 68 6f 75 74 20 6e 6f 74 69 63 65 2e 20 20 54 68 hout notice. Th
33db0 65 73 65 20 76 61 6c 75 65 73 20 61 72 65 20 66 ese values are f
33dc0 6f 72 20 74 65 73 74 69 6e 67 20 70 75 72 70 6f or testing purpo
33dd0 73 65 73 20 6f 6e 6c 79 2e 0a 2a 2a 20 41 70 70 ses only..** App
33de0 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 lications should
33df0 20 6e 6f 74 20 75 73 65 20 61 6e 79 20 6f 66 20 not use any of
33e00 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 these parameters
33e10 20 6f 72 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 or the.** [sqli
33e20 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c te3_test_control
33e30 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a ()] interface..*
33e40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
33e50 5f 54 45 53 54 43 54 52 4c 5f 46 41 55 4c 54 5f _TESTCTRL_FAULT_
33e60 43 4f 4e 46 49 47 20 20 20 20 20 20 20 20 20 20 CONFIG
33e70 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 1.#define SQL
33e80 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 46 41 55 ITE_TESTCTRL_FAU
33e90 4c 54 5f 46 41 49 4c 55 52 45 53 20 20 20 20 20 LT_FAILURES
33ea0 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 2.#define
33eb0 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f SQLITE_TESTCTRL_
33ec0 46 41 55 4c 54 5f 42 45 4e 49 47 4e 5f 46 41 49 FAULT_BENIGN_FAI
33ed0 4c 55 52 45 53 20 20 20 20 33 0a 23 64 65 66 69 LURES 3.#defi
33ee0 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 ne SQLITE_TESTCT
33ef0 52 4c 5f 46 41 55 4c 54 5f 50 45 4e 44 49 4e 47 RL_FAULT_PENDING
33f00 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 0a 0a 4...
33f10 0a 0a 0a 2f 2a 0a 2a 2a 20 55 6e 64 6f 20 74 68 .../*.** Undo th
33f20 65 20 68 61 63 6b 20 74 68 61 74 20 63 6f 6e 76 e hack that conv
33f30 65 72 74 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f erts floating po
33f40 69 6e 74 20 74 79 70 65 73 20 74 6f 20 69 6e 74 int types to int
33f50 65 67 65 72 20 66 6f 72 0a 2a 2a 20 62 75 69 6c eger for.** buil
33f60 64 73 20 6f 6e 20 70 72 6f 63 65 73 73 6f 72 73 ds on processors
33f70 20 77 69 74 68 6f 75 74 20 66 6c 6f 61 74 69 6e without floatin
33f80 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2e g point support.
33f90 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 .*/.#ifdef SQLIT
33fa0 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f E_OMIT_FLOATING_
33fb0 50 4f 49 4e 54 0a 23 20 75 6e 64 65 66 20 64 6f POINT.# undef do
33fc0 75 62 6c 65 0a 23 65 6e 64 69 66 0a 0a 23 69 66 uble.#endif..#if
33fd0 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a def __cplusplus.
33fe0 7d 20 20 2f 2a 20 45 6e 64 20 6f 66 20 74 68 65 } /* End of the
33ff0 20 27 65 78 74 65 72 6e 20 22 43 22 27 20 62 6c 'extern "C"' bl
34000 6f 63 6b 20 2a 2f 0a 23 65 6e 64 69 66 0a 23 65 ock */.#endif.#e
34010 6e 64 69 66 0a ndif.