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 33 31 32 20 32 30 30 38 2f in,v 1.312 2008/
05f0: 30 35 2f 31 32 20 31 32 3a 33 39 3a 35 36 20 64 05/12 12:39:56 d
0600: 72 68 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66 6e rh Exp $.*/.#ifn
0610: 64 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a def _SQLITE3_H_.
0620: 23 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 #define _SQLITE3
0630: 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 _H_.#include <st
0640: 64 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e darg.h> /* N
0650: 65 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65 eeded for the de
0660: 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c finition of va_l
0670: 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 ist */../*.** Ma
0680: 6b 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63 ke sure we can c
0690: 61 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66 all this stuff f
06a0: 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 rom C++..*/.#ifd
06b0: 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 ef __cplusplus.e
06c0: 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 xtern "C" {.#end
06d0: 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 if.../*.** Add t
06e0: 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 he ability to ov
06f0: 65 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a erride 'extern'.
0700: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 */.#ifndef SQLIT
0710: 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e E_EXTERN.# defin
0720: 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 e SQLITE_EXTERN
0730: 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 2f extern.#endif../
0740: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 74 *.** Make sure t
0750: 68 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 68 65 hese symbols whe
0760: 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 re not defined b
0770: 79 20 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 y some previous
0780: 68 65 61 64 65 72 0a 2a 2a 20 66 69 6c 65 2e 0a header.** file..
0790: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 */.#ifdef SQLITE
07a0: 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66 _VERSION.# undef
07b0: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a SQLITE_VERSION.
07c0: 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51 #endif.#ifdef SQ
07d0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d LITE_VERSION_NUM
07e0: 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 BER.# undef SQLI
07f0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 TE_VERSION_NUMBE
0800: 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 R.#endif../*.**
0810: 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c CAPI3REF: Compil
0820: 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 e-Time Library V
0830: 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 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 69 SQLite is a stri
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 39 22 0a 23 64 "3.5.9".#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 20 33 30 30 SION_NUMBER 300
0d80: 35 30 30 39 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 5009../*.** CAPI
0d90: 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 3REF: Run-Time L
0da0: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e ibrary Version N
0db0: 75 6d 62 65 72 73 20 7b 46 31 30 30 32 30 7d 0a umbers {F10020}.
0dc0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c ** KEYWORDS: sql
0dd0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 0a 2a 2a 0a ite3_version.**.
0de0: 2a 2a 20 54 68 65 73 65 20 66 65 61 74 75 72 65 ** These feature
0df0: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 s provide the sa
0e00: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 me information a
0e10: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 s the [SQLITE_VE
0e20: 52 53 49 4f 4e 5d 0a 2a 2a 20 61 6e 64 20 5b 53 RSION].** and [S
0e30: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 QLITE_VERSION_NU
0e40: 4d 42 45 52 5d 20 23 64 65 66 69 6e 65 73 20 69 MBER] #defines i
0e50: 6e 20 74 68 65 20 68 65 61 64 65 72 2c 20 62 75 n the header, bu
0e60: 74 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 t are associated
0e70: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6c 69 62 .** with the lib
0e80: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20 rary instead of
0e90: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e the header file.
0ea0: 20 20 43 61 75 74 69 6f 75 73 20 70 72 6f 67 72 Cautious progr
0eb0: 61 6d 6d 65 72 73 20 6d 69 67 68 74 0a 2a 2a 20 ammers might.**
0ec0: 69 6e 63 6c 75 64 65 20 61 20 63 68 65 63 6b 20 include a check
0ed0: 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 in their applica
0ee0: 74 69 6f 6e 20 74 6f 20 76 65 72 69 66 79 20 74 tion to verify t
0ef0: 68 61 74 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f hat .** sqlite3_
0f00: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 libversion_numbe
0f10: 72 28 29 20 61 6c 77 61 79 73 20 72 65 74 75 72 r() always retur
0f20: 6e 73 20 74 68 65 20 76 61 6c 75 65 20 0a 2a 2a ns the value .**
0f30: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e [SQLITE_VERSION
0f40: 5f 4e 55 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 _NUMBER]..**.**
0f50: 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 The sqlite3_libv
0f60: 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f ersion() functio
0f70: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 61 n returns the sa
0f80: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 me information a
0f90: 73 20 69 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 s is.** in the s
0fa0: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d qlite3_version[]
0fb0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 string constant
0fc0: 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 . The function
0fd0: 69 73 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 is provided.** f
0fe0: 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 or use in DLLs s
0ff0: 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 ince DLL users u
1000: 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 sually do not ha
1010: 76 65 20 64 69 72 65 63 74 20 61 63 63 65 73 73 ve direct access
1020: 20 74 6f 20 73 74 72 69 6e 67 0a 2a 2a 20 63 6f to string.** co
1030: 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 nstants within t
1040: 68 65 20 44 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e he DLL..**.** IN
1050: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
1060: 7b 46 31 30 30 32 31 7d 20 54 68 65 20 5b 73 71 {F10021} The [sq
1070: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e lite3_libversion
1080: 5f 6e 75 6d 62 65 72 28 29 5d 20 69 6e 74 65 72 _number()] inter
1090: 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 6e 20 face returns an
10a0: 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 integer.**
10b0: 20 20 20 20 65 71 75 61 6c 20 74 6f 20 5b 53 51 equal to [SQ
10c0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d LITE_VERSION_NUM
10d0: 42 45 52 5d 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 BER]. .**.** {F1
10e0: 30 30 32 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 0022} The [sqlit
10f0: 65 33 5f 76 65 72 73 69 6f 6e 5d 20 73 74 72 69 e3_version] stri
1100: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 ng constant cont
1110: 61 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 ains the text of
1120: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
1130: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e [SQLITE_VERSION
1140: 5d 20 73 74 72 69 6e 67 2e 20 0a 2a 2a 0a 2a 2a ] string. .**.**
1150: 20 7b 46 31 30 30 32 33 7d 20 54 68 65 20 5b 73 {F10023} The [s
1160: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
1170: 6e 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 n()] function re
1180: 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 turns.**
1190: 20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 a pointer to t
11a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 73 he [sqlite3_vers
11b0: 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 ion] string cons
11c0: 74 61 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f tant..*/.SQLITE_
11d0: 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 EXTERN const cha
11e0: 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f r sqlite3_versio
11f0: 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 n[];.const char
1200: 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 *sqlite3_libvers
1210: 69 6f 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 ion(void);.int s
1220: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
1230: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a n_number(void);.
1240: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1250: 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 Test To See If
1260: 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 The Library Is T
1270: 68 72 65 61 64 73 61 66 65 20 7b 46 31 30 31 30 hreadsafe {F1010
1280: 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 0}.**.** SQLite
1290: 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 can be compiled
12a0: 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 with or without
12b0: 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a mutexes. When.*
12c0: 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 54 48 52 * the SQLITE_THR
12d0: 45 41 44 53 41 46 45 20 43 20 70 72 65 70 72 6f EADSAFE C prepro
12e0: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 cessor macro is
12f0: 74 72 75 65 2c 20 6d 75 74 65 78 65 73 0a 2a 2a true, mutexes.**
1300: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 are enabled and
1310: 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 SQLite is threa
1320: 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68 61 dsafe. When tha
1330: 74 20 6d 61 63 72 6f 20 69 73 20 66 61 6c 73 65 t macro is false
1340: 2c 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 ,.** the mutexes
1350: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 are omitted. W
1360: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 ithout the mutex
1370: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 es, it is not sa
1380: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c fe.** to use SQL
1390: 69 74 65 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 ite from more th
13a0: 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a an one thread..*
13b0: 2a 0a 2a 2a 20 54 68 65 72 65 20 69 73 20 61 20 *.** There is a
13c0: 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f measurable perfo
13d0: 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 20 66 rmance penalty f
13e0: 6f 72 20 65 6e 61 62 6c 69 6e 67 20 6d 75 74 65 or enabling mute
13f0: 78 65 73 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 xes..** So if sp
1400: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 eed is of utmost
1410: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 importance, it
1420: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64 makes sense to d
1430: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 isable.** the mu
1440: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20 texes. But for
1450: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 maximum safety,
1460: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62 mutexes should b
1470: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68 e enabled..** Th
1480: 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 e default behavi
1490: 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65 or is for mutexe
14a0: 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e s to be enabled.
14b0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 .**.** This inte
14c0: 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 rface can be use
14d0: 64 20 62 79 20 61 20 70 72 6f 67 72 61 6d 20 74 d by a program t
14e0: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 o make sure that
14f0: 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 the.** version
1500: 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 of SQLite that i
1510: 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 t is linking aga
1520: 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 inst was compile
1530: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 d with.** the de
1540: 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 sired setting of
1550: 20 74 68 65 20 53 51 4c 49 54 45 5f 54 48 52 45 the SQLITE_THRE
1560: 41 44 53 41 46 45 20 6d 61 63 72 6f 2e 0a 2a 2a ADSAFE macro..**
1570: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
1580: 2a 2a 0a 2a 2a 20 7b 46 31 30 31 30 31 7d 20 54 **.** {F10101} T
1590: 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 he [sqlite3_thre
15a0: 61 64 73 61 66 65 28 29 5d 20 66 75 6e 63 74 69 adsafe()] functi
15b0: 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 7a 65 on returns nonze
15c0: 72 6f 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 ro if.**
15d0: 20 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d SQLite was com
15e0: 70 69 6c 65 64 20 77 69 74 68 20 69 74 73 20 6d piled with its m
15f0: 75 74 65 78 65 73 20 65 6e 61 62 6c 65 64 20 6f utexes enabled o
1600: 72 20 7a 65 72 6f 0a 2a 2a 20 20 20 20 20 20 20 r zero.**
1610: 20 20 20 69 66 20 53 51 4c 69 74 65 20 77 61 73 if SQLite was
1620: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d compiled with m
1630: 75 74 65 78 65 73 20 64 69 73 61 62 6c 65 64 2e utexes disabled.
1640: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
1650: 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29 threadsafe(void)
1660: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1670: 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e F: Database Conn
1680: 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 20 7b 46 ection Handle {F
1690: 31 32 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 12000}.** KEYWOR
16a0: 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f DS: {database co
16b0: 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 nnection} {datab
16c0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d ase connections}
16d0: 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e .**.** Each open
16e0: 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 SQLite database
16f0: 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 is represented
1700: 62 79 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e by pointer to an
1710: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 instance of the
1720: 0a 2a 2a 20 6f 70 61 71 75 65 20 73 74 72 75 63 .** opaque struc
1730: 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 ture named "sqli
1740: 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 te3". It is use
1750: 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 ful to think of
1760: 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f an sqlite3.** po
1770: 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 inter as an obje
1780: 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 ct. The [sqlite
1790: 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 3_open()], [sqli
17a0: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 te3_open16()], a
17b0: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f nd.** [sqlite3_o
17c0: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 pen_v2()] interf
17d0: 61 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e aces are its con
17e0: 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20 61 6e 64 structors.** and
17f0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 [sqlite3_close(
1800: 29 5d 20 69 73 20 69 74 73 20 64 65 73 74 72 75 )] is its destru
1810: 63 74 6f 72 2e 20 20 54 68 65 72 65 20 61 72 65 ctor. There are
1820: 20 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 many other inte
1830: 72 66 61 63 65 73 0a 2a 2a 20 28 73 75 63 68 20 rfaces.** (such
1840: 61 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 as [sqlite3_prep
1850: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 are_v2()], [sqli
1860: 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
1870: 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b ion()], and.** [
1880: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d sqlite3_busy_tim
1890: 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 eout()] to name
18a0: 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20 but three) that
18b0: 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 74 are methods on t
18c0: 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 2e 0a 2a his.** object..*
18d0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
18e0: 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 sqlite3 sqlite3
18f0: 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 ;.../*.** CAPI3R
1900: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 EF: 64-Bit Integ
1910: 65 72 20 54 79 70 65 73 20 7b 46 31 30 32 30 30 er Types {F10200
1920: 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 }.** KEYWORDS: s
1930: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 qlite_int64 sqli
1940: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 te_uint64.**.**
1950: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73 Because there is
1960: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f no cross-platfo
1970: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 rm way to specif
1980: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 y 64-bit integer
1990: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 types.** SQLite
19a0: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 includes typede
19b0: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 fs for 64-bit si
19c0: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 gned and unsigne
19d0: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a d integers..**.*
19e0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e * The sqlite3_in
19f0: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f t64 and sqlite3_
1a00: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 uint64 are the p
1a10: 72 65 66 65 72 72 65 64 20 74 79 70 65 0a 2a 2a referred type.**
1a20: 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 20 20 54 definitions. T
1a30: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 he sqlite_int64
1a40: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 and sqlite_uint6
1a50: 34 20 74 79 70 65 73 20 61 72 65 0a 2a 2a 20 73 4 types are.** s
1a60: 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 upported for bac
1a70: 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 kwards compatibi
1a80: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a lity only..**.**
1a90: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
1aa0: 2a 2a 20 7b 46 31 30 32 30 31 7d 20 54 68 65 20 ** {F10201} The
1ab0: 5b 73 71 6c 69 74 65 5f 69 6e 74 36 34 5d 20 61 [sqlite_int64] a
1ac0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 nd [sqlite3_int6
1ad0: 34 5d 20 74 79 70 65 73 20 73 70 65 63 69 66 79 4] types specify
1ae0: 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 36 a.** 6
1af0: 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 4-bit signed int
1b00: 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 eger..**.** {F10
1b10: 32 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 202} The [sqlite
1b20: 5f 75 69 6e 74 36 34 5d 20 61 6e 64 20 5b 73 71 _uint64] and [sq
1b30: 6c 69 74 65 33 5f 75 69 6e 74 36 34 5d 20 74 79 lite3_uint64] ty
1b40: 70 65 73 20 73 70 65 63 69 66 79 0a 2a 2a 20 20 pes specify.**
1b50: 20 20 20 20 20 20 20 20 61 20 36 34 2d 62 69 74 a 64-bit
1b60: 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 unsigned intege
1b70: 72 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c r..*/.#ifdef SQL
1b80: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 ITE_INT64_TYPE.
1b90: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f typedef SQLITE_
1ba0: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 INT64_TYPE sqlit
1bb0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 e_int64;. typed
1bc0: 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 ef unsigned SQLI
1bd0: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 TE_INT64_TYPE sq
1be0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c lite_uint64;.#el
1bf0: 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f if defined(_MSC_
1c00: 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 VER) || defined(
1c10: 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 __BORLANDC__).
1c20: 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 typedef __int64
1c30: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 sqlite_int64;.
1c40: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 typedef unsigned
1c50: 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f __int64 sqlite_
1c60: 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 uint64;.#else.
1c70: 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e typedef long lon
1c80: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 g int sqlite_int
1c90: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 64;. typedef un
1ca0: 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 signed long long
1cb0: 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 int sqlite_uint
1cc0: 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 64;.#endif.typed
1cd0: 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 ef sqlite_int64
1ce0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 sqlite3_int64;.t
1cf0: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69 ypedef sqlite_ui
1d00: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e nt64 sqlite3_uin
1d10: 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 t64;../*.** If c
1d20: 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 ompiling for a p
1d30: 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61 rocessor that la
1d40: 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 cks floating poi
1d50: 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 nt support,.** s
1d60: 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 65 ubstitute intege
1d70: 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 r for floating-p
1d80: 6f 69 6e 74 0a 2a 2f 0a 23 69 66 64 65 66 20 53 oint.*/.#ifdef S
1d90: 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 QLITE_OMIT_FLOAT
1da0: 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 ING_POINT.# defi
1db0: 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 ne double sqlite
1dc0: 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 3_int64.#endif..
1dd0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1de0: 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61 Closing A Databa
1df0: 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 46 se Connection {F
1e00: 31 32 30 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 12010}.**.** Thi
1e10: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 s routine is the
1e20: 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 destructor for
1e30: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 the [sqlite3] ob
1e40: 6a 65 63 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 41 70 ject. .**.** Ap
1e50: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c plications shoul
1e60: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c d [sqlite3_final
1e70: 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 ize | finalize]
1e80: 61 6c 6c 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 all.** [prepared
1e90: 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 61 6e 64 statements] and
1ea0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f .** [sqlite3_blo
1eb0: 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d b_close | close]
1ec0: 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 6c all [sqlite3_bl
1ed0: 6f 62 20 7c 20 42 4c 4f 42 73 5d 20 0a 2a 2a 20 ob | BLOBs] .**
1ee0: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
1ef0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 the [sqlite3] ob
1f00: 6a 65 63 74 20 70 72 69 6f 72 0a 2a 2a 20 74 6f ject prior.** to
1f10: 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 attempting to c
1f20: 6c 6f 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 lose the [sqlite
1f30: 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 3] object..**.**
1f40: 20 3c 74 6f 64 6f 3e 57 68 61 74 20 68 61 70 70 <todo>What happ
1f50: 65 6e 73 20 74 6f 20 70 65 6e 64 69 6e 67 20 74 ens to pending t
1f60: 72 61 6e 73 61 63 74 69 6f 6e 73 3f 20 20 41 72 ransactions? Ar
1f70: 65 20 74 68 65 79 0a 2a 2a 20 72 6f 6c 6c 65 64 e they.** rolled
1f80: 20 62 61 63 6b 2c 20 6f 72 20 61 62 61 6e 64 6f back, or abando
1f90: 6e 65 64 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a ned?</todo>.**.*
1fa0: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
1fb0: 0a 2a 2a 20 7b 46 31 32 30 31 31 7d 20 54 68 65 .** {F12011} The
1fc0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 [sqlite3_close(
1fd0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 65 73 )] interface des
1fe0: 74 72 6f 79 73 20 61 6e 20 5b 73 71 6c 69 74 65 troys an [sqlite
1ff0: 33 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 20 20 20 3] object.**
2000: 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 64 20 allocated
2010: 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 by a prior call
2020: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e to [sqlite3_open
2030: 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ()],.**
2040: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
2050: 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 ()], or [sqlite3
2060: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a _open_v2()]..**.
2070: 2a 2a 20 7b 46 31 32 30 31 32 7d 20 54 68 65 20 ** {F12012} The
2080: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 [sqlite3_close()
2090: 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 6c 65 61 ] function relea
20a0: 73 65 73 20 61 6c 6c 20 6d 65 6d 6f 72 79 20 75 ses all memory u
20b0: 73 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 sed by the.**
20c0: 20 20 20 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f connectio
20d0: 6e 20 61 6e 64 20 63 6c 6f 73 65 73 20 61 6c 6c n and closes all
20e0: 20 6f 70 65 6e 20 66 69 6c 65 73 2e 0a 2a 2a 0a open files..**.
20f0: 2a 2a 20 7b 46 31 32 30 31 33 7d 20 49 66 20 74 ** {F12013} If t
2100: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
2110: 65 63 74 69 6f 6e 20 63 6f 6e 74 61 69 6e 73 0a ection contains.
2120: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 ** [pre
2130: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
2140: 5d 20 74 68 61 74 20 68 61 76 65 20 6e 6f 74 20 ] that have not
2150: 62 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 been.**
2160: 20 66 69 6e 61 6c 69 7a 65 64 20 62 79 20 5b 73 finalized by [s
2170: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2180: 29 5d 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 )], then [sqlite
2190: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 20 20 3_close()].**
21a0: 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 5b returns [
21b0: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 SQLITE_BUSY] and
21c0: 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 6e leaves the conn
21d0: 65 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2a 0a ection open..**.
21e0: 2a 2a 20 7b 46 31 32 30 31 34 7d 20 47 69 76 69 ** {F12014} Givi
21f0: 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 ng sqlite3_close
2200: 28 29 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 () a NULL pointe
2210: 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 r is a harmless
2220: 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d no-op..**.** LIM
2230: 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 ITATIONS:.**.**
2240: 7b 55 31 32 30 31 35 7d 20 54 68 65 20 70 61 72 {U12015} The par
2250: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 ameter to [sqlit
2260: 65 33 5f 63 6c 6f 73 65 28 29 5d 20 6d 75 73 74 e3_close()] must
2270: 20 62 65 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d be an [sqlite3]
2280: 20 6f 62 6a 65 63 74 0a 2a 2a 20 20 20 20 20 20 object.**
2290: 20 20 20 20 70 6f 69 6e 74 65 72 20 70 72 65 76 pointer prev
22a0: 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 iously obtained
22b0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 from [sqlite3_op
22c0: 65 6e 28 29 5d 20 6f 72 20 74 68 65 20 0a 2a 2a en()] or the .**
22d0: 20 20 20 20 20 20 20 20 20 20 65 71 75 69 76 61 equiva
22e0: 6c 65 6e 74 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a lent, or NULL..*
22f0: 2a 0a 2a 2a 20 7b 55 31 32 30 31 36 7d 20 54 68 *.** {U12016} Th
2300: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b e parameter to [
2310: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d sqlite3_close()]
2320: 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 must not have b
2330: 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a een previously.*
2340: 2a 20 20 20 20 20 20 20 20 20 20 63 6c 6f 73 65 * close
2350: 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 d..*/.int sqlite
2360: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 3_close(sqlite3
2370: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 *);../*.** The t
2380: 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 ype for a callba
2390: 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 ck function..**
23a0: 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 This is legacy a
23b0: 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 nd deprecated.
23c0: 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 It is included f
23d0: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a or historical.**
23e0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 compatibility a
23f0: 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 nd is not docume
2400: 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 nted..*/.typedef
2410: 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 int (*sqlite3_c
2420: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 allback)(void*,i
2430: 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a nt,char**, char*
2440: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
2450: 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 REF: One-Step Qu
2460: 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e ery Execution In
2470: 74 65 72 66 61 63 65 20 7b 46 31 32 31 30 30 7d terface {F12100}
2480: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
2490: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 e3_exec() interf
24a0: 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 ace is a conveni
24b0: 65 6e 74 20 77 61 79 20 6f 66 20 72 75 6e 6e 69 ent way of runni
24c0: 6e 67 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 ng.** one or mor
24d0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 e SQL statements
24e0: 20 77 69 74 68 6f 75 74 20 61 20 6c 6f 74 20 6f without a lot o
24f0: 66 20 43 20 63 6f 64 65 2e 20 20 54 68 65 0a 2a f C code. The.*
2500: 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 * SQL statements
2510: 20 61 72 65 20 70 61 73 73 65 64 20 69 6e 20 61 are passed in a
2520: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 s the second par
2530: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c ameter to.** sql
2540: 69 74 65 33 5f 65 78 65 63 28 29 2e 20 20 54 68 ite3_exec(). Th
2550: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 e statements are
2560: 20 65 76 61 6c 75 61 74 65 64 20 6f 6e 65 20 62 evaluated one b
2570: 79 20 6f 6e 65 0a 2a 2a 20 75 6e 74 69 6c 20 65 y one.** until e
2580: 69 74 68 65 72 20 61 6e 20 65 72 72 6f 72 20 6f ither an error o
2590: 72 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20 69 r an interrupt i
25a0: 73 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6f 72 s encountered or
25b0: 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 79 20 61 .** until they a
25c0: 72 65 20 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 re all done. Th
25d0: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 e 3rd parameter
25e0: 69 73 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 0a 2a is an optional.*
25f0: 2a 20 63 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 * callback that
2600: 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 is invoked once
2610: 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 for each row of
2620: 61 6e 79 20 71 75 65 72 79 20 72 65 73 75 6c 74 any query result
2630: 73 0a 2a 2a 20 70 72 6f 64 75 63 65 64 20 62 79 s.** produced by
2640: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
2650: 6e 74 73 2e 20 20 54 68 65 20 35 74 68 20 70 61 nts. The 5th pa
2660: 72 61 6d 65 74 65 72 20 74 65 6c 6c 73 20 77 68 rameter tells wh
2670: 65 72 65 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20 ere.** to write
2680: 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 any error messag
2690: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 es..**.** The sq
26a0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 lite3_exec() int
26b0: 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d erface is implem
26c0: 65 6e 74 65 64 20 69 6e 20 74 65 72 6d 73 20 6f ented in terms o
26d0: 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 f.** [sqlite3_pr
26e0: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 epare_v2()], [sq
26f0: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 lite3_step()], a
2700: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 nd [sqlite3_fina
2710: 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 lize()]..** The
2720: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 72 sqlite3_exec() r
2730: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 68 outine does noth
2740: 69 6e 67 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 ing that cannot
2750: 62 65 20 64 6f 6e 65 0a 2a 2a 20 62 79 20 5b 73 be done.** by [s
2760: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
2770: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 2()], [sqlite3_s
2780: 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c tep()], and [sql
2790: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
27a0: 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 ..** The sqlite3
27b0: 5f 65 78 65 63 28 29 20 69 73 20 6a 75 73 74 20 _exec() is just
27c0: 61 20 63 6f 6e 76 65 6e 69 65 6e 74 20 77 72 61 a convenient wra
27d0: 70 70 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 pper..**.** INVA
27e0: 52 49 41 4e 54 53 3a 0a 2a 2a 20 0a 2a 2a 20 7b RIANTS:.** .** {
27f0: 46 31 32 31 30 31 7d 20 54 68 65 20 5b 73 71 6c F12101} The [sql
2800: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 6e 74 ite3_exec()] int
2810: 65 72 66 61 63 65 20 65 76 61 6c 75 61 74 65 73 erface evaluates
2820: 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 zero or more UT
2830: 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 F-8.**
2840: 65 6e 63 6f 64 65 64 2c 20 73 65 6d 69 63 6f 6c encoded, semicol
2850: 6f 6e 2d 73 65 70 61 72 61 74 65 64 2c 20 53 51 on-separated, SQ
2860: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 L statements in
2870: 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
2880: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
2890: 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e string of its 2n
28a0: 64 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 d parameter with
28b0: 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 in the.**
28c0: 20 20 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 context of th
28d0: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 e [sqlite3] obje
28e0: 63 74 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 ct given in the
28f0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 1st parameter..*
2900: 2a 0a 2a 2a 20 7b 46 31 32 31 30 34 7d 20 54 68 *.** {F12104} Th
2910: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f e return value o
2920: 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 f [sqlite3_exec(
2930: 29 5d 20 69 73 20 53 51 4c 49 54 45 5f 4f 4b 20 )] is SQLITE_OK
2940: 69 66 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 if all.**
2950: 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 SQL statement
2960: 73 20 72 75 6e 20 73 75 63 63 65 73 73 66 75 6c s run successful
2970: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 30 ly..**.** {F1210
2980: 35 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 5} The return va
2990: 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f lue of [sqlite3_
29a0: 65 78 65 63 28 29 5d 20 69 73 20 61 6e 20 61 70 exec()] is an ap
29b0: 70 72 6f 70 72 69 61 74 65 20 0a 2a 2a 20 20 20 propriate .**
29c0: 20 20 20 20 20 20 20 6e 6f 6e 2d 7a 65 72 6f 20 non-zero
29d0: 65 72 72 6f 72 20 63 6f 64 65 20 69 66 20 61 6e error code if an
29e0: 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 y SQL statement
29f0: 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 fails..**.** {F1
2a00: 32 31 30 37 7d 20 49 66 20 6f 6e 65 20 6f 72 20 2107} If one or
2a10: 6d 6f 72 65 20 6f 66 20 74 68 65 20 53 51 4c 20 more of the SQL
2a20: 73 74 61 74 65 6d 65 6e 74 73 20 68 61 6e 64 65 statements hande
2a30: 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 d to [sqlite3_ex
2a40: 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 ec()].**
2a50: 20 20 72 65 74 75 72 6e 20 72 65 73 75 6c 74 73 return results
2a60: 20 61 6e 64 20 74 68 65 20 33 72 64 20 70 61 72 and the 3rd par
2a70: 61 6d 65 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 ameter is not NU
2a80: 4c 4c 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 LL, then.**
2a90: 20 20 20 20 20 74 68 65 20 63 61 6c 6c 62 61 63 the callbac
2aa0: 6b 20 66 75 6e 63 74 69 6f 6e 20 73 70 65 63 69 k function speci
2ab0: 66 69 65 64 20 62 79 20 74 68 65 20 33 72 64 20 fied by the 3rd
2ac0: 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 parameter is.**
2ad0: 20 20 20 20 20 20 20 20 20 69 6e 76 6f 6b 65 64 invoked
2ae0: 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 72 once for each r
2af0: 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 0a 2a 2a ow of result..**
2b00: 0a 2a 2a 20 7b 46 31 32 31 31 30 7d 20 49 66 20 .** {F12110} If
2b10: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 the callback ret
2b20: 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 urns a non-zero
2b30: 76 61 6c 75 65 20 74 68 65 6e 20 5b 73 71 6c 69 value then [sqli
2b40: 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 te3_exec()].**
2b50: 20 20 20 20 20 20 20 20 77 69 6c 6c 20 61 62 6f will abo
2b60: 72 74 65 64 20 74 68 65 20 53 51 4c 20 73 74 61 rted the SQL sta
2b70: 74 65 6d 65 6e 74 20 69 74 20 69 73 20 63 75 72 tement it is cur
2b80: 72 65 6e 74 6c 79 20 65 76 61 6c 75 61 74 69 6e rently evaluatin
2b90: 67 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 g,.** s
2ba0: 6b 69 70 20 61 6c 6c 20 73 75 62 73 65 71 75 65 kip all subseque
2bb0: 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 nt SQL statement
2bc0: 73 2c 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 s, and return [S
2bd0: 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a QLITE_ABORT]..**
2be0: 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e <todo>
2bf0: 57 68 61 74 20 68 61 70 70 65 6e 73 20 74 6f 20 What happens to
2c00: 2a 65 72 72 6d 73 67 20 68 65 72 65 3f 20 20 44 *errmsg here? D
2c10: 6f 65 73 20 74 68 65 20 72 65 73 75 6c 74 20 63 oes the result c
2c20: 6f 64 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 ode for.**
2c30: 20 20 20 20 73 71 6c 69 74 65 33 5f 65 72 72 63 sqlite3_errc
2c40: 6f 64 65 28 29 20 67 65 74 20 73 65 74 3f 3c 2f ode() get set?</
2c50: 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 todo>.**.** {F12
2c60: 31 31 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 113} The [sqlite
2c70: 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 3_exec()] routin
2c80: 65 20 77 69 6c 6c 20 70 61 73 73 20 69 74 73 20 e will pass its
2c90: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 4th parameter th
2ca0: 72 6f 75 67 68 0a 2a 2a 20 20 20 20 20 20 20 20 rough.**
2cb0: 20 20 61 73 20 74 68 65 20 31 73 74 20 70 61 72 as the 1st par
2cc0: 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 63 61 ameter of the ca
2cd0: 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 llback..**.** {F
2ce0: 31 32 31 31 36 7d 20 54 68 65 20 5b 73 71 6c 69 12116} The [sqli
2cf0: 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 te3_exec()] rout
2d00: 69 6e 65 20 73 65 74 73 20 74 68 65 20 32 6e 64 ine sets the 2nd
2d10: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 69 74 parameter of it
2d20: 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 s.** ca
2d30: 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 74 68 65 llback to be the
2d40: 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
2d50: 6e 73 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e ns in the curren
2d60: 74 20 72 6f 77 20 6f 66 0a 2a 2a 20 20 20 20 20 t row of.**
2d70: 20 20 20 20 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a result..**.
2d80: 2a 2a 20 7b 46 31 32 31 31 39 7d 20 54 68 65 20 ** {F12119} The
2d90: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
2da0: 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 74 68 routine sets th
2db0: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 e 3rd parameter
2dc0: 6f 66 20 69 74 73 20 0a 2a 2a 20 20 20 20 20 20 of its .**
2dd0: 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 callback to
2de0: 62 65 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 be an array of p
2df0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e ointers to strin
2e00: 67 73 20 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a gs holding the.*
2e10: 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 * value
2e20: 73 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d s for each colum
2e30: 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 n in the current
2e40: 20 72 65 73 75 6c 74 20 73 65 74 20 72 6f 77 20 result set row
2e50: 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f as.** o
2e60: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
2e70: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
2e80: 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 t()]..**.** {F12
2e90: 31 32 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 122} The [sqlite
2ea0: 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 3_exec()] routin
2eb0: 65 20 73 65 74 73 20 74 68 65 20 34 74 68 20 70 e sets the 4th p
2ec0: 61 72 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a arameter of its.
2ed0: 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c ** call
2ee0: 62 61 63 6b 20 74 6f 20 62 65 20 61 6e 20 61 72 back to be an ar
2ef0: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 ray of pointers
2f00: 74 6f 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 to strings holdi
2f10: 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 ng the.**
2f20: 20 20 20 6e 61 6d 65 73 20 6f 66 20 72 65 73 75 names of resu
2f30: 6c 74 20 63 6f 6c 75 6d 6e 73 20 61 73 20 6f 62 lt columns as ob
2f40: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c tained from [sql
2f50: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
2f60: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 ()]..**.** {F121
2f70: 32 35 7d 20 49 66 20 74 68 65 20 33 72 64 20 70 25} If the 3rd p
2f80: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c arameter to [sql
2f90: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20 ite3_exec()] is
2fa0: 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 NULL then.**
2fb0: 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 [sqlite3_e
2fc0: 78 65 63 28 29 5d 20 6e 65 76 65 72 20 69 6e 76 xec()] never inv
2fd0: 6f 6b 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 2e okes a callback.
2fe0: 20 20 41 6c 6c 20 71 75 65 72 79 0a 2a 2a 20 20 All query.**
2ff0: 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 73 20 results
3000: 61 72 65 20 73 69 6c 65 6e 74 6c 79 20 64 69 73 are silently dis
3010: 63 61 72 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 carded..**.** {F
3020: 31 32 31 32 38 7d 20 49 66 20 61 6e 20 65 72 72 12128} If an err
3030: 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 or occurs while
3040: 70 61 72 73 69 6e 67 20 6f 72 20 65 76 61 6c 75 parsing or evalu
3050: 61 74 69 6e 67 20 61 6e 79 20 6f 66 20 74 68 65 ating any of the
3060: 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 SQL.**
3070: 20 73 74 61 74 65 6d 65 6e 74 73 20 68 61 6e 64 statements hand
3080: 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 ed to [sqlite3_e
3090: 78 65 63 28 29 5d 20 74 68 65 6e 20 5b 73 71 6c xec()] then [sql
30a0: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 77 69 6c ite3_exec()] wil
30b0: 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 l.** re
30c0: 74 75 72 6e 20 61 6e 20 5b 65 72 72 6f 72 20 63 turn an [error c
30d0: 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 ode] other than
30e0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a [SQLITE_OK]..**.
30f0: 2a 2a 20 7b 46 31 32 31 33 31 7d 20 49 66 20 61 ** {F12131} If a
3100: 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 n error occurs w
3110: 68 69 6c 65 20 70 61 72 73 69 6e 67 20 6f 72 20 hile parsing or
3120: 65 76 61 6c 75 61 74 69 6e 67 20 61 6e 79 20 6f evaluating any o
3130: 66 20 74 68 65 20 53 51 4c 0a 2a 2a 20 20 20 20 f the SQL.**
3140: 20 20 20 20 20 20 68 61 6e 64 65 64 20 74 6f 20 handed to
3150: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
3160: 20 61 6e 64 20 69 66 20 74 68 65 20 35 74 68 20 and if the 5th
3170: 70 61 72 61 6d 65 74 65 72 20 28 65 72 72 6d 73 parameter (errms
3180: 67 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 g).** t
3190: 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 o [sqlite3_exec(
31a0: 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 )] is not NULL,
31b0: 74 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6d 65 then an error me
31c0: 73 73 61 67 65 20 69 73 0a 2a 2a 20 20 20 20 20 ssage is.**
31d0: 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 64 20 75 allocated u
31e0: 73 69 6e 67 20 74 68 65 20 65 71 75 69 76 61 6c sing the equival
31f0: 65 6e 74 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f ent of [sqlite3_
3200: 6d 70 72 69 6e 74 66 28 29 5d 20 61 6e 64 0a 2a mprintf()] and.*
3210: 2a 20 20 20 20 20 20 20 20 20 20 2a 65 72 72 6d * *errm
3220: 73 67 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f sg is made to po
3230: 69 6e 74 20 74 6f 20 74 68 61 74 20 6d 65 73 73 int to that mess
3240: 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 age..**.** {F121
3250: 33 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 34} The [sqlite3
3260: 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 _exec()] routine
3270: 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 does not change
3280: 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a the value of.**
3290: 20 20 20 20 20 20 20 20 20 20 2a 65 72 72 6d 73 *errms
32a0: 67 20 69 66 20 65 72 72 6d 73 67 20 69 73 20 4e g if errmsg is N
32b0: 55 4c 4c 20 6f 72 20 69 66 20 74 68 65 72 65 20 ULL or if there
32c0: 61 72 65 20 6e 6f 20 65 72 72 6f 72 73 2e 0a 2a are no errors..*
32d0: 2a 0a 2a 2a 20 7b 46 31 32 31 33 37 7d 20 54 68 *.** {F12137} Th
32e0: 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 e [sqlite3_exec(
32f0: 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 )] function sets
3300: 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 the error code
3310: 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 and message.**
3320: 20 20 20 20 20 20 20 20 61 63 63 65 73 73 69 62 accessib
3330: 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f le via [sqlite3_
3340: 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c errcode()], [sql
3350: 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 ite3_errmsg()],
3360: 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 and.**
3370: 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 [sqlite3_errmsg1
3380: 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 6()]..**.** LIMI
3390: 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b TATIONS:.**.** {
33a0: 55 31 32 31 34 31 7d 20 54 68 65 20 66 69 72 73 U12141} The firs
33b0: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b t parameter to [
33c0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 sqlite3_exec()]
33d0: 6d 75 73 74 20 62 65 20 61 6e 20 76 61 6c 69 64 must be an valid
33e0: 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20 20 20 20 and open.**
33f0: 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 [database
3400: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a connection]..**.
3410: 2a 2a 20 7b 55 31 32 31 34 32 7d 20 54 68 65 20 ** {U12142} The
3420: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3430: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 ion must not be
3440: 63 6c 6f 73 65 64 20 77 68 69 6c 65 0a 2a 2a 20 closed while.**
3450: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
3460: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 3_exec()] is run
3470: 6e 69 6e 67 2e 0a 2a 2a 20 0a 2a 2a 20 7b 55 31 ning..** .** {U1
3480: 32 31 34 33 7d 20 54 68 65 20 63 61 6c 6c 69 6e 2143} The callin
3490: 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 68 g function is sh
34a0: 6f 75 6c 64 20 75 73 65 20 5b 73 71 6c 69 74 65 ould use [sqlite
34b0: 33 5f 66 72 65 65 28 29 5d 20 74 6f 20 66 72 65 3_free()] to fre
34c0: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 e.** th
34d0: 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 2a 65 e memory that *e
34e0: 72 72 6d 73 67 20 69 73 20 6c 65 66 74 20 70 6f rrmsg is left po
34f0: 69 6e 74 69 6e 67 20 61 74 20 6f 6e 63 65 20 74 inting at once t
3500: 68 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20 he error.**
3510: 20 20 20 20 20 6d 65 73 73 61 67 65 20 69 73 20 message is
3520: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 no longer needed
3530: 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34 35 7d ..**.** {U12145}
3540: 20 54 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 The SQL stateme
3550: 6e 74 20 74 65 78 74 20 69 6e 20 74 68 65 20 32 nt text in the 2
3560: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 nd parameter to
3570: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
3580: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 75 73 .** mus
3590: 74 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 t remain unchang
35a0: 65 64 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 ed while [sqlite
35b0: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 3_exec()] is run
35c0: 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c ning..*/.int sql
35d0: 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c ite3_exec(. sql
35e0: 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 ite3*,
35f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3600: 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 /* An op
3610: 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 en database */.
3620: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c const char *sql
3630: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
3640: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 /* S
3650: 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 74 65 QL to be evalute
3660: 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c d */. int (*cal
3670: 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 lback)(void*,int
3680: 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c ,char**,char**),
3690: 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 /* Callback fu
36a0: 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 nction */. void
36b0: 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 *,
36c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
36d0: 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 /* 1st ar
36e0: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 gument to callba
36f0: 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 ck */. char **e
3700: 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 rrmsg
3710: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3720: 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 /* Error msg
3730: 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a written here */.
3740: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
3750: 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 EF: Result Codes
3760: 20 7b 46 31 30 32 31 30 7d 0a 2a 2a 20 4b 45 59 {F10210}.** KEY
3770: 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b WORDS: SQLITE_OK
3780: 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 {error code} {e
3790: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a rror codes}.**.*
37a0: 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 * Many SQLite fu
37b0: 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 nctions return a
37c0: 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 n integer result
37d0: 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 code from the s
37e0: 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 et shown.** here
37f0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 in order to ind
3800: 69 63 61 74 65 73 20 73 75 63 63 65 73 73 20 6f icates success o
3810: 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a r failure..**.**
3820: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 See also: [SQLI
3830: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 TE_IOERR_READ |
3840: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
3850: 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e codes].*/.#defin
3860: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 e SQLITE_OK
3870: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 0 /* Suc
3880: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a cessful result *
3890: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f /./* beginning-o
38a0: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f f-error-codes */
38b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
38c0: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 ERROR 1
38d0: 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 /* SQL error or
38e0: 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 missing databas
38f0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
3900: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 ITE_INTERNAL
3910: 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 2 /* Internal
3920: 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 logic error in
3930: 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e SQLite */.#defin
3940: 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 e SQLITE_PERM
3950: 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 3 /* Acc
3960: 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 ess permission d
3970: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 enied */.#define
3980: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 SQLITE_ABORT
3990: 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 4 /* Call
39a0: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 back routine req
39b0: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 uested an abort
39c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
39d0: 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 E_BUSY 5
39e0: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 /* The databa
39f0: 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 se file is locke
3a00: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
3a10: 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 ITE_LOCKED
3a20: 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 6 /* A table
3a30: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 in the database
3a40: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 is locked */.#de
3a50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 fine SQLITE_NOME
3a60: 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 M 7 /*
3a70: 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 A malloc() faile
3a80: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
3a90: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 ITE_READONLY
3aa0: 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 8 /* Attempt
3ab0: 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f to write a reado
3ac0: 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a nly database */.
3ad0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
3ae0: 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 NTERRUPT 9
3af0: 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 /* Operation ter
3b00: 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 minated by sqlit
3b10: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f e3_interrupt()*/
3b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3b30: 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 IOERR 10
3b40: 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 /* Some kind of
3b50: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 disk I/O error
3b60: 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 occurred */.#def
3b70: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 ine SQLITE_CORRU
3b80: 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 PT 11 /* T
3b90: 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b he database disk
3ba0: 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 image is malfor
3bb0: 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 med */.#define S
3bc0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 QLITE_NOTFOUND
3bd0: 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53 12 /* NOT US
3be0: 45 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 65 63 ED. Table or rec
3bf0: 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f ord not found */
3c00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3c10: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 FULL 13
3c20: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 /* Insertion fa
3c30: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74 iled because dat
3c40: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f abase is full */
3c50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3c60: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 CANTOPEN 14
3c70: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 /* Unable to op
3c80: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
3c90: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 file */.#define
3ca0: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 SQLITE_PROTOCOL
3cb0: 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20 55 15 /* NOT U
3cc0: 53 45 44 2e 20 44 61 74 61 62 61 73 65 20 6c 6f SED. Database lo
3cd0: 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f ck protocol erro
3ce0: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c r */.#define SQL
3cf0: 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 ITE_EMPTY
3d00: 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 16 /* Database
3d10: 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 is empty */.#de
3d20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 fine SQLITE_SCHE
3d30: 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 MA 17 /*
3d40: 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 The database sch
3d50: 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 ema changed */.#
3d60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f define SQLITE_TO
3d70: 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20 2f OBIG 18 /
3d80: 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 * String or BLOB
3d90: 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 exceeds size li
3da0: 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 mit */.#define S
3db0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
3dc0: 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 19 /* Abort
3dd0: 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e due to constrain
3de0: 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 t violation */.#
3df0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 define SQLITE_MI
3e00: 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 2f SMATCH 20 /
3e10: 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d * Data type mism
3e20: 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 atch */.#define
3e30: 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 SQLITE_MISUSE
3e40: 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 21 /* Libra
3e50: 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 ry used incorrec
3e60: 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 tly */.#define S
3e70: 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 QLITE_NOLFS
3e80: 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 22 /* Uses O
3e90: 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 S features not s
3ea0: 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 upported on host
3eb0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
3ec0: 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 TE_AUTH 2
3ed0: 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 3 /* Authoriza
3ee0: 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 tion denied */.#
3ef0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f define SQLITE_FO
3f00: 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 2f RMAT 24 /
3f10: 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 * Auxiliary data
3f20: 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f base format erro
3f30: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c r */.#define SQL
3f40: 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 ITE_RANGE
3f50: 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 25 /* 2nd para
3f60: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
3f70: 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e _bind out of ran
3f80: 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ge */.#define SQ
3f90: 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 LITE_NOTADB
3fa0: 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 26 /* File op
3fb0: 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 ened that is not
3fc0: 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 a database file
3fd0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
3fe0: 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 TE_ROW 1
3ff0: 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 00 /* sqlite3_s
4000: 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 tep() has anothe
4010: 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 r row ready */.#
4020: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f define SQLITE_DO
4030: 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f NE 101 /
4040: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 * sqlite3_step()
4050: 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 has finished ex
4060: 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e ecuting */./* en
4070: 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 d-of-error-codes
4080: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
4090: 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 REF: Extended Re
40a0: 73 75 6c 74 20 43 6f 64 65 73 20 7b 46 31 30 32 sult Codes {F102
40b0: 32 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20}.** KEYWORDS:
40c0: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 {extended error
40d0: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 code} {extended
40e0: 20 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a error codes}.**
40f0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 KEYWORDS: {exte
4100: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
4110: 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 s}.**.** In its
4120: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 default configur
4130: 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 ation, SQLite AP
4140: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 I routines retur
4150: 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65 n one of 26 inte
4160: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f ger.** [SQLITE_O
4170: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 K | result codes
4180: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 ]. However, exp
4190: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 erience has show
41a0: 6e 20 74 68 61 74 0a 2a 2a 20 6d 61 6e 79 20 6f n that.** many o
41b0: 66 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 f these result c
41c0: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 75 odes are too cou
41d0: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 rse-grained. Th
41e0: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 ey do not provid
41f0: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 e as.** much inf
4200: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 ormation about p
4210: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 roblems as progr
4220: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b ammers might lik
4230: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 e. In an effort
4240: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 to.** address t
4250: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 his, newer versi
4260: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 ons of SQLite (v
4270: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 ersion 3.3.8 and
4280: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a later) include.
4290: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 ** support for a
42a0: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 dditional result
42b0: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 codes that prov
42c0: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 ide more detaile
42d0: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a d information.**
42e0: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 about errors. T
42f0: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 he extended resu
4300: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61 lt codes are ena
4310: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 bled or disabled
4320: 0a 2a 2a 20 66 6f 72 20 65 61 63 68 20 64 61 74 .** for each dat
4330: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
4340: 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 using the [sqli
4350: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 te3_extended_res
4360: 75 6c 74 5f 63 6f 64 65 73 28 29 5d 0a 2a 2a 20 ult_codes()].**
4370: 41 50 49 2e 0a 2a 2a 20 0a 2a 2a 20 53 6f 6d 65 API..** .** Some
4380: 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c of the availabl
4390: 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c e extended resul
43a0: 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 t codes are list
43b0: 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 ed here..** One
43c0: 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20 6e may expect the n
43d0: 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65 umber of extende
43e0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77 d result codes w
43f0: 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a ill be expand.**
4400: 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 over time. Sof
4410: 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73 20 tware that uses
4420: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
4430: 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70 codes should exp
4440: 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 ect.** to see ne
4450: 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69 w result codes i
4460: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
4470: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a s of SQLite..**.
4480: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b ** The SQLITE_OK
4490: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c result code wil
44a0: 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e l never be exten
44b0: 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c ded. It will al
44c0: 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 ways.** be exact
44d0: 6c 79 20 7a 65 72 6f 2e 0a 2a 2a 20 0a 2a 2a 20 ly zero..** .**
44e0: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
44f0: 2a 20 7b 46 31 30 32 32 33 7d 20 54 68 65 20 73 * {F10223} The s
4500: 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 66 6f 72 ymbolic name for
4510: 20 61 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 an extended res
4520: 75 6c 74 20 63 6f 64 65 20 61 6c 77 61 79 73 20 ult code always
4530: 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 contains.**
4540: 20 20 20 20 20 61 20 72 65 6c 61 74 65 64 20 70 a related p
4550: 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f rimary result co
4560: 64 65 20 61 73 20 61 20 70 72 65 66 69 78 2e 0a de as a prefix..
4570: 2a 2a 0a 2a 2a 20 7b 46 31 30 32 32 34 7d 20 50 **.** {F10224} P
4580: 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f rimary result co
4590: 64 65 20 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e de names contain
45a0: 20 61 20 73 69 6e 67 6c 65 20 22 5f 22 20 63 68 a single "_" ch
45b0: 61 72 61 63 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b aracter..**.** {
45c0: 46 31 30 32 32 35 7d 20 45 78 74 65 6e 64 65 64 F10225} Extended
45d0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6e 61 6d result code nam
45e0: 65 73 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20 6f es contain two o
45f0: 72 20 6d 6f 72 65 20 22 5f 22 20 63 68 61 72 61 r more "_" chara
4600: 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 cters..**.** {F1
4610: 30 32 32 36 7d 20 54 68 65 20 6e 75 6d 65 72 69 0226} The numeri
4620: 63 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 65 78 c value of an ex
4630: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
4640: 64 65 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a de contains the.
4650: 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 65 ** nume
4660: 72 69 63 20 76 61 6c 75 65 20 6f 66 20 69 74 73 ric value of its
4670: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 70 corresponding p
4680: 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f rimary result co
4690: 64 65 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 de in.**
46a0: 20 20 69 74 73 20 6c 65 61 73 74 20 73 69 67 6e its least sign
46b0: 69 66 69 63 61 6e 74 20 38 20 62 69 74 73 2e 0a ificant 8 bits..
46c0: 2a 2f 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 52 45 41 44 20 20 20 20 E_IOERR_READ
46e0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
46f0: 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 ERR | (1<<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 53 48 4f 52 54 5f 52 45 41 44 20 20 20 RR_SHORT_READ
4720: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
4730: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (2<<8)).#define
4740: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 SQLITE_IOERR_WR
4750: 49 54 45 20 20 20 20 20 20 20 20 20 28 53 51 4c ITE (SQL
4760: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c ITE_IOERR | (3<<
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 46 53 59 4e 43 20 20 TE_IOERR_FSYNC
4790: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
47a0: 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 OERR | (4<<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 44 49 52 5f 46 53 59 4e 43 20 20 20 ERR_DIR_FSYNC
47d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
47e0: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (5<<8)).#defin
47f0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 e SQLITE_IOERR_T
4800: 52 55 4e 43 41 54 45 20 20 20 20 20 20 28 53 51 RUNCATE (SQ
4810: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c LITE_IOERR | (6<
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 46 53 54 41 54 20 ITE_IOERR_FSTAT
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 37 3c 3c 38 29 29 0a IOERR | (7<<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 55 4e 4c 4f 43 4b 20 20 20 20 20 OERR_UNLOCK
4880: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
4890: 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 | (8<<8)).#defi
48a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
48b0: 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 28 53 RDLOCK (S
48c0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 QLITE_IOERR | (9
48d0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
48e0: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 LITE_IOERR_DELET
48f0: 45 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 E (SQLITE
4900: 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 _IOERR | (10<<8)
4910: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
4920: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 _IOERR_BLOCKED
4930: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
4940: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 RR | (11<<8)).#d
4950: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
4960: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 RR_NOMEM
4970: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
4980: 20 28 31 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a (12<<8))../*.**
4990: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 CAPI3REF: Flags
49a0: 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f For File Open O
49b0: 70 65 72 61 74 69 6f 6e 73 20 7b 46 31 30 32 33 perations {F1023
49c0: 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 0}.**.** These b
49d0: 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e it values are in
49e0: 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 tended for use i
49f0: 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 n the.** 3rd par
4a00: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 ameter to the [s
4a10: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
4a20: 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a ] interface and.
4a30: 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 ** in the 4th pa
4a40: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 78 rameter to the x
4a50: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 Open method of t
4a60: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 he.** [sqlite3_v
4a70: 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 fs] object..*/.#
4a80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
4a90: 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 EN_READONLY
4aa0: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 0x00000001.#
4ab0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
4ac0: 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 EN_READWRITE
4ad0: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 0x00000002.#
4ae0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
4af0: 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 EN_CREATE
4b00: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 0x00000004.#
4b10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
4b20: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 EN_DELETEONCLOSE
4b30: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 0x00000008.#
4b40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
4b50: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 EN_EXCLUSIVE
4b60: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 0x00000010.#
4b70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
4b80: 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 EN_MAIN_DB
4b90: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 0x00000100.#
4ba0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
4bb0: 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 EN_TEMP_DB
4bc0: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 0x00000200.#
4bd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
4be0: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 EN_TRANSIENT_DB
4bf0: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 0x00000400.#
4c00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
4c10: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 EN_MAIN_JOURNAL
4c20: 20 20 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 0x00000800.#
4c30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
4c40: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 EN_TEMP_JOURNAL
4c50: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 0x00001000.#
4c60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
4c70: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 EN_SUBJOURNAL
4c80: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 23 0x00002000.#
4c90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
4ca0: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 EN_MASTER_JOURNA
4cb0: 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 0a 0a L 0x00004000..
4cc0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
4cd0: 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65 72 Device Character
4ce0: 69 73 74 69 63 73 20 7b 46 31 30 32 34 30 7d 0a istics {F10240}.
4cf0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 **.** The xDevic
4d00: 65 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65 eCapabilities me
4d10: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c thod of the [sql
4d20: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
4d30: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 .** object retur
4d40: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 ns an integer wh
4d50: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 ich is a vector
4d60: 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 of the these.**
4d70: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 bit values expre
4d80: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 ssing I/O charac
4d90: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 teristics of the
4da0: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a mass storage.**
4db0: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c device that hol
4dc0: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 ds the file that
4dd0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f the [sqlite3_io
4de0: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 _methods].** ref
4df0: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 ers to..**.** Th
4e00: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
4e10: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d TOMIC property m
4e20: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 eans that all wr
4e30: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 ites of.** any s
4e40: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 ize are atomic.
4e50: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
4e60: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 P_ATOMICnnn valu
4e70: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 es.** mean that
4e80: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 writes of blocks
4e90: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 that are nnn by
4ea0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a tes in size and.
4eb0: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 ** are aligned t
4ec0: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 o an address whi
4ed0: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ch is an integer
4ee0: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 multiple of.**
4ef0: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 nnn are atomic.
4f00: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
4f10: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 P_SAFE_APPEND va
4f20: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 lue means.** tha
4f30: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 t when data is a
4f40: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c ppended to a fil
4f50: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 e, the data is a
4f60: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 ppended.** first
4f70: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f then the size o
4f80: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 f the file is ex
4f90: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 tended, never th
4fa0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 e other.** way a
4fb0: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 round. The SQLI
4fc0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 TE_IOCAP_SEQUENT
4fd0: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 IAL property mea
4fe0: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 ns that.** infor
4ff0: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 mation is writte
5000: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 n to disk in the
5010: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 same order as c
5020: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 alls.** to xWrit
5030: 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 e()..*/.#define
5040: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5050: 4d 49 43 20 20 20 20 20 20 20 20 20 20 30 78 30 MIC 0x0
5060: 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 0000001.#define
5070: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5080: 4d 49 43 35 31 32 20 20 20 20 20 20 20 30 78 30 MIC512 0x0
5090: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 0000002.#define
50a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
50b0: 4d 49 43 31 4b 20 20 20 20 20 20 20 20 30 78 30 MIC1K 0x0
50c0: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 0000004.#define
50d0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
50e0: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 30 78 30 MIC2K 0x0
50f0: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 0000008.#define
5100: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5110: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 30 78 30 MIC4K 0x0
5120: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 0000010.#define
5130: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5140: 4d 49 43 38 4b 20 20 20 20 20 20 20 20 30 78 30 MIC8K 0x0
5150: 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 0000020.#define
5160: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
5170: 4d 49 43 31 36 4b 20 20 20 20 20 20 20 30 78 30 MIC16K 0x0
5180: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 0000040.#define
5190: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
51a0: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 30 78 30 MIC32K 0x0
51b0: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 0000080.#define
51c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
51d0: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 30 78 30 MIC64K 0x0
51e0: 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 0000100.#define
51f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 SQLITE_IOCAP_SAF
5200: 45 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78 30 E_APPEND 0x0
5210: 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 0000200.#define
5220: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 SQLITE_IOCAP_SEQ
5230: 55 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30 UENTIAL 0x0
5240: 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 0000400../*.** C
5250: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f API3REF: File Lo
5260: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 46 31 cking Levels {F1
5270: 30 32 35 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 0250}.**.** SQLi
5280: 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 te uses one of t
5290: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c hese integer val
52a0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e ues as the secon
52b0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f d.** argument to
52c0: 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 calls it makes
52d0: 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 to the xLock() a
52e0: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 nd xUnlock() met
52f0: 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 hods.** of an [s
5300: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
5310: 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 s] object..*/.#d
5320: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 efine SQLITE_LOC
5330: 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 K_NONE
5340: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
5350: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 _LOCK_SHARED
5360: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 1.#define SQ
5370: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 LITE_LOCK_RESERV
5380: 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e ED 2.#defin
5390: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 e SQLITE_LOCK_PE
53a0: 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 NDING 3.#d
53b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 efine SQLITE_LOC
53c0: 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 K_EXCLUSIVE
53d0: 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 4../*.** CAPI3RE
53e0: 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 F: Synchronizati
53f0: 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20 7b 46 on Type Flags {F
5400: 31 30 32 36 30 7d 0a 2a 2a 0a 2a 2a 20 57 68 65 10260}.**.** Whe
5410: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 n SQLite invokes
5420: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 the xSync() met
5430: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 hod of an.** [sq
5440: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
5450: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 ] object it uses
5460: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f a combination o
5470: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 f.** these integ
5480: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 er values as the
5490: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
54a0: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 ..**.** When the
54b0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 SQLITE_SYNC_DAT
54c0: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 AONLY flag is us
54d0: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 ed, it means tha
54e0: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 t the.** sync op
54f0: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 eration only nee
5500: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 ds to flush data
5510: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 to mass storage
5520: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f . Inode.** info
5530: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 rmation need not
5540: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 54 68 65 be flushed. The
5550: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 SQLITE_SYNC_NOR
5560: 4d 41 4c 20 66 6c 61 67 20 6d 65 61 6e 73 20 0a MAL flag means .
5570: 2a 2a 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c ** to use normal
5580: 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 fsync() semanti
5590: 63 73 2e 20 54 68 65 20 53 51 4c 49 54 45 5f 53 cs. The SQLITE_S
55a0: 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 20 6d 65 YNC_FULL flag me
55b0: 61 6e 73 20 0a 2a 2a 20 74 6f 20 75 73 65 20 4d ans .** to use M
55c0: 61 63 20 4f 53 2d 58 20 73 74 79 6c 65 20 66 75 ac OS-X style fu
55d0: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f llsync instead o
55e0: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64 f fsync()..*/.#d
55f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e efine SQLITE_SYN
5600: 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 C_NORMAL
5610: 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 0x00002.#define
5620: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c SQLITE_SYNC_FULL
5630: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
5640: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 3.#define SQLITE
5650: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 _SYNC_DATAONLY
5660: 20 20 20 20 30 78 30 30 30 31 30 0a 0a 0a 2f 2a 0x00010.../*
5670: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 .** CAPI3REF: OS
5680: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 Interface Open
5690: 46 69 6c 65 20 48 61 6e 64 6c 65 20 7b 46 31 31 File Handle {F11
56a0: 31 31 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 110}.**.** An [s
56b0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a qlite3_file] obj
56c0: 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 ect represents a
56d0: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 n open file in t
56e0: 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66 61 he OS.** interfa
56f0: 63 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 69 76 ce layer. Indiv
5700: 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 idual OS interfa
5710: 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ce implementatio
5720: 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 ns will.** want
5730: 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 to subclass this
5740: 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e object by appen
5750: 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 ding additional
5760: 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 fields.** for th
5770: 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 eir own use. Th
5780: 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 e pMethods entry
5790: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
57a0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f an.** [sqlite3_
57b0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 io_methods] obje
57c0: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 ct that defines
57d0: 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 methods for perf
57e0: 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 orming.** I/O op
57f0: 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 erations on the
5800: 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 open file..*/.ty
5810: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
5820: 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 ite3_file sqlite
5830: 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 3_file;.struct s
5840: 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 qlite3_file {.
5850: 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c const struct sql
5860: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 ite3_io_methods
5870: 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d *pMethods; /* M
5880: 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 ethods for an op
5890: 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f en file */.};../
58a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
58b0: 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 S Interface File
58c0: 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 Virtual Methods
58d0: 20 4f 62 6a 65 63 74 20 7b 46 31 31 31 32 30 7d Object {F11120}
58e0: 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c .**.** Every fil
58f0: 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 e opened by the
5900: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f [sqlite3_vfs] xO
5910: 70 65 6e 20 6d 65 74 68 6f 64 20 63 6f 6e 74 61 pen method conta
5920: 69 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f ins a pointer to
5930: 0a 2a 2a 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 .** an instance
5940: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 20 of this object.
5950: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 This object def
5960: 69 6e 65 73 20 74 68 65 0a 2a 2a 20 6d 65 74 68 ines the.** meth
5970: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 ods used to perf
5980: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 orm various oper
5990: 61 74 69 6f 6e 73 20 61 67 61 69 6e 73 74 20 74 ations against t
59a0: 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2a he open file..**
59b0: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 .** The flags ar
59c0: 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 gument to xSync
59d0: 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 may be one of [S
59e0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 QLITE_SYNC_NORMA
59f0: 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 L] or.** [SQLITE
5a00: 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 _SYNC_FULL]. Th
5a10: 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 e first choice i
5a20: 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 s the normal fsy
5a30: 6e 63 28 29 2e 0a 2a 20 20 54 68 65 20 73 65 63 nc()..* The sec
5a40: 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 6e ond choice is an
5a50: 0a 2a 2a 20 4f 53 2d 58 20 73 74 79 6c 65 20 66 .** OS-X style f
5a60: 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 53 51 ullsync. The SQ
5a70: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 20 66 LITE_SYNC_DATA f
5a80: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 lag may be ORed
5a90: 69 6e 20 74 6f 0a 2a 2a 20 69 6e 64 69 63 61 74 in to.** indicat
5aa0: 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 e that only the
5ab0: 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 data of the file
5ac0: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f and not its ino
5ad0: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 0a 2a de needs to be.*
5ae0: 2a 20 73 79 6e 63 65 64 2e 0a 2a 2a 20 0a 2a 2a * synced..** .**
5af0: 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c The integer val
5b00: 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 ues to xLock() a
5b10: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 nd xUnlock() are
5b20: 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a one of.** <ul>.
5b30: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
5b40: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c LOCK_NONE],.** <
5b50: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b li> [SQLITE_LOCK
5b60: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 _SHARED],.** <li
5b70: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 > [SQLITE_LOCK_R
5b80: 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 ESERVED],.** <li
5b90: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 > [SQLITE_LOCK_P
5ba0: 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c ENDING], or.** <
5bb0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b li> [SQLITE_LOCK
5bc0: 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 _EXCLUSIVE]..**
5bd0: 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 </ul>.** xLock()
5be0: 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c increases the l
5bf0: 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 ock. xUnlock() d
5c00: 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 ecreases the loc
5c10: 6b 2e 20 20 0a 2a 2a 20 54 68 65 20 78 43 68 65 k. .** The xChe
5c20: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 ckReservedLock()
5c30: 20 6d 65 74 68 6f 64 20 6c 6f 6f 6b 73 0a 2a 2a method looks.**
5c40: 20 74 6f 20 73 65 65 20 69 66 20 61 6e 79 20 64 to see if any d
5c50: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
5c60: 6f 6e 2c 20 65 69 74 68 65 72 20 69 6e 20 74 68 on, either in th
5c70: 69 73 0a 2a 2a 20 70 72 6f 63 65 73 73 20 6f 72 is.** process or
5c80: 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 in some other p
5c90: 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 rocess, is holdi
5ca0: 6e 67 20 61 6e 20 52 45 53 45 52 56 45 44 2c 0a ng an RESERVED,.
5cb0: 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 ** PENDING, or E
5cc0: 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e XCLUSIVE lock on
5cd0: 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 the file. It r
5ce0: 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 eturns true.** i
5cf0: 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 f such a lock ex
5d00: 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 69 ists and false i
5d10: 66 20 6e 6f 74 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 f not..** .** Th
5d20: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 e xFileControl()
5d30: 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e method is a gen
5d40: 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 eric interface t
5d50: 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f hat allows custo
5d60: 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 m.** VFS impleme
5d70: 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 ntations to dire
5d80: 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 ctly control an
5d90: 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 open file using
5da0: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
5db0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 file_control()]
5dc0: 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 interface. The
5dd0: 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 second "op" argu
5de0: 6d 65 6e 74 0a 2a 2a 20 69 73 20 61 6e 20 69 6e ment.** is an in
5df0: 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 20 teger opcode.
5e00: 54 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 The third.** arg
5e10: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 ument is a gener
5e20: 69 63 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 ic pointer which
5e30: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 is intended to
5e40: 62 65 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 be a pointer.**
5e50: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 to a structure t
5e60: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 hat may contain
5e70: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 arguments or spa
5e80: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a ce in which to.*
5e90: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 * write return v
5ea0: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 alues. Potentia
5eb0: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 l uses for xFile
5ec0: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 Control() might
5ed0: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 be.** functions
5ee0: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 to enable blocki
5ef0: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 ng locks with ti
5f00: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 meouts, to chang
5f10: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 e the.** locking
5f20: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 strategy (for e
5f30: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f xample to use do
5f40: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 t-file locks), t
5f50: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f o inquire.** abo
5f60: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 ut the status of
5f70: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 a lock, or to b
5f80: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 reak stale locks
5f90: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a . The SQLite.**
5fa0: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 6f core reserves o
5fb0: 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e pcodes less than
5fc0: 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 100 for its own
5fd0: 20 75 73 65 2e 20 0a 2a 2a 20 41 20 5b 53 51 4c use. .** A [SQL
5fe0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 ITE_FCNTL_LOCKST
5ff0: 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 ATE | list of op
6000: 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e codes] less than
6010: 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 100 is availabl
6020: 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f e..** Applicatio
6030: 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 ns that define a
6040: 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e custom xFileCon
6050: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 trol method shou
6060: 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 20 0a ld use opcodes .
6070: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 ** greater than
6080: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 100 to avoid con
6090: 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 flicts..**.** Th
60a0: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 e xSectorSize()
60b0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 method returns t
60c0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f he sector size o
60d0: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 f the.** device
60e0: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 that underlies t
60f0: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 he file. The se
6100: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 ctor size is the
6110: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 .** minimum writ
6120: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 e that can be pe
6130: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 rformed without
6140: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 disturbing.** ot
6150: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 her bytes in the
6160: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 file. The xDev
6170: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 iceCharacteristi
6180: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 cs().** method r
6190: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 eturns a bit vec
61a0: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 tor describing b
61b0: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a ehaviors of the.
61c0: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 ** underlying de
61d0: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e vice:.**.** <ul>
61e0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
61f0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a _IOCAP_ATOMIC].*
6200: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
6210: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a OCAP_ATOMIC512].
6220: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
6230: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a IOCAP_ATOMIC1K].
6240: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
6250: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a IOCAP_ATOMIC2K].
6260: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
6270: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a IOCAP_ATOMIC4K].
6280: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
6290: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a IOCAP_ATOMIC8K].
62a0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
62b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d IOCAP_ATOMIC16K]
62c0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
62d0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b _IOCAP_ATOMIC32K
62e0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
62f0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 E_IOCAP_ATOMIC64
6300: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
6310: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 TE_IOCAP_SAFE_AP
6320: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 PEND].** <li> [S
6330: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 QLITE_IOCAP_SEQU
6340: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e ENTIAL].** </ul>
6350: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 .**.** The SQLIT
6360: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 E_IOCAP_ATOMIC p
6370: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 roperty means th
6380: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 at all writes of
6390: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 .** any size are
63a0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
63b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
63c0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d Cnnn values.** m
63d0: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 ean that writes
63e0: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 of blocks that a
63f0: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 re nnn bytes in
6400: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 size and.** are
6410: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 aligned to an ad
6420: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 dress which is a
6430: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 n integer multip
6440: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 le of.** nnn are
6450: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
6460: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f LITE_IOCAP_SAFE_
6470: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 APPEND value mea
6480: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 ns.** that when
6490: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
64a0: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 to a file, the
64b0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
64c0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 .** first then t
64d0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 he size of the f
64e0: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c ile is extended,
64f0: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 never the other
6500: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 .** way around.
6510: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
6520: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f P_SEQUENTIAL pro
6530: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
6540: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 .** information
6550: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 is written to di
6560: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f sk in the same o
6570: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a rder as calls.**
6580: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f to xWrite()..*/
6590: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
65a0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
65b0: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 ds sqlite3_io_me
65c0: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 thods;.struct sq
65d0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
65e0: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f {. int iVersio
65f0: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 n;. int (*xClos
6600: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a e)(sqlite3_file*
6610: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 );. int (*xRead
6620: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
6630: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 void*, int iAmt
6640: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
6650: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a iOfst);. int (*
6660: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f xWrite)(sqlite3_
6670: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 file*, const voi
6680: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 d*, int iAmt, sq
6690: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 lite3_int64 iOfs
66a0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 t);. int (*xTru
66b0: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 ncate)(sqlite3_f
66c0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e ile*, sqlite3_in
66d0: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 t64 size);. int
66e0: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 (*xSync)(sqlite
66f0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 3_file*, int fla
6700: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 gs);. int (*xFi
6710: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f leSize)(sqlite3_
6720: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 file*, sqlite3_i
6730: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 nt64 *pSize);.
6740: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c int (*xLock)(sql
6750: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 ite3_file*, int)
6760: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 ;. int (*xUnloc
6770: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a k)(sqlite3_file*
6780: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a , int);. int (*
6790: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f xCheckReservedLo
67a0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ck)(sqlite3_file
67b0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c *);. int (*xFil
67c0: 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 eControl)(sqlite
67d0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 3_file*, int op,
67e0: 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 void *pArg);.
67f0: 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a int (*xSectorSiz
6800: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a e)(sqlite3_file*
6810: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 );. int (*xDevi
6820: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 ceCharacteristic
6830: 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a s)(sqlite3_file*
6840: 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e );. /* Addition
6850: 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 al methods may b
6860: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
6870: 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b e releases */.};
6880: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
6890: 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 : Standard File
68a0: 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 20 Control Opcodes
68b0: 7b 46 31 31 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 {F11310}.**.** T
68c0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e hese integer con
68d0: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 stants are opcod
68e0: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 es for the xFile
68f0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a Control method.*
6900: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 * of the [sqlite
6910: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
6920: 6a 65 63 74 20 61 6e 64 20 74 6f 20 74 68 65 20 ject and to the
6930: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
6940: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 ntrol()].** inte
6950: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 rface..**.** The
6960: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c [SQLITE_FCNTL_L
6970: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 OCKSTATE] opcode
6980: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 is used for deb
6990: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a ugging. This.**
69a0: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 opcode causes t
69b0: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 he xFileControl
69c0: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 method to write
69d0: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 the current stat
69e0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b e of.** the lock
69f0: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 (one of [SQLITE
6a00: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 _LOCK_NONE], [SQ
6a10: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 LITE_LOCK_SHARED
6a20: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f ],.** [SQLITE_LO
6a30: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 CK_RESERVED], [S
6a40: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 QLITE_LOCK_PENDI
6a50: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f NG], or [SQLITE_
6a60: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 LOCK_EXCLUSIVE])
6a70: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 .** into an inte
6a80: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72 ger that the pAr
6a90: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 g argument point
6aa0: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 s to. This capab
6ab0: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 ility.** is used
6ac0: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 during testing
6ad0: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 and only needs t
6ae0: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 o be supported w
6af0: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a hen SQLITE_TEST.
6b00: 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a ** is defined..*
6b10: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6b20: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 _FCNTL_LOCKSTATE
6b30: 20 20 20 20 20 20 20 20 31 0a 0a 2f 2a 0a 2a 2a 1../*.**
6b40: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 CAPI3REF: Mutex
6b50: 20 48 61 6e 64 6c 65 20 7b 46 31 37 31 31 30 7d Handle {F17110}
6b60: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 .**.** The mutex
6b70: 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 module within S
6b80: 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 QLite defines [s
6b90: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f qlite3_mutex] to
6ba0: 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 be an.** abstra
6bb0: 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 ct type for a mu
6bc0: 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 tex object. The
6bd0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 SQLite core nev
6be0: 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 er looks.** at t
6bf0: 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 he internal repr
6c00: 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e esentation of an
6c10: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d [sqlite3_mutex]
6c20: 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 . It only.** de
6c30: 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 als with pointer
6c40: 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 s to the [sqlite
6c50: 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 3_mutex] object.
6c60: 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 .**.** Mutexes a
6c70: 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 re created using
6c80: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
6c90: 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 alloc()]..*/.typ
6ca0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
6cb0: 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 te3_mutex sqlite
6cc0: 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 3_mutex;../*.**
6cd0: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 CAPI3REF: OS Int
6ce0: 65 72 66 61 63 65 20 4f 62 6a 65 63 74 20 7b 46 erface Object {F
6cf0: 31 31 31 34 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 11140}.**.** An
6d00: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
6d10: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 object defines
6d20: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 the interface be
6d30: 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20 53 51 4c tween the.** SQL
6d40: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 ite core and the
6d50: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 underlying oper
6d60: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 ating system. T
6d70: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 he "vfs".** in t
6d80: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f he name of the o
6d90: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 bject stands for
6da0: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 "virtual file s
6db0: 79 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 ystem"..**.** Th
6dc0: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 e iVersion field
6dd0: 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 is initially 1
6de0: 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 but may be large
6df0: 72 20 66 6f 72 20 66 75 74 75 72 65 0a 2a 2a 20 r for future.**
6e00: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
6e10: 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 te. Additional
6e20: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 fields may be ap
6e30: 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a pended to this.*
6e40: 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 * object when th
6e50: 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 e iVersion value
6e60: 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 0a 2a is increased..*
6e70: 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c *.** The szOsFil
6e80: 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 e field is the s
6e90: 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c ize of the subcl
6ea0: 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 assed [sqlite3_f
6eb0: 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 ile].** structur
6ec0: 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 e used by this V
6ed0: 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 FS. mxPathname
6ee0: 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c is the maximum l
6ef0: 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 ength of.** a pa
6f00: 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 thname in this V
6f10: 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 FS..**.** Regist
6f20: 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 ered sqlite3_vfs
6f30: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 objects are kep
6f40: 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 t on a linked li
6f50: 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 st formed by.**
6f60: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 the pNext pointe
6f70: 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 r. The [sqlite3
6f80: 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d _vfs_register()]
6f90: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 .** and [sqlite3
6fa0: 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 _vfs_unregister(
6fb0: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 )] interfaces ma
6fc0: 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a nage this list.*
6fd0: 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 * in a thread-sa
6fe0: 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 fe way. The [sq
6ff0: 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 lite3_vfs_find()
7000: 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 ] interface.** s
7010: 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 earches the list
7020: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 ..**.** The pNex
7030: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f t field is the o
7040: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 nly field in the
7050: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 0a 2a 2a sqlite3_vfs .**
7060: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 structure that
7070: 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 SQLite will ever
7080: 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 modify. SQLite
7090: 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 will only acces
70a0: 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 s.** or modify t
70b0: 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 his field while
70c0: 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 holding a partic
70d0: 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 ular static mute
70e0: 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 x..** The applic
70f0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 ation should nev
7100: 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 er modify anythi
7110: 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 ng within the sq
7120: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a lite3_vfs.** obj
7130: 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a ect once the obj
7140: 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 ect has been reg
7150: 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 istered..**.** T
7160: 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 he zName field h
7170: 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 olds the name of
7180: 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e the VFS module.
7190: 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a The name must.
71a0: 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 ** be unique acr
71b0: 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 oss all VFS modu
71c0: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31 les..**.** {F111
71d0: 34 31 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 41} SQLite will
71e0: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 guarantee that t
71f0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 73 74 72 he zFilename str
7200: 69 6e 67 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a ing passed to.**
7210: 20 78 4f 70 65 6e 28 29 20 69 73 20 61 20 66 75 xOpen() is a fu
7220: 6c 6c 20 70 61 74 68 6e 61 6d 65 20 61 73 20 67 ll pathname as g
7230: 65 6e 65 72 61 74 65 64 20 62 79 20 78 46 75 6c enerated by xFul
7240: 6c 50 61 74 68 6e 61 6d 65 28 29 20 61 6e 64 0a lPathname() and.
7250: 2a 2a 20 74 68 61 74 20 74 68 65 20 73 74 72 69 ** that the stri
7260: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 ng will be valid
7270: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 and unchanged u
7280: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 ntil xClose() is
7290: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 20 7b 45 4e .** called. {EN
72a0: 44 7d 20 53 6f 20 74 68 65 20 5b 73 71 6c 69 74 D} So the [sqlit
72b0: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 74 6f e3_file] can sto
72c0: 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 re a pointer to
72d0: 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 the.** filename
72e0: 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 if it needs to r
72f0: 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 emember the file
7300: 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 name for some re
7310: 61 73 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 ason..**.** {F11
7320: 31 34 32 7d 20 54 68 65 20 66 6c 61 67 73 20 61 142} The flags a
7330: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e rgument to xOpen
7340: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 () includes all
7350: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 bits set in.** t
7360: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e he flags argumen
7370: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 t to [sqlite3_op
7380: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 en_v2()]. Or if
7390: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
73a0: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 ].** or [sqlite3
73b0: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 _open16()] is us
73c0: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 ed, then flags i
73d0: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 ncludes at least
73e0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e .** [SQLITE_OPEN
73f0: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 _READWRITE] | [S
7400: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
7410: 45 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 49 66 20 E]. {END}.** If
7420: 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 xOpen() opens a
7430: 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 file read-only t
7440: 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 hen it sets *pOu
7450: 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 tFlags to.** inc
7460: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 lude [SQLITE_OPE
7470: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 N_READONLY]. Ot
7480: 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 her bits in *pOu
7490: 74 46 6c 61 67 73 20 6d 61 79 20 62 65 0a 2a 2a tFlags may be.**
74a0: 20 73 65 74 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 set..** .** {F1
74b0: 31 31 34 33 7d 20 53 51 4c 69 74 65 20 77 69 6c 1143} SQLite wil
74c0: 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f l also add one o
74d0: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 f the following
74e0: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 flags to the xOp
74f0: 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 en().** call, de
7500: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f pending on the o
7510: 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e bject being open
7520: 65 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a ed:.** .** <ul>.
7530: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
7540: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a _OPEN_MAIN_DB].*
7550: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
7560: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 OPEN_MAIN_JOURNA
7570: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c L].** <li> [SQL
7580: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 ITE_OPEN_TEMP_DB
7590: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 ].** <li> [SQLI
75a0: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 TE_OPEN_TEMP_JOU
75b0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b RNAL].** <li> [
75c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e SQLITE_OPEN_TRAN
75d0: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 SIENT_DB].** <li
75e0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
75f0: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c SUBJOURNAL].** <
7600: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
7610: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c N_MASTER_JOURNAL
7620: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d ].** </ul> {END}
7630: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 .**.** The file
7640: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 I/O implementati
7650: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f on can use the o
7660: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 bject type flags
7670: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 to.** changes t
7680: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 he way it deals
7690: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 with files. For
76a0: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 example, an app
76b0: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 lication.** that
76c0: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 does not care a
76d0: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 bout crash recov
76e0: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 ery or rollback
76f0: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 might make.** th
7700: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 e open of a jour
7710: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 nal file a no-op
7720: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 . Writes to thi
7730: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a s journal would.
7740: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 ** also be no-op
7750: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d s, and any attem
7760: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a pt to read the j
7770: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 ournal would ret
7780: 75 72 6e 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 urn .** SQLITE_I
7790: 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d OERR. Or the im
77a0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 plementation mig
77b0: 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 ht recognize tha
77c0: 74 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a t a database .**
77d0: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f file will be do
77e0: 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 ing page-aligned
77f0: 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e sector reads an
7800: 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 d writes in a ra
7810: 6e 64 6f 6d 20 0a 2a 2a 20 6f 72 64 65 72 20 61 ndom .** order a
7820: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f nd set up its I/
7830: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f O subsystem acco
7840: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 20 0a 2a 2a 20 rdingly..** .**
7850: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 SQLite might als
7860: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 o add one of the
7870: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 following flags
7880: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a to the xOpen.**
7890: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 20 0a 2a 2a 20 method:.** .**
78a0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 <ul>.** <li> [SQ
78b0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
78c0: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e ONCLOSE].** <li>
78d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 [SQLITE_OPEN_EX
78e0: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c CLUSIVE].** </ul
78f0: 3e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31 34 35 >.** .** {F11145
7900: 7d 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 } The [SQLITE_OP
7910: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 EN_DELETEONCLOSE
7920: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 ] flag means the
7930: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a file should be.
7940: 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 ** deleted when
7950: 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 7b it is closed. {
7960: 46 31 31 31 34 36 7d 20 54 68 65 20 5b 53 51 4c F11146} The [SQL
7970: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f ITE_OPEN_DELETEO
7980: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 NCLOSE].** will
7990: 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 be set for TEMP
79a0: 20 64 61 74 61 62 61 73 65 73 2c 20 6a 6f 75 72 databases, jour
79b0: 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 62 nals and for sub
79c0: 6a 6f 75 72 6e 61 6c 73 2e 20 0a 2a 2a 20 7b 46 journals. .** {F
79d0: 31 31 31 34 37 7d 20 54 68 65 20 5b 53 51 4c 49 11147} The [SQLI
79e0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 TE_OPEN_EXCLUSIV
79f0: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 E] flag means th
7a00: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 e file should be
7a10: 20 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f 72 20 65 opened.** for e
7a20: 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e xclusive access.
7a30: 20 20 54 68 69 73 20 66 6c 61 67 20 69 73 20 73 This flag is s
7a40: 65 74 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65 73 et for all files
7a50: 20 65 78 63 65 70 74 0a 2a 2a 20 66 6f 72 20 74 except.** for t
7a60: 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 he main database
7a70: 20 66 69 6c 65 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 file. {END}.**
7a80: 0a 2a 2a 20 7b 46 31 31 31 34 38 7d 20 41 74 20 .** {F11148} At
7a90: 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 least szOsFile b
7aa0: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 ytes of memory a
7ab0: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 re allocated by
7ac0: 53 51 4c 69 74 65 20 0a 2a 2a 20 74 6f 20 68 6f SQLite .** to ho
7ad0: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 ld the [sqlite3
7ae0: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 _file] structure
7af0: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 passed as the t
7b00: 68 69 72 64 20 0a 2a 2a 20 61 72 67 75 6d 65 6e hird .** argumen
7b10: 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 7b 45 4e t to xOpen. {EN
7b20: 44 7d 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 D} The xOpen me
7b30: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 thod does not ha
7b40: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 ve to.** allocat
7b50: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b e the structure;
7b60: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 it should just
7b70: 66 69 6c 6c 20 69 74 20 69 6e 2e 0a 2a 2a 20 0a fill it in..** .
7b80: 2a 2a 20 7b 46 31 31 31 34 39 7d 20 54 68 65 20 ** {F11149} The
7b90: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 flags argument t
7ba0: 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 o xAccess() may
7bb0: 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 be [SQLITE_ACCES
7bc0: 53 5f 45 58 49 53 54 53 5d 20 0a 2a 2a 20 74 6f S_EXISTS] .** to
7bd0: 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 test for the ex
7be0: 69 73 74 61 6e 63 65 20 6f 66 20 61 20 66 69 6c istance of a fil
7bf0: 65 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 e,.** or [SQLITE
7c00: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 _ACCESS_READWRIT
7c10: 45 5d 20 74 6f 20 74 65 73 74 20 74 6f 20 73 65 E] to test to se
7c20: 65 0a 2a 2a 20 69 66 20 61 20 66 69 6c 65 20 69 e.** if a file i
7c30: 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 s readable and w
7c40: 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c ritable, or [SQL
7c50: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d ITE_ACCESS_READ]
7c60: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 74 6f 20 73 .** to test to s
7c70: 65 65 20 69 66 20 61 20 66 69 6c 65 20 69 73 20 ee if a file is
7c80: 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c at least readabl
7c90: 65 2e 20 20 7b 45 4e 44 7d 20 54 68 65 20 66 69 e. {END} The fi
7ca0: 6c 65 20 63 61 6e 20 62 65 20 61 20 0a 2a 2a 20 le can be a .**
7cb0: 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 0a 2a directory..** .*
7cc0: 2a 20 7b 46 31 31 31 35 30 7d 20 53 51 4c 69 74 * {F11150} SQLit
7cd0: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c e will always al
7ce0: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 locate at least
7cf0: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 mxPathname+1 byt
7d00: 65 73 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6f 75 es for.** the ou
7d10: 74 70 75 74 20 62 75 66 66 65 72 73 20 66 6f 72 tput buffers for
7d20: 20 78 47 65 74 54 65 6d 70 6e 61 6d 65 20 61 6e xGetTempname an
7d30: 64 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e d xFullPathname.
7d40: 20 7b 46 31 31 31 35 31 7d 20 54 68 65 20 65 78 {F11151} The ex
7d50: 61 63 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 74 act.** size of t
7d60: 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 he output buffer
7d70: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 is also passed
7d80: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 as a parameter t
7d90: 6f 20 62 6f 74 68 20 0a 2a 2a 20 6d 65 74 68 6f o both .** metho
7da0: 64 73 2e 20 7b 45 4e 44 7d 20 49 66 20 74 68 65 ds. {END} If the
7db0: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 69 output buffer i
7dc0: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 s not large enou
7dd0: 67 68 2c 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f gh, SQLITE_CANTO
7de0: 50 45 4e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 PEN.** should be
7df0: 20 72 65 74 75 72 6e 65 64 2e 20 41 73 20 74 68 returned. As th
7e00: 69 73 20 69 73 20 68 61 6e 64 6c 65 64 20 61 73 is is handled as
7e10: 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 a fatal error b
7e20: 79 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 76 66 73 y SQLite,.** vfs
7e30: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
7e40: 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 should endeavor
7e50: 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 to prevent this
7e60: 20 62 79 20 73 65 74 74 69 6e 67 20 0a 2a 2a 20 by setting .**
7e70: 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 mxPathname to a
7e80: 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 sufficiently lar
7e90: 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 20 0a 2a 2a ge value..** .**
7ea0: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 The xRandomness
7eb0: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61 6e (), xSleep(), an
7ec0: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 d xCurrentTime()
7ed0: 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 interfaces.** a
7ee0: 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 re not strictly
7ef0: 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 a part of the fi
7f00: 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 lesystem, but th
7f10: 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 ey are.** includ
7f20: 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 ed in the VFS st
7f30: 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 ructure for comp
7f40: 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 leteness..** The
7f50: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 xRandomness() f
7f60: 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 unction attempts
7f70: 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 to return nByte
7f80: 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f s bytes.** of go
7f90: 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f od-quality rando
7fa0: 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e mness into zOut.
7fb0: 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c The return val
7fc0: 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 ue is.** the act
7fd0: 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 ual number of by
7fe0: 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 tes of randomnes
7ff0: 73 20 6f 62 74 61 69 6e 65 64 2e 20 20 54 68 65 s obtained. The
8000: 0a 2a 2a 20 78 53 6c 65 65 70 28 29 20 6d 65 74 .** xSleep() met
8010: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63 hod causes the c
8020: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f alling thread to
8030: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a sleep for at.**
8040: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 least the numbe
8050: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 r of microsecond
8060: 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43 s given. The xC
8070: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 urrentTime().**
8080: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 method returns a
8090: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 Julian Day Numb
80a0: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 er for the curre
80b0: 6e 74 20 64 61 74 65 20 61 6e 64 0a 2a 2a 20 74 nt date and.** t
80c0: 69 6d 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ime..*/.typedef
80d0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 struct sqlite3_v
80e0: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a fs sqlite3_vfs;.
80f0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 struct sqlite3_v
8100: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 fs {. int iVers
8110: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 ion;
8120: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 /* Structure ver
8130: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 sion number */.
8140: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 int szOsFile;
8150: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a /* Siz
8160: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 e of subclassed
8170: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a sqlite3_file */.
8180: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 int mxPathname
8190: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 ; /* Ma
81a0: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e ximum file pathn
81b0: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 ame length */.
81c0: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 sqlite3_vfs *pNe
81d0: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 xt; /* Next
81e0: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 registered VFS
81f0: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
8200: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a *zName; /*
8210: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 Name of this vi
8220: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 rtual file syste
8230: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 m */. void *pAp
8240: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 pData;
8250: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 /* Pointer to ap
8260: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 plication-specif
8270: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 ic data */. int
8280: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 (*xOpen)(sqlite
8290: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
82a0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 ar *zName, sqlit
82b0: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 e3_file*,.
82c0: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 int fla
82d0: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 gs, int *pOutFla
82e0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 gs);. int (*xDe
82f0: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 lete)(sqlite3_vf
8300: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a s*, const char *
8310: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 zName, int syncD
8320: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 ir);. int (*xAc
8330: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 cess)(sqlite3_vf
8340: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a s*, const char *
8350: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 zName, int flags
8360: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 54 );. int (*xGetT
8370: 65 6d 70 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 empname)(sqlite3
8380: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 4f 75 74 2c _vfs*, int nOut,
8390: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 char *zOut);.
83a0: 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e int (*xFullPathn
83b0: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ame)(sqlite3_vfs
83c0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
83d0: 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 Name, int nOut,
83e0: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 char *zOut);. v
83f0: 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 oid *(*xDlOpen)(
8400: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
8410: 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e nst char *zFilen
8420: 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 ame);. void (*x
8430: 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 DlError)(sqlite3
8440: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 _vfs*, int nByte
8450: 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 , char *zErrMsg)
8460: 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 53 ;. void *(*xDlS
8470: 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ym)(sqlite3_vfs*
8480: 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 ,void*, const ch
8490: 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 3b 0a 20 20 ar *zSymbol);.
84a0: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 void (*xDlClose)
84b0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 (sqlite3_vfs*, v
84c0: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 oid*);. int (*x
84d0: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 Randomness)(sqli
84e0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 te3_vfs*, int nB
84f0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 yte, char *zOut)
8500: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 ;. int (*xSleep
8510: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
8520: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 int microseconds
8530: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 );. int (*xCurr
8540: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 entTime)(sqlite3
8550: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b _vfs*, double*);
8560: 0a 20 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64 73 . /* New fields
8570: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 may be appended
8580: 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 in figure versi
8590: 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 ons. The iVersi
85a0: 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 on. ** value wi
85b0: 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 ll increment whe
85c0: 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 never this happe
85d0: 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a ns. */.};../*.**
85e0: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 CAPI3REF: Flags
85f0: 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 for the xAccess
8600: 20 56 46 53 20 6d 65 74 68 6f 64 20 7b 46 31 31 VFS method {F11
8610: 31 39 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31 190}.**.** {F111
8620: 39 31 7d 20 54 68 65 73 65 20 69 6e 74 65 67 65 91} These intege
8630: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 r constants can
8640: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 be used as the t
8650: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 hird parameter t
8660: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 o.** the xAccess
8670: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 method of an [s
8680: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
8690: 63 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79 20 ct. {END} They
86a0: 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 determine.** wha
86b0: 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 t kind of permis
86c0: 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 sions the xAcces
86d0: 73 20 6d 65 74 68 6f 64 20 69 73 0a 2a 2a 20 6c s method is.** l
86e0: 6f 6f 6b 69 6e 67 20 66 6f 72 2e 20 20 7b 46 31 ooking for. {F1
86f0: 31 31 39 32 7d 20 57 69 74 68 20 53 51 4c 49 54 1192} With SQLIT
8700: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c E_ACCESS_EXISTS,
8710: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 the xAccess met
8720: 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 hod.** simply ch
8730: 65 63 6b 73 20 74 6f 20 73 65 65 20 69 66 20 74 ecks to see if t
8740: 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 20 he file exists.
8750: 7b 46 31 31 31 39 33 7d 20 57 69 74 68 0a 2a 2a {F11193} With.**
8760: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 SQLITE_ACCESS_R
8770: 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 EADWRITE, the xA
8780: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 63 68 65 ccess method che
8790: 63 6b 73 20 74 6f 20 73 65 65 0a 2a 2a 20 69 66 cks to see.** if
87a0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 62 6f 74 the file is bot
87b0: 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 h readable and w
87c0: 72 69 74 61 62 6c 65 2e 20 20 7b 46 31 31 31 39 ritable. {F1119
87d0: 34 7d 20 57 69 74 68 0a 2a 2a 20 53 51 4c 49 54 4} With.** SQLIT
87e0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 74 68 E_ACCESS_READ th
87f0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 e xAccess method
8800: 0a 2a 2a 20 63 68 65 63 6b 73 20 74 6f 20 73 65 .** checks to se
8810: 65 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 e if the file is
8820: 20 72 65 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 readable..*/.#d
8830: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 efine SQLITE_ACC
8840: 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a ESS_EXISTS 0.
8850: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
8860: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 CCESS_READWRITE
8870: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
8880: 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 _ACCESS_READ
8890: 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 2../*.** CAPI3
88a0: 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 REF: Enable Or D
88b0: 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 isable Extended
88c0: 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 46 31 Result Codes {F1
88d0: 32 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 2200}.**.** The
88e0: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
88f0: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 _result_codes()
8900: 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 routine enables
8910: 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a or disables the.
8920: 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 ** [SQLITE_IOERR
8930: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 _READ | extended
8940: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 result codes] f
8950: 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 eature of SQLite
8960: 2e 0a 2a 2a 20 54 68 65 20 65 78 74 65 6e 64 65 ..** The extende
8970: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 d result codes a
8980: 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 re disabled by d
8990: 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f efault for histo
89a0: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 rical.** compati
89b0: 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e bility..**.** IN
89c0: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
89d0: 7b 46 31 32 32 30 31 7d 20 45 61 63 68 20 6e 65 {F12201} Each ne
89e0: 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e w [database conn
89f0: 65 63 74 69 6f 6e 5d 20 68 61 73 20 74 68 65 20 ection] has the
8a00: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 65 78 .** [ex
8a10: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
8a20: 64 65 73 5d 20 66 65 61 74 75 72 65 0a 2a 2a 20 des] feature.**
8a30: 20 20 20 20 20 20 20 20 20 64 69 73 61 62 6c 65 disable
8a40: 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a d by default..**
8a50: 0a 2a 2a 20 7b 46 31 32 32 30 32 7d 20 54 68 65 .** {F12202} The
8a60: 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 [sqlite3_extend
8a70: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 ed_result_codes(
8a80: 44 2c 46 29 5d 20 69 6e 74 65 72 66 61 63 65 20 D,F)] interface
8a90: 77 69 6c 6c 20 65 6e 61 62 6c 65 0a 2a 2a 20 20 will enable.**
8aa0: 20 20 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 [extende
8ab0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 d result codes]
8ac0: 66 6f 72 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 for the .**
8ad0: 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 [database c
8ae0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 69 66 20 onnection] D if
8af0: 74 68 65 20 46 20 70 61 72 61 6d 65 74 65 72 0a the F parameter.
8b00: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 74 ** is t
8b10: 72 75 65 2c 20 6f 72 20 64 69 73 61 62 6c 65 20 rue, or disable
8b20: 74 68 65 6d 20 69 66 20 46 20 69 73 20 66 61 6c them if F is fal
8b30: 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 se..*/.int sqlit
8b40: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 e3_extended_resu
8b50: 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 lt_codes(sqlite3
8b60: 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a *, int onoff);..
8b70: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
8b80: 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 Last Insert Rowi
8b90: 64 20 7b 46 31 32 32 32 30 7d 0a 2a 2a 0a 2a 2a d {F12220}.**.**
8ba0: 20 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 Each entry in a
8bb0: 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 n SQLite table h
8bc0: 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 as a unique 64-b
8bd0: 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 it signed.** int
8be0: 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 eger key called
8bf0: 74 68 65 20 22 72 6f 77 69 64 22 2e 20 54 68 65 the "rowid". The
8c00: 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 rowid is always
8c10: 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 available.** as
8c20: 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 an undeclared c
8c30: 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 olumn named ROWI
8c40: 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 D, OID, or _ROWI
8c50: 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 D_ as long as th
8c60: 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 ose.** names are
8c70: 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 not also used b
8c80: 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 y explicitly dec
8c90: 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49 lared columns. I
8ca0: 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 f.** the table h
8cb0: 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 as a column of t
8cc0: 79 70 65 20 49 4e 54 45 47 45 52 20 50 52 49 4d ype INTEGER PRIM
8cd0: 41 52 59 20 4b 45 59 20 74 68 65 6e 20 74 68 61 ARY KEY then tha
8ce0: 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 t column.** is a
8cf0: 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 nother alias for
8d00: 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a the rowid..**.*
8d10: 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 * This routine r
8d20: 65 74 75 72 6e 73 20 74 68 65 20 72 6f 77 69 64 eturns the rowid
8d30: 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 of the most rec
8d40: 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 ent.** successfu
8d50: 6c 20 49 4e 53 45 52 54 20 69 6e 74 6f 20 74 68 l INSERT into th
8d60: 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 e database from
8d70: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
8d80: 6e 65 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f 77 6e nection.** shown
8d90: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
8da0: 67 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20 73 gument. If no s
8db0: 75 63 63 65 73 73 66 75 6c 20 69 6e 73 65 72 74 uccessful insert
8dc0: 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f s.** have ever o
8dd0: 63 63 75 72 72 65 64 20 6f 6e 20 74 68 69 73 20 ccurred on this
8de0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
8df0: 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 ion, zero is ret
8e00: 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 urned..**.** If
8e10: 61 6e 20 49 4e 53 45 52 54 20 6f 63 63 75 72 73 an INSERT occurs
8e20: 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 within a trigge
8e30: 72 2c 20 74 68 65 6e 20 74 68 65 20 72 6f 77 69 r, then the rowi
8e40: 64 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6e 73 65 d of the.** inse
8e50: 72 74 65 64 20 72 6f 77 20 69 73 20 72 65 74 75 rted row is retu
8e60: 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 rned by this rou
8e70: 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 tine as long as
8e80: 74 68 65 20 74 72 69 67 67 65 72 0a 2a 2a 20 69 the trigger.** i
8e90: 73 20 72 75 6e 6e 69 6e 67 2e 20 20 42 75 74 20 s running. But
8ea0: 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 once the trigger
8eb0: 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 terminates, the
8ec0: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a value returned.
8ed0: 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 ** by this routi
8ee0: 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 74 68 ne reverts to th
8ef0: 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73 e last value ins
8f00: 65 72 74 65 64 20 62 65 66 6f 72 65 20 74 68 65 erted before the
8f10: 0a 2a 2a 20 74 72 69 67 67 65 72 20 66 69 72 65 .** trigger fire
8f20: 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 49 4e 53 45 d..**.** An INSE
8f30: 52 54 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 RT that fails du
8f40: 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e e to a constrain
8f50: 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e t violation is n
8f60: 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 ot a.** successf
8f70: 75 6c 20 69 6e 73 65 72 74 20 61 6e 64 20 64 6f ul insert and do
8f80: 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 es not change th
8f90: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
8fa0: 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 by this.** rout
8fb0: 69 6e 65 2e 20 20 54 68 75 73 20 49 4e 53 45 52 ine. Thus INSER
8fc0: 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 T OR FAIL, INSER
8fd0: 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 T OR IGNORE, INS
8fe0: 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c ERT OR ROLLBACK,
8ff0: 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f .** and INSERT O
9000: 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 R ABORT make no
9010: 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 changes to the r
9020: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 eturn value of t
9030: 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 his.** routine w
9040: 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 hen their insert
9050: 69 6f 6e 20 66 61 69 6c 73 2e 20 20 57 68 65 6e ion fails. When
9060: 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 INSERT OR REPLA
9070: 43 45 20 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 CE .** encounter
9080: 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 s a constraint v
9090: 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 iolation, it doe
90a0: 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 s not fail. The
90b0: 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 .** INSERT conti
90c0: 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 nues to completi
90d0: 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e on after deletin
90e0: 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 g rows that caus
90f0: 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 ed.** the constr
9100: 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 aint problem so
9110: 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 INSERT OR REPLAC
9120: 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 E will always ch
9130: 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 ange.** the retu
9140: 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 rn value of this
9150: 20 69 6e 74 65 72 66 61 63 65 2e 20 0a 2a 2a 0a interface. .**.
9160: 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f ** For the purpo
9170: 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 ses of this rout
9180: 69 6e 65 2c 20 61 6e 20 69 6e 73 65 72 74 20 69 ine, an insert i
9190: 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a s considered to.
91a0: 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c ** be successful
91b0: 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 even if it is s
91c0: 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c ubsequently roll
91d0: 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 ed back..**.** I
91e0: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
91f0: 20 7b 46 31 32 32 32 31 7d 20 54 68 65 20 5b 73 {F12221} The [s
9200: 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 qlite3_last_inse
9210: 72 74 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 rt_rowid()] func
9220: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 tion returns the
9230: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 77 .** row
9240: 69 64 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 id of the most r
9250: 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c ecent successful
9260: 20 69 6e 73 65 72 74 20 64 6f 6e 65 0a 2a 2a 20 insert done.**
9270: 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20 on the
9280: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f same database co
9290: 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 77 69 74 nnection and wit
92a0: 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 hin the same.**
92b0: 20 20 20 20 20 20 20 20 20 74 72 69 67 67 65 72 trigger
92c0: 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72 context, or zer
92d0: 6f 20 69 66 20 74 68 65 72 65 20 68 61 76 65 0a o if there have.
92e0: 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 65 6e ** been
92f0: 20 6e 6f 20 71 75 61 6c 69 66 79 69 6e 67 20 69 no qualifying i
9300: 6e 73 65 72 74 73 20 6f 6e 20 74 68 61 74 20 63 nserts on that c
9310: 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a onnection..**.**
9320: 20 7b 46 31 32 32 32 33 7d 20 54 68 65 20 5b 73 {F12223} The [s
9330: 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 qlite3_last_inse
9340: 72 74 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 rt_rowid()] func
9350: 74 69 6f 6e 20 72 65 74 75 72 6e 73 0a 2a 2a 20 tion returns.**
9360: 20 20 20 20 20 20 20 20 20 73 61 6d 65 20 76 61 same va
9370: 6c 75 65 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 lue when called
9380: 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 72 from the same tr
9390: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 0a 2a 2a igger context.**
93a0: 20 20 20 20 20 20 20 20 20 20 69 6d 6d 65 64 69 immedi
93b0: 61 74 65 6c 79 20 62 65 66 6f 72 65 20 61 6e 64 ately before and
93c0: 20 61 66 74 65 72 20 61 20 52 4f 4c 4c 42 41 43 after a ROLLBAC
93d0: 4b 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 K..**.** LIMITAT
93e0: 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 IONS:.**.** {U12
93f0: 32 33 32 7d 20 49 66 20 61 20 73 65 70 61 72 61 232} If a separa
9400: 74 65 20 74 68 72 65 61 64 20 64 6f 65 73 20 61 te thread does a
9410: 20 6e 65 77 20 69 6e 73 65 72 74 20 6f 6e 20 74 new insert on t
9420: 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 he same.**
9430: 20 20 20 20 64 61 74 61 62 61 73 65 20 63 6f 6e database con
9440: 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 nection while th
9450: 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f e [sqlite3_last_
9460: 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a insert_rowid()].
9470: 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 ** func
9480: 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 tion is running
9490: 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 and thus changes
94a0: 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 the last insert
94b0: 20 72 6f 77 69 64 2c 0a 2a 2a 20 20 20 20 20 20 rowid,.**
94c0: 20 20 20 20 74 68 65 6e 20 74 68 65 20 76 61 6c then the val
94d0: 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b ue returned by [
94e0: 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 sqlite3_last_ins
94f0: 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a ert_rowid()] is.
9500: 2a 2a 20 20 20 20 20 20 20 20 20 20 75 6e 70 72 ** unpr
9510: 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 edictable and mi
9520: 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 ght not equal ei
9530: 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 ther the old or
9540: 74 68 65 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 the new.**
9550: 20 20 20 20 6c 61 73 74 20 69 6e 73 65 72 74 20 last insert
9560: 72 6f 77 69 64 2e 0a 2a 2f 0a 73 71 6c 69 74 65 rowid..*/.sqlite
9570: 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 3_int64 sqlite3_
9580: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 last_insert_rowi
9590: 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a d(sqlite3*);../*
95a0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
95b0: 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f unt The Number O
95c0: 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 f Rows Modified
95d0: 7b 46 31 32 32 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 {F12240}.**.** T
95e0: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 his function ret
95f0: 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
9600: 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 of database rows
9610: 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 that were chang
9620: 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 ed.** or inserte
9630: 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 d or deleted by
9640: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c the most recentl
9650: 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 y completed SQL
9660: 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 statement.** on
9670: 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 the connection s
9680: 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 pecified by the
9690: 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e first parameter.
96a0: 20 20 4f 6e 6c 79 0a 2a 2a 20 63 68 61 6e 67 65 Only.** change
96b0: 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63 s that are direc
96c0: 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79 tly specified by
96d0: 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44 the INSERT, UPD
96e0: 41 54 45 2c 20 6f 72 0a 2a 2a 20 44 45 4c 45 54 ATE, or.** DELET
96f0: 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 E statement are
9700: 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 counted. Auxili
9710: 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 ary changes caus
9720: 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 ed by.** trigger
9730: 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 s are not counte
9740: 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 d. Use the [sqli
9750: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
9760: 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a s()] function.**
9770: 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 to find the tot
9780: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 al number of cha
9790: 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 63 nges including c
97a0: 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 hanges caused by
97b0: 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a triggers..**.**
97c0: 20 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 A "row change"
97d0: 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 is a change to a
97e0: 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 single row of a
97f0: 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a single table.**
9800: 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e caused by an IN
9810: 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 SERT, DELETE, or
9820: 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e UPDATE statemen
9830: 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a t. Rows that.**
9840: 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 are changed as
9850: 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 side effects of
9860: 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 REPLACE constrai
9870: 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a nt resolution,.*
9880: 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 * rollback, ABOR
9890: 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 44 52 T processing, DR
98a0: 4f 50 20 54 41 42 4c 45 2c 20 6f 72 20 62 79 20 OP TABLE, or by
98b0: 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 any other.** mec
98c0: 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 hanisms do not c
98d0: 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 ount as direct r
98e0: 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a ow changes..**.*
98f0: 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e * A "trigger con
9900: 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 text" is a scope
9910: 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 of execution th
9920: 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a at begins and.**
9930: 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 ends with the s
9940: 63 72 69 70 74 20 6f 66 20 61 20 74 72 69 67 67 cript of a trigg
9950: 65 72 2e 20 20 4d 6f 73 74 20 53 51 4c 20 73 74 er. Most SQL st
9960: 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 atements are.**
9970: 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 evaluated outsid
9980: 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 e of any trigger
9990: 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22 . This is the "
99a0: 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 top level".** tr
99b0: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 igger context.
99c0: 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72 If a trigger fir
99d0: 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 es from the top
99e0: 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 level, a.** new
99f0: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 trigger context
9a00: 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 is entered for t
9a10: 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 he duration of t
9a20: 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 hat one.** trigg
9a30: 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 er. Subtriggers
9a40: 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 create subconte
9a50: 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 xts for their du
9a60: 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 ration..**.** Ca
9a70: 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 lling [sqlite3_e
9a80: 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 xec()] or [sqlit
9a90: 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 e3_step()] recur
9aa0: 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e sively does.** n
9ab0: 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 ot create a new
9ac0: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e trigger context.
9ad0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 .**.** This func
9ae0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 tion returns the
9af0: 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 number of direc
9b00: 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e t row changes in
9b10: 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 the.** most rec
9b20: 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 ent INSERT, UPDA
9b30: 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 TE, or DELETE st
9b40: 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 atement within t
9b50: 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 he same.** trigg
9b60: 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a er context..**.*
9b70: 2a 20 53 6f 20 77 68 65 6e 20 63 61 6c 6c 65 64 * So when called
9b80: 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 from the top le
9b90: 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 vel, this functi
9ba0: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a on returns the.*
9bb0: 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e * number of chan
9bc0: 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 ges in the most
9bd0: 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 recent INSERT, U
9be0: 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 PDATE, or DELETE
9bf0: 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 .** that also oc
9c00: 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74 6f curred at the to
9c10: 70 20 6c 65 76 65 6c 2e 0a 2a 2a 20 57 69 74 68 p level..** With
9c20: 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 in the body of a
9c30: 20 74 72 69 67 67 65 72 2c 20 74 68 65 20 73 71 trigger, the sq
9c40: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 lite3_changes()
9c50: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 63 61 6e interface.** can
9c60: 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 be called to fi
9c70: 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 nd the number of
9c80: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 .** changes in t
9c90: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 he most recently
9ca0: 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 completed INSER
9cb0: 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 T, UPDATE, or DE
9cc0: 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e LETE.** statemen
9cd0: 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 t within the bod
9ce0: 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72 y of the same tr
9cf0: 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 igger..** Howeve
9d00: 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65 r, the number re
9d10: 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 turned does not
9d20: 69 6e 63 6c 75 64 65 20 69 6e 20 63 68 61 6e 67 include in chang
9d30: 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 es.** caused by
9d40: 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 subtriggers sinc
9d50: 65 20 74 68 65 79 20 68 61 76 65 20 74 68 65 69 e they have thei
9d60: 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 0a 2a r own context..*
9d70: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c *.** SQLite impl
9d80: 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 ements the comma
9d90: 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 nd "DELETE FROM
9da0: 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 0a 2a table" without.*
9db0: 2a 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 * a WHERE clause
9dc0: 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 by dropping and
9dd0: 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 recreating the
9de0: 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73 table. (This is
9df0: 20 6d 75 63 68 0a 2a 2a 20 66 61 73 74 65 72 20 much.** faster
9e00: 74 68 61 6e 20 67 6f 69 6e 67 20 74 68 72 6f 75 than going throu
9e10: 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 gh and deleting
9e20: 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 individual eleme
9e30: 6e 74 73 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 nts from the.**
9e40: 74 61 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 table.) Because
9e50: 20 6f 66 20 74 68 69 73 20 6f 70 74 69 6d 69 7a of this optimiz
9e60: 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 ation, the delet
9e70: 69 6f 6e 73 20 69 6e 0a 2a 2a 20 22 44 45 4c 45 ions in.** "DELE
9e80: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 TE FROM table" a
9e90: 72 65 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 re not row chang
9ea0: 65 73 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 20 es and will not
9eb0: 62 65 20 63 6f 75 6e 74 65 64 0a 2a 2a 20 62 79 be counted.** by
9ec0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 the sqlite3_cha
9ed0: 6e 67 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 nges() or [sqlit
9ee0: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
9ef0: 28 29 5d 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a ()] functions..*
9f00: 2a 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75 * To get an accu
9f10: 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 rate count of th
9f20: 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 e number of rows
9f30: 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a deleted, use.**
9f40: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 "DELETE FROM ta
9f50: 62 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e 73 ble WHERE 1" ins
9f60: 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 tead..**.** INVA
9f70: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 RIANTS:.**.** {F
9f80: 31 32 32 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 12241} The [sqli
9f90: 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 te3_changes()] f
9fa0: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
9fb0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a the number of.**
9fc0: 20 20 20 20 20 20 20 20 20 20 72 6f 77 20 63 68 row ch
9fd0: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 anges caused by
9fe0: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
9ff0: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 0a INSERT, UPDATE,.
a000: 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 44 ** or D
a010: 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 ELETE statement
a020: 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 on the same data
a030: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
a040: 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 and.**
a050: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 within the same
a060: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c trigger context,
a070: 20 6f 72 20 7a 65 72 6f 20 69 66 20 74 68 65 72 or zero if ther
a080: 65 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 e have.**
a090: 20 20 20 6e 6f 74 20 62 65 65 6e 20 61 6e 79 20 not been any
a0a0: 71 75 61 6c 69 66 79 69 6e 67 20 72 6f 77 20 63 qualifying row c
a0b0: 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 4c 49 hanges..**.** LI
a0c0: 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a MITATIONS:.**.**
a0d0: 20 7b 55 31 32 32 35 32 7d 20 49 66 20 61 20 73 {U12252} If a s
a0e0: 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d eparate thread m
a0f0: 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 akes changes on
a100: 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
a110: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
a120: 20 20 20 20 20 20 20 20 20 77 68 69 6c 65 20 5b while [
a130: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
a140: 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 )] is running th
a150: 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 en the value ret
a160: 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 urned.**
a170: 20 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 is unpredictab
a180: 6c 65 20 61 6e 64 20 75 6e 6d 65 61 6e 69 6e 67 le and unmeaning
a190: 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ful..*/.int sqli
a1a0: 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 te3_changes(sqli
a1b0: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
a1c0: 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 PI3REF: Total Nu
a1d0: 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 mber Of Rows Mod
a1e0: 69 66 69 65 64 20 7b 46 31 32 32 36 30 7d 0a 2a ified {F12260}.*
a1f0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 **.** This funct
a200: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 ion returns the
a210: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 number of row ch
a220: 61 6e 67 65 73 20 63 61 75 73 65 64 0a 2a 2a 20 anges caused.**
a230: 62 79 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 by INSERT, UPDAT
a240: 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 E or DELETE stat
a250: 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 ements since the
a260: 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 database handle
a270: 0a 2a 2a 20 77 61 73 20 6f 70 65 6e 65 64 2e 20 .** was opened.
a280: 20 54 68 65 20 63 6f 75 6e 74 20 69 6e 63 6c 75 The count inclu
a290: 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 20 des all changes
a2a0: 66 72 6f 6d 20 61 6c 6c 20 74 72 69 67 67 65 72 from all trigger
a2b0: 0a 2a 2a 20 63 6f 6e 74 65 78 74 73 2e 20 20 42 .** contexts. B
a2c0: 75 74 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 ut the count doe
a2d0: 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 s not include ch
a2e0: 61 6e 67 65 73 20 75 73 65 64 20 74 6f 0a 2a 2a anges used to.**
a2f0: 20 69 6d 70 6c 65 6d 65 6e 74 20 52 45 50 4c 41 implement REPLA
a300: 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 20 CE constraints,
a310: 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 do rollbacks or
a320: 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 ABORT processing
a330: 2c 0a 2a 2a 20 6f 72 20 44 52 4f 50 20 74 61 62 ,.** or DROP tab
a340: 6c 65 20 70 72 6f 63 65 73 73 69 6e 67 2e 0a 2a le processing..*
a350: 2a 20 54 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a * The changes.**
a360: 20 61 72 65 20 63 6f 75 6e 74 65 64 20 61 73 20 are counted as
a370: 73 6f 6f 6e 20 61 73 20 74 68 65 20 73 74 61 74 soon as the stat
a380: 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 ement that makes
a390: 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 them is complet
a3a0: 65 64 20 0a 2a 2a 20 28 77 68 65 6e 20 74 68 65 ed .** (when the
a3b0: 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c statement handl
a3c0: 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b e is passed to [
a3d0: 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
a3e0: 20 6f 72 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 or .** [sqlite3
a3f0: 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a _finalize()])..*
a400: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c *.** SQLite impl
a410: 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 ements the comma
a420: 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 nd "DELETE FROM
a430: 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 0a 2a table" without.*
a440: 2a 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 * a WHERE clause
a450: 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 by dropping and
a460: 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 recreating the
a470: 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73 table. (This is
a480: 20 6d 75 63 68 0a 2a 2a 20 66 61 73 74 65 72 20 much.** faster
a490: 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 than going.** th
a4a0: 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 rough and deleti
a4b0: 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c ng individual el
a4c0: 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 ements from the
a4d0: 74 61 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 table.) Because
a4e0: 20 6f 66 0a 2a 2a 20 74 68 69 73 20 6f 70 74 69 of.** this opti
a4f0: 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 63 68 mization, the ch
a500: 61 6e 67 65 20 63 6f 75 6e 74 20 66 6f 72 20 22 ange count for "
a510: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c DELETE FROM tabl
a520: 65 22 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 7a 65 e" will be.** ze
a530: 72 6f 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 ro regardless of
a540: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 the number of e
a550: 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 lements that wer
a560: 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 e originally in
a570: 74 68 65 0a 2a 2a 20 74 61 62 6c 65 2e 20 54 6f the.** table. To
a580: 20 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 get an accurate
a590: 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 count of the nu
a5a0: 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c mber of rows del
a5b0: 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 eted, use.** "DE
a5c0: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 LETE FROM table
a5d0: 57 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 WHERE 1" instead
a5e0: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
a5f0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 the [sqlite3_ch
a600: 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 anges()] interfa
a610: 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 ce..**.** INVARI
a620: 41 4e 54 53 3a 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 ANTS:.** .** {F1
a630: 32 32 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 2261} The [sqlit
a640: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
a650: 28 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65 20 ()] returns the
a660: 74 6f 74 61 6c 20 6e 75 6d 62 65 72 0a 2a 2a 20 total number.**
a670: 20 20 20 20 20 20 20 20 20 6f 66 20 72 6f 77 20 of row
a680: 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 changes caused b
a690: 79 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 y INSERT, UPDATE
a6a0: 2c 20 61 6e 64 2f 6f 72 20 44 45 4c 45 54 45 0a , and/or DELETE.
a6b0: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 61 74 ** stat
a6c0: 65 6d 65 6e 74 73 20 6f 6e 20 74 68 65 20 73 61 ements on the sa
a6d0: 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e me [database con
a6e0: 6e 65 63 74 69 6f 6e 5d 2c 20 69 6e 20 61 6e 79 nection], in any
a6f0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 72 69 .** tri
a700: 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 73 69 gger context, si
a710: 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73 65 nce the database
a720: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 0a connection was.
a730: 2a 2a 20 20 20 20 20 20 20 20 20 20 63 72 65 61 ** crea
a740: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 ted..**.** LIMIT
a750: 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 ATIONS:.**.** {U
a760: 31 32 32 36 34 7d 20 49 66 20 61 20 73 65 70 61 12264} If a sepa
a770: 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 rate thread make
a780: 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 s changes on the
a790: 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 same database c
a7a0: 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 onnection.**
a7b0: 20 20 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c while [sql
a7c0: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
a7d0: 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 es()] is running
a7e0: 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 then the value
a7f0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 .** ret
a800: 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 urned is unpredi
a810: 63 74 61 62 6c 65 20 61 6e 64 20 75 6e 6d 65 61 ctable and unmea
a820: 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 ningful..*/.int
a830: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
a840: 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b anges(sqlite3*);
a850: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
a860: 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f : Interrupt A Lo
a870: 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 ng-Running Query
a880: 20 7b 46 31 32 32 37 30 7d 0a 2a 2a 0a 2a 2a 20 {F12270}.**.**
a890: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 This function ca
a8a0: 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 uses any pending
a8b0: 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 database operat
a8c0: 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 ion to abort and
a8d0: 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 .** return at it
a8e0: 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 s earliest oppor
a8f0: 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 tunity. This rou
a900: 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c tine is typicall
a910: 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 y.** called in r
a920: 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 esponse to a use
a930: 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 r action such as
a940: 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 pressing "Cance
a950: 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 l".** or Ctrl-C
a960: 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 where the user w
a970: 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 ants a long quer
a980: 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 y operation to h
a990: 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 alt.** immediate
a9a0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 ly..**.** It is
a9b0: 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 safe to call thi
a9c0: 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 s routine from a
a9d0: 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e thread differen
a9e0: 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 t from the.** th
a9f0: 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 read that is cur
aa00: 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 rently running t
aa10: 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 he database oper
aa20: 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a ation. But it.*
aa30: 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f * is not safe to
aa40: 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 call this routi
aa50: 6e 65 20 77 69 74 68 20 61 20 64 61 74 61 62 61 ne with a databa
aa60: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 se connection th
aa70: 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 at.** is closed
aa80: 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 or might close b
aa90: 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e efore sqlite3_in
aaa0: 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e terrupt() return
aab0: 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 53 s..**.** If an S
aac0: 51 4c 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c QL is very nearl
aad0: 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 y finished at th
aae0: 65 20 74 69 6d 65 20 77 68 65 6e 20 73 71 6c 69 e time when sqli
aaf0: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 0a te3_interrupt().
ab00: 2a 2a 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 ** is called, th
ab10: 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 en it might not
ab20: 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e have an opportun
ab30: 69 74 79 20 74 6f 20 62 65 20 69 6e 74 65 72 72 ity to be interr
ab40: 75 70 74 65 64 2e 0a 2a 2a 20 49 74 20 6d 69 67 upted..** It mig
ab50: 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 ht continue to c
ab60: 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 20 41 6e ompletion..** An
ab70: 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 SQL operation t
ab80: 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 hat is interrupt
ab90: 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a ed will return.*
aba0: 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 * [SQLITE_INTERR
abb0: 55 50 54 5d 2e 20 20 49 66 20 74 68 65 20 69 6e UPT]. If the in
abc0: 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 terrupted SQL op
abd0: 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 0a 2a 2a eration is an.**
abe0: 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c INSERT, UPDATE,
abf0: 20 6f 72 20 44 45 4c 45 54 45 20 74 68 61 74 20 or DELETE that
ac00: 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 is inside an exp
ac10: 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f licit transactio
ac20: 6e 2c 20 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 n, .** then the
ac30: 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 entire transacti
ac40: 6f 6e 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 on will be rolle
ac50: 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 d back automatic
ac60: 61 6c 6c 79 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 ally..** A call
ac70: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 to sqlite3_inter
ac80: 72 75 70 74 28 29 20 68 61 73 20 6e 6f 20 65 66 rupt() has no ef
ac90: 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 fect on SQL stat
aca0: 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 ements.** that a
acb0: 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 re started after
acc0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
acd0: 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a pt() returns..**
ace0: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
acf0: 2a 2a 0a 2a 2a 20 7b 46 31 32 32 37 31 7d 20 54 **.** {F12271} T
ad00: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 he [sqlite3_inte
ad10: 72 72 75 70 74 28 29 5d 20 69 6e 74 65 72 66 61 rrupt()] interfa
ad20: 63 65 20 77 69 6c 6c 20 66 6f 72 63 65 20 61 6c ce will force al
ad30: 6c 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20 l running.**
ad40: 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d SQL statem
ad50: 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 ents associated
ad60: 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 64 61 with the same da
ad70: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
ad80: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f n.** to
ad90: 20 68 61 6c 74 20 61 66 74 65 72 20 70 72 6f 63 halt after proc
ada0: 65 73 73 69 6e 67 20 61 74 20 6d 6f 73 74 20 6f essing at most o
adb0: 6e 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 6f ne additional ro
adc0: 77 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 w of.**
add0: 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 data..**.** {F1
ade0: 32 32 37 32 7d 20 41 6e 79 20 53 51 4c 20 73 74 2272} Any SQL st
adf0: 61 74 65 6d 65 6e 74 20 74 68 61 74 20 69 73 20 atement that is
ae00: 69 6e 74 65 72 72 75 70 74 65 64 20 62 79 20 5b interrupted by [
ae10: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
ae20: 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 t()].**
ae30: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 will return [SQ
ae40: 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e LITE_INTERRUPT].
ae50: 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f .**.** LIMITATIO
ae60: 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 37 NS:.**.** {U1227
ae70: 39 7d 20 49 66 20 74 68 65 20 64 61 74 61 62 61 9} If the databa
ae80: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c se connection cl
ae90: 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 oses while [sqli
aea0: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d te3_interrupt()]
aeb0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 .** is
aec0: 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 running then bad
aed0: 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b things will lik
aee0: 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 ely happen..*/.v
aef0: 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 oid sqlite3_inte
af00: 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b rrupt(sqlite3*);
af10: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
af20: 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 : Determine If A
af30: 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 n SQL Statement
af40: 49 73 20 43 6f 6d 70 6c 65 74 65 20 7b 46 31 30 Is Complete {F10
af50: 35 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 510}.**.** These
af60: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 routines are us
af70: 65 66 75 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 eful for command
af80: 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 -line input to d
af90: 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a etermine if the.
afa0: 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 ** currently ent
afb0: 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 ered text seems
afc0: 74 6f 20 66 6f 72 6d 20 63 6f 6d 70 6c 65 74 65 to form complete
afd0: 20 61 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 a SQL statement
afe0: 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 or.** if additi
aff0: 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 onal input is ne
b000: 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 eded before send
b010: 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 ing the text int
b020: 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 o.** SQLite for
b030: 70 61 72 73 69 6e 67 2e 20 20 54 68 65 73 65 20 parsing. These
b040: 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
b050: 74 72 75 65 20 69 66 20 74 68 65 20 69 6e 70 75 true if the inpu
b060: 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 t string.** appe
b070: 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 ars to be a comp
b080: 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 lete SQL stateme
b090: 6e 74 2e 20 20 41 20 73 74 61 74 65 6d 65 6e 74 nt. A statement
b0a0: 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 is judged to be
b0b0: 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 .** complete if
b0c0: 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 it ends with a s
b0d0: 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 emicolon token a
b0e0: 6e 64 20 69 73 20 6e 6f 74 20 61 20 66 72 61 67 nd is not a frag
b0f0: 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 43 52 45 ment of a.** CRE
b100: 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 ATE TRIGGER stat
b110: 65 6d 65 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f ement. Semicolo
b120: 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 ns that are embe
b130: 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 dded within.** s
b140: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f tring literals o
b150: 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 r quoted identif
b160: 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d ier names or com
b170: 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a ments are not.**
b180: 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b independent tok
b190: 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 ens (they are pa
b1a0: 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 rt of the token
b1b0: 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 in which they ar
b1c0: 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 e.** embedded) a
b1d0: 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 nd thus do not c
b1e0: 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d ount as a statem
b1f0: 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a ent terminator..
b200: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
b210: 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 ines do not pars
b220: 65 20 74 68 65 20 53 51 4c 20 61 6e 64 0a 2a 2a e the SQL and.**
b230: 20 73 6f 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 so will not det
b240: 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c ect syntacticall
b250: 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e y incorrect SQL.
b260: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
b270: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 31 31 S:.**.** {F10511
b280: 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f } The sqlite3_co
b290: 6d 70 6c 65 74 65 28 29 20 61 6e 64 20 73 71 6c mplete() and sql
b2a0: 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 ite3_complete16(
b2b0: 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 20 ) functions.**
b2c0: 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 74 return t
b2d0: 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 rue (non-zero) i
b2e0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 f and only if th
b2f0: 65 20 6c 61 73 74 0a 2a 2a 20 20 20 20 20 20 20 e last.**
b300: 20 20 20 6e 6f 6e 2d 77 68 69 74 65 73 70 61 63 non-whitespac
b310: 65 20 74 6f 6b 65 6e 20 69 6e 20 74 68 65 69 72 e token in their
b320: 20 69 6e 70 75 74 20 69 73 20 61 20 73 65 6d 69 input is a semi
b330: 63 6f 6c 6f 6e 20 74 68 61 74 0a 2a 2a 20 20 20 colon that.**
b340: 20 20 20 20 20 20 20 69 73 20 6e 6f 74 20 69 6e is not in
b350: 20 62 65 74 77 65 65 6e 20 74 68 65 20 42 45 47 between the BEG
b360: 49 4e 20 61 6e 64 20 45 4e 44 20 6f 66 20 61 20 IN and END of a
b370: 43 52 45 41 54 45 20 54 52 49 47 47 45 52 0a 2a CREATE TRIGGER.*
b380: 2a 20 20 20 20 20 20 20 20 20 20 73 74 61 74 65 * state
b390: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 ment..**.** LIMI
b3a0: 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b TATIONS:.**.** {
b3b0: 55 31 30 35 31 32 7d 20 54 68 65 20 69 6e 70 75 U10512} The inpu
b3c0: 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d t to sqlite3_com
b3d0: 70 6c 65 74 65 28 29 20 6d 75 73 74 20 62 65 20 plete() must be
b3e0: 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
b3f0: 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54 d.** UT
b400: 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a F-8 string..**.*
b410: 2a 20 7b 55 31 30 35 31 33 7d 20 54 68 65 20 69 * {U10513} The i
b420: 6e 70 75 74 20 74 6f 20 73 71 6c 69 74 65 33 5f nput to sqlite3_
b430: 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 6d 75 73 complete16() mus
b440: 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d t be a zero-term
b450: 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 inated.**
b460: 20 20 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 UTF-16 string
b470: 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 in native byte
b480: 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 order..*/.int sq
b490: 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 lite3_complete(c
b4a0: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b onst char *sql);
b4b0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d .int sqlite3_com
b4c0: 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f plete16(const vo
b4d0: 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a id *sql);../*.**
b4e0: 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 CAPI3REF: Regis
b4f0: 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 ter A Callback T
b500: 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f o Handle SQLITE_
b510: 42 55 53 59 20 45 72 72 6f 72 73 20 7b 46 31 32 BUSY Errors {F12
b520: 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 310}.**.** This
b530: 72 6f 75 74 69 6e 65 20 69 64 65 6e 74 69 66 69 routine identifi
b540: 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 es a callback fu
b550: 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 nction that migh
b560: 74 20 62 65 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 t be.** invoked
b570: 77 68 65 6e 65 76 65 72 20 61 6e 20 61 74 74 65 whenever an atte
b580: 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f mpt is made to o
b590: 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 pen a database t
b5a0: 61 62 6c 65 20 0a 2a 2a 20 74 68 61 74 20 61 6e able .** that an
b5b0: 6f 74 68 65 72 20 74 68 72 65 61 64 20 6f 72 20 other thread or
b5c0: 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b process has lock
b5d0: 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 ed..** If the bu
b5e0: 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e sy callback is N
b5f0: 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 ULL, then [SQLIT
b600: 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 E_BUSY].** or [S
b610: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 QLITE_IOERR_BLOC
b620: 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 KED].** is retur
b630: 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 ned immediately
b640: 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e upon encounterin
b650: 67 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 49 g the lock..** I
b660: 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 f the busy callb
b670: 61 63 6b 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c ack is not NULL,
b680: 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 63 61 6c then the.** cal
b690: 6c 62 61 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e lback will be in
b6a0: 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 voked with two a
b6b0: 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 0a 2a rguments. The.*
b6c0: 2a 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 * first argument
b6d0: 20 74 6f 20 74 68 65 20 68 61 6e 64 6c 65 72 20 to the handler
b6e0: 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 is a copy of the
b6f0: 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 void* pointer w
b700: 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 hich.** is the t
b710: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f hird argument to
b720: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 20 20 this routine.
b730: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d The second argum
b740: 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61 ent to.** the ha
b750: 6e 64 6c 65 72 20 69 73 20 74 68 65 20 6e 75 6d ndler is the num
b760: 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 ber of times tha
b770: 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c t the busy handl
b780: 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 er has.** been i
b790: 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 nvoked for this
b7a0: 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 locking event.
b7b0: 20 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 If the.** busy
b7c0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
b7d0: 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 0, then no addi
b7e0: 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 tional attempts
b7f0: 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 are made to.** a
b800: 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 ccess the databa
b810: 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 se and [SQLITE_B
b820: 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f USY] or [SQLITE_
b830: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 IOERR_BLOCKED] i
b840: 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 s returned..** I
b850: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 f the callback r
b860: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c eturns non-zero,
b870: 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 then another at
b880: 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 tempt.** is made
b890: 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 to open the dat
b8a0: 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e abase for readin
b8b0: 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 g and the cycle
b8c0: 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 repeats..**.** T
b8d0: 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 he presence of a
b8e0: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f busy handler do
b8f0: 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 es not guarantee
b900: 20 74 68 61 74 0a 2a 2a 20 69 74 20 77 69 6c 6c that.** it will
b910: 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e be invoked when
b920: 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 there is lock c
b930: 6f 6e 74 65 6e 74 69 6f 6e 2e 0a 2a 2a 20 49 66 ontention..** If
b940: 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e SQLite determin
b950: 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 es that invoking
b960: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
b970: 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 r could result i
b980: 6e 0a 2a 2a 20 61 20 64 65 61 64 6c 6f 63 6b 2c n.** a deadlock,
b990: 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 it will go ahea
b9a0: 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 d and return [SQ
b9b0: 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 0a 2a 2a LITE_BUSY] or.**
b9c0: 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 [SQLITE_IOERR_B
b9d0: 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 LOCKED] instead
b9e0: 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 0a of invoking the.
b9f0: 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e ** busy handler.
ba00: 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 .** Consider a s
ba10: 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e cenario where on
ba20: 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c e process is hol
ba30: 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b ding a read lock
ba40: 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 that.** it is t
ba50: 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 rying to promote
ba60: 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c to a reserved l
ba70: 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 ock and.** a sec
ba80: 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 ond process is h
ba90: 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 olding a reserve
baa0: 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 d lock that it i
bab0: 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 s trying.** to p
bac0: 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 romote to an exc
bad0: 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 lusive lock. Th
bae0: 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 e first process
baf0: 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a cannot proceed.*
bb00: 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 * because it is
bb10: 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 blocked by the s
bb20: 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 econd and the se
bb30: 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e cond process can
bb40: 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 not.** proceed b
bb50: 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f ecause it is blo
bb60: 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 cked by the firs
bb70: 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 t. If both proc
bb80: 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 esses.** invoke
bb90: 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
bba0: 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 s, neither will
bbb0: 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 make any progres
bbc0: 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a s. Therefore,.*
bbd0: 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 * SQLite returns
bbe0: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 [SQLITE_BUSY] f
bbf0: 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f or the first pro
bc00: 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 cess, hoping tha
bc10: 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 t this.** will i
bc20: 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 nduce the first
bc30: 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 process to relea
bc40: 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b se its read lock
bc50: 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 and allow.** th
bc60: 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 e second process
bc70: 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a to proceed..**.
bc80: 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 62 ** The default b
bc90: 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 usy callback is
bca0: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 NULL..**.** The
bcb0: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 [SQLITE_BUSY] er
bcc0: 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 ror is converted
bcd0: 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 to [SQLITE_IOER
bce0: 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 R_BLOCKED].** wh
bcf0: 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 en SQLite is in
bd00: 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 the middle of a
bd10: 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f large transactio
bd20: 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a n where all the.
bd30: 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 ** changes will
bd40: 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 not fit into the
bd50: 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 in-memory cache
bd60: 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a . SQLite will.*
bd70: 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 * already hold a
bd80: 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f RESERVED lock o
bd90: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 n the database f
bda0: 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 ile, but it need
bdb0: 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 s.** to promote
bdc0: 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 this lock to EXC
bdd0: 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 LUSIVE so that i
bde0: 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 t can spill cach
bdf0: 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 e.** pages into
be00: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
be10: 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 e without harm t
be20: 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 o concurrent.**
be30: 72 65 61 64 65 72 73 2e 20 20 49 66 20 69 74 20 readers. If it
be40: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f is unable to pro
be50: 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 mote the lock, t
be60: 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 hen the in-memor
be70: 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 y.** cache will
be80: 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e be left in an in
be90: 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 consistent state
bea0: 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f and so the erro
beb0: 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f r.** code is pro
bec0: 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 moted from the r
bed0: 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e elatively benign
bee0: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 [SQLITE_BUSY] t
bef0: 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 o.** the more se
bf00: 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 vere [SQLITE_IOE
bf10: 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 RR_BLOCKED]. Th
bf20: 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 is error code pr
bf30: 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 omotion.** force
bf40: 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 s an automatic r
bf50: 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 ollback of the c
bf60: 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 hanges. See the
bf70: 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 .** <a href="htt
bf80: 70 3a 2f 2f 77 77 77 2e 73 71 6c 69 74 65 2e 6f p://www.sqlite.o
bf90: 72 67 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f rg/cvstrac/wiki?
bfa0: 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c p=CorruptionFoll
bfb0: 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e owingBusyError">
bfc0: 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f .** CorruptionFo
bfd0: 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 llowingBusyError
bfe0: 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 </a> wiki page f
bff0: 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 or a discussion
c000: 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 of why.** this i
c010: 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 09 s important..**.
c020: 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e .** There can on
c030: 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 ly be a single b
c040: 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 usy handler defi
c050: 6e 65 64 20 66 6f 72 20 65 61 63 68 20 64 61 74 ned for each dat
c060: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 abase.** connect
c070: 69 6f 6e 2e 20 20 53 65 74 74 69 6e 67 20 61 20 ion. Setting a
c080: 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 new busy handler
c090: 20 63 6c 65 61 72 73 20 61 6e 79 20 70 72 65 76 clears any prev
c0a0: 69 6f 75 73 20 6f 6e 65 2e 20 0a 2a 2a 20 4e 6f ious one. .** No
c0b0: 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 te that calling
c0c0: 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 [sqlite3_busy_ti
c0d0: 6d 65 6f 75 74 28 29 5d 20 77 69 6c 6c 20 61 6c meout()] will al
c0e0: 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 0a so set or clear.
c0f0: 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ** the busy hand
c100: 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 ler..**.** INVAR
c110: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 IANTS:.**.** {F1
c120: 32 33 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 2311} The [sqlit
c130: 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 e3_busy_handler(
c140: 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c )] function repl
c150: 61 63 65 73 20 74 68 65 20 62 75 73 79 20 68 61 aces the busy ha
c160: 6e 64 6c 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 ndler.**
c170: 20 20 63 61 6c 6c 62 61 63 6b 20 69 6e 20 74 68 callback in th
c180: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
c190: 63 74 69 6f 6e 20 69 64 65 6e 74 69 66 69 65 64 ction identified
c1a0: 20 62 79 20 74 68 65 20 31 73 74 0a 2a 2a 20 20 by the 1st.**
c1b0: 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 paramete
c1c0: 72 20 77 69 74 68 20 61 20 6e 65 77 20 62 75 73 r with a new bus
c1d0: 79 20 68 61 6e 64 6c 65 72 20 69 64 65 6e 74 69 y handler identi
c1e0: 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 fied by the 2nd
c1f0: 61 6e 64 20 33 72 64 0a 2a 2a 20 20 20 20 20 20 and 3rd.**
c200: 20 20 20 20 70 61 72 61 6d 65 74 65 72 73 2e 0a parameters..
c210: 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 32 7d 20 54 **.** {F12312} T
c220: 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 he default busy
c230: 68 61 6e 64 6c 65 72 20 66 6f 72 20 6e 65 77 20 handler for new
c240: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
c250: 69 6f 6e 73 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a ions is NULL..**
c260: 0a 2a 2a 20 7b 46 31 32 33 31 34 7d 20 57 68 65 .** {F12314} Whe
c270: 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 64 61 n two or more da
c280: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
c290: 6e 20 73 68 61 72 65 20 61 20 63 6f 6d 6d 6f 6e n share a common
c2a0: 20 63 61 63 68 65 2c 0a 2a 2a 20 20 20 20 20 20 cache,.**
c2b0: 20 20 20 20 74 68 65 20 62 75 73 79 20 68 61 6e the busy han
c2c0: 64 6c 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 dler for the dat
c2d0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
c2e0: 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 currently using
c2f0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
c300: 20 63 61 63 68 65 20 69 73 20 69 6e 76 6f 6b 65 cache is invoke
c310: 64 20 77 68 65 6e 20 74 68 65 20 63 61 63 68 65 d when the cache
c320: 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 6c 6f encounters a lo
c330: 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 ck..**.** {F1231
c340: 36 7d 20 49 66 20 61 20 62 75 73 79 20 68 61 6e 6} If a busy han
c350: 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 dler callback re
c360: 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 6e turns zero, then
c370: 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 20 the SQLite.**
c380: 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 interfac
c390: 65 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 e that provoked
c3a0: 74 68 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e the locking even
c3b0: 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a t will return.**
c3c0: 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 [SQLIT
c3d0: 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b E_BUSY]..**.** {
c3e0: 46 31 32 33 31 38 7d 20 53 51 4c 69 74 65 20 77 F12318} SQLite w
c3f0: 69 6c 6c 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 ill invokes the
c400: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 77 69 74 busy handler wit
c410: 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 20 77 h two argument w
c420: 68 69 63 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 hich.**
c430: 20 61 72 65 20 61 20 63 6f 70 79 20 6f 66 20 74 are a copy of t
c440: 68 65 20 70 6f 69 6e 74 65 72 20 73 75 70 70 6c he pointer suppl
c450: 69 65 64 20 62 79 20 74 68 65 20 33 72 64 20 70 ied by the 3rd p
c460: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 arameter to.**
c470: 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
c480: 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d _busy_handler()]
c490: 20 61 6e 64 20 61 20 63 6f 75 6e 74 20 6f 66 20 and a count of
c4a0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 72 the number of pr
c4b0: 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ior.**
c4c0: 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 invocations of t
c4d0: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 he busy handler
c4e0: 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 for the same loc
c4f0: 6b 69 6e 67 20 65 76 65 6e 74 2e 0a 2a 2a 0a 2a king event..**.*
c500: 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a * LIMITATIONS:.*
c510: 2a 0a 2a 2a 20 7b 55 31 32 33 31 39 7d 20 41 20 *.** {U12319} A
c520: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 73 68 6f busy handler sho
c530: 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 63 6c 6f uld not call clo
c540: 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 se the database
c550: 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 connection.**
c560: 20 20 20 20 20 20 20 6f 72 20 70 72 65 70 61 72 or prepar
c570: 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 ed statement tha
c580: 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 t invoked the bu
c590: 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 sy handler..*/.i
c5a0: 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f nt sqlite3_busy_
c5b0: 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a handler(sqlite3*
c5c0: 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 , int(*)(void*,i
c5d0: 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a nt), void*);../*
c5e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 .** CAPI3REF: Se
c5f0: 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 t A Busy Timeout
c600: 20 7b 46 31 32 33 34 30 7d 0a 2a 2a 0a 2a 2a 20 {F12340}.**.**
c610: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 This routine set
c620: 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 s a [sqlite3_bus
c630: 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 y_handler | busy
c640: 20 68 61 6e 64 6c 65 72 5d 0a 2a 2a 20 74 68 61 handler].** tha
c650: 74 20 73 6c 65 65 70 73 20 66 6f 72 20 61 20 77 t sleeps for a w
c660: 68 69 6c 65 20 77 68 65 6e 20 61 0a 2a 2a 20 74 hile when a.** t
c670: 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 able is locked.
c680: 20 54 68 65 20 68 61 6e 64 6c 65 72 20 77 69 6c The handler wil
c690: 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 l sleep multiple
c6a0: 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 0a 2a 2a times until .**
c6b0: 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d at least "ms" m
c6c0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 illiseconds of s
c6d0: 6c 65 65 70 69 6e 67 20 68 61 76 65 20 62 65 65 leeping have bee
c6e0: 6e 20 64 6f 6e 65 2e 20 7b 46 31 32 33 34 33 7d n done. {F12343}
c6f0: 20 41 66 74 65 72 0a 2a 2a 20 22 6d 73 22 20 6d After.** "ms" m
c700: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 illiseconds of s
c710: 6c 65 65 70 69 6e 67 2c 20 74 68 65 20 68 61 6e leeping, the han
c720: 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 dler returns 0 w
c730: 68 69 63 68 0a 2a 2a 20 63 61 75 73 65 73 20 5b hich.** causes [
c740: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
c750: 74 6f 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 to return [SQLIT
c760: 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 E_BUSY] or [SQLI
c770: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 TE_IOERR_BLOCKED
c780: 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 ]..**.** Calling
c790: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 this routine wi
c7a0: 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c th an argument l
c7b0: 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 ess than or equa
c7c0: 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 l to zero.** tur
c7d0: 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 ns off all busy
c7e0: 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 handlers..**.**
c7f0: 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 There can only b
c800: 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 e a single busy
c810: 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 handler for a pa
c820: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 rticular databas
c830: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e e.** connection.
c840: 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 If another bus
c850: 79 20 68 61 6e 64 6c 65 72 20 77 61 73 20 64 65 y handler was de
c860: 66 69 6e 65 64 20 20 0a 2a 2a 20 28 75 73 69 6e fined .** (usin
c870: 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f g [sqlite3_busy_
c880: 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f handler()]) prio
c890: 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 r to calling.**
c8a0: 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 this routine, th
c8b0: 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 at other busy ha
c8c0: 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 ndler is cleared
c8d0: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
c8e0: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 TS:.**.** {F1234
c8f0: 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 1} The [sqlite3_
c900: 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 busy_timeout()]
c910: 66 75 6e 63 74 69 6f 6e 20 6f 76 65 72 72 69 64 function overrid
c920: 65 73 20 61 6e 79 20 70 72 69 6f 72 0a 2a 2a 20 es any prior.**
c930: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
c940: 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 3_busy_timeout()
c950: 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 62 75 ] or [sqlite3_bu
c960: 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 73 65 sy_handler()] se
c970: 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 tting.**
c980: 20 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 on the same da
c990: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
c9a0: 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 33 n..**.** {F12343
c9b0: 7d 20 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 } If the 2nd par
c9c0: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 ameter to [sqlit
c9d0: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 e3_busy_timeout(
c9e0: 29 5d 20 69 73 20 6c 65 73 73 20 74 68 61 6e 0a )] is less than.
c9f0: 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 65 ** or e
ca00: 71 75 61 6c 20 74 6f 20 7a 65 72 6f 2c 20 74 68 qual to zero, th
ca10: 65 6e 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 en the busy hand
ca20: 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 20 73 ler is cleared s
ca30: 6f 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 o that.**
ca40: 20 20 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e all subsequen
ca50: 74 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 73 t locking events
ca60: 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 72 65 74 immediately ret
ca70: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 urn [SQLITE_BUSY
ca80: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 34 ]..**.** {F12344
ca90: 7d 20 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 } If the 2nd par
caa0: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 ameter to [sqlit
cab0: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 e3_busy_timeout(
cac0: 29 5d 20 69 73 20 61 20 70 6f 73 69 74 69 76 65 )] is a positive
cad0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d .** num
cae0: 62 65 72 20 4e 2c 20 74 68 65 6e 20 61 20 62 75 ber N, then a bu
caf0: 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 73 65 sy handler is se
cb00: 74 20 74 68 61 74 20 72 65 70 65 61 74 65 64 6c t that repeatedl
cb10: 79 20 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 y calls.**
cb20: 20 20 20 20 74 68 65 20 78 53 6c 65 65 70 28 29 the xSleep()
cb30: 20 6d 65 74 68 6f 64 20 69 6e 20 74 68 65 20 56 method in the V
cb40: 46 53 20 69 6e 74 65 72 66 61 63 65 20 75 6e 74 FS interface unt
cb50: 69 6c 20 65 69 74 68 65 72 20 74 68 65 0a 2a 2a il either the.**
cb60: 20 20 20 20 20 20 20 20 20 20 6c 6f 63 6b 20 63 lock c
cb70: 6c 65 61 72 73 20 6f 72 20 75 6e 74 69 6c 20 74 lears or until t
cb80: 68 65 20 63 75 6d 75 6c 61 74 69 76 65 20 73 6c he cumulative sl
cb90: 65 65 70 20 74 69 6d 65 20 72 65 70 6f 72 74 65 eep time reporte
cba0: 64 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 d back.**
cbb0: 20 20 20 62 79 20 78 53 6c 65 65 70 28 29 20 65 by xSleep() e
cbc0: 78 63 65 65 64 73 20 4e 20 6d 69 6c 6c 69 73 65 xceeds N millise
cbd0: 63 6f 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 conds..*/.int sq
cbe0: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f lite3_busy_timeo
cbf0: 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 ut(sqlite3*, int
cc00: 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ms);../*.** CAP
cc10: 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e I3REF: Convenien
cc20: 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 ce Routines For
cc30: 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 20 Running Queries
cc40: 7b 46 31 32 33 37 30 7d 0a 2a 2a 0a 2a 2a 20 44 {F12370}.**.** D
cc50: 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e efinition: A <b>
cc60: 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e result table</b>
cc70: 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 is memory data
cc80: 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 structure create
cc90: 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c d by the.** [sql
cca0: 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
ccb0: 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 ] interface. A
ccc0: 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 result table rec
ccd0: 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 ords the.** comp
cce0: 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c lete query resul
ccf0: 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d ts from one or m
cd00: 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a ore queries..**.
cd10: 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e ** The table con
cd20: 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 ceptually has a
cd30: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 number of rows a
cd40: 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 nd columns. But
cd50: 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 .** these number
cd60: 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f s are not part o
cd70: 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 f the result tab
cd80: 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 le itself. Thes
cd90: 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 e.** numbers are
cda0: 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 obtained separa
cdb0: 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 tely. Let N be
cdc0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f the number of ro
cdd0: 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 ws.** and M be t
cde0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c he number of col
cdf0: 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 umns..**.** A re
ce00: 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e sult table is an
ce10: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 array of pointe
ce20: 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 rs to zero-termi
ce30: 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 nated.** UTF-8 s
ce40: 74 72 69 6e 67 73 2e 20 20 54 68 65 72 65 20 61 trings. There a
ce50: 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 re (N+1)*M eleme
ce60: 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 nts in the array
ce70: 2e 20 20 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 . .** The first
ce80: 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e M pointers poin
ce90: 74 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e t to zero-termin
cea0: 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 ated strings tha
ceb0: 74 20 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 74 68 t .** contain th
cec0: 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 e names of the c
ced0: 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 olumns..** The r
cee0: 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 emaining entries
cef0: 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 all point to qu
cf00: 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 ery results. NU
cf10: 4c 4c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 72 65 LL.** values are
cf20: 20 67 69 76 65 20 61 20 4e 55 4c 4c 20 70 6f 69 give a NULL poi
cf30: 6e 74 65 72 2e 20 20 41 6c 6c 20 6f 74 68 65 72 nter. All other
cf40: 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 0a 2a values are in.*
cf50: 2a 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 * their UTF-8 ze
cf60: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 ro-terminated st
cf70: 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 ring representat
cf80: 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 ion as returned
cf90: 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 by.** [sqlite3_c
cfa0: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a olumn_text()]..*
cfb0: 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 *.** A result ta
cfc0: 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 ble might consis
cfd0: 74 73 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 ts of one or mor
cfe0: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
cff0: 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e ions..** It is n
d000: 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 ot safe to pass
d010: 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 a result table d
d020: 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 irectly to [sqli
d030: 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 te3_free()]..**
d040: 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 A result table s
d050: 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 hould be dealloc
d060: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 ated using [sqli
d070: 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 te3_free_table()
d080: 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 ]..**.** As an e
d090: 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 xample of the re
d0a0: 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 sult table forma
d0b0: 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 t, suppose a que
d0c0: 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 ry result.** is
d0d0: 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a as follows:.**.*
d0e0: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
d0f0: 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 re>.** Na
d100: 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a me | Age.
d110: 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d ** ------
d120: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
d130: 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 -.** Alic
d140: 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 e | 43.**
d150: 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 Bob
d160: 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 | 28.**
d170: 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 Cindy |
d180: 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 21.** </pre></bl
d190: 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
d1a0: 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f There are two co
d1b0: 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 lumn (M==2) and
d1c0: 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 three rows (N==3
d1d0: 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 ). Thus the.**
d1e0: 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 result table has
d1f0: 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 8 entries. Sup
d200: 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 pose the result
d210: 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a table is stored.
d220: 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e ** in an array n
d230: 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 ames azResult.
d240: 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f Then azResult ho
d250: 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 lds this content
d260: 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
d270: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 ote><pre>.**
d280: 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
d290: 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a ;0] = "Name";.**
d2a0: 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
d2b0: 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b [1] = "Age";
d2c0: 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
d2d0: 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c ult[2] = "Al
d2e0: 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 ice";.**
d2f0: 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 azResult[3]
d300: 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 = "43";.**
d310: 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 azResult[4
d320: 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 ] = "Bob";.**
d330: 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
d340: 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 1;5] = "28";.**
d350: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
d360: 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 #91;6] = "Cindy"
d370: 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
d380: 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 sult[7] = "2
d390: 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 1";.** </pre></b
d3a0: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
d3b0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 The sqlite3_get
d3c0: 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f _table() functio
d3d0: 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 n evaluates one
d3e0: 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 or more.** semic
d3f0: 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 olon-separated S
d400: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e QL statements in
d410: 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e the zero-termin
d420: 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 ated UTF-8.** st
d430: 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 ring of its 2nd
d440: 70 61 72 61 6d 65 74 65 72 2e 20 20 49 74 20 72 parameter. It r
d450: 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 eturns a result
d460: 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 table to the.**
d470: 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e pointer given in
d480: 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 its 3rd paramet
d490: 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 er..**.** After
d4a0: 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 the calling func
d4b0: 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 tion has finishe
d4c0: 64 20 75 73 69 6e 67 20 74 68 65 20 72 65 73 75 d using the resu
d4d0: 6c 74 2c 20 69 74 20 73 68 6f 75 6c 64 20 0a 2a lt, it should .*
d4e0: 2a 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 * pass the point
d4f0: 65 72 20 74 6f 20 74 68 65 20 72 65 73 75 6c 74 er to the result
d500: 20 74 61 62 6c 65 20 74 6f 20 73 71 6c 69 74 65 table to sqlite
d510: 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 3_free_table() i
d520: 6e 20 6f 72 64 65 72 20 74 6f 20 0a 2a 2a 20 72 n order to .** r
d530: 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 elease the memor
d540: 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f y that was mallo
d550: 63 2d 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f c-ed. Because o
d560: 66 20 74 68 65 20 77 61 79 20 74 68 65 20 0a 2a f the way the .*
d570: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f * [sqlite3_mallo
d580: 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 c()] happens wit
d590: 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f hin sqlite3_get_
d5a0: 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c table(), the cal
d5b0: 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e ling.** function
d5c0: 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f must not try to
d5d0: 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 call [sqlite3_f
d5e0: 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e ree()] directly.
d5f0: 20 20 4f 6e 6c 79 20 0a 2a 2a 20 5b 73 71 6c 69 Only .** [sqli
d600: 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 te3_free_table()
d610: 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c ] is able to rel
d620: 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 ease the memory
d630: 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 properly and saf
d640: 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ely..**.** The s
d650: 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
d660: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
d670: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 implemented as a
d680: 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a wrapper around.
d690: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 ** [sqlite3_exec
d6a0: 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 ()]. The sqlite
d6b0: 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 3_get_table() ro
d6c0: 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 utine does not h
d6d0: 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f ave access.** to
d6e0: 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 any internal da
d6f0: 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 ta structures of
d700: 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 SQLite. It use
d710: 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 s only the publi
d720: 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 c.** interface d
d730: 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 efined here. As
d740: 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 a consequence,
d750: 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 errors that occu
d760: 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 r in the.** wrap
d770: 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 per layer outsid
d780: 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 e of the interna
d790: 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 l [sqlite3_exec(
d7a0: 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a )] call are not.
d7b0: 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 ** reflected in
d7c0: 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 subsequent calls
d7d0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 to [sqlite3_err
d7e0: 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 code()] or.** [s
d7f0: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d qlite3_errmsg()]
d800: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
d810: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 TS:.**.** {F1237
d820: 31 7d 20 49 66 20 61 20 5b 73 71 6c 69 74 65 33 1} If a [sqlite3
d830: 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 61 _get_table()] fa
d840: 69 6c 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c ils a memory all
d850: 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a ocation, then.**
d860: 20 20 20 20 20 20 20 20 20 20 69 74 20 66 72 65 it fre
d870: 65 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 es the result ta
d880: 62 6c 65 20 75 6e 64 65 72 20 63 6f 6e 73 74 72 ble under constr
d890: 75 63 74 69 6f 6e 2c 20 61 62 6f 72 74 73 20 74 uction, aborts t
d8a0: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 71 he.** q
d8b0: 75 65 72 79 20 69 6e 20 70 72 6f 63 65 73 73 2c uery in process,
d8c0: 20 73 6b 69 70 73 20 61 6e 79 20 73 75 62 73 65 skips any subse
d8d0: 71 75 65 6e 74 20 71 75 65 72 69 65 73 2c 20 73 quent queries, s
d8e0: 65 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 ets the.**
d8f0: 20 20 20 20 2a 72 65 73 75 6c 74 70 20 6f 75 74 *resultp out
d900: 70 75 74 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e put pointer to N
d910: 55 4c 4c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 ULL and returns
d920: 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a [SQLITE_NOMEM]..
d930: 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 33 7d 20 49 **.** {F12373} I
d940: 66 20 74 68 65 20 6e 63 6f 6c 75 6d 6e 20 70 61 f the ncolumn pa
d950: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
d960: 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d te3_get_table()]
d970: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 is not NULL.**
d980: 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 then [s
d990: 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
d9a0: 28 29 5d 20 77 72 69 74 65 20 74 68 65 20 6e 75 ()] write the nu
d9b0: 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 mber of columns
d9c0: 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 in the.**
d9d0: 20 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 result set of
d9e0: 20 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 the query into
d9f0: 2a 6e 63 6f 6c 75 6d 6e 20 69 66 20 74 68 65 20 *ncolumn if the
da00: 71 75 65 72 79 20 69 73 0a 2a 2a 20 20 20 20 20 query is.**
da10: 20 20 20 20 20 73 75 63 63 65 73 73 66 75 6c 20 successful
da20: 28 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e (if the function
da30: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f returns SQLITE_
da40: 4f 4b 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 OK)..**.** {F123
da50: 37 34 7d 20 49 66 20 74 68 65 20 6e 72 6f 77 20 74} If the nrow
da60: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
da70: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
da80: 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a )] is not NULL.*
da90: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 * then
daa0: 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 [sqlite3_get_tab
dab0: 6c 65 28 29 5d 20 77 72 69 74 65 20 74 68 65 20 le()] write the
dac0: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69 number of rows i
dad0: 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 n the.**
dae0: 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 result set of
daf0: 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a the query into *
db00: 6e 72 6f 77 20 69 66 20 74 68 65 20 71 75 65 72 nrow if the quer
db10: 79 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 y is.**
db20: 20 73 75 63 63 65 73 73 66 75 6c 20 28 69 66 20 successful (if
db30: 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 the function ret
db40: 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 29 2e urns SQLITE_OK).
db50: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 36 7d 20 .**.** {F12376}
db60: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 The [sqlite3_get
db70: 5f 74 61 62 6c 65 28 29 5d 20 66 75 6e 63 74 69 _table()] functi
db80: 6f 6e 20 73 65 74 73 20 69 74 73 20 2a 6e 63 6f on sets its *nco
db90: 6c 75 6d 6e 20 76 61 6c 75 65 0a 2a 2a 20 20 20 lumn value.**
dba0: 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 6e 75 to the nu
dbb0: 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 mber of columns
dbc0: 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 in the result se
dbd0: 74 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 69 t of the query i
dbe0: 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 n the.**
dbf0: 20 20 73 71 6c 20 70 61 72 61 6d 65 74 65 72 2c sql parameter,
dc00: 20 6f 72 20 74 6f 20 7a 65 72 6f 20 69 66 20 74 or to zero if t
dc10: 68 65 20 71 75 65 72 79 20 69 6e 20 73 71 6c 20 he query in sql
dc20: 68 61 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 has an empty.**
dc30: 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 result
dc40: 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 set..*/.int sqli
dc50: 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 te3_get_table(.
dc60: 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 sqlite3*,
dc70: 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 /* An ope
dc80: 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 n database */.
dc90: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c const char *sql,
dca0: 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 /* SQL to
dcb0: 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a be evaluated */.
dcc0: 20 20 63 68 61 72 20 2a 2a 2a 70 52 65 73 75 6c char ***pResul
dcd0: 74 2c 20 20 20 20 20 20 2f 2a 20 52 65 73 75 6c t, /* Resul
dce0: 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 ts of the query
dcf0: 2a 2f 0a 20 20 69 6e 74 20 2a 6e 72 6f 77 2c 20 */. int *nrow,
dd00: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 /* Nu
dd10: 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 mber of result r
dd20: 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 ows written here
dd30: 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e 63 6f 6c 75 */. int *ncolu
dd40: 6d 6e 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e mn, /* N
dd50: 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 umber of result
dd60: 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 columns written
dd70: 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a here */. char *
dd80: 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 *errmsg
dd90: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 /* Error msg wri
dda0: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a tten here */.);.
ddb0: 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 void sqlite3_fre
ddc0: 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 e_table(char **r
ddd0: 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 esult);../*.** C
dde0: 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 API3REF: Formatt
ddf0: 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 ed String Printi
de00: 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31 ng Functions {F1
de10: 37 34 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 7400}.**.** Thes
de20: 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 e routines are w
de30: 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 orkalikes of the
de40: 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 "printf()" fami
de50: 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a ly of functions.
de60: 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e ** from the stan
de70: 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a dard C library..
de80: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
de90: 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 3_mprintf() and
dea0: 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 sqlite3_vmprintf
deb0: 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 () routines writ
dec0: 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c e their.** resul
ded0: 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f ts into memory o
dee0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
def0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e lite3_malloc()].
df00: 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 .** The strings
df10: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 returned by thes
df20: 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 e two routines s
df30: 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 hould be.** rele
df40: 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 ased by [sqlite3
df50: 5f 66 72 65 65 28 29 5d 2e 20 20 20 42 6f 74 68 _free()]. Both
df60: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
df70: 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 a.** NULL point
df80: 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d er if [sqlite3_m
df90: 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 alloc()] is unab
dfa0: 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 le to allocate e
dfb0: 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 nough.** memory
dfc0: 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 to hold the resu
dfd0: 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a lting string..**
dfe0: 0a 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 .** In sqlite3_s
dff0: 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e nprintf() routin
e000: 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 e is similar to
e010: 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f "snprintf()" fro
e020: 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 m.** the standar
e030: 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 d C library. Th
e040: 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 e result is writ
e050: 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 ten into the.**
e060: 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 buffer supplied
e070: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 as the second pa
e080: 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 rameter whose si
e090: 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a ze is given by.*
e0a0: 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 * the first para
e0b0: 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 meter. Note that
e0c0: 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 the order of th
e0d0: 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 e.** first two p
e0e0: 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 arameters is rev
e0f0: 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 ersed from snpri
e100: 6e 74 66 28 29 2e 20 20 54 68 69 73 20 69 73 20 ntf(). This is
e110: 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c an.** historical
e120: 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 accident that c
e130: 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 annot be fixed w
e140: 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a ithout breaking.
e150: 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d ** backwards com
e160: 70 61 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 patibility. Not
e170: 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 e also that sqli
e180: 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a te3_snprintf().*
e190: 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e * returns a poin
e1a0: 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 ter to its buffe
e1b0: 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 r instead of the
e1c0: 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 number of.** ch
e1d0: 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c aracters actuall
e1e0: 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 y written into t
e1f0: 68 65 20 62 75 66 66 65 72 2e 20 20 57 65 20 61 he buffer. We a
e200: 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 dmit that.** the
e210: 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 number of chara
e220: 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f cters written wo
e230: 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 uld be a more us
e240: 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 eful return.** v
e250: 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e alue but we cann
e260: 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d ot change the im
e270: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
e280: 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
e290: 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 ().** now withou
e2a0: 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 t breaking compa
e2b0: 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 tibility..**.**
e2c0: 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 As long as the b
e2d0: 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 uffer size is gr
e2e0: 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c eater than zero,
e2f0: 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
e300: 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 f().** guarantee
e310: 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 s that the buffe
e320: 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f r is always zero
e330: 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 -terminated. Th
e340: 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d e first.** param
e350: 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 eter "n" is the
e360: 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 total size of th
e370: 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 e buffer, includ
e380: 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a ing space for.**
e390: 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e the zero termin
e3a0: 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f ator. So the lo
e3b0: 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 ngest string tha
e3c0: 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 t can be complet
e3d0: 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 ely.** written w
e3e0: 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 ill be n-1 chara
e3f0: 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 cters..**.** The
e400: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 se routines all
e410: 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 implement some a
e420: 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 dditional format
e430: 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 ting.** options
e440: 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 that are useful
e450: 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 for constructing
e460: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e SQL statements.
e470: 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 .** All of the u
e480: 73 75 61 6c 20 70 72 69 6e 74 66 20 66 6f 72 6d sual printf form
e490: 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 atting options a
e4a0: 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 pply. In additi
e4b0: 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 on, there.** is
e4c0: 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 are "%q", "%Q",
e4d0: 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 and "%z" options
e4e0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f ..**.** The %q o
e4f0: 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 ption works like
e500: 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 %s in that it s
e510: 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c ubstitutes a nul
e520: 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 l-terminated.**
e530: 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 string from the
e540: 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 argument list.
e550: 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 But %q also doub
e560: 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 les every '\'' c
e570: 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 haracter..** %q
e580: 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 is designed for
e590: 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 use inside a str
e5a0: 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 ing literal. By
e5b0: 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 doubling each '
e5c0: 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 \''.** character
e5d0: 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 it escapes that
e5e0: 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 character and a
e5f0: 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 llows it to be i
e600: 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 nserted into.**
e610: 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a the string..**.*
e620: 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 73 * For example, s
e630: 6f 20 73 6f 6d 65 20 73 74 72 69 6e 67 20 76 61 o some string va
e640: 72 69 61 62 6c 65 20 63 6f 6e 74 61 69 6e 73 20 riable contains
e650: 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a text as follows:
e660: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
e670: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 te><pre>.** cha
e680: 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 r *zText = "It's
e690: 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a a happy day!";.
e6a0: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
e6b0: 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 quote>.**.** One
e6c0: 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 can use this te
e6d0: 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 xt in an SQL sta
e6e0: 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 tement as follow
e6f0: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s:.**.** <blockq
e700: 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 uote><pre>.** c
e710: 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 har *zSQL = sqli
e720: 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 te3_mprintf("INS
e730: 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 ERT INTO table V
e740: 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 ALUES('%q')", zT
e750: 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 ext);.** sqlite
e760: 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 3_exec(db, zSQL,
e770: 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 0, 0, 0);.** s
e780: 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c qlite3_free(zSQL
e790: 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c );.** </pre></bl
e7a0: 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
e7b0: 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 Because the %q f
e7c0: 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 ormat string is
e7d0: 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 used, the '\'' c
e7e0: 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 haracter in zTex
e7f0: 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 t.** is escaped
e800: 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 and the SQL gene
e810: 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c rated is as foll
e820: 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 ows:.**.** <bloc
e830: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 kquote><pre>.**
e840: 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 INSERT INTO tab
e850: 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 le1 VALUES('It''
e860: 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 s a happy day!')
e870: 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
e880: 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 kquote>.**.** Th
e890: 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 is is correct.
e8a0: 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 Had we used %s i
e8b0: 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 nstead of %q, th
e8c0: 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a e generated SQL.
e8d0: 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f ** would have lo
e8e0: 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a oked like this:.
e8f0: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
e900: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 e><pre>.** INSE
e910: 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 RT INTO table1 V
e920: 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 ALUES('It's a ha
e930: 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c ppy day!');.** <
e940: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
e950: 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 e>.**.** This se
e960: 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 cond example is
e970: 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 an SQL syntax er
e980: 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 ror. As a gener
e990: 61 6c 20 72 75 6c 65 20 79 6f 75 0a 2a 2a 20 73 al rule you.** s
e9a0: 68 6f 75 6c 64 20 61 6c 77 61 79 73 20 75 73 65 hould always use
e9b0: 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 %q instead of %
e9c0: 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 s when inserting
e9d0: 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 text into a str
e9e0: 69 6e 67 20 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e ing .** literal.
e9f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f 70 .**.** The %Q op
ea00: 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 tion works like
ea10: 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 %q except it als
ea20: 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 o adds single qu
ea30: 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 otes around.** t
ea40: 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 he outside of th
ea50: 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 e total string.
ea60: 20 4f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d Or if the param
ea70: 65 74 65 72 20 69 6e 20 74 68 65 20 61 72 67 75 eter in the argu
ea80: 6d 65 6e 74 0a 2a 2a 20 6c 69 73 74 20 69 73 20 ment.** list is
ea90: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 a NULL pointer,
eaa0: 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 %Q substitutes t
eab0: 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 he text "NULL" (
eac0: 77 69 74 68 6f 75 74 20 73 69 6e 67 6c 65 0a 2a without single.*
ead0: 2a 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c 61 * quotes) in pla
eae0: 63 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70 74 ce of the %Q opt
eaf0: 69 6f 6e 2e 20 7b 45 4e 44 7d 20 20 53 6f 2c 20 ion. {END} So,
eb00: 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 for example, one
eb10: 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a could say:.**.*
eb20: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
eb30: 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 re>.** char *zS
eb40: 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 QL = sqlite3_mpr
eb50: 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 intf("INSERT INT
eb60: 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 O table VALUES(%
eb70: 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 Q)", zText);.**
eb80: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 sqlite3_exec(db
eb90: 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 , zSQL, 0, 0, 0)
eba0: 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 ;.** sqlite3_fr
ebb0: 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 ee(zSQL);.** </p
ebc0: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
ebd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 .**.** The code
ebe0: 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 above will rende
ebf0: 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 r a correct SQL
ec00: 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 statement in the
ec10: 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c zSQL.** variabl
ec20: 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 e even if the zT
ec30: 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 ext variable is
ec40: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a a NULL pointer..
ec50: 2a 2a 0a 2a 2a 20 54 68 65 20 22 25 7a 22 20 66 **.** The "%z" f
ec60: 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e ormatting option
ec70: 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 6c works exactly l
ec80: 69 6b 65 20 22 25 73 22 20 77 69 74 68 20 74 68 ike "%s" with th
ec90: 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 e.** addition th
eca0: 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72 at after the str
ecb0: 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 ing has been rea
ecc0: 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 d and copied int
ecd0: 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c o.** the result,
ece0: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
ecf0: 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 ] is called on t
ed00: 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e he input string.
ed10: 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 4e 56 {END}.**.** INV
ed20: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
ed30: 46 31 37 34 30 33 7d 20 20 54 68 65 20 5b 73 71 F17403} The [sq
ed40: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d lite3_mprintf()]
ed50: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 6d and [sqlite3_vm
ed60: 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 printf()] interf
ed70: 61 63 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 aces.**
ed80: 20 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 return either
ed90: 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f pointers to zero
eda0: 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d -terminated UTF-
edb0: 38 20 73 74 72 69 6e 67 73 20 68 65 6c 64 20 69 8 strings held i
edc0: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6d n.** m
edd0: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 emory obtained f
ede0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c rom [sqlite3_mal
edf0: 6c 6f 63 28 29 5d 20 6f 72 20 4e 55 4c 4c 20 70 loc()] or NULL p
ee00: 6f 69 6e 74 65 72 73 20 69 66 0a 2a 2a 20 20 20 ointers if.**
ee10: 20 20 20 20 20 20 20 20 61 20 63 61 6c 6c 20 74 a call t
ee20: 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f o [sqlite3_mallo
ee30: 63 28 29 5d 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a c()] fails..**.*
ee40: 2a 20 7b 46 31 37 34 30 36 7d 20 20 54 68 65 20 * {F17406} The
ee50: 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 [sqlite3_snprint
ee60: 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 f()] interface w
ee70: 72 69 74 65 73 20 61 20 7a 65 72 6f 2d 74 65 72 rites a zero-ter
ee80: 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 minated.**
ee90: 20 20 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e UTF-8 strin
eea0: 67 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 g into the buffe
eeb0: 72 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 r pointed to by
eec0: 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
eed0: 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 eter.**
eee0: 20 20 70 72 6f 76 69 64 65 64 20 74 68 61 74 20 provided that
eef0: 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 the first parame
ef00: 74 65 72 20 69 73 20 67 72 65 61 74 65 72 20 74 ter is greater t
ef10: 68 61 6e 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 han zero..**.**
ef20: 7b 46 31 37 34 30 37 7d 20 20 54 68 65 20 5b 73 {F17407} The [s
ef30: 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
ef40: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 )] interface doe
ef50: 73 20 6e 6f 74 20 77 72 69 74 65 73 20 73 6c 6f s not writes slo
ef60: 74 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 ts of.**
ef70: 20 20 20 69 74 73 20 6f 75 74 70 75 74 20 62 75 its output bu
ef80: 66 66 65 72 20 28 74 68 65 20 73 65 63 6f 6e 64 ffer (the second
ef90: 20 70 61 72 61 6d 65 74 65 72 29 20 6f 75 74 73 parameter) outs
efa0: 69 64 65 20 74 68 65 20 72 61 6e 67 65 0a 2a 2a ide the range.**
efb0: 20 20 20 20 20 20 20 20 20 20 20 6f 66 20 30 20 of 0
efc0: 74 68 72 6f 75 67 68 20 4e 2d 31 20 28 77 68 65 through N-1 (whe
efd0: 72 65 20 4e 20 69 73 20 74 68 65 20 66 69 72 73 re N is the firs
efe0: 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 t parameter).**
eff0: 20 20 20 20 20 20 20 20 20 20 72 65 67 61 72 64 regard
f000: 6c 65 73 73 20 6f 66 20 74 68 65 20 6c 65 6e 67 less of the leng
f010: 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 th of the string
f020: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 .** re
f030: 71 75 65 73 74 65 64 20 62 79 20 74 68 65 20 66 quested by the f
f040: 6f 72 6d 61 74 20 73 70 65 63 69 66 69 63 61 74 ormat specificat
f050: 69 6f 6e 2e 0a 2a 2a 20 20 20 0a 2a 2f 0a 63 68 ion..** .*/.ch
f060: 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 ar *sqlite3_mpri
f070: 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c ntf(const char*,
f080: 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 ...);.char *sqli
f090: 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e te3_vmprintf(con
f0a0: 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 st char*, va_lis
f0b0: 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 t);.char *sqlite
f0c0: 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 3_snprintf(int,c
f0d0: 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a har*,const char*
f0e0: 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 , ...);../*.** C
f0f0: 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 API3REF: Memory
f100: 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 Allocation Subsy
f110: 73 74 65 6d 20 7b 46 31 37 33 30 30 7d 0a 2a 2a stem {F17300}.**
f120: 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 .** The SQLite c
f130: 6f 72 65 20 20 75 73 65 73 20 74 68 65 73 65 20 ore uses these
f140: 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 three routines f
f150: 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 or all of its ow
f160: 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 n.** internal me
f170: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
f180: 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e needs. "Core" in
f190: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 the previous se
f1a0: 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e ntence.** does n
f1b0: 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 ot include opera
f1c0: 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 ting-system spec
f1d0: 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 ific VFS impleme
f1e0: 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a ntation. The.**
f1f0: 20 77 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 windows VFS use
f200: 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 20 s native malloc
f210: 61 6e 64 20 66 72 65 65 20 66 6f 72 20 73 6f 6d and free for som
f220: 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a e operations..**
f230: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
f240: 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 malloc() routine
f250: 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
f260: 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a er to a block.**
f270: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 of memory at le
f280: 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c ast N bytes in l
f290: 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 ength, where N i
f2a0: 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e s the parameter.
f2b0: 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d .** If sqlite3_m
f2c0: 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c alloc() is unabl
f2d0: 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 e to obtain suff
f2e0: 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d icient free.** m
f2f0: 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e emory, it return
f300: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
f310: 2e 20 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 . If the parame
f320: 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 ter N to.** sqli
f330: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 te3_malloc() is
f340: 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 zero or negative
f350: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 then sqlite3_ma
f360: 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a lloc() returns.*
f370: 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 * a NULL pointer
f380: 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 ..**.** Calling
f390: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 sqlite3_free() w
f3a0: 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 ith a pointer pr
f3b0: 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 eviously returne
f3c0: 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f d.** by sqlite3_
f3d0: 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 malloc() or sqli
f3e0: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 te3_realloc() re
f3f0: 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f leases that memo
f400: 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 ry so.** that it
f410: 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 might be reused
f420: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 . The sqlite3_f
f430: 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 ree() routine is
f440: 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 .** a no-op if i
f450: 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 s called with a
f460: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 NULL pointer. P
f470: 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f assing a NULL po
f480: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 inter.** to sqli
f490: 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 te3_free() is ha
f4a0: 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 rmless. After b
f4b0: 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f eing freed, memo
f4c0: 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 ry.** should nei
f4d0: 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 ther be read nor
f4e0: 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 written. Even
f4f0: 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 reading previous
f500: 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f ly freed.** memo
f510: 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 ry might result
f520: 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f in a segmentatio
f530: 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 n fault or other
f540: 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a severe error..*
f550: 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 * Memory corrupt
f560: 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 ion, a segmentat
f570: 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 ion fault, or ot
f580: 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 her severe error
f590: 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 .** might result
f5a0: 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 if sqlite3_free
f5b0: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 () is called wit
f5c0: 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 h a non-NULL poi
f5d0: 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 nter that.** was
f5e0: 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 not obtained fr
f5f0: 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f om sqlite3_mallo
f600: 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 66 c() or sqlite3_f
f610: 72 65 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ree()..**.** The
f620: 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
f630: 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 () interface att
f640: 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 empts to resize
f650: 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 a.** prior memor
f660: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 y allocation to
f670: 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 be at least N by
f680: 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 tes, where N is
f690: 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 the.** second pa
f6a0: 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 rameter. The me
f6b0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
f6c0: 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 to be resized is
f6d0: 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 the first.** pa
f6e0: 72 61 6d 65 74 65 72 2e 20 20 49 66 20 74 68 65 rameter. If the
f6f0: 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
f700: 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c to sqlite3_real
f710: 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 loc().** is a NU
f720: 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 LL pointer then
f730: 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 its behavior is
f740: 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c identical to cal
f750: 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ling.** sqlite3_
f760: 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 malloc(N) where
f770: 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 N is the second
f780: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
f790: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a ite3_realloc()..
f7a0: 2a 2a 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64 ** If the second
f7b0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
f7c0: 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 lite3_realloc()
f7d0: 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 is zero or.** ne
f7e0: 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 gative then the
f7f0: 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 behavior is exac
f800: 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 tly the same as
f810: 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 calling.** sqlit
f820: 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 e3_free(P) where
f830: 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74 20 P is the first
f840: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
f850: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a ite3_realloc()..
f860: 2a 2a 20 53 71 6c 69 74 65 33 5f 72 65 61 6c 6c ** Sqlite3_reall
f870: 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 oc() returns a p
f880: 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f ointer to a memo
f890: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a ry allocation.**
f8a0: 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 of at least N b
f8b0: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 ytes in size or
f8c0: 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 NULL if sufficie
f8d0: 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 nt memory is una
f8e0: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 49 66 20 vailable..** If
f8f0: 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 M is the size of
f900: 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 the prior alloc
f910: 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 ation, then min(
f920: 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 N,M) bytes.** of
f930: 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 the prior alloc
f940: 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 ation are copied
f950: 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e into the beginn
f960: 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 ing of buffer re
f970: 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c turned.** by sql
f980: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 ite3_realloc() a
f990: 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c nd the prior all
f9a0: 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 ocation is freed
f9b0: 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f ..** If sqlite3_
f9c0: 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e realloc() return
f9d0: 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 s NULL, then the
f9e0: 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f prior allocatio
f9f0: 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 n.** is not free
fa00: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d d..**.** The mem
fa10: 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 ory returned by
fa20: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
fa30: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 and sqlite3_rea
fa40: 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 lloc().** is alw
fa50: 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 ays aligned to a
fa60: 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 t least an 8 byt
fa70: 65 20 62 6f 75 6e 64 61 72 79 2e 20 7b 45 4e 44 e boundary. {END
fa80: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 }.**.** The defa
fa90: 75 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ult implementati
faa0: 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 65 6d on.** of the mem
fab0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 ory allocation s
fac0: 75 62 73 79 73 74 65 6d 20 75 73 65 73 20 74 68 ubsystem uses th
fad0: 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c e malloc(), real
fae0: 6c 6f 63 28 29 0a 2a 2a 20 61 6e 64 20 66 72 65 loc().** and fre
faf0: 65 28 29 20 70 72 6f 76 69 64 65 64 20 62 79 20 e() provided by
fb00: 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c the standard C l
fb10: 69 62 72 61 72 79 2e 20 7b 46 31 37 33 38 32 7d ibrary. {F17382}
fb20: 20 48 6f 77 65 76 65 72 2c 20 69 66 20 0a 2a 2a However, if .**
fb30: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
fb40: 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 6f 6c led with the fol
fb50: 6c 6f 77 69 6e 67 20 43 20 70 72 65 70 72 6f 63 lowing C preproc
fb60: 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 0a 2a essor macro.**.*
fb70: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 20 53 * <blockquote> S
fb80: 51 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a QLITE_MEMORY_SIZ
fb90: 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 3c 2f 62 E=<i>NNN</i> </b
fba0: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
fbb0: 20 77 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 where <i>NNN</i
fbc0: 3e 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 2c > is an integer,
fbd0: 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 72 65 then SQLite cre
fbe0: 61 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a 20 ate a static.**
fbf0: 61 72 72 61 79 20 6f 66 20 61 74 20 6c 65 61 73 array of at leas
fc00: 74 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74 t <i>NNN</i> byt
fc10: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 20 75 es in size and u
fc20: 73 65 20 74 68 61 74 20 61 72 72 61 79 0a 2a 2a se that array.**
fc30: 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 for all of its
fc40: 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 dynamic memory a
fc50: 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e llocation needs.
fc60: 20 7b 45 4e 44 7d 20 20 41 64 64 69 74 69 6f 6e {END} Addition
fc70: 61 6c 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c al.** memory all
fc80: 6f 63 61 74 6f 72 20 6f 70 74 69 6f 6e 73 20 6d ocator options m
fc90: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 ay be added in f
fca0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a uture releases..
fcb0: 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 **.** In SQLite
fcc0: 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e version 3.5.0 an
fcd0: 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 d 3.5.1, it was
fce0: 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 possible to defi
fcf0: 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 ne.** the SQLITE
fd00: 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c _OMIT_MEMORY_ALL
fd10: 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f OCATION which wo
fd20: 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 uld cause the bu
fd30: 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d ilt-in.** implem
fd40: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 entation of thes
fd50: 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 e routines to be
fd60: 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 omitted. That
fd70: 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 capability.** is
fd80: 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 no longer provi
fd90: 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 ded. Only built
fda0: 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 -in memory alloc
fdb0: 61 74 6f 72 73 20 63 61 6e 20 62 65 0a 2a 2a 20 ators can be.**
fdc0: 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 used..**.** The
fdd0: 77 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 windows OS inter
fde0: 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 face layer calls
fdf0: 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d .** the system m
fe00: 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 alloc() and free
fe10: 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e () directly when
fe20: 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 converting.** f
fe30: 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e ilenames between
fe40: 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 the UTF-8 encod
fe50: 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 ing used by SQLi
fe60: 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 te.** and whatev
fe70: 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f er filename enco
fe80: 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 ding is used by
fe90: 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 77 the particular w
fea0: 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c indows.** instal
feb0: 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 lation. Memory
fec0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 allocation error
fed0: 73 20 61 72 65 20 64 65 74 65 63 74 65 64 2c 20 s are detected,
fee0: 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 but.** they are
fef0: 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 reported back as
ff00: 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 [SQLITE_CANTOPE
ff10: 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 N] or.** [SQLITE
ff20: 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 _IOERR] rather t
ff30: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 han [SQLITE_NOME
ff40: 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 M]..**.** INVARI
ff50: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 ANTS:.**.** {F17
ff60: 33 30 33 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 303} The [sqlit
ff70: 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e e3_malloc(N)] in
ff80: 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
ff90: 65 69 74 68 65 72 20 61 20 70 6f 69 6e 74 65 72 either a pointer
ffa0: 20 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 to .**
ffb0: 20 20 6e 65 77 6c 79 20 63 68 65 63 6b 65 64 2d newly checked-
ffc0: 6f 75 74 20 62 6c 6f 63 6b 20 6f 66 20 61 74 20 out block of at
ffd0: 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 6f 66 least N bytes of
ffe0: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 memory.**
fff0: 20 20 20 20 20 74 68 61 74 20 69 73 20 38 2d 62 that is 8-b
10000 79 74 65 20 61 6c 69 67 6e 65 64 2c 20 0a 2a 2a yte aligned, .**
10010 20 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 74 or it
10020 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 returns NULL if
10030 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f it is unable to
10040 20 66 75 6c 66 69 6c 6c 20 74 68 65 20 72 65 71 fulfill the req
10050 75 65 73 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 uest..**.** {F17
10060 33 30 34 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 304} The [sqlit
10070 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e e3_malloc(N)] in
10080 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
10090 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 a NULL pointer i
100a0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 4e f.** N
100b0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 is less than or
100c0 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 2e 0a equal to zero..
100d0 2a 2a 0a 2a 2a 20 7b 46 31 37 33 30 35 7d 20 20 **.** {F17305}
100e0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 The [sqlite3_fre
100f0 65 28 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 e(P)] interface
10100 72 65 6c 65 61 73 65 73 20 6d 65 6d 6f 72 79 20 releases memory
10110 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 previously.**
10120 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 65 64 returned
10130 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
10140 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c alloc()] or [sql
10150 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c ite3_realloc()],
10160 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6d 61 .** ma
10170 6b 69 6e 67 20 69 74 20 61 76 61 69 6c 61 62 6c king it availabl
10180 65 20 66 6f 72 20 72 65 75 73 65 2e 0a 2a 2a 0a e for reuse..**.
10190 2a 2a 20 7b 46 31 37 33 30 36 7d 20 20 41 20 63 ** {F17306} A c
101a0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
101b0 66 72 65 65 28 4e 55 4c 4c 29 5d 20 69 73 20 61 free(NULL)] is a
101c0 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e harmless no-op.
101d0 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 30 7d 20 .**.** {F17310}
101e0 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 A call to [sqli
101f0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 30 2c 4e 29 te3_realloc(0,N)
10200 5d 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 ] is equivalent
10210 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 to a call.**
10220 20 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69 74 to [sqlit
10230 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 2e 0a 2a e3_malloc(N)]..*
10240 2a 0a 2a 2a 20 7b 46 31 37 33 31 32 7d 20 20 41 *.** {F17312} A
10250 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
10260 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 30 29 5d 20 3_realloc(P,0)]
10270 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f is equivalent to
10280 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 a call.**
10290 20 20 20 20 20 74 6f 20 5b 73 71 6c 69 74 65 33 to [sqlite3
102a0 5f 66 72 65 65 28 50 29 5d 2e 0a 2a 2a 0a 2a 2a _free(P)]..**.**
102b0 20 7b 46 31 37 33 31 35 7d 20 20 54 68 65 20 53 {F17315} The S
102c0 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 QLite core uses
102d0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
102e0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 )], [sqlite3_rea
102f0 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 lloc()],.**
10300 20 20 20 20 20 20 61 6e 64 20 5b 73 71 6c 69 74 and [sqlit
10310 65 33 5f 66 72 65 65 28 29 5d 20 66 6f 72 20 61 e3_free()] for a
10320 6c 6c 20 6f 66 20 69 74 73 20 6d 65 6d 6f 72 79 ll of its memory
10330 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 6e 64 0a allocation and.
10340 2a 2a 20 20 20 20 20 20 20 20 20 20 20 64 65 61 ** dea
10350 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e llocation needs.
10360 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 38 7d 20 .**.** {F17318}
10370 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 The [sqlite3_re
10380 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 69 6e 74 65 alloc(P,N)] inte
10390 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 rface returns ei
103a0 74 68 65 72 20 61 20 70 6f 69 6e 74 65 72 0a 2a ther a pointer.*
103b0 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 61 * to a
103c0 20 62 6c 6f 63 6b 20 6f 66 20 63 68 65 63 6b 65 block of checke
103d0 64 2d 6f 75 74 20 6d 65 6d 6f 72 79 20 6f 66 20 d-out memory of
103e0 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 at least N bytes
103f0 20 69 6e 20 73 69 7a 65 0a 2a 2a 20 20 20 20 20 in size.**
10400 20 20 20 20 20 20 74 68 61 74 20 69 73 20 38 2d that is 8-
10410 62 79 74 65 20 61 6c 69 67 6e 65 64 2c 20 6f 72 byte aligned, or
10420 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
10430 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 32 31 7d 20 .**.** {F17321}
10440 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 When [sqlite3_r
10450 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 ealloc(P,N)] ret
10460 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 urns a non-NULL
10470 70 6f 69 6e 74 65 72 2c 20 69 74 20 66 69 72 73 pointer, it firs
10480 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 t.** c
10490 6f 70 69 65 73 20 74 68 65 20 66 69 72 73 74 20 opies the first
104a0 4b 20 62 79 74 65 73 20 6f 66 20 63 6f 6e 74 65 K bytes of conte
104b0 6e 74 20 66 72 6f 6d 20 50 20 69 6e 74 6f 20 74 nt from P into t
104c0 68 65 20 6e 65 77 6c 79 20 61 6c 6c 6f 63 61 74 he newly allocat
104d0 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 ed.**
104e0 77 68 65 72 65 20 4b 20 69 73 20 74 68 65 20 6c where K is the l
104f0 65 73 73 6f 72 20 6f 66 20 4e 20 61 6e 64 20 74 essor of N and t
10500 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 he size of the b
10510 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b uffer P..**.** {
10520 46 31 37 33 32 32 7d 20 20 57 68 65 6e 20 5b 73 F17322} When [s
10530 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 qlite3_realloc(P
10540 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 20 6e ,N)] returns a n
10550 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c on-NULL pointer,
10560 20 69 74 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 it first.**
10570 20 20 20 20 20 20 20 72 65 6c 65 61 73 65 73 20 releases
10580 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a the buffer P..**
10590 0a 2a 2a 20 7b 46 31 37 33 32 33 7d 20 20 57 68 .** {F17323} Wh
105a0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c en [sqlite3_real
105b0 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e loc(P,N)] return
105c0 73 20 4e 55 4c 4c 2c 20 74 68 65 20 62 75 66 66 s NULL, the buff
105d0 65 72 20 50 20 69 73 0a 2a 2a 20 20 20 20 20 20 er P is.**
105e0 20 20 20 20 20 6e 6f 74 20 6d 6f 64 69 66 69 65 not modifie
105f0 64 20 6f 72 20 72 65 6c 65 61 73 65 64 2e 0a 2a d or released..*
10600 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 *.** LIMITATIONS
10610 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 37 33 35 30 7d :.**.** {U17350}
10620 20 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 The pointer ar
10630 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 guments to [sqli
10640 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 te3_free()] and
10650 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
10660 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ()].**
10670 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 must be either
10680 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 61 20 70 NULL or else a p
10690 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 20 ointer obtained
106a0 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 from a prior.**
106b0 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f 63 61 invoca
106c0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 tion of [sqlite3
106d0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 _malloc()] or [s
106e0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
106f0 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 20 20 ] that has.**
10700 20 20 20 20 20 20 20 20 6e 6f 74 20 62 65 65 6e not been
10710 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a released..**.**
10720 20 7b 55 31 37 33 35 31 7d 20 20 54 68 65 20 61 {U17351} The a
10730 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
10740 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 not read or writ
10750 65 20 61 6e 79 20 70 61 72 74 20 6f 66 20 0a 2a e any part of .*
10760 2a 20 20 20 20 20 20 20 20 20 20 20 61 20 62 6c * a bl
10770 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 ock of memory af
10780 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 ter it has been
10790 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a released using.*
107a0 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c * [sql
107b0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 ite3_free()] or
107c0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
107d0 28 29 5d 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 ()]..**.*/.void
107e0 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 *sqlite3_malloc(
107f0 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 int);.void *sqli
10800 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 te3_realloc(void
10810 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 *, int);.void sq
10820 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a lite3_free(void*
10830 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
10840 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 EF: Memory Alloc
10850 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 20 ator Statistics
10860 7b 46 31 37 33 37 30 7d 0a 2a 2a 0a 2a 2a 20 53 {F17370}.**.** S
10870 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 QLite provides t
10880 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 hese two interfa
10890 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e ces for reportin
108a0 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a g on the status.
108b0 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ** of the [sqlit
108c0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 e3_malloc()], [s
108d0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 qlite3_free()],
108e0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 and [sqlite3_rea
108f0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 74 68 65 20 6d lloc()].** the m
10900 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
10910 20 73 75 62 73 79 73 74 65 6d 20 69 6e 63 6c 75 subsystem inclu
10920 64 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 53 ded within the S
10930 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 QLite..**.** INV
10940 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
10950 46 31 37 33 37 31 7d 20 54 68 65 20 5b 73 71 6c F17371} The [sql
10960 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 ite3_memory_used
10970 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 ()] routine retu
10980 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 rns the.**
10990 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 number of by
109a0 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 tes of memory cu
109b0 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 rrently outstand
109c0 69 6e 67 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 ing .**
109d0 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e (malloced but n
109e0 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 0a 2a 2a ot freed)..**.**
109f0 20 7b 46 31 37 33 37 33 7d 20 54 68 65 20 5b 73 {F17373} The [s
10a00 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
10a10 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 ghwater()] routi
10a20 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d ne returns the m
10a30 61 78 69 6d 75 6d 0a 2a 2a 20 20 20 20 20 20 20 aximum.**
10a40 20 20 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c value of [sql
10a50 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 ite3_memory_used
10a60 28 29 5d 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 ()] .**
10a70 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 77 since the highw
10a80 61 74 65 72 20 6d 61 72 6b 20 77 61 73 20 6c 61 ater mark was la
10a90 73 74 20 72 65 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 st reset..**.**
10aa0 7b 46 31 37 33 37 34 7d 20 54 68 65 20 76 61 6c {F17374} The val
10ab0 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 ues returned by
10ac0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
10ad0 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 used()] and.**
10ae0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
10af0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 _memory_highwate
10b00 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 r()] include any
10b10 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 20 20 20 overhead.**
10b20 20 20 20 20 20 20 61 64 64 65 64 20 62 79 20 53 added by S
10b30 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 QLite in its imp
10b40 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b lementation of [
10b50 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
10b60 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 ],.** b
10b70 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 ut not overhead
10b80 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 added by the any
10b90 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 underlying syst
10ba0 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 20 20 em library.**
10bb0 20 20 20 20 20 20 20 72 6f 75 74 69 6e 65 73 20 routines
10bc0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 that [sqlite3_ma
10bd0 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c lloc()] may call
10be0 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 37 33 37 35 ..** .** {F17375
10bf0 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 } The memory hig
10c00 68 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 hwater mark is r
10c10 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 eset to the curr
10c20 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 ent value of.**
10c30 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
10c40 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 3_memory_used()]
10c50 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 if and only if
10c60 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f the parameter to
10c70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
10c80 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
10c90 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 hwater()] is tru
10ca0 65 2e 20 20 54 68 65 20 76 61 6c 75 65 20 72 65 e. The value re
10cb0 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 turned.**
10cc0 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d by [sqlite3_m
10cd0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 emory_highwater(
10ce0 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 77 1)] is the highw
10cf0 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 20 20 20 ater mark.**
10d00 20 20 20 20 20 20 70 72 69 6f 72 20 74 6f 20 74 prior to t
10d10 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c he reset..*/.sql
10d20 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 ite3_int64 sqlit
10d30 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 e3_memory_used(v
10d40 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e oid);.sqlite3_in
10d50 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f t64 sqlite3_memo
10d60 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 ry_highwater(int
10d70 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a resetFlag);../*
10d80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 .** CAPI3REF: Ps
10d90 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 eudo-Random Numb
10da0 65 72 20 47 65 6e 65 72 61 74 6f 72 20 7b 46 31 er Generator {F1
10db0 37 33 39 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 7390}.**.** SQLi
10dc0 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 te contains a hi
10dd0 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 gh-quality pseud
10de0 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 o-random number
10df0 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 generator (PRNG)
10e00 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 used to.** sele
10e10 63 74 20 72 61 6e 64 6f 6d 20 52 4f 57 49 44 73 ct random ROWIDs
10e20 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 when inserting
10e30 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f new records into
10e40 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a a table that.**
10e50 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 already uses th
10e60 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 e largest possib
10e70 6c 65 20 52 4f 57 49 44 2e 20 20 54 68 65 20 50 le ROWID. The P
10e80 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 RNG is also used
10e90 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c for.** the buil
10ea0 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e d-in random() an
10eb0 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 d randomblob() S
10ec0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 QL functions. T
10ed0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c his interface al
10ee0 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 61 74 69 lows.** appliati
10ef0 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 ons to access th
10f00 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 e same PRNG for
10f10 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a other purposes..
10f20 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 **.** A call to
10f30 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f this routine sto
10f40 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 res N bytes of r
10f50 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 andomness into b
10f60 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 uffer P..**.** T
10f70 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 he first time th
10f80 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e is routine is in
10f90 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e voked (either in
10fa0 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a ternally or by.*
10fb0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f * the applicatio
10fc0 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 n) the PRNG is s
10fd0 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 eeded using rand
10fe0 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a omness obtained.
10ff0 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e ** from the xRan
11000 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f domness method o
11010 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 f the default [s
11020 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
11030 63 74 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75 ct..** On all su
11040 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 bsequent invocat
11050 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f ions, the pseudo
11060 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 -randomness is g
11070 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 enerated.** inte
11080 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f rnally and witho
11090 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 ut recourse to t
110a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d he [sqlite3_vfs]
110b0 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 xRandomness.**
110c0 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e method..**.** IN
110d0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
110e0 7b 46 31 37 33 39 32 7d 20 54 68 65 20 5b 73 71 {F17392} The [sq
110f0 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 lite3_randomness
11100 28 4e 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 (N,P)] interface
11110 20 77 72 69 74 65 73 20 4e 20 62 79 74 65 73 20 writes N bytes
11120 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 of.** h
11130 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 igh-quality pseu
11140 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e do-randomness in
11150 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2f 0a to buffer P..*/.
11160 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e void sqlite3_ran
11170 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 domness(int N, v
11180 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 oid *P);../*.**
11190 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c CAPI3REF: Compil
111a0 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 e-Time Authoriza
111b0 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b tion Callbacks {
111c0 46 31 32 35 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 F12500}.**.** Th
111d0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 is routine regis
111e0 74 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 ters a authorize
111f0 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 r callback with
11200 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 a particular.**
11210 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
11220 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 tion], supplied
11230 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 in the first arg
11240 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 75 ument..** The au
11250 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
11260 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 k is invoked as
11270 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 SQL statements a
11280 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 re being compile
11290 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 d.** by [sqlite3
112a0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 _prepare()] or i
112b0 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c ts variants [sql
112c0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
112d0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
112e0 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 prepare16()] and
112f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
11300 65 31 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 e16_v2()]. At v
11310 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 arious.** points
11320 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 during the comp
11330 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c ilation process,
11340 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 as logic is bei
11350 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f ng created.** to
11360 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 perform various
11370 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 actions, the au
11380 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
11390 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a k is invoked to.
113a0 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 ** see if those
113b0 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f actions are allo
113c0 77 65 64 2e 20 20 54 68 65 20 61 75 74 68 6f 72 wed. The author
113d0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 izer callback sh
113e0 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b ould.** return [
113f0 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c SQLITE_OK] to al
11400 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 low the action,
11410 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 [SQLITE_IGNORE]
11420 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a to disallow the.
11430 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 ** specific acti
11440 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 on but allow the
11450 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
11460 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 o continue to be
11470 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 .** compiled, or
11480 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 [SQLITE_DENY] t
11490 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 o cause the enti
114a0 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 re SQL statement
114b0 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 to be.** reject
114c0 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 ed with an error
114d0 2e 20 20 20 49 66 20 74 68 65 20 61 75 74 68 6f . If the autho
114e0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 rizer callback r
114f0 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 eturns.** any va
11500 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b lue other than [
11510 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 SQLITE_IGNORE],
11520 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 [SQLITE_OK], or
11530 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a [SQLITE_DENY].**
11540 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 then [sqlite3_p
11550 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
11560 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 equivalent call
11570 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a that triggered.*
11580 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 * the authorizer
11590 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 will fail with
115a0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 an error message
115b0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 ..**.** When the
115c0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
115d0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 s [SQLITE_OK], t
115e0 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 hat means the op
115f0 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 eration.** reque
11600 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 57 68 65 sted is ok. Whe
11610 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 n the callback r
11620 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 eturns [SQLITE_D
11630 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 ENY], the.** [sq
11640 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
11650 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e ()] or equivalen
11660 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 t call that trig
11670 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 gered the.** aut
11680 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 horizer will fai
11690 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 l with an error
116a0 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 message explaini
116b0 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 ng that.** acces
116c0 73 20 69 73 20 64 65 6e 69 65 64 2e 20 20 49 66 s is denied. If
116d0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
116e0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f code is [SQLITE_
116f0 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 READ].** and the
11700 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
11710 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 s [SQLITE_IGNORE
11720 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 ] then the.** [p
11730 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
11740 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 t] statement is
11750 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 constructed to s
11760 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e ubstitute.** a N
11770 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 ULL value in pla
11780 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 ce of the table
11790 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c column that woul
117a0 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 d have.** been r
117b0 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f ead if [SQLITE_O
117c0 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 K] had been retu
117d0 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 rned. The [SQLI
117e0 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 TE_IGNORE].** re
117f0 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 turn can be used
11800 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 to deny an untr
11810 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 usted user acces
11820 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a s to individual.
11830 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 ** columns of a
11840 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 table..**.** The
11850 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
11860 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a to the authoriz
11870 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 er callback is a
11880 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 copy of.** the
11890 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
118a0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 to the sqlite3_s
118b0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 et_authorizer()
118c0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 54 68 interface..** Th
118d0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
118e0 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 er to the callba
118f0 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ck is an integer
11900 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 50 .** [SQLITE_COP
11910 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d Y | action code]
11920 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 that specifies
11930 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 the particular a
11940 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 62 65 20 61 ction.** to be a
11950 75 74 68 6f 72 69 7a 65 64 2e 20 54 68 65 20 74 uthorized. The t
11960 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 hird through six
11970 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 th.** parameters
11980 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
11990 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e are zero-termin
119a0 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 ated strings tha
119b0 74 20 63 6f 6e 74 61 69 6e 20 0a 2a 2a 20 61 64 t contain .** ad
119c0 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 ditional details
119d0 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f about the actio
119e0 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a n to be authoriz
119f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 ed..**.** An aut
11a00 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 horizer is used
11a10 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 when [sqlite3_pr
11a20 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e epare | preparin
11a30 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d g].** SQL statem
11a40 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 ents from an unt
11a50 72 75 73 74 65 64 0a 2a 2a 20 73 6f 75 72 63 65 rusted.** source
11a60 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 , to ensure that
11a70 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
11a80 6e 74 73 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 nts do not try t
11a90 6f 20 61 63 63 65 73 73 20 64 61 74 61 0a 2a 2a o access data.**
11aa0 20 74 68 61 74 20 74 68 65 79 20 61 72 65 20 6e that they are n
11ab0 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 ot allowed to se
11ac0 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 e, or that they
11ad0 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 0a 2a 2a do not try to.**
11ae0 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f execute malicio
11af0 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 us statements th
11b00 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 at damage the da
11b10 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 tabase. For.**
11b20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c example, an appl
11b30 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f ication may allo
11b40 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 w a user to ente
11b50 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 r arbitrary.** S
11b60 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 QL queries for e
11b70 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 valuation by a d
11b80 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 atabase. But th
11b90 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f e application do
11ba0 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 es.** not want t
11bb0 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 he user to be ab
11bc0 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 le to make arbit
11bd0 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 rary changes to
11be0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e the.** database.
11bf0 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 An authorizer
11c00 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 could then be pu
11c10 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 t in place while
11c20 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 the.** user-ent
11c30 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e ered SQL is bein
11c40 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 g [sqlite3_prepa
11c50 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 re | prepared] t
11c60 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 hat.** disallows
11c70 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 everything exce
11c80 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 pt [SELECT] stat
11c90 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 ements..**.** Ap
11ca0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 plications that
11cb0 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 need to process
11cc0 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 SQL from untrust
11cd0 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 ed sources.** mi
11ce0 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 ght also conside
11cf0 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 r lowering resou
11d00 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 rce limits using
11d10 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 [sqlite3_limit(
11d20 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 )].** and limiti
11d30 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 ng database size
11d40 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f using the [max_
11d50 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 page_count] [PRA
11d60 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 GMA].** in addit
11d70 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 ion to using an
11d80 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a authorizer..**.*
11d90 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 * Only a single
11da0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 authorizer can b
11db0 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 e in place on a
11dc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
11dd0 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 ion.** at a time
11de0 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 . Each call to
11df0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
11e00 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 orizer overrides
11e10 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 the.** previous
11e20 20 63 61 6c 6c 2e 20 20 44 69 73 61 62 6c 65 20 call. Disable
11e30 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 the authorizer b
11e40 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e y installing a N
11e50 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a ULL callback..**
11e60 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 The authorizer
11e70 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 is disabled by d
11e80 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 4e 6f efault..**.** No
11e90 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 te that the auth
11ea0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
11eb0 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 is invoked only
11ec0 64 75 72 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 during .** [sqli
11ed0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f te3_prepare()] o
11ee0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 r its variants.
11ef0 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 Authorization i
11f00 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d s not.** perform
11f10 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d ed during statem
11f20 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 ent evaluation i
11f30 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 n [sqlite3_step(
11f40 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 )]..**.** INVARI
11f50 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 ANTS:.**.** {F12
11f60 35 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 501} The [sqlite
11f70 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
11f80 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 (D,...)] interfa
11f90 63 65 20 72 65 67 69 73 74 65 72 73 20 61 0a 2a ce registers a.*
11fa0 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 68 6f * autho
11fb0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 rizer callback w
11fc0 69 74 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e ith database con
11fd0 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a nection D..**.**
11fe0 20 7b 46 31 32 35 30 32 7d 20 54 68 65 20 61 75 {F12502} The au
11ff0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
12000 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 k is invoked as
12010 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 SQL statements a
12020 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 re.** b
12030 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a eing compiled.**
12040 0a 2a 2a 20 7b 46 31 32 35 30 33 7d 20 49 66 20 .** {F12503} If
12050 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
12060 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
12070 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 any value other
12080 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 than.**
12090 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d [SQLITE_IGNORE]
120a0 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f , [SQLITE_OK], o
120b0 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 r [SQLITE_DENY]
120c0 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 then.**
120d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 the [sqlite3_pr
120e0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 epare_v2()] or e
120f0 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 quivalent call t
12100 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 20 20 hat caused.**
12110 20 20 20 20 20 20 20 74 68 65 20 61 75 74 68 6f the autho
12120 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 74 rizer callback t
12130 6f 20 72 75 6e 20 73 68 61 6c 6c 20 66 61 69 6c o run shall fail
12140 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 with an.**
12150 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 [SQLITE_ERR
12160 4f 52 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61 OR] error code a
12170 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 nd an appropriat
12180 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e e error message.
12190 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 34 7d 20 .**.** {F12504}
121a0 57 68 65 6e 20 74 68 65 20 61 75 74 68 6f 72 69 When the authori
121b0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 zer callback ret
121c0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d urns [SQLITE_OK]
121d0 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a , the operation.
121e0 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 73 63 ** desc
121f0 72 69 62 65 64 20 69 73 20 63 6f 64 65 64 20 6e ribed is coded n
12200 6f 72 6d 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b ormally..**.** {
12210 46 31 32 35 30 35 7d 20 57 68 65 6e 20 74 68 65 F12505} When the
12220 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
12230 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 back returns [SQ
12240 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a LITE_DENY], the.
12250 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
12260 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
12270 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 )] or equivalent
12280 20 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73 65 call that cause
12290 64 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 d the.**
122a0 20 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c authorizer cal
122b0 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 lback to run sha
122c0 6c 6c 20 66 61 69 6c 0a 2a 2a 20 20 20 20 20 20 ll fail.**
122d0 20 20 20 20 77 69 74 68 20 61 6e 20 5b 53 51 4c with an [SQL
122e0 49 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 ITE_ERROR] error
122f0 20 63 6f 64 65 20 61 6e 64 20 61 6e 20 65 72 72 code and an err
12300 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 or message.**
12310 20 20 20 20 20 20 20 65 78 70 6c 61 69 6e 69 6e explainin
12320 67 20 74 68 61 74 20 61 63 63 65 73 73 20 69 73 g that access is
12330 20 64 65 6e 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b denied..**.** {
12340 46 31 32 35 30 36 7d 20 49 66 20 74 68 65 20 61 F12506} If the a
12350 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 28 uthorizer code (
12360 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
12370 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 r to the authori
12380 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 zer.**
12390 63 61 6c 6c 62 61 63 6b 29 20 69 73 20 5b 53 51 callback) is [SQ
123a0 4c 49 54 45 5f 52 45 41 44 5d 20 61 6e 64 20 74 LITE_READ] and t
123b0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
123c0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a llback returns.*
123d0 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 * [SQLI
123e0 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 TE_IGNORE] then
123f0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 the prepared sta
12400 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 tement is constr
12410 75 63 74 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 ucted to.**
12420 20 20 20 20 20 69 6e 73 65 72 74 20 61 20 4e 55 insert a NU
12430 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 LL value in plac
12440 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 e of the table c
12450 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 olumn that would
12460 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 have.**
12470 20 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b been read if [
12480 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 SQLITE_OK] had b
12490 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a een returned..**
124a0 0a 2a 2a 20 7b 46 31 32 35 30 37 7d 20 49 66 20 .** {F12507} If
124b0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
124c0 6f 64 65 20 28 74 68 65 20 32 6e 64 20 70 61 72 ode (the 2nd par
124d0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 ameter to the au
124e0 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20 thorizer.**
124f0 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69 callback) i
12500 73 20 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 s anything other
12510 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 45 than [SQLITE_RE
12520 41 44 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 AD], then.**
12530 20 20 20 20 20 20 61 20 72 65 74 75 72 6e 20 6f a return o
12540 66 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 f [SQLITE_IGNORE
12550 5d 20 68 61 73 20 74 68 65 20 73 61 6d 65 20 65 ] has the same e
12560 66 66 65 63 74 20 61 73 20 5b 53 51 4c 49 54 45 ffect as [SQLITE
12570 5f 44 45 4e 59 5d 2e 20 0a 2a 2a 0a 2a 2a 20 7b _DENY]. .**.** {
12580 46 31 32 35 31 30 7d 20 54 68 65 20 66 69 72 73 F12510} The firs
12590 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 t parameter to t
125a0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
125b0 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 llback is a copy
125c0 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 of.**
125d0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
125e0 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 ter to the [sqli
125f0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
12600 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e er()] interface.
12610 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 31 31 7d 20 .**.** {F12511}
12620 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
12630 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c eter to the call
12640 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 back is an integ
12650 65 72 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 er .**
12660 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 [SQLITE_COPY | a
12670 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 ction code] that
12680 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 70 specifies the p
12690 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e articular action
126a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 .** to
126b0 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a be authorized..*
126c0 2a 0a 2a 2a 20 7b 46 31 32 35 31 32 7d 20 54 68 *.** {F12512} Th
126d0 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 e third through
126e0 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 sixth parameters
126f0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
12700 20 61 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 are.**
12710 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
12720 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f strings that co
12730 6e 74 61 69 6e 20 0a 2a 2a 20 20 20 20 20 20 20 ntain .**
12740 20 20 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 additional de
12750 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 tails about the
12760 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 action to be aut
12770 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b horized..**.** {
12780 46 31 32 35 32 30 7d 20 45 61 63 68 20 63 61 6c F12520} Each cal
12790 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 65 l to [sqlite3_se
127a0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 t_authorizer()]
127b0 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a overrides the.**
127c0 20 20 20 20 20 20 20 20 20 20 61 6e 79 20 70 72 any pr
127d0 65 76 69 6f 75 73 6c 79 20 69 6e 73 74 61 6c 6c eviously install
127e0 65 64 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a ed authorizer..*
127f0 2a 0a 2a 2a 20 7b 46 31 32 35 32 31 7d 20 41 20 *.** {F12521} A
12800 4e 55 4c 4c 20 61 75 74 68 6f 72 69 7a 65 72 20 NULL authorizer
12810 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f 20 61 75 means that no au
12820 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 20 thorization.**
12830 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b callback
12840 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a is invoked..**.
12850 2a 2a 20 7b 46 31 32 35 32 32 7d 20 54 68 65 20 ** {F12522} The
12860 64 65 66 61 75 6c 74 20 61 75 74 68 6f 72 69 7a default authoriz
12870 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 er is NULL..*/.i
12880 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 nt sqlite3_set_a
12890 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c uthorizer(. sql
128a0 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 ite3*,. int (*x
128b0 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c Auth)(void*,int,
128c0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 const char*,cons
128d0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 t char*,const ch
128e0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 ar*,const char*)
128f0 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 ,. void *pUserD
12900 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ata.);../*.** CA
12910 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a PI3REF: Authoriz
12920 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 20 er Return Codes
12930 7b 46 31 32 35 39 30 7d 0a 2a 2a 0a 2a 2a 20 54 {F12590}.**.** T
12940 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f he [sqlite3_set_
12950 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 authorizer | aut
12960 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
12970 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a function] must.
12980 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 ** return either
12990 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 [SQLITE_OK] or
129a0 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f one of these two
129b0 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 constants in or
129c0 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c der.** to signal
129d0 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 SQLite whether
129e0 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f or not the actio
129f0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 n is permitted.
12a00 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c See the.** [sql
12a10 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
12a20 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 zer | authorizer
12a30 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 documentation]
12a40 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a for additional.*
12a50 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a * information..*
12a60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
12a70 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 _DENY 1 /* A
12a80 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 bort the SQL sta
12a90 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 tement with an e
12aa0 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rror */.#define
12ab0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 SQLITE_IGNORE 2
12ac0 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 /* Don't allow
12ad0 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e access, but don
12ae0 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 't generate an e
12af0 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 rror */../*.** C
12b00 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 API3REF: Authori
12b10 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 zer Action Codes
12b20 20 7b 46 31 32 35 35 30 7d 0a 2a 2a 0a 2a 2a 20 {F12550}.**.**
12b30 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 The [sqlite3_set
12b40 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 _authorizer()] i
12b50 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 nterface registe
12b60 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 rs a callback fu
12b70 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 nction.** that i
12b80 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 s invoked to aut
12b90 68 6f 72 69 7a 65 72 20 63 65 72 74 61 69 6e 20 horizer certain
12ba0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 SQL statement ac
12bb0 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 tions. The.** s
12bc0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
12bd0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
12be0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f is an integer co
12bf0 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 de that specifie
12c00 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e s.** what action
12c10 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 is being author
12c20 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 ized. These are
12c30 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 the integer act
12c40 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a ion codes that.*
12c50 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 * the authorizer
12c60 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 callback may be
12c70 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 passed..**.** T
12c80 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 hese action code
12c90 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 values signify
12ca0 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 what kind of ope
12cb0 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 ration is to be
12cc0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 .** authorized.
12cd0 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 The 3rd and 4th
12ce0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 parameters to t
12cf0 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e he authorization
12d00 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e .** callback fun
12d10 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 ction will be pa
12d20 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c rameters or NULL
12d30 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 depending on wh
12d40 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 ich of these.**
12d50 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 codes is used as
12d60 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
12d70 6d 65 74 65 72 2e 20 20 54 68 65 20 35 74 68 20 meter. The 5th
12d80 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
12d90 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 .** authorizer c
12da0 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e allback is the n
12db0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 ame of the datab
12dc0 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 ase ("main", "te
12dd0 6d 70 22 2c 20 0a 2a 2a 20 65 74 63 2e 29 20 69 mp", .** etc.) i
12de0 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 20 20 54 f applicable. T
12df0 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 he 6th parameter
12e00 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a to the authoriz
12e10 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 er callback.** i
12e20 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
12e30 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 e inner-most tri
12e40 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 gger or view tha
12e50 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 t is responsible
12e60 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 for.** the acce
12e70 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 ss attempt or NU
12e80 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 LL if this acces
12e90 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 s attempt is dir
12ea0 65 63 74 6c 79 20 66 72 6f 6d 20 0a 2a 2a 20 74 ectly from .** t
12eb0 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 op-level SQL cod
12ec0 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 e..**.** INVARIA
12ed0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 NTS:.**.** {F125
12ee0 35 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 51} The second p
12ef0 61 72 61 6d 65 74 65 72 20 74 6f 20 61 6e 20 0a arameter to an .
12f00 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
12f10 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
12f20 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 zer | authorizer
12f30 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6c 77 callback is alw
12f40 61 79 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a ays an integer.*
12f50 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 * [SQLI
12f60 54 45 5f 43 4f 50 59 20 7c 20 61 75 74 68 6f 72 TE_COPY | author
12f70 69 7a 65 72 20 63 6f 64 65 5d 20 74 68 61 74 20 izer code] that
12f80 73 70 65 63 69 66 69 65 73 20 77 68 61 74 20 61 specifies what a
12f90 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 ction.**
12fa0 20 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f is being autho
12fb0 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 rized..**.** {F1
12fc0 32 35 35 32 7d 20 54 68 65 20 33 72 64 20 61 6e 2552} The 3rd an
12fd0 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 d 4th parameters
12fe0 20 74 6f 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 to the .**
12ff0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 [sqlite3_se
13000 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 t_authorizer | a
13010 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63 61 6c uthorization cal
13020 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 0a lback function].
13030 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c ** will
13040 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f be parameters o
13050 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 r NULL depending
13060 20 6f 6e 20 77 68 69 63 68 20 0a 2a 2a 20 20 20 on which .**
13070 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 [SQLITE_C
13080 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 OPY | authorizer
13090 20 63 6f 64 65 5d 20 69 73 20 75 73 65 64 20 61 code] is used a
130a0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 s the second par
130b0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 ameter..**.** {F
130c0 31 32 35 35 33 7d 20 54 68 65 20 35 74 68 20 70 12553} The 5th p
130d0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a arameter to the.
130e0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
130f0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
13100 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 zer | authorizer
13110 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20 74 68 callback] is th
13120 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 e name.**
13130 20 20 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 of the databa
13140 73 65 20 28 65 78 61 6d 70 6c 65 3a 20 22 6d 61 se (example: "ma
13150 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 65 74 63 in", "temp", etc
13160 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 .) if applicable
13170 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 34 7d ..**.** {F12554}
13180 20 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 The 6th paramet
13190 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 er to the.**
131a0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 [sqlite3_s
131b0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 et_authorizer |
131c0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
131d0 61 63 6b 5d 20 69 73 20 74 68 65 20 6e 61 6d 65 ack] is the name
131e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 .** of
131f0 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 the inner-most t
13200 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 rigger or view t
13210 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 hat is responsib
13220 6c 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 le for.**
13230 20 20 20 74 68 65 20 61 63 63 65 73 73 20 61 74 the access at
13240 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 tempt or NULL if
13250 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 this access att
13260 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 empt is directly
13270 20 66 72 6f 6d 20 0a 2a 2a 20 20 20 20 20 20 20 from .**
13280 20 20 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c top-level SQL
13290 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a code..*/./*****
132a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
132b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
132c0 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a ****** 3rd *****
132d0 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a ******* 4th ****
132e0 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 *******/.#define
132f0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 SQLITE_CREATE_I
13300 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 NDEX 1
13310 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 /* Index Name
13320 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 Table Name
13330 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
13340 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 SQLITE_CREATE_TA
13350 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 BLE 2
13360 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
13370 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
13380 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
13390 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d QLITE_CREATE_TEM
133a0 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 P_INDEX 3
133b0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 /* Index Name
133c0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
133d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
133e0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 LITE_CREATE_TEMP
133f0 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f _TABLE 4 /
13400 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
13410 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
13420 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
13430 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f ITE_CREATE_TEMP_
13440 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a TRIGGER 5 /*
13450 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 Trigger Name
13460 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
13470 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
13480 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 TE_CREATE_TEMP_V
13490 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 IEW 6 /*
134a0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 View Name
134b0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
134c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
134d0 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 E_CREATE_TRIGGER
134e0 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 7 /* T
134f0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 rigger Name T
13500 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
13510 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
13520 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 _CREATE_VIEW
13530 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 8 /* Vi
13540 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 ew Name NU
13550 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
13560 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
13570 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 DELETE
13580 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 9 /* Tab
13590 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
135a0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
135b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
135c0 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 ROP_INDEX
135d0 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 10 /* Inde
135e0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c x Name Tabl
135f0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
13600 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
13610 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 OP_TABLE
13620 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 11 /* Table
13630 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
13640 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
13650 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
13660 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 P_TEMP_INDEX
13670 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 12 /* Index
13680 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 Name Table
13690 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
136a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
136b0 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 _TEMP_TABLE
136c0 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 13 /* Table N
136d0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
136e0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
136f0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
13700 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 TEMP_TRIGGER
13710 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 14 /* Trigger
13720 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 Name Table Na
13730 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
13740 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
13750 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 EMP_VIEW 1
13760 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 5 /* View Name
13770 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
13780 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
13790 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 e SQLITE_DROP_TR
137a0 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 IGGER 16
137b0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 /* Trigger Na
137c0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 me Table Name
137d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
137e0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 SQLITE_DROP_VIE
137f0 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 W 17
13800 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 /* View Name
13810 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
13820 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
13830 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 SQLITE_INSERT
13840 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 18
13850 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
13860 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
13870 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
13880 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 QLITE_PRAGMA
13890 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 19
138a0 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 /* Pragma Name
138b0 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 1st arg or NU
138c0 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 LL */.#define SQ
138d0 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 LITE_READ
138e0 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 20 /
138f0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
13900 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 Column Name
13910 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
13920 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 ITE_SELECT
13930 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 21 /*
13940 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
13950 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
13960 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
13970 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 TE_TRANSACTION
13980 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 22 /*
13990 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
139a0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
139b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
139c0 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 E_UPDATE
139d0 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 23 /* T
139e0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 able Name C
139f0 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a olumn Name *
13a00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
13a10 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 _ATTACH
13a20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 24 /* Fi
13a30 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 lename NU
13a40 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
13a50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
13a60 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 DETACH
13a70 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 25 /* Dat
13a80 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c abase Name NUL
13a90 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
13aa0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
13ab0 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 LTER_TABLE
13ac0 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 26 /* Data
13ad0 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c base Name Tabl
13ae0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
13af0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 define SQLITE_RE
13b00 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 INDEX
13b10 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 27 /* Index
13b20 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
13b30 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
13b40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 efine SQLITE_ANA
13b50 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 LYZE
13b60 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 28 /* Table
13b70 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
13b80 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
13b90 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
13ba0 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 TE_VTABLE
13bb0 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 29 /* Table N
13bc0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 ame Module
13bd0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 Name */.#def
13be0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
13bf0 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 VTABLE
13c00 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 30 /* Table Na
13c10 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e me Module N
13c20 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 ame */.#defi
13c30 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 ne SQLITE_FUNCTI
13c40 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 ON 3
13c50 31 20 20 20 2f 2a 20 46 75 6e 63 74 69 6f 6e 20 1 /* Function
13c60 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 Name NULL
13c70 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
13c80 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 e SQLITE_COPY
13c90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
13ca0 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 /* No longer
13cb0 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 used */../*.** C
13cc0 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 API3REF: Tracing
13cd0 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 And Profiling F
13ce0 75 6e 63 74 69 6f 6e 73 20 7b 46 31 32 32 38 30 unctions {F12280
13cf0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f }.**.** These ro
13d00 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 utines register
13d10 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
13d20 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 ns that can be u
13d30 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 sed for.** traci
13d40 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 ng and profiling
13d50 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f the execution o
13d60 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 f SQL statements
13d70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c ..**.** The call
13d80 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 back function re
13d90 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 gistered by sqli
13da0 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 te3_trace() is i
13db0 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 nvoked at.** var
13dc0 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 ious times when
13dd0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 an SQL statement
13de0 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 is being run by
13df0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
13e00 5d 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 ]..** The callba
13e10 63 6b 20 72 65 74 75 72 6e 73 20 61 20 55 54 46 ck returns a UTF
13e20 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 -8 rendering of
13e30 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
13e40 74 20 74 65 78 74 0a 2a 2a 20 61 73 20 74 68 65 t text.** as the
13e50 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 statement first
13e60 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e begins executin
13e70 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 g. Additional c
13e80 61 6c 6c 62 61 63 6b 73 20 6f 63 63 75 72 0a 2a allbacks occur.*
13e90 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65 * as each trigge
13ea0 72 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 rsubprogram is e
13eb0 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c ntered. The cal
13ec0 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 lbacks for trigg
13ed0 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 ers.** contain a
13ee0 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 UTF-8 SQL comme
13ef0 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 nt that identifi
13f00 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 0a es the trigger..
13f10 2a 2a 20 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 ** .** The callb
13f20 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 ack function reg
13f30 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 istered by sqlit
13f40 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 e3_profile() is
13f50 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 invoked.** as ea
13f60 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ch SQL statement
13f70 20 66 69 6e 69 73 68 65 73 2e 20 20 54 68 65 20 finishes. The
13f80 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b profile callback
13f90 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 contains.** the
13fa0 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d original statem
13fb0 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 ent text and an
13fc0 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c estimate of wall
13fd0 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f -clock time.** o
13fe0 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 f how long that
13ff0 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 statement took t
14000 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 o run..**.** The
14010 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 sqlite3_profile
14020 28 29 20 41 50 49 20 69 73 20 63 75 72 72 65 6e () API is curren
14030 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 20 65 tly considered e
14040 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 0a xperimental and.
14050 2a 2a 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f ** is subject to
14060 20 63 68 61 6e 67 65 20 6f 72 20 72 65 6d 6f 76 change or remov
14070 61 6c 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 al in a future r
14080 65 6c 65 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 elease..**.** Th
14090 65 20 74 72 69 67 67 65 72 20 72 65 70 6f 72 74 e trigger report
140a0 69 6e 67 20 66 65 61 74 75 72 65 20 6f 66 20 74 ing feature of t
140b0 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 he trace callbac
140c0 6b 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 0a k is considered.
140d0 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 ** experimental
140e0 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 and is subject t
140f0 6f 20 63 68 61 6e 67 65 20 6f 72 20 72 65 6d 6f o change or remo
14100 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65 val in future re
14110 6c 65 61 73 65 73 2e 0a 2a 2a 20 46 75 74 75 72 leases..** Futur
14120 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
14130 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 Lite might also
14140 61 64 64 20 6e 65 77 20 74 72 61 63 65 20 63 61 add new trace ca
14150 6c 6c 62 61 63 6b 20 0a 2a 2a 20 69 6e 76 6f 63 llback .** invoc
14160 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e ations..**.** IN
14170 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
14180 7b 46 31 32 32 38 31 7d 20 54 68 65 20 63 61 6c {F12281} The cal
14190 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 lback function r
141a0 65 67 69 73 74 65 72 65 64 20 62 79 20 5b 73 71 egistered by [sq
141b0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 69 lite3_trace()] i
141c0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 s.** wh
141d0 65 6e 65 76 65 72 20 61 6e 20 53 51 4c 20 73 74 enever an SQL st
141e0 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 atement first be
141f0 67 69 6e 73 20 74 6f 20 65 78 65 63 75 74 65 20 gins to execute
14200 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 and.**
14210 77 68 65 6e 65 76 65 72 20 61 20 74 72 69 67 67 whenever a trigg
14220 65 72 20 73 75 62 70 72 6f 67 72 61 6d 20 66 69 er subprogram fi
14230 72 73 74 20 62 65 67 69 6e 73 20 74 6f 20 72 75 rst begins to ru
14240 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 32 n..**.** {F12282
14250 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b } Each call to [
14260 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d sqlite3_trace()]
14270 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 20 70 overrides the p
14280 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 reviously.**
14290 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64 registered
142a0 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 2e trace callback.
142b0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 33 7d 20 .**.** {F12283}
142c0 41 20 4e 55 4c 4c 20 74 72 61 63 65 20 63 61 6c A NULL trace cal
142d0 6c 62 61 63 6b 20 64 69 73 61 62 6c 65 73 20 74 lback disables t
142e0 72 61 63 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 racing..**.** {F
142f0 31 32 32 38 34 7d 20 54 68 65 20 66 69 72 73 74 12284} The first
14300 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
14310 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 trace callback
14320 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 is a copy of.**
14330 20 20 20 20 20 20 20 20 20 74 68 65 20 70 6f 69 the poi
14340 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74 nter which was t
14350 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 he 3rd argument
14360 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 to [sqlite3_trac
14370 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 e()]..**.** {F12
14380 32 38 35 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 285} The second
14390 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
143a0 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 trace callback i
143b0 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 s a.**
143c0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
143d0 55 54 46 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 UTF8 string cont
143e0 61 69 6e 69 6e 67 20 74 68 65 20 6f 72 69 67 69 aining the origi
143f0 6e 61 6c 20 74 65 78 74 0a 2a 2a 20 20 20 20 20 nal text.**
14400 20 20 20 20 20 6f 66 20 74 68 65 20 53 51 4c 20 of the SQL
14410 73 74 61 74 65 6d 65 6e 74 20 61 73 20 69 74 20 statement as it
14420 77 61 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 was passed into
14430 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
14440 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 _v2()].**
14450 20 20 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 or the equiva
14460 6c 65 6e 74 2c 20 6f 72 20 61 6e 20 53 51 4c 20 lent, or an SQL
14470 63 6f 6d 6d 65 6e 74 20 69 6e 64 69 63 61 74 69 comment indicati
14480 6e 67 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 ng the beginning
14490 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 .** of
144a0 61 20 74 72 69 67 67 65 72 20 73 75 62 70 72 6f a trigger subpro
144b0 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 gram..**.** {F12
144c0 32 38 37 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 287} The callbac
144d0 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 k function regis
144e0 74 65 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65 tered by [sqlite
144f0 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 69 73 20 3_profile()] is
14500 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 20 20 invoked.**
14510 20 20 20 20 61 73 20 65 61 63 68 20 53 51 4c 20 as each SQL
14520 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 statement finish
14530 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 es..**.** {F1228
14540 38 7d 20 54 68 65 20 66 69 72 73 74 20 70 61 72 8} The first par
14550 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70 72 ameter to the pr
14560 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 ofile callback i
14570 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 s a copy of.**
14580 20 20 20 20 20 20 20 20 74 68 65 20 33 72 64 20 the 3rd
14590 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
145a0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d lite3_profile()]
145b0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 39 7d ..**.** {F12289}
145c0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 The second para
145d0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f meter to the pro
145e0 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 file callback is
145f0 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a a.** z
14600 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 ero-terminated U
14610 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 61 74 TF-8 string that
14620 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 63 6f contains the co
14630 6d 70 6c 65 74 65 20 74 65 78 74 20 6f 66 0a 2a mplete text of.*
14640 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 53 * the S
14650 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 QL statement as
14660 69 74 20 77 61 73 20 70 72 6f 63 65 73 73 65 64 it was processed
14670 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 by [sqlite3_pre
14680 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 pare_v2()].**
14690 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 65 71 or the eq
146a0 75 69 76 61 6c 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 uivalent..**.**
146b0 7b 46 31 32 32 39 30 7d 20 54 68 65 20 74 68 69 {F12290} The thi
146c0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
146d0 74 68 65 20 70 72 6f 66 69 6c 65 20 20 63 61 6c the profile cal
146e0 6c 62 61 63 6b 20 69 73 20 61 6e 20 65 73 74 69 lback is an esti
146f0 6d 61 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 mate.**
14700 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f of the number o
14710 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 20 6f 66 f nanoseconds of
14720 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 wall-clock time
14730 20 72 65 71 75 69 72 65 64 20 74 6f 0a 2a 2a 20 required to.**
14740 20 20 20 20 20 20 20 20 20 72 75 6e 20 74 68 65 run the
14750 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 SQL statement f
14760 72 6f 6d 20 73 74 61 72 74 20 74 6f 20 66 69 6e rom start to fin
14770 69 73 68 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 ish..*/.void *sq
14780 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 lite3_trace(sqli
14790 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 te3*, void(*xTra
147a0 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 ce)(void*,const
147b0 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a char*), void*);.
147c0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 void *sqlite3_pr
147d0 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a ofile(sqlite3*,.
147e0 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c void(*xProfil
147f0 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 e)(void*,const c
14800 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e har*,sqlite3_uin
14810 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f t64), void*);../
14820 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 *.** CAPI3REF: Q
14830 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 uery Progress Ca
14840 6c 6c 62 61 63 6b 73 20 7b 46 31 32 39 31 30 7d llbacks {F12910}
14850 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
14860 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73 20 61 ine configures a
14870 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
14880 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67 on - the.** prog
14890 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20 ress callback -
148a0 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 that is invoked
148b0 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 periodically dur
148c0 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e ing long.** runn
148d0 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 ing calls to [sq
148e0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b lite3_exec()], [
148f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
14900 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
14910 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 20 get_table()].
14920 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 An example use f
14930 6f 72 20 74 68 69 73 20 0a 2a 2a 20 69 6e 74 65 or this .** inte
14940 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 rface is to keep
14950 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 a GUI updated d
14960 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 uring a large qu
14970 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ery..**.** If th
14980 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 e progress callb
14990 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d ack returns non-
149a0 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 74 69 zero, the operti
149b0 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 on is.** interru
149c0 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 pted. This feat
149d0 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ure can be used
149e0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a to implement a.*
149f0 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f * "Cancel" butto
14a00 6e 20 6f 6e 20 61 20 47 55 49 20 64 69 61 6c 6f n on a GUI dialo
14a10 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 g box..**.** INV
14a20 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
14a30 46 31 32 39 31 31 7d 20 54 68 65 20 63 61 6c 6c F12911} The call
14a40 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 back function re
14a50 67 69 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c gistered by [sql
14a60 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 ite3_progress_ha
14a70 6e 64 6c 65 72 28 29 5d 0a 2a 2a 20 20 20 20 20 ndler()].**
14a80 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 is invoked
14a90 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 periodically dur
14aa0 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 ing long running
14ab0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20 20 calls to.**
14ac0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 [sqlite3_s
14ad0 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 tep()]..**.** {F
14ae0 31 32 39 31 32 7d 20 54 68 65 20 70 72 6f 67 72 12912} The progr
14af0 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ess callback is
14b00 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 invoked once for
14b10 20 65 76 65 72 79 20 4e 20 76 69 72 74 75 61 6c every N virtual
14b20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 61 63 .** mac
14b30 68 69 6e 65 20 6f 70 63 6f 64 65 73 2c 20 77 68 hine opcodes, wh
14b40 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 ere N is the sec
14b50 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ond argument to
14b60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
14b70 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 [sqlite3_progre
14b80 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 20 63 61 ss_handler()] ca
14b90 6c 6c 20 74 68 61 74 20 72 65 67 69 73 74 65 72 ll that register
14ba0 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 ed.** t
14bb0 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 3c 74 he callback. <t
14bc0 6f 64 6f 3e 57 68 61 74 20 69 66 20 4e 20 69 73 odo>What if N is
14bd0 20 6c 65 73 73 20 74 68 61 6e 20 31 3f 3c 2f 74 less than 1?</t
14be0 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 odo>.**.** {F129
14bf0 31 33 7d 20 54 68 65 20 70 72 6f 67 72 65 73 73 13} The progress
14c00 20 63 61 6c 6c 62 61 63 6b 20 69 74 73 65 6c 66 callback itself
14c10 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 is identified b
14c20 79 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 20 y the third.**
14c30 20 20 20 20 20 20 20 20 61 72 67 75 6d 65 6e 74 argument
14c40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f to [sqlite3_pro
14c50 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d gress_handler()]
14c60 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 34 7d ..**.** {F12914}
14c70 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 The fourth argu
14c80 6d 65 6e 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 ment [sqlite3_pr
14c90 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 ogress_handler()
14ca0 5d 20 69 73 20 61 0a 2a 2a 2a 20 20 20 20 20 20 ] is a.***
14cb0 20 20 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 void pointer
14cc0 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 70 72 passed to the pr
14cd0 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 0a ogress callback.
14ce0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 ** func
14cf0 74 69 6f 6e 20 65 61 63 68 20 74 69 6d 65 20 69 tion each time i
14d00 74 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a t is invoked..**
14d10 0a 2a 2a 20 7b 46 31 32 39 31 35 7d 20 49 66 20 .** {F12915} If
14d20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 a call to [sqlit
14d30 65 33 5f 73 74 65 70 28 29 5d 20 72 65 73 75 6c e3_step()] resul
14d40 74 73 20 69 6e 20 66 65 77 65 72 20 74 68 61 6e ts in fewer than
14d50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 20 6f .** N o
14d60 70 63 6f 64 65 73 20 62 65 69 6e 67 20 65 78 65 pcodes being exe
14d70 63 75 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 cuted,.**
14d80 20 20 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 then the prog
14d90 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 ress callback is
14da0 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 64 2e 20 never invoked.
14db0 7b 45 4e 44 7d 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 {END}.** .** {F1
14dc0 32 39 31 36 7d 20 45 76 65 72 79 20 63 61 6c 6c 2916} Every call
14dd0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f to [sqlite3_pro
14de0 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d gress_handler()]
14df0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65 .** ove
14e00 72 77 72 69 74 65 73 20 61 6e 79 20 70 72 65 76 rwrites any prev
14e10 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 iously registere
14e20 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 progress handle
14e30 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 37 r..**.** {F12917
14e40 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 } If the progres
14e50 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 s handler callba
14e60 63 6b 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 ck is NULL then
14e70 6e 6f 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 20 no progress.**
14e80 20 20 20 20 20 20 20 20 68 61 6e 64 6c 65 72 20 handler
14e90 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a is invoked..**.*
14ea0 2a 20 7b 46 31 32 39 31 38 7d 20 49 66 20 74 68 * {F12918} If th
14eb0 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 e progress callb
14ec0 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 72 65 ack returns a re
14ed0 73 75 6c 74 20 6f 74 68 65 72 20 74 68 61 6e 20 sult other than
14ee0 30 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 0, then.**
14ef0 20 20 20 20 74 68 65 20 62 65 68 61 76 69 6f 72 the behavior
14f00 20 69 73 20 61 20 69 66 20 5b 73 71 6c 69 74 65 is a if [sqlite
14f10 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20 68 3_interrupt()] h
14f20 61 64 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a ad been called..
14f30 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f */.void sqlite3_
14f40 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 progress_handler
14f50 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 (sqlite3*, int,
14f60 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 int(*)(void*), v
14f70 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 oid*);../*.** CA
14f80 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 PI3REF: Opening
14f90 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 A New Database C
14fa0 6f 6e 6e 65 63 74 69 6f 6e 20 7b 46 31 32 37 30 onnection {F1270
14fb0 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 0}.**.** These r
14fc0 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 outines open an
14fd0 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 SQLite database
14fe0 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 0a file whose name.
14ff0 2a 2a 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 ** is given by t
15000 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 he filename argu
15010 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 66 69 6c ment..** The fil
15020 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 ename argument i
15030 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 s interpreted as
15040 20 55 54 46 2d 38 0a 2a 2a 20 66 6f 72 20 5b 73 UTF-8.** for [s
15050 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 qlite3_open()] a
15060 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e nd [sqlite3_open
15070 5f 76 32 28 29 5d 20 61 6e 64 20 61 73 20 55 54 _v2()] and as UT
15080 46 2d 31 36 0a 2a 2a 20 69 6e 20 74 68 65 20 6e F-16.** in the n
15090 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
150a0 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 for [sqlite3_op
150b0 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 41 6e 20 5b en16()]..** An [
150c0 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 sqlite3*] handle
150d0 20 69 73 20 75 73 75 61 6c 6c 79 20 72 65 74 75 is usually retu
150e0 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 rned in *ppDb, e
150f0 76 65 6e 0a 2a 2a 20 69 66 20 61 6e 20 65 72 72 ven.** if an err
15100 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 or occurs. The
15110 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 only exception i
15120 73 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 s if SQLite is u
15130 6e 61 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c 6f nable.** to allo
15140 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 cate memory to h
15150 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 old the [sqlite3
15160 5d 20 6f 62 6a 65 63 74 2c 20 61 20 4e 55 4c 4c ] object, a NULL
15170 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 77 72 69 74 will.** be writ
15180 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 ten into *ppDb i
15190 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e nstead of a poin
151a0 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 ter to the [sqli
151b0 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 te3] object..**
151c0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 If the database
151d0 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f is opened (and/o
151e0 72 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 73 75 r created).** su
151f0 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e ccessfully, then
15200 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 [SQLITE_OK] is
15210 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 returned. Other
15220 77 69 73 65 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 wise an.** error
15230 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 code is returne
15240 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 d. The.** [sqli
15250 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 te3_errmsg()] or
15260 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
15270 31 36 28 29 5d 20 20 72 6f 75 74 69 6e 65 73 20 16()] routines
15280 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f can be used to o
15290 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c btain.** an Engl
152a0 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 ish language des
152b0 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 cription of the
152c0 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 error..**.** The
152d0 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e default encodin
152e0 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 g for the databa
152f0 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 se will be UTF-8
15300 20 69 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f if.** [sqlite3_
15310 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 open()] or [sqli
15320 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 te3_open_v2()] i
15330 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 s called and.**
15340 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 UTF-16 in the na
15350 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 tive byte order
15360 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e if [sqlite3_open
15370 31 36 28 29 5d 20 69 73 20 75 73 65 64 2e 0a 2a 16()] is used..*
15380 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 *.** Whether or
15390 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 not an error occ
153a0 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f urs when it is o
153b0 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 pened, resources
153c0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 .** associated w
153d0 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33 ith the [sqlite3
153e0 2a 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 *] handle should
153f0 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 20 be released by
15400 70 61 73 73 69 6e 67 20 69 74 0a 2a 2a 20 74 6f passing it.** to
15410 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 [sqlite3_close(
15420 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f )] when it is no
15430 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 longer required
15440 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c ..**.** The [sql
15450 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 ite3_open_v2()]
15460 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 interface works
15470 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 like [sqlite3_op
15480 65 6e 28 29 5d 20 0a 2a 2a 20 65 78 63 65 70 74 en()] .** except
15490 20 74 68 61 74 20 69 74 20 61 63 63 63 65 70 74 that it acccept
154a0 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c s two additional
154b0 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 parameters for
154c0 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 additional contr
154d0 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e ol.** over the n
154e0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ew database conn
154f0 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61 ection. The fla
15500 67 73 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e gs parameter can
15510 20 62 65 0a 2a 2a 20 6f 6e 65 20 6f 66 3a 0a 2a be.** one of:.*
15520 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ol>.** <li
15530 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
15540 52 45 41 44 4f 4e 4c 59 5d 0a 2a 2a 20 3c 6c 69 READONLY].** <li
15550 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
15560 52 45 41 44 57 52 49 54 45 5d 0a 2a 2a 20 3c 6c READWRITE].** <l
15570 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
15580 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 _READWRITE] | [S
15590 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
155a0 45 5d 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a E].** </ol>.**.*
155b0 2a 20 54 68 65 20 66 69 72 73 74 20 76 61 6c 75 * The first valu
155c0 65 20 6f 70 65 6e 73 20 74 68 65 20 64 61 74 61 e opens the data
155d0 62 61 73 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 base read-only.
155e0 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 .** If the datab
155f0 61 73 65 20 64 6f 65 73 20 6e 6f 74 20 70 72 65 ase does not pre
15600 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 61 viously exist, a
15610 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 n error is retur
15620 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f ned..** The seco
15630 6e 64 20 6f 70 74 69 6f 6e 20 6f 70 65 6e 73 0a nd option opens.
15640 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
15650 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 for reading and
15660 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 writing if possi
15670 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 20 ble, or reading
15680 6f 6e 6c 79 20 69 66 0a 2a 2a 20 69 66 20 74 68 only if.** if th
15690 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 e file is write
156a0 70 72 6f 74 65 63 74 65 64 2e 20 20 49 6e 20 65 protected. In e
156b0 69 74 68 65 72 20 63 61 73 65 20 74 68 65 20 64 ither case the d
156c0 61 74 61 62 61 73 65 0a 2a 2a 20 6d 75 73 74 20 atabase.** must
156d0 61 6c 72 65 61 64 79 20 65 78 69 73 74 20 6f 72 already exist or
156e0 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 an error is ret
156f0 75 72 6e 65 64 2e 20 20 54 68 65 20 74 68 69 72 urned. The thir
15700 64 20 6f 70 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e d option.** open
15710 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 s the database f
15720 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 or reading and w
15730 72 69 74 69 6e 67 20 61 6e 64 20 63 72 65 61 74 riting and creat
15740 65 73 20 69 74 20 69 66 20 69 74 20 64 6f 65 73 es it if it does
15750 0a 2a 2a 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 .** not already
15760 65 78 69 73 74 2e 0a 2a 2a 20 54 68 65 20 74 68 exist..** The th
15770 69 72 64 20 6f 70 74 69 6f 6e 73 20 69 73 20 62 ird options is b
15780 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 ehavior that is
15790 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 20 always used for
157a0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
157b0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 .** and [sqlite3
157c0 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a _open16()]..**.*
157d0 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 * If the 3rd par
157e0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 ameter to [sqlit
157f0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73 e3_open_v2()] is
15800 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a not one of the.
15810 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 ** combinations
15820 73 68 6f 77 6e 20 61 62 6f 76 65 20 74 68 65 6e shown above then
15830 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
15840 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
15850 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d * If the filenam
15860 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c e is ":memory:",
15870 20 74 68 65 6e 20 61 6e 20 70 72 69 76 61 74 65 then an private
15880 0a 2a 2a 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 .** in-memory da
15890 74 61 62 61 73 65 20 69 73 20 63 72 65 61 74 65 tabase is create
158a0 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 d for the connec
158b0 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d tion. This in-m
158c0 65 6d 6f 72 79 0a 2a 2a 20 64 61 74 61 62 61 73 emory.** databas
158d0 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 e will vanish wh
158e0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
158f0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c connection is cl
15900 6f 73 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a osed. Future.**
15910 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 version of SQLi
15920 74 65 20 6d 69 67 68 74 20 6d 61 6b 65 20 75 73 te might make us
15930 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 e of additional
15940 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 special filename
15950 73 0a 2a 2a 20 74 68 61 74 20 62 65 67 69 6e 20 s.** that begin
15960 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 with the ":" cha
15970 72 61 63 74 65 72 2e 20 20 49 74 20 69 73 20 72 racter. It is r
15980 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 ecommended that
15990 0a 2a 2a 20 77 68 65 6e 20 61 20 64 61 74 61 62 .** when a datab
159a0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 72 65 61 ase filename rea
159b0 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 lly does begin w
159c0 69 74 68 0a 2a 2a 20 22 3a 22 20 74 68 61 74 20 ith.** ":" that
159d0 79 6f 75 20 70 72 65 66 69 78 20 74 68 65 20 66 you prefix the f
159e0 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 ilename with a p
159f0 61 74 68 6e 61 6d 65 20 6c 69 6b 65 20 22 2e 2f athname like "./
15a00 22 20 74 6f 0a 2a 2a 20 61 76 6f 69 64 20 61 6d " to.** avoid am
15a10 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 biguity..**.** I
15a20 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 f the filename i
15a30 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e s an empty strin
15a40 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 g, then a privat
15a50 65 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f e temporary.** o
15a60 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 n-disk database
15a70 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e will be created.
15a80 20 20 54 68 69 73 20 70 72 69 76 61 74 65 20 64 This private d
15a90 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a atabase will be.
15aa0 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ** automatically
15ab0 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e deleted as soon
15ac0 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 as the database
15ad0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 connection is c
15ae0 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 losed..**.** The
15af0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
15b00 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 r to sqlite3_ope
15b10 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 n_v2() is the na
15b20 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 me of the.** [sq
15b30 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
15b40 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 t that defines t
15b50 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 he operating sys
15b60 74 65 6d 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 tem .** interfac
15b70 65 20 74 68 61 74 20 74 68 65 20 6e 65 77 20 64 e that the new d
15b80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
15b90 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 on should use.
15ba0 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 If the.** fourth
15bb0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 parameter is a
15bc0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 NULL pointer the
15bd0 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 n the default [s
15be0 71 6c 69 74 65 33 5f 76 66 73 5d 0a 2a 2a 20 6f qlite3_vfs].** o
15bf0 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a bject is used..*
15c00 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 *.** <b>Note to
15c10 77 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f windows users:</
15c20 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 b> The encoding
15c30 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 used for the fi
15c40 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a lename argument.
15c50 2a 2a 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6f ** of [sqlite3_o
15c60 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 pen()] and [sqli
15c70 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6d te3_open_v2()] m
15c80 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f ust be UTF-8, no
15c90 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f t whatever.** co
15ca0 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e depage is curren
15cb0 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 tly defined. Fi
15cc0 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 lenames containi
15cd0 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c ng international
15ce0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d .** characters m
15cf0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 ust be converted
15d00 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 to UTF-8 prior
15d10 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 to passing them
15d20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 into.** [sqlite3
15d30 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c _open()] or [sql
15d40 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e ite3_open_v2()].
15d50 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
15d60 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 31 S:.**.** {F12701
15d70 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f } The [sqlite3_o
15d80 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 pen()], [sqlite3
15d90 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a _open16()], and.
15da0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
15db0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 ite3_open_v2()]
15dc0 69 6e 74 65 72 66 61 63 65 73 20 63 72 65 61 74 interfaces creat
15dd0 65 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 e a new.**
15de0 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f [database co
15df0 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f 63 69 nnection] associ
15e00 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 20 20 20 ated with.**
15e10 20 20 20 20 20 20 74 68 65 20 64 61 74 61 62 61 the databa
15e20 73 65 20 66 69 6c 65 20 67 69 76 65 6e 20 69 6e se file given in
15e30 20 74 68 65 69 72 20 66 69 72 73 74 20 70 61 72 their first par
15e40 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 ameter..**.** {F
15e50 31 32 37 30 32 7d 20 54 68 65 20 66 69 6c 65 6e 12702} The filen
15e60 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ame argument is
15e70 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 interpreted as U
15e80 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 TF-8.**
15e90 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 for [sqlite3_op
15ea0 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 en()] and [sqlit
15eb0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e e3_open_v2()] an
15ec0 64 20 61 73 20 55 54 46 2d 31 36 0a 2a 2a 20 20 d as UTF-16.**
15ed0 20 20 20 20 20 20 20 20 69 6e 20 74 68 65 20 6e in the n
15ee0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
15ef0 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 for [sqlite3_op
15f00 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b en16()]..**.** {
15f10 46 31 32 37 30 33 7d 20 41 20 73 75 63 63 65 73 F12703} A succes
15f20 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 sful invocation
15f30 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e of [sqlite3_open
15f40 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ()], [sqlite3_op
15f50 65 6e 31 36 28 29 5d 2c 20 0a 2a 2a 20 20 20 20 en16()], .**
15f60 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 or [sqlite
15f70 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 72 69 3_open_v2()] wri
15f80 74 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f tes a pointer to
15f90 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 a new.**
15fa0 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e [database con
15fb0 6e 65 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 2a 70 nection] into *p
15fc0 70 44 62 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 pDb..**.** {F127
15fd0 30 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 04} The [sqlite3
15fe0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 _open()], [sqlit
15ff0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e e3_open16()], an
16000 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 d.** [s
16010 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
16020 5d 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 ] interfaces ret
16030 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 urn [SQLITE_OK]
16040 75 70 6f 6e 20 73 75 63 63 65 73 73 2c 0a 2a 2a upon success,.**
16050 20 20 20 20 20 20 20 20 20 20 6f 72 20 61 6e 20 or an
16060 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 appropriate [err
16070 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 66 61 69 6c or code] on fail
16080 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 ure..**.** {F127
16090 30 36 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 06} The default
160a0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f text encoding fo
160b0 72 20 61 20 6e 65 77 20 64 61 74 61 62 61 73 65 r a new database
160c0 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a created using.*
160d0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
160e0 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b te3_open()] or [
160f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
16100 29 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 )] will be UTF-8
16110 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 37 7d ..**.** {F12707}
16120 20 54 68 65 20 64 65 66 61 75 6c 74 20 74 65 78 The default tex
16130 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 61 t encoding for a
16140 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 72 new database cr
16150 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 eated using.**
16160 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
16170 5f 6f 70 65 6e 31 36 28 29 5d 20 77 69 6c 6c 20 _open16()] will
16180 62 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a be UTF-16..**.**
16190 20 7b 46 31 32 37 30 39 7d 20 54 68 65 20 5b 73 {F12709} The [s
161a0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 46 2c 44 29 qlite3_open(F,D)
161b0 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 ] interface is e
161c0 71 75 69 76 61 6c 65 6e 74 20 74 6f 0a 2a 2a 20 quivalent to.**
161d0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
161e0 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 3_open_v2(F,D,G,
161f0 30 29 5d 20 77 68 65 72 65 20 74 68 65 20 47 20 0)] where the G
16200 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 parameter is.**
16210 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 [SQLITE
16220 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d _OPEN_READWRITE]
16230 7c 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 |[SQLITE_OPEN_CR
16240 45 41 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 EATE]..**.** {F1
16250 32 37 31 31 7d 20 49 66 20 74 68 65 20 47 20 70 2711} If the G p
16260 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c arameter to [sql
16270 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 ite3_open_v2(F,D
16280 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 ,G,V)] contains
16290 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
162a0 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 bit value [SQLIT
162b0 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d E_OPEN_READONLY]
162c0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 then the databa
162d0 73 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 se is opened.**
162e0 20 20 20 20 20 20 20 20 20 66 6f 72 20 72 65 61 for rea
162f0 64 69 6e 67 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a ding only..**.**
16300 20 7b 46 31 32 37 31 32 7d 20 49 66 20 74 68 65 {F12712} If the
16310 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 G parameter to
16320 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
16330 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 (F,D,G,V)] conta
16340 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 ins the.**
16350 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 bit value [S
16360 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
16370 52 49 54 45 5d 20 74 68 65 6e 20 74 68 65 20 64 RITE] then the d
16380 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 atabase is opene
16390 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 d.** re
163a0 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e ading and writin
163b0 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f g if possible, o
163c0 72 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e r for reading on
163d0 6c 79 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 ly if the.**
163e0 20 20 20 20 20 20 66 69 6c 65 20 69 73 20 77 72 file is wr
163f0 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 ite protected by
16400 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 the operating s
16410 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 ystem..**.** {F1
16420 32 37 31 33 7d 20 49 66 20 74 68 65 20 47 20 70 2713} If the G p
16430 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c arameter to [sql
16440 69 74 65 33 5f 6f 70 65 6e 28 76 32 28 46 2c 44 ite3_open(v2(F,D
16450 2c 47 2c 56 29 5d 20 6f 6d 69 74 73 20 74 68 65 ,G,V)] omits the
16460 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 .** bit
16470 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f value [SQLITE_O
16480 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64 20 PEN_CREATE] and
16490 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 the database doe
164a0 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 s not.**
164b0 20 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69 previously exi
164c0 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 st, an error is
164d0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
164e0 7b 46 31 32 37 31 34 7d 20 49 66 20 74 68 65 20 {F12714} If the
164f0 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b G parameter to [
16500 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 76 32 28 sqlite3_open(v2(
16510 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 F,D,G,V)] contai
16520 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 ns the.**
16530 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 bit value [SQ
16540 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
16550 5d 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 ] and the databa
16560 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 se does not.**
16570 20 20 20 20 20 20 20 20 70 72 65 76 69 6f 75 73 previous
16580 6c 79 20 65 78 69 73 74 2c 20 74 68 65 6e 20 61 ly exist, then a
16590 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 n attempt is mad
165a0 65 20 74 6f 20 63 72 65 61 74 65 20 61 6e 64 0a e to create and.
165b0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 69 74 ** init
165c0 69 61 6c 69 7a 65 20 74 68 65 20 64 61 74 61 62 ialize the datab
165d0 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 ase..**.** {F127
165e0 31 37 7d 20 49 66 20 74 68 65 20 66 69 6c 65 6e 17} If the filen
165f0 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ame argument to
16600 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
16610 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 , [sqlite3_open1
16620 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 6()],.**
16630 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 or [sqlite3_op
16640 65 6e 5f 76 32 28 29 5d 20 69 73 20 22 3a 6d 65 en_v2()] is ":me
16650 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e 20 mory:", then an
16660 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20 20 private,.**
16670 20 20 20 20 20 65 70 68 65 6d 65 72 61 6c 2c 20 ephemeral,
16680 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 in-memory databa
16690 73 65 20 69 73 20 63 72 65 61 74 65 64 20 66 6f se is created fo
166a0 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e r the connection
166b0 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74 ..** <t
166c0 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f 50 odo>Is SQLITE_OP
166d0 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49 54 45 EN_CREATE|SQLITE
166e0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 _OPEN_READWRITE
166f0 72 65 71 75 69 72 65 64 0a 2a 2a 20 20 20 20 20 required.**
16700 20 20 20 20 20 69 6e 20 73 71 6c 69 74 65 33 5f in sqlite3_
16710 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f open_v2()?</todo
16720 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 39 7d >.**.** {F12719}
16730 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 If the filename
16740 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 is NULL or an e
16750 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 mpty string, the
16760 6e 20 61 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20 n a private,.**
16770 20 20 20 20 20 20 20 20 20 65 70 68 65 72 6d 65 epherme
16780 72 61 6c 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 ral on-disk data
16790 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 base will be cre
167a0 61 74 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20 20 ated..**
167b0 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54 <todo>Is SQLIT
167c0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51 E_OPEN_CREATE|SQ
167d0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
167e0 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 ITE required.**
167f0 20 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69 in sqli
16800 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f te3_open_v2()?</
16810 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 todo>.**.** {F12
16820 37 32 31 7d 20 54 68 65 20 5b 64 61 74 61 62 61 721} The [databa
16830 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 se connection] c
16840 72 65 61 74 65 64 20 62 79 20 0a 2a 2a 20 20 20 reated by .**
16850 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
16860 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 open_v2(F,D,G,V)
16870 5d 20 77 69 6c 6c 20 75 73 65 20 74 68 65 0a 2a ] will use the.*
16880 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
16890 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 te3_vfs] object
168a0 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 identified by th
168b0 65 20 56 20 70 61 72 61 6d 65 74 65 72 2c 20 6f e V parameter, o
168c0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 r.** th
168d0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 e default [sqlit
168e0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 e3_vfs] object i
168f0 73 20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f s V is a NULL po
16900 69 6e 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 inter..*/.int sq
16910 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f lite3_open(. co
16920 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 nst char *filena
16930 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 me, /* Databas
16940 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d e filename (UTF-
16950 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 8) */. sqlite3
16960 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 **ppDb
16970 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 /* OUT: SQLite d
16980 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 b handle */.);.i
16990 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 nt sqlite3_open1
169a0 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 6(. const void
169b0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 *filename, /*
169c0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d Database filenam
169d0 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 e (UTF-16) */.
169e0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 sqlite3 **ppDb
169f0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 /* OUT:
16a00 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 SQLite db handle
16a10 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 */.);.int sqlit
16a20 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f e3_open_v2(. co
16a30 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 nst char *filena
16a40 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 me, /* Databas
16a50 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d e filename (UTF-
16a60 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 8) */. sqlite3
16a70 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 **ppDb,
16a80 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 /* OUT: SQLite d
16a90 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e b handle */. in
16aa0 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 t flags,
16ab0 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a /* Flags *
16ac0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
16ad0 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e zVfs /* N
16ae0 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c ame of VFS modul
16af0 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a e to use */.);..
16b00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
16b10 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 Error Codes And
16b20 4d 65 73 73 61 67 65 73 20 7b 46 31 32 38 30 30 Messages {F12800
16b30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 }.**.** The sqli
16b40 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e te3_errcode() in
16b50 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
16b60 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 5b the numeric.** [
16b70 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 SQLITE_OK | resu
16b80 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 53 51 4c lt code] or [SQL
16b90 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c ITE_IOERR_READ |
16ba0 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 extended result
16bb0 20 63 6f 64 65 5d 0a 2a 2a 20 66 6f 72 20 74 68 code].** for th
16bc0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 e most recent fa
16bd0 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 iled sqlite3_* A
16be0 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 PI call associat
16bf0 65 64 0a 2a 2a 20 77 69 74 68 20 5b 73 71 6c 69 ed.** with [sqli
16c00 74 65 33 5d 20 68 61 6e 64 6c 65 20 27 64 62 27 te3] handle 'db'
16c10 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 . If a prior API
16c20 20 63 61 6c 6c 20 66 61 69 6c 65 64 20 62 75 74 call failed but
16c30 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 the.** most rec
16c40 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 ent API call suc
16c50 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 ceeded, the retu
16c60 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 rn value from sq
16c70 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 0a lite3_errcode().
16c80 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e ** is undefined.
16c90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
16ca0 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 e3_errmsg() and
16cb0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 sqlite3_errmsg16
16cc0 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 () return Englis
16cd0 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 h-language.** te
16ce0 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 xt that describe
16cf0 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 s the error, as
16d00 65 69 74 68 65 72 20 55 54 46 38 20 6f 72 20 55 either UTF8 or U
16d10 54 46 31 36 20 72 65 73 70 65 63 74 69 76 65 6c TF16 respectivel
16d20 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 y..** Memory to
16d30 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d hold the error m
16d40 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 essage string is
16d50 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 managed interna
16d60 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c lly..** The appl
16d70 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 ication does not
16d80 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 77 need to worry w
16d90 69 74 68 20 66 72 65 65 69 6e 67 20 74 68 65 20 ith freeing the
16da0 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 result..** Howev
16db0 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 er, the error st
16dc0 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 ring might be ov
16dd0 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 erwritten or dea
16de0 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 llocated by.** s
16df0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 ubsequent calls
16e00 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 to other SQLite
16e10 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 interface functi
16e20 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 ons..**.** INVAR
16e30 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 IANTS:.**.** {F1
16e40 32 38 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 2801} The [sqlit
16e50 65 33 5f 65 72 72 63 6f 64 65 28 44 29 5d 20 69 e3_errcode(D)] i
16e60 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
16e70 20 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 the numeric.**
16e80 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 [SQLITE
16e90 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 _OK | result cod
16ea0 65 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 e] or.**
16eb0 20 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f [SQLITE_IOERR_
16ec0 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 READ | extended
16ed0 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 result code].**
16ee0 20 20 20 20 20 20 20 20 20 66 6f 72 20 74 68 65 for the
16ef0 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 66 most recently f
16f00 61 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20 ailed interface
16f10 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a call associated.
16f20 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 ** with
16f30 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
16f40 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 ction] D..**.**
16f50 7b 46 31 32 38 30 33 7d 20 54 68 65 20 5b 73 71 {F12803} The [sq
16f60 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 44 29 5d lite3_errmsg(D)]
16f70 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 and [sqlite3_er
16f80 72 6d 73 67 31 36 28 44 29 5d 0a 2a 2a 20 20 20 rmsg16(D)].**
16f90 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 interface
16fa0 73 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 s return English
16fb0 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 20 74 -language text t
16fc0 68 61 74 20 64 65 73 63 72 69 62 65 73 0a 2a 2a hat describes.**
16fd0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 65 72 the er
16fe0 72 6f 72 20 69 6e 20 74 68 65 20 6d 6f 73 74 6c ror in the mostl
16ff0 79 20 72 65 63 65 6e 74 6c 79 20 66 61 69 6c 65 y recently faile
17000 64 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c d interface call
17010 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e ,.** en
17020 63 6f 64 65 64 20 61 73 20 65 69 74 68 65 72 20 coded as either
17030 55 54 46 38 20 6f 72 20 55 54 46 31 36 20 72 65 UTF8 or UTF16 re
17040 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a spectively..**.*
17050 2a 20 7b 46 31 32 38 30 37 7d 20 54 68 65 20 73 * {F12807} The s
17060 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 trings returned
17070 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d by [sqlite3_errm
17080 73 67 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 sg()] and [sqlit
17090 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a e3_errmsg16()].*
170a0 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20 76 * are v
170b0 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 6e alid until the n
170c0 65 78 74 20 53 51 4c 69 74 65 20 69 6e 74 65 72 ext SQLite inter
170d0 66 61 63 65 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a face call..**.**
170e0 20 7b 46 31 32 38 30 38 7d 20 43 61 6c 6c 73 20 {F12808} Calls
170f0 74 6f 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 to API routines
17100 74 68 61 74 20 64 6f 20 6e 6f 74 20 72 65 74 75 that do not retu
17110 72 6e 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 rn an error code
17120 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 28 65 78 .** (ex
17130 61 6d 70 6c 65 3a 20 5b 73 71 6c 69 74 65 33 5f ample: [sqlite3_
17140 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 29 20 64 data_count()]) d
17150 6f 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 o not.**
17160 20 20 63 68 61 6e 67 65 20 74 68 65 20 65 72 72 change the err
17170 6f 72 20 63 6f 64 65 20 6f 72 20 6d 65 73 73 61 or code or messa
17180 67 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a ge returned by.*
17190 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
171a0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 te3_errcode()],
171b0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 [sqlite3_errmsg(
171c0 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f )], or [sqlite3_
171d0 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a errmsg16()]..**.
171e0 2a 2a 20 7b 46 31 32 38 30 39 7d 20 49 6e 74 65 ** {F12809} Inte
171f0 72 66 61 63 65 73 20 74 68 61 74 20 61 72 65 20 rfaces that are
17200 6e 6f 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 not associated w
17210 69 74 68 20 61 20 73 70 65 63 69 66 69 63 0a 2a ith a specific.*
17220 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 * [data
17230 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
17240 20 28 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20 20 (examples:.**
17250 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
17260 5f 6d 70 72 69 6e 74 66 28 29 5d 20 6f 72 20 5b _mprintf()] or [
17270 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 sqlite3_enable_s
17280 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 0a 2a hared_cache()].*
17290 2a 20 20 20 20 20 20 20 20 20 20 64 6f 20 6e 6f * do no
172a0 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c t change the val
172b0 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a ues returned by.
172c0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
172d0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c ite3_errcode()],
172e0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
172f0 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 ()], or [sqlite3
17300 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f _errmsg16()]..*/
17310 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 .int sqlite3_err
17320 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 code(sqlite3 *db
17330 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 );.const char *s
17340 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 qlite3_errmsg(sq
17350 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 lite3*);.const v
17360 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 oid *sqlite3_err
17370 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b msg16(sqlite3*);
17380 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
17390 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 : SQL Statement
173a0 4f 62 6a 65 63 74 20 7b 46 31 33 30 30 30 7d 0a Object {F13000}.
173b0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 ** KEYWORDS: {pr
173c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
173d0 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 } {prepared stat
173e0 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e ements}.**.** An
173f0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 instance of thi
17400 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 s object represe
17410 6e 74 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 nt single SQL st
17420 61 74 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 0a atements. This.
17430 2a 2a 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 ** object is var
17440 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 iously known as
17450 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74 a "prepared stat
17460 65 6d 65 6e 74 22 20 6f 72 20 61 20 0a 2a 2a 20 ement" or a .**
17470 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 "compiled SQL st
17480 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 atement" or simp
17490 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 ly as a "stateme
174a0 6e 74 22 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 nt"..** .** The
174b0 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d life of a statem
174c0 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 ent object goes
174d0 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 something like t
174e0 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a his:.**.** <ol>.
174f0 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 ** <li> Create t
17500 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 he object using
17510 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
17520 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 _v2()] or a rela
17530 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 ted.** func
17540 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 tion..** <li> Bi
17550 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 nd values to hos
17560 74 20 70 61 72 61 6d 65 74 65 72 73 20 75 73 69 t parameters usi
17570 6e 67 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 ng.** [sqli
17580 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 te3_bind_blob |
17590 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 69 sqlite3_bind_* i
175a0 6e 74 65 72 66 61 63 65 73 5d 2e 0a 2a 2a 20 3c nterfaces]..** <
175b0 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 li> Run the SQL
175c0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 by calling [sqli
175d0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 te3_step()] one
175e0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a or more times..*
175f0 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 * <li> Reset the
17600 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 statement using
17610 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
17620 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a )] then go back.
17630 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 ** to step
17640 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 2. Do this zero
17650 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a or more times..
17660 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 ** <li> Destroy
17670 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 the object using
17680 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
17690 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a ze()]..** </ol>.
176a0 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 **.** Refer to d
176b0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 ocumentation on
176c0 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f individual metho
176d0 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 ds above for add
176e0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 itional.** infor
176f0 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 mation..*/.typed
17700 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
17710 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 3_stmt sqlite3_s
17720 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 tmt;../*.** CAPI
17730 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 3REF: Run-time L
17740 69 6d 69 74 73 20 7b 46 31 32 37 36 30 7d 0a 2a imits {F12760}.*
17750 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 *.** This interf
17760 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 ace allows the s
17770 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 ize of various c
17780 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 onstructs to be
17790 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 limited.** on a
177a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f connection by co
177b0 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 nnection basis.
177c0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d The first param
177d0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b eter is the.** [
177e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
177f0 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 ion] whose limit
17800 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 is to be set or
17810 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a queried. The.*
17820 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 * second paramet
17830 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 er is one of the
17840 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 [limit categori
17850 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 es] that define
17860 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f a.** class of co
17870 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 nstructs to be s
17880 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 ize limited. Th
17890 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
178a0 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 r is the.** new
178b0 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 limit for that c
178c0 6f 6e 73 74 72 75 63 74 2e 20 20 54 68 65 20 66 onstruct. The f
178d0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
178e0 74 68 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a 2a the old limit..*
178f0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 65 77 20 *.** If the new
17900 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 limit is a negat
17910 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 ive number, the
17920 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 limit is unchang
17930 65 64 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6c ed..** For the l
17940 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 6f 66 imit category of
17950 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59 SQLITE_LIMIT_XY
17960 5a 20 74 68 65 72 65 20 69 73 20 61 20 68 61 72 Z there is a har
17970 64 20 75 70 70 65 72 0a 2a 2a 20 62 6f 75 6e 64 d upper.** bound
17980 20 73 65 74 20 62 79 20 61 20 63 6f 6d 70 69 6c set by a compil
17990 65 2d 74 69 6d 65 20 43 2d 70 72 65 70 72 6f 63 e-time C-preproc
179a0 65 73 73 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20 ess macro named
179b0 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 2e 0a SQLITE_MAX_XYZ..
179c0 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f ** (The "_LIMIT_
179d0 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 " in the name is
179e0 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 changed to "_MA
179f0 58 5f 22 2e 29 0a 2a 2a 20 41 74 74 65 6d 70 74 X_".).** Attempt
17a00 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 s to increase a
17a10 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 limit above its
17a20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 hard upper bound
17a30 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 are.** silently
17a40 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 truncated to th
17a50 65 20 68 61 72 64 20 75 70 70 65 72 20 6c 69 6d e hard upper lim
17a60 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69 it..**.** Run ti
17a70 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e me limits are in
17a80 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 tended for use i
17a90 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 n applications t
17aa0 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f hat manage.** bo
17ab0 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 th their own int
17ac0 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 ernal database a
17ad0 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 nd also database
17ae0 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 s that are contr
17af0 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 olled.** by untr
17b00 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 usted external s
17b10 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d ources. An exam
17b20 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 ple application
17b30 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 might be a.** we
17b40 62 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 bbrowser that ha
17b50 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 s its own databa
17b60 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 ses for storing
17b70 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 history and.** s
17b80 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 eparate database
17b90 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 s controlled by
17ba0 6a 61 76 61 73 63 72 69 70 74 20 61 70 70 6c 69 javascript appli
17bb0 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 cations download
17bc0 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 69 6e ed.** off the in
17bd0 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 ternet. The int
17be0 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 ernal databases
17bf0 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 can be given the
17c00 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 .** large, defau
17c10 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 lt limits. Data
17c20 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 bases managed by
17c30 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 external source
17c40 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 s can.** be give
17c50 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c n much smaller l
17c60 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 imits designed t
17c70 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 o prevent a deni
17c80 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a al of service.**
17c90 20 61 74 74 61 63 68 2e 20 20 44 65 76 65 6c 6f attach. Develo
17ca0 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 pers might also
17cb0 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 want to use the
17cc0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 [sqlite3_set_aut
17cd0 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e horizer()].** in
17ce0 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 terface to furth
17cf0 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 er control untru
17d00 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 sted SQL. The s
17d10 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 ize of the datab
17d20 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 ase.** created b
17d30 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 y an untrusted s
17d40 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e cript can be con
17d50 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 tained using the
17d60 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f .** [max_page_co
17d70 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a unt] [PRAGMA]..*
17d80 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 *.** This interf
17d90 61 63 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 ace is currently
17da0 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 considered expe
17db0 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 rimental and is
17dc0 73 75 62 6a 65 63 74 0a 2a 2a 20 74 6f 20 63 68 subject.** to ch
17dd0 61 6e 67 65 20 6f 72 20 72 65 6d 6f 76 61 6c 20 ange or removal
17de0 77 69 74 68 6f 75 74 20 70 72 69 6f 72 20 6e 6f without prior no
17df0 74 69 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 tice..**.** INVA
17e00 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 RIANTS:.**.** {F
17e10 31 32 37 36 32 7d 20 41 20 73 75 63 63 65 73 73 12762} A success
17e20 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ful call to [sql
17e30 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 ite3_limit(D,C,V
17e40 29 5d 20 77 68 65 72 65 20 56 20 69 73 0a 2a 2a )] where V is.**
17e50 20 20 20 20 20 20 20 20 20 20 70 6f 73 69 74 69 positi
17e60 76 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a ve changes the.*
17e70 2a 20 20 20 20 20 20 20 20 20 20 6c 69 6d 69 74 * limit
17e80 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 on the size of
17e90 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e 20 5b construct C in [
17ea0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
17eb0 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 ion] D.**
17ec0 20 20 20 74 6f 20 74 68 65 20 6c 65 73 73 6f 72 to the lessor
17ed0 20 6f 66 20 56 20 61 6e 64 20 74 68 65 20 68 61 of V and the ha
17ee0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f rd upper bound o
17ef0 6e 20 74 68 65 20 73 69 7a 65 0a 2a 2a 20 20 20 n the size.**
17f00 20 20 20 20 20 20 20 6f 66 20 43 20 74 68 61 74 of C that
17f10 20 69 73 20 73 65 74 20 61 74 20 63 6f 6d 70 69 is set at compi
17f20 6c 65 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b le-time..**.** {
17f30 46 31 32 37 36 36 7d 20 41 20 73 75 63 63 65 73 F12766} A succes
17f40 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 sful call to [sq
17f50 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c lite3_limit(D,C,
17f60 56 29 5d 20 77 68 65 72 65 20 56 20 69 73 20 6e V)] where V is n
17f70 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 egative.**
17f80 20 20 20 20 6c 65 61 76 65 73 20 74 68 65 20 73 leaves the s
17f90 74 61 74 65 20 6f 66 20 5b 64 61 74 61 62 61 73 tate of [databas
17fa0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 e connection] D
17fb0 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a unchanged..**.**
17fc0 20 7b 46 31 32 37 36 39 7d 20 41 20 73 75 63 63 {F12769} A succ
17fd0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b essful call to [
17fe0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c sqlite3_limit(D,
17ff0 43 2c 56 29 5d 20 72 65 74 75 72 6e 73 20 74 68 C,V)] returns th
18000 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 e.** va
18010 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 lue of the limit
18020 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 on the size of
18030 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e 0a 2a construct C in.*
18040 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 5b 64 * in [d
18050 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
18060 6f 6e 5d 20 44 20 61 73 20 69 74 20 77 61 73 20 on] D as it was
18070 70 72 69 6f 72 20 74 6f 20 74 68 65 20 63 61 6c prior to the cal
18080 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 l..*/.int sqlite
18090 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 3_limit(sqlite3*
180a0 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 , int id, int ne
180b0 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 wVal);../*.** CA
180c0 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 PI3REF: Run-Time
180d0 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 Limit Categorie
180e0 73 20 7b 46 31 32 37 39 30 7d 0a 2a 2a 20 4b 45 s {F12790}.** KE
180f0 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 YWORDS: {limit c
18100 61 74 65 67 6f 72 79 7d 20 7b 6c 69 6d 69 74 20 ategory} {limit
18110 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 20 0a categories}.** .
18120 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e ** These constan
18130 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 ts define variou
18140 73 20 61 73 70 65 63 74 73 20 6f 66 20 61 20 5b s aspects of a [
18150 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
18160 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 63 61 6e ion].** that can
18170 20 62 65 20 6c 69 6d 69 74 65 64 20 69 6e 20 73 be limited in s
18180 69 7a 65 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 ize by calls to
18190 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 [sqlite3_limit()
181a0 5d 2e 0a 2a 2a 20 54 68 65 20 6d 65 61 6e 69 6e ]..** The meanin
181b0 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 gs of the variou
181c0 73 20 6c 69 6d 69 74 73 20 61 72 65 20 61 73 20 s limits are as
181d0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c follows:.**.** <
181e0 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 dl>.** <dt>SQLIT
181f0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f E_LIMIT_LENGTH</
18200 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
18210 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 aximum size of a
18220 6e 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 ny.** string or
18230 62 6c 6f 62 20 6f 72 20 74 61 62 6c 65 20 72 6f blob or table ro
18240 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 w.<dd>.**.** <dt
18250 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 >SQLITE_LIMIT_SQ
18260 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a L_LENGTH</dt>.**
18270 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
18280 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 length of an SQ
18290 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 L statement.</dd
182a0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
182b0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c TE_LIMIT_COLUMN<
182c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
182d0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
182e0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 f columns in a t
182f0 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 able definition
18300 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 or in the.** res
18310 75 6c 74 20 73 65 74 20 6f 66 20 61 20 53 45 4c ult set of a SEL
18320 45 43 54 20 6f 72 20 74 68 65 20 6d 61 78 69 6d ECT or the maxim
18330 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c um number of col
18340 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 umns in an index
18350 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 .** or in an ORD
18360 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 ER BY or GROUP B
18370 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 0a 2a Y clause.</dd>.*
18380 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
18390 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 LIMIT_EXPR_DEPTH
183a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
183b0 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f maximum depth o
183c0 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 f the parse tree
183d0 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 on any expressi
183e0 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c on.</dd>.**.** <
183f0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
18400 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c COMPOUND_SELECT<
18410 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
18420 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
18430 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d f terms in a com
18440 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 pound SELECT sta
18450 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a tement.</dd>.**.
18460 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ** <dt>SQLITE_LI
18470 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e MIT_VDBE_OP</dt>
18480 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
18490 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e mum number of in
184a0 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 structions in a
184b0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 virtual machine
184c0 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 program.** used
184d0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 to implement an
184e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f SQL statement.</
184f0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
18500 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 LITE_LIMIT_FUNCT
18510 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 ION_ARG</dt>.**
18520 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
18530 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 number of argume
18540 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f nts on a functio
18550 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 n.</dd>.**.** <d
18560 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 t>SQLITE_LIMIT_A
18570 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 TTACHED</dt>.**
18580 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
18590 6e 75 6d 62 65 72 20 6f 66 20 61 74 74 61 63 68 number of attach
185a0 65 64 20 64 61 74 61 62 61 73 65 73 2e 3c 2f 64 ed databases.</d
185b0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
185c0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 ITE_LIMIT_LIKE_P
185d0 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 ATTERN_LENGTH</d
185e0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
185f0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
18600 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 the pattern argu
18610 6d 65 6e 74 20 74 6f 20 74 68 65 20 4c 49 4b 45 ment to the LIKE
18620 20 6f 72 0a 2a 2a 20 47 4c 4f 42 20 6f 70 65 72 or.** GLOB oper
18630 61 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ators.</dd>.**.*
18640 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d * <dt>SQLITE_LIM
18650 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 IT_VARIABLE_NUMB
18660 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 ER</dt>.** <dd>T
18670 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
18680 72 20 6f 66 20 76 61 72 69 61 62 6c 65 73 20 69 r of variables i
18690 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 n an SQL stateme
186a0 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20 62 nt that can.** b
186b0 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a e bound.</dd>.**
186c0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e </dl>.*/.#defin
186d0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c e SQLITE_LIMIT_L
186e0 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 ENGTH
186f0 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 0.#defi
18700 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
18710 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 SQL_LENGTH
18720 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 1.#def
18730 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
18740 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 _COLUMN
18750 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 2.#de
18760 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
18770 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 T_EXPR_DEPTH
18780 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 3.#d
18790 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
187a0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 IT_COMPOUND_SELE
187b0 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 CT 4.#
187c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
187d0 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 MIT_VDBE_OP
187e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 5.
187f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
18800 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 IMIT_FUNCTION_AR
18810 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 G 6
18820 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
18830 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 LIMIT_ATTACHED
18840 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
18850 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 7.#define SQLITE
18860 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 _LIMIT_LIKE_PATT
18870 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 ERN_LENGTH
18880 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 8.#define SQLIT
18890 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 E_LIMIT_VARIABLE
188a0 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 _NUMBER
188b0 20 20 39 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 9../*.** CAPI3
188c0 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 REF: Compiling A
188d0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 n SQL Statement
188e0 7b 46 31 33 30 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 {F13010}.**.** T
188f0 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c o execute an SQL
18900 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 query, it must
18910 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 first be compile
18920 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f d into a byte-co
18930 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 de.** program us
18940 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 ing one of these
18950 20 72 6f 75 74 69 6e 65 73 2e 20 0a 2a 2a 0a 2a routines. .**.*
18960 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 * The first argu
18970 6d 65 6e 74 20 22 64 62 22 20 69 73 20 61 6e 20 ment "db" is an
18980 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
18990 74 69 6f 6e 5d 20 0a 2a 2a 20 6f 62 74 61 69 6e tion] .** obtain
189a0 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 20 ed from a prior
189b0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
189c0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 _open()], [sqlit
189d0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 0a 2a 2a e3_open_v2()].**
189e0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 or [sqlite3_ope
189f0 6e 31 36 28 29 5d 2e 20 0a 2a 2a 20 54 68 65 20 n16()]. .** The
18a00 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
18a10 22 7a 53 71 6c 22 20 69 73 20 74 68 65 20 73 74 "zSql" is the st
18a20 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f atement to be co
18a30 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a mpiled, encoded.
18a40 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 ** as either UTF
18a50 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 -8 or UTF-16. T
18a60 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 he sqlite3_prepa
18a70 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 re() and sqlite3
18a80 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a _prepare_v2().**
18a90 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 73 interfaces uses
18aa0 20 55 54 46 2d 38 20 61 6e 64 20 73 71 6c 69 74 UTF-8 and sqlit
18ab0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 e3_prepare16() a
18ac0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nd sqlite3_prepa
18ad0 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 re16_v2().** use
18ae0 20 55 54 46 2d 31 36 2e 20 7b 45 4e 44 7d 0a 2a UTF-16. {END}.*
18af0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79 74 *.** If the nByt
18b00 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 e argument is le
18b10 73 73 0a 2a 2a 20 74 68 61 6e 20 7a 65 72 6f 2c ss.** than zero,
18b20 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 then zSql is re
18b30 61 64 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 ad up to the fir
18b40 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 st zero terminat
18b50 6f 72 2e 0a 2a 2a 20 49 66 20 6e 42 79 74 65 20 or..** If nByte
18b60 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c is non-negative,
18b70 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 then it is the
18b80 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
18b90 66 20 0a 2a 2a 20 62 79 74 65 73 20 72 65 61 64 f .** bytes read
18ba0 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65 from zSql. Whe
18bb0 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e n nByte is non-n
18bc0 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 egative, the.**
18bd0 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 zSql string ends
18be0 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66 at either the f
18bf0 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 irst '\000' or '
18c00 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65 \u0000' characte
18c10 72 20 6f 72 20 0a 2a 2a 20 74 68 65 20 6e 42 79 r or .** the nBy
18c20 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 te-th byte, whic
18c30 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 hever comes firs
18c40 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 t. If the caller
18c50 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 knows.** that t
18c60 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 he supplied stri
18c70 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e ng is nul-termin
18c80 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 ated, then there
18c90 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 is a small.** p
18ca0 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e erformance advan
18cb0 74 61 67 65 20 74 6f 20 62 65 20 68 61 64 20 62 tage to be had b
18cc0 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 y passing an nBy
18cd0 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 te parameter tha
18ce0 74 20 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 t .** is equal t
18cf0 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 o the number of
18d00 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 bytes in the inp
18d10 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 ut string <i>inc
18d20 6c 75 64 69 6e 67 3c 2f 69 3e 20 0a 2a 2a 20 74 luding</i> .** t
18d30 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f he nul-terminato
18d40 72 20 62 79 74 65 73 2e 7b 45 4e 44 7d 0a 2a 2a r bytes.{END}.**
18d50 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d .** *pzTail is m
18d60 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 ade to point to
18d70 74 68 65 20 66 69 72 73 74 20 62 79 74 65 20 70 the first byte p
18d80 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 ast the end of t
18d90 68 65 0a 2a 2a 20 66 69 72 73 74 20 53 51 4c 20 he.** first SQL
18da0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 statement in zSq
18db0 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e l. These routin
18dc0 65 73 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c 65 73 es only compiles
18dd0 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 73 74 the first.** st
18de0 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c atement in zSql,
18df0 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c so *pzTail is l
18e00 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 eft pointing to
18e10 77 68 61 74 20 72 65 6d 61 69 6e 73 0a 2a 2a 20 what remains.**
18e20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a uncompiled..**.*
18e30 2a 20 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 * *ppStmt is lef
18e40 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 t pointing to a
18e50 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 compiled [prepar
18e60 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
18e70 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 at can be.** exe
18e80 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c cuted using [sql
18e90 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 4f ite3_step()]. O
18ea0 72 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e r if there is an
18eb0 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 error, *ppStmt
18ec0 69 73 0a 2a 2a 20 73 65 74 20 74 6f 20 4e 55 4c is.** set to NUL
18ed0 4c 2e 20 20 49 66 20 74 68 65 20 69 6e 70 75 74 L. If the input
18ee0 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e text contains n
18ef0 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e o SQL (if the in
18f00 70 75 74 0a 2a 2a 20 69 73 20 61 6e 64 20 65 6d put.** is and em
18f10 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 61 20 pty string or a
18f20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 comment) then *p
18f30 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 pStmt is set to
18f40 4e 55 4c 4c 2e 0a 2a 2a 20 7b 55 31 33 30 31 38 NULL..** {U13018
18f50 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 } The calling pr
18f60 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f ocedure is respo
18f70 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 nsible for delet
18f80 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 ing the.** compi
18f90 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e led SQL statemen
18fa0 74 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 t.** using [sqli
18fb0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
18fc0 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e after it has fin
18fd0 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a ished with it..*
18fe0 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c *.** On success,
18ff0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 [SQLITE_OK] is
19000 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 returned. Other
19010 77 69 73 65 20 61 6e 20 0a 2a 2a 20 5b 65 72 72 wise an .** [err
19020 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 or code] is retu
19030 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 rned..**.** The
19040 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
19050 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 v2() and sqlite3
19060 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 _prepare16_v2()
19070 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a interfaces are.*
19080 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f * recommended fo
19090 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 r all new progra
190a0 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 ms. The two olde
190b0 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 r interfaces are
190c0 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 retained.** for
190d0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 backwards compa
190e0 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 tibility, but th
190f0 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f eir use is disco
19100 75 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 uraged..** In th
19110 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 e "v2" interface
19120 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 s, the prepared
19130 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 statement.** tha
19140 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 t is returned (t
19150 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 he [sqlite3_stmt
19160 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 ] object) contai
19170 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 ns a copy of the
19180 20 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 .** original SQ
19190 4c 20 74 65 78 74 2e 20 7b 45 4e 44 7d 20 54 68 L text. {END} Th
191a0 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 is causes the [s
191b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 qlite3_step()] i
191c0 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 nterface to.** b
191d0 65 68 61 76 65 20 61 20 64 69 66 66 65 72 65 6e ehave a differen
191e0 74 6c 79 20 69 6e 20 74 77 6f 20 77 61 79 73 3a tly in two ways:
191f0 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c .**.** <ol>.** <
19200 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 li>.** If the da
19210 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 tabase schema ch
19220 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f anges, instead o
19230 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c f returning [SQL
19240 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 ITE_SCHEMA] as i
19250 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 t.** always used
19260 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 to do, [sqlite3
19270 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 _step()] will au
19280 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f tomatically reco
19290 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a mpile the SQL.**
192a0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 statement and t
192b0 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 ry to run it aga
192c0 69 6e 2e 20 20 49 66 20 74 68 65 20 73 63 68 65 in. If the sche
192d0 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64 20 69 ma has changed i
192e0 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68 61 74 20 n.** a way that
192f0 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74 65 6d makes the statem
19300 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 ent no longer va
19310 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 lid, [sqlite3_st
19320 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c ep()] will still
19330 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 .** return [SQLI
19340 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75 74 TE_SCHEMA]. But
19350 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67 61 unlike the lega
19360 63 79 20 62 65 68 61 76 69 6f 72 2c 20 0a 2a 2a cy behavior, .**
19370 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d [SQLITE_SCHEMA]
19380 20 69 73 20 6e 6f 77 20 61 20 66 61 74 61 6c 20 is now a fatal
19390 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 0a error. Calling.
193a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
193b0 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 are_v2()] again
193c0 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 will not make th
193d0 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 e.** error go aw
193e0 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b ay. Note: use [
193f0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
19400 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65 ] to find the te
19410 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 72 xt.** of the par
19420 73 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74 20 sing error that
19430 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 results in an [S
19440 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 QLITE_SCHEMA] re
19450 74 75 72 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 3c turn. {END}.** <
19460 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a /li>.**.** <li>.
19470 2a 2a 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 ** When an error
19480 20 6f 63 63 75 72 73 2c 20 0a 2a 2a 20 5b 73 71 occurs, .** [sq
19490 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 lite3_step()] wi
194a0 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 ll return one of
194b0 20 74 68 65 20 64 65 74 61 69 6c 65 64 20 0a 2a the detailed .*
194c0 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 * [error codes]
194d0 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 or [extended err
194e0 6f 72 20 63 6f 64 65 73 5d 2e 20 0a 2a 2a 20 54 or codes]. .** T
194f0 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 he legacy behavi
19500 6f 72 20 77 61 73 20 74 68 61 74 20 5b 73 71 6c or was that [sql
19510 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 ite3_step()] wou
19520 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 ld only return a
19530 20 67 65 6e 65 72 69 63 0a 2a 2a 20 5b 53 51 4c generic.** [SQL
19540 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c ITE_ERROR] resul
19550 74 20 63 6f 64 65 20 61 6e 64 20 79 6f 75 20 77 t code and you w
19560 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b ould have to mak
19570 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 e a second call
19580 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 to.** [sqlite3_r
19590 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72 eset()] in order
195a0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 to find the und
195b0 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 erlying cause of
195c0 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 0a 2a 2a the problem..**
195d0 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 With the "v2" p
195e0 72 65 70 61 72 65 20 69 6e 74 65 72 66 61 63 65 repare interface
195f0 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e s, the underlyin
19600 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 g reason for the
19610 20 65 72 72 6f 72 20 69 73 0a 2a 2a 20 72 65 74 error is.** ret
19620 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c urned immediatel
19630 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c y..** </li>.** <
19640 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 /ol>.**.** INVAR
19650 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 IANTS:.**.** {F1
19660 33 30 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 3011} The [sqlit
19670 65 33 5f 70 72 65 70 61 72 65 28 64 62 2c 7a 53 e3_prepare(db,zS
19680 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 ql,...)] and.**
19690 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
196a0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 3_prepare_v2(db,
196b0 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 zSql,...)] inter
196c0 66 61 63 65 73 20 69 6e 74 65 72 70 72 65 74 20 faces interpret
196d0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
196e0 74 65 78 74 20 69 6e 20 74 68 65 69 72 20 7a 53 text in their zS
196f0 71 6c 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 ql parameter as
19700 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 UTF-8..**.** {F1
19710 33 30 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 3012} The [sqlit
19720 65 33 5f 70 72 65 70 61 72 65 31 36 28 64 62 2c e3_prepare16(db,
19730 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a zSql,...)] and.*
19740 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
19750 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
19760 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 (db,zSql,...)] i
19770 6e 74 65 72 66 61 63 65 73 20 69 6e 74 65 72 70 nterfaces interp
19780 72 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 ret the.**
19790 20 20 20 20 74 65 78 74 20 69 6e 20 74 68 65 69 text in thei
197a0 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72 r zSql parameter
197b0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 as UTF-16 in th
197c0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 e native byte or
197d0 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 der..**.** {F130
197e0 31 33 7d 20 49 66 20 74 68 65 20 6e 42 79 74 65 13} If the nByte
197f0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 argument to [sq
19800 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
19810 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e (db,zSql,nByte,.
19820 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 ..)].**
19830 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 and its variant
19840 73 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a s is less than z
19850 65 72 6f 2c 20 74 68 65 6e 20 53 51 4c 20 74 65 ero, then SQL te
19860 78 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 xt is.**
19870 20 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c read from zSql
19880 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 is read up to t
19890 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 he first zero te
198a0 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 rminator..**.**
198b0 7b 46 31 33 30 31 34 7d 20 49 66 20 74 68 65 20 {F13014} If the
198c0 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74 nByte argument t
198d0 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 o [sqlite3_prepa
198e0 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 re_v2(db,zSql,nB
198f0 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 yte,...)].**
19900 20 20 20 20 20 20 61 6e 64 20 69 74 73 20 76 61 and its va
19910 72 69 61 6e 74 73 20 69 73 20 6e 6f 6e 2d 6e 65 riants is non-ne
19920 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 74 20 gative, then at
19930 6d 6f 73 74 20 6e 42 79 74 65 73 20 62 79 74 65 most nBytes byte
19940 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 s.** SQ
19950 4c 20 74 65 78 74 20 69 73 20 72 65 61 64 20 66 L text is read f
19960 72 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20 rom zSql..**.**
19970 7b 46 31 33 30 31 35 7d 20 49 6e 20 5b 73 71 6c {F13015} In [sql
19980 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
19990 64 62 2c 7a 53 71 6c 2c 4e 2c 50 2c 70 7a 54 61 db,zSql,N,P,pzTa
199a0 69 6c 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 il)] and its var
199b0 69 61 6e 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 iants.**
199c0 20 20 69 66 20 74 68 65 20 7a 53 71 6c 20 69 6e if the zSql in
199d0 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e put text contain
199e0 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 s more than one
199f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a SQL statement.**
19a00 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 70 7a and pz
19a10 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c Tail is not NULL
19a20 2c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 , then *pzTail i
19a30 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 s made to point
19a40 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 to the.**
19a50 20 20 20 66 69 72 73 74 20 62 79 74 65 20 70 61 first byte pa
19a60 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 st the end of th
19a70 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 e first SQL stat
19a80 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 0a 2a ement in zSql..*
19a90 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f * <todo
19aa0 3e 57 68 61 74 20 64 6f 65 73 20 2a 70 7a 54 61 >What does *pzTa
19ab0 69 6c 20 70 6f 69 6e 74 20 74 6f 20 69 66 20 74 il point to if t
19ac0 68 65 72 65 20 69 73 20 6f 6e 65 20 73 74 61 74 here is one stat
19ad0 65 6d 65 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a ement?</todo>.**
19ae0 0a 2a 2a 20 7b 46 31 33 30 31 36 7d 20 41 20 73 .** {F13016} A s
19af0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
19b00 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 o [sqlite3_prepa
19b10 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c re_v2(db,zSql,N,
19b20 70 70 53 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20 ppStmt,...)].**
19b30 20 20 20 20 20 20 20 20 20 6f 72 20 6f 6e 65 20 or one
19b40 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 of its variants
19b50 77 72 69 74 65 73 20 69 6e 74 6f 20 2a 70 70 53 writes into *ppS
19b60 74 6d 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f tmt a pointer to
19b70 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 a new.**
19b80 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 [prepared sta
19b90 74 65 6d 65 6e 74 5d 20 6f 72 20 61 20 70 6f 69 tement] or a poi
19ba0 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 0a 2a 2a 20 nter to NULL.**
19bb0 20 20 20 20 20 20 20 20 20 69 66 20 7a 53 71 6c if zSql
19bc0 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 74 68 69 6e contains nothin
19bd0 67 20 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69 g other than whi
19be0 74 65 73 70 61 63 65 20 6f 72 20 63 6f 6d 6d 65 tespace or comme
19bf0 6e 74 73 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 nts. .**.** {F13
19c00 30 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 019} The [sqlite
19c10 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
19c20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 20 69 74 interface and it
19c30 73 20 76 61 72 69 61 6e 74 73 20 72 65 74 75 72 s variants retur
19c40 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 n.** [S
19c50 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 61 6e 20 QLITE_OK] or an
19c60 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 appropriate [err
19c70 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 20 66 61 or code] upon fa
19c80 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 ilure..**.** {F1
19c90 33 30 32 31 7d 20 42 65 66 6f 72 65 20 5b 73 71 3021} Before [sq
19ca0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 64 62 lite3_prepare(db
19cb0 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 70 70 53 74 ,zSql,nByte,ppSt
19cc0 6d 74 2c 70 7a 54 61 69 6c 29 5d 20 6f 72 20 69 mt,pzTail)] or i
19cd0 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 ts.** v
19ce0 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e 73 20 ariants returns
19cf0 61 6e 20 65 72 72 6f 72 20 28 61 6e 79 20 76 61 an error (any va
19d00 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b lue other than [
19d10 53 51 4c 49 54 45 5f 4f 4b 5d 29 0a 2a 2a 20 20 SQLITE_OK]).**
19d20 20 20 20 20 20 20 20 20 69 74 20 66 69 72 73 74 it first
19d30 20 73 65 74 73 20 2a 70 70 53 74 6d 74 20 74 6f sets *ppStmt to
19d40 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 NULL..*/.int sq
19d50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 lite3_prepare(.
19d60 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
19d70 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
19d80 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 base handle */.
19d90 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 const char *zSq
19da0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 l, /* SQL
19db0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 statement, UTF-8
19dc0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e encoded */. in
19dd0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 t nByte,
19de0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d /* Maximum
19df0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 length of zSql
19e00 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 in bytes. */. s
19e10 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 qlite3_stmt **pp
19e20 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 Stmt, /* OUT: S
19e30 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 tatement handle
19e40 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
19e50 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 **pzTail /*
19e60 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 OUT: Pointer to
19e70 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f unused portion o
19e80 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 f zSql */.);.int
19e90 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
19ea0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a _v2(. sqlite3 *
19eb0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f db, /
19ec0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c * Database handl
19ed0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
19ee0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f r *zSql, /
19ef0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c * SQL statement,
19f00 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a UTF-8 encoded *
19f10 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 /. int nByte,
19f20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d /* M
19f30 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
19f40 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 zSql in bytes.
19f50 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d */. sqlite3_stm
19f60 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 t **ppStmt, /*
19f70 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 OUT: Statement h
19f80 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
19f90 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 char **pzTail
19fa0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 /* OUT: Point
19fb0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 er to unused por
19fc0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a tion of zSql */.
19fd0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 );.int sqlite3_p
19fe0 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 repare16(. sqli
19ff0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
1a000 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
1a010 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
1a020 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 t void *zSql,
1a030 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 /* SQL state
1a040 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 ment, UTF-16 enc
1a050 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 oded */. int nB
1a060 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 yte,
1a070 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e /* Maximum len
1a080 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 gth of zSql in b
1a090 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 ytes. */. sqlit
1a0a0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 e3_stmt **ppStmt
1a0b0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 , /* OUT: State
1a0c0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 ment handle */.
1a0d0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a const void **pz
1a0e0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a Tail /* OUT:
1a0f0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 Pointer to unus
1a100 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 ed portion of zS
1a110 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c ql */.);.int sql
1a120 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
1a130 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2(. sqlite3 *db
1a140 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 , /*
1a150 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 Database handle
1a160 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
1a170 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 *zSql, /*
1a180 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 SQL statement, U
1a190 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f TF-16 encoded */
1a1a0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 . int nByte,
1a1b0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 /* Ma
1a1c0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
1a1d0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a zSql in bytes. *
1a1e0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
1a1f0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
1a200 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
1a210 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
1a220 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 void **pzTail
1a230 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
1a240 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
1a250 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
1a260 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 52 45 46 ;../*.** CAPIREF
1a270 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 : Retrieving Sta
1a280 74 65 6d 65 6e 74 20 53 51 4c 20 7b 46 31 33 31 tement SQL {F131
1a290 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 00}.**.** This i
1a2a0 6e 74 65 72 65 66 61 63 65 20 63 61 6e 20 62 65 ntereface can be
1a2b0 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 used to retriev
1a2c0 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f e a saved copy o
1a2d0 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a f the original.*
1a2e0 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 * SQL text used
1a2f0 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 to create a [pre
1a300 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
1a310 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
1a320 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 TS:.**.** {F1310
1a330 31 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 1} If the [prepa
1a340 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 red statement] p
1a350 61 73 73 65 64 20 61 73 20 0a 2a 2a 20 20 20 20 assed as .**
1a360 20 20 20 20 20 20 74 68 65 20 61 6e 20 61 72 67 the an arg
1a370 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 ument to [sqlite
1a380 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 3_sql()] was com
1a390 70 69 6c 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 piled.**
1a3a0 20 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 compiled using
1a3b0 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 either [sqlite3
1a3c0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
1a3d0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 r.** [s
1a3e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
1a3f0 5f 76 32 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 _v2()],.**
1a400 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 then [sqlite
1a410 33 5f 73 71 6c 28 29 5d 20 66 75 6e 63 74 69 6f 3_sql()] functio
1a420 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e n returns a poin
1a430 74 65 72 20 74 6f 20 61 0a 2a 2a 20 20 20 20 20 ter to a.**
1a440 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e zero-termin
1a450 61 74 65 64 20 73 74 72 69 6e 67 20 63 6f 6e 74 ated string cont
1a460 61 69 6e 69 6e 67 20 61 20 55 54 46 2d 38 20 72 aining a UTF-8 r
1a470 65 6e 64 65 72 69 6e 67 0a 2a 2a 20 20 20 20 20 endering.**
1a480 20 20 20 20 20 6f 66 20 74 68 65 20 6f 72 69 67 of the orig
1a490 69 6e 61 6c 20 53 51 4c 20 73 74 61 74 65 6d 65 inal SQL stateme
1a4a0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 nt..**.** {F1310
1a4b0 32 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 2} If the [prepa
1a4c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 red statement] p
1a4d0 61 73 73 65 64 20 61 73 20 0a 2a 2a 20 20 20 20 assed as .**
1a4e0 20 20 20 20 20 20 74 68 65 20 61 6e 20 61 72 67 the an arg
1a4f0 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 ument to [sqlite
1a500 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 3_sql()] was com
1a510 70 69 6c 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 piled.**
1a520 20 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 compiled using
1a530 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 either [sqlite3
1a540 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a _prepare()] or.*
1a550 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
1a560 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d te3_prepare16()]
1a570 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 ,.** th
1a580 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 en [sqlite3_sql(
1a590 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 )] function retu
1a5a0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 rns a NULL point
1a5b0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 er..**.** {F1310
1a5c0 33 7d 20 54 68 65 20 73 74 72 69 6e 67 20 72 65 3} The string re
1a5d0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
1a5e0 65 33 5f 73 71 6c 28 53 29 5d 20 69 73 20 76 61 e3_sql(S)] is va
1a5f0 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 0a 2a 2a lid until the.**
1a600 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 [prepa
1a610 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
1a620 20 69 73 20 64 65 6c 65 74 65 64 20 75 73 69 6e is deleted usin
1a630 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c g [sqlite3_final
1a640 69 7a 65 28 53 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 ize(S)]..*/.cons
1a650 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
1a660 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 sql(sqlite3_stmt
1a670 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
1a680 20 43 41 50 49 33 52 45 46 3a 20 20 44 79 6e 61 CAPI3REF: Dyna
1a690 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 mically Typed Va
1a6a0 6c 75 65 20 4f 62 6a 65 63 74 20 20 7b 46 31 35 lue Object {F15
1a6b0 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 000}.** KEYWORDS
1a6c0 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c : {protected sql
1a6d0 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 ite3_value} {unp
1a6e0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
1a6f0 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 _value}.**.** SQ
1a700 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 Lite uses the sq
1a710 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
1a720 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 ct to represent
1a730 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 all values.** th
1a740 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 at can be stored
1a750 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 in a database t
1a760 61 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 able..** SQLite
1a770 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 uses dynamic typ
1a780 69 6e 67 20 66 6f 72 20 74 68 65 20 76 61 6c 75 ing for the valu
1a790 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 0a es it stores. .
1a7a0 2a 2a 20 56 61 6c 75 65 73 20 73 74 6f 72 65 64 ** Values stored
1a7b0 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 in sqlite3_valu
1a7c0 65 20 6f 62 6a 65 63 74 73 20 63 61 6e 20 62 65 e objects can be
1a7d0 0a 2a 2a 20 62 65 20 69 6e 74 65 67 65 72 73 2c .** be integers,
1a7e0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
1a7f0 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c values, strings,
1a800 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e BLOBs, or NULL.
1a810 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 .**.** An sqlite
1a820 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 3_value object m
1a830 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 ay be either "pr
1a840 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 otected" or "unp
1a850 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f rotected"..** So
1a860 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 me interfaces re
1a870 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 quire a protecte
1a880 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e d sqlite3_value.
1a890 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 Other interfac
1a8a0 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 es.** will accep
1a8b0 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 t either a prote
1a8c0 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f cted or an unpro
1a8d0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
1a8e0 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 alue..** Every i
1a8f0 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 nterface that ac
1a900 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 cepts sqlite3_va
1a910 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 lue arguments sp
1a920 65 63 69 66 69 65 73 20 0a 2a 2a 20 77 68 65 74 ecifies .** whet
1a930 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 her or not it re
1a940 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 quires a protect
1a950 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
1a960 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d ..**.** The term
1a970 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e s "protected" an
1a980 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 d "unprotected"
1a990 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 refer to whether
1a9a0 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 or not.** a mut
1a9b0 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 20 69 ex is held. A i
1a9c0 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 nternal mutex is
1a9d0 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 held for a prot
1a9e0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ected.** sqlite3
1a9f0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 _value object bu
1aa00 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 t no mutex is he
1aa10 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 ld for an unprot
1aa20 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ected.** sqlite3
1aa30 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 _value object.
1aa40 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
1aa50 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 piled to be sing
1aa60 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 le-threaded.** (
1aa70 77 69 74 68 20 53 51 4c 49 54 45 5f 54 48 52 45 with SQLITE_THRE
1aa80 41 44 53 41 46 45 3d 30 20 61 6e 64 20 77 69 74 ADSAFE=0 and wit
1aa90 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 h [sqlite3_threa
1aaa0 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 dsafe()] returni
1aab0 6e 67 20 30 29 0a 2a 2a 20 74 68 65 6e 20 74 68 ng 0).** then th
1aac0 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e ere is no distin
1aad0 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a ction between.**
1aae0 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 protected and u
1aaf0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
1ab00 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
1ab10 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 and they can be
1ab20 0a 2a 2a 20 75 73 65 64 20 69 6e 74 65 72 63 68 .** used interch
1ab30 61 6e 67 61 62 6c 65 2e 20 20 48 6f 77 65 76 65 angable. Howeve
1ab40 72 2c 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 r, for maximum c
1ab50 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 ode portability
1ab60 69 74 0a 2a 2a 20 69 73 20 72 65 63 6f 6d 6d 65 it.** is recomme
1ab70 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 nded that applic
1ab80 61 74 69 6f 6e 73 20 6d 61 6b 65 20 74 68 65 20 ations make the
1ab90 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 distinction betw
1aba0 65 65 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 70 een.** between p
1abb0 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 rotected and unp
1abc0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
1abd0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 _value objects e
1abe0 76 65 6e 20 69 66 0a 2a 2a 20 74 68 65 79 20 61 ven if.** they a
1abf0 72 65 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 re single thread
1ac00 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ed..**.** The sq
1ac10 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
1ac20 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 cts that are pas
1ac30 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 sed as parameter
1ac40 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d s into the.** im
1ac50 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
1ac60 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
1ac70 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ned SQL function
1ac80 73 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e s are protected.
1ac90 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
1aca0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 value object ret
1acb0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c urned by.** [sql
1acc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 ite3_column_valu
1acd0 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 e()] is unprotec
1ace0 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 ted..** Unprotec
1acf0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
1ad00 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e e objects may on
1ad10 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a ly be used with.
1ad20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 ** [sqlite3_resu
1ad30 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 lt_value()] and
1ad40 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 [sqlite3_bind_va
1ad50 6c 75 65 28 29 5d 2e 20 20 41 6c 6c 20 6f 74 68 lue()]. All oth
1ad60 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 er.** interfaces
1ad70 20 74 68 61 74 20 75 73 65 20 73 71 6c 69 74 65 that use sqlite
1ad80 33 5f 76 61 6c 75 65 20 72 65 71 75 69 72 65 20 3_value require
1ad90 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
1ada0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 3_value objects.
1adb0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
1adc0 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 ct Mem sqlite3_v
1add0 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 alue;../*.** CAP
1ade0 49 33 52 45 46 3a 20 20 53 51 4c 20 46 75 6e 63 I3REF: SQL Func
1adf0 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a tion Context Obj
1ae00 65 63 74 20 7b 46 31 36 30 30 31 7d 0a 2a 2a 0a ect {F16001}.**.
1ae10 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 ** The context i
1ae20 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 n which an SQL f
1ae30 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 unction executes
1ae40 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e is stored in an
1ae50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 .** sqlite3_cont
1ae60 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 41 20 70 ext object. A p
1ae70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c ointer to an sql
1ae80 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 20 ite3_context.**
1ae90 6f 62 6a 65 63 74 20 69 73 20 61 6c 77 61 79 73 object is always
1aea0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
1aeb0 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d to application-
1aec0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
1aed0 74 69 6f 6e 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 tions..*/.typede
1aee0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
1aef0 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 _context sqlite3
1af00 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a _context;../*.**
1af10 20 43 41 50 49 33 52 45 46 3a 20 20 42 69 6e 64 CAPI3REF: Bind
1af20 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 ing Values To Pr
1af30 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
1af40 73 20 7b 46 31 33 35 30 30 7d 0a 2a 2a 0a 2a 2a s {F13500}.**.**
1af50 20 49 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69 In the SQL stri
1af60 6e 67 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 ngs input to [sq
1af70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
1af80 28 29 5d 20 61 6e 64 20 69 74 73 0a 2a 2a 20 76 ()] and its.** v
1af90 61 72 69 61 6e 74 73 2c 20 6c 69 74 65 72 61 6c ariants, literal
1afa0 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 s may be replace
1afb0 20 62 79 20 61 20 70 61 72 61 6d 65 74 65 72 20 by a parameter
1afc0 69 6e 20 6f 6e 65 0a 2a 2a 20 6f 66 20 74 68 65 in one.** of the
1afd0 73 65 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 se forms:.**.**
1afe0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a <ul>.** <li> ?.
1aff0 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a ** <li> ?NNN.**
1b000 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c <li> :VVV.** <
1b010 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 li> @VVV.** <li
1b020 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e > $VVV.** </ul>
1b030 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70 61 .**.** In the pa
1b040 72 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 73 68 rameter forms sh
1b050 6f 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69 73 own above NNN is
1b060 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 an integer lite
1b070 72 61 6c 2c 0a 2a 2a 20 56 56 56 20 61 6c 70 68 ral,.** VVV alph
1b080 61 2d 6e 75 6d 65 72 69 63 20 70 61 72 61 6d 65 a-numeric parame
1b090 74 65 72 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 ter name..** The
1b0a0 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 values of these
1b0b0 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 parameters (als
1b0c0 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 o called "host p
1b0d0 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 0a arameter names".
1b0e0 2a 2a 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d ** or "SQL param
1b0f0 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 eters").** can b
1b100 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 e set using the
1b110 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 sqlite3_bind_*()
1b120 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 routines define
1b130 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 d here..**.** Th
1b140 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
1b150 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
1b160 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 bind_*() routine
1b170 73 20 61 6c 77 61 79 73 0a 2a 2a 20 69 73 20 61 s always.** is a
1b180 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
1b190 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f [sqlite3_stmt] o
1b1a0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 bject returned f
1b1b0 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f rom.** [sqlite3_
1b1c0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
1b1d0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 54 its variants. T
1b1e0 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 he second.** arg
1b1f0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 ument is the ind
1b200 65 78 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 ex of the parame
1b210 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 20 54 ter to be set. T
1b220 68 65 0a 2a 2a 20 66 69 72 73 74 20 70 61 72 61 he.** first para
1b230 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 meter has an ind
1b240 65 78 20 6f 66 20 31 2e 20 20 57 68 65 6e 20 74 ex of 1. When t
1b250 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a he same named.**
1b260 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 parameter is us
1b270 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 ed more than onc
1b280 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 e, second and su
1b290 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 bsequent.** occu
1b2a0 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 rrences have the
1b2b0 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 same index as t
1b2c0 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 he first occurre
1b2d0 6e 63 65 2e 20 0a 2a 2a 20 54 68 65 20 69 6e 64 nce. .** The ind
1b2e0 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 ex for named par
1b2f0 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c ameters can be l
1b300 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 ooked up using t
1b310 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 he.** [sqlite3_b
1b320 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 ind_parameter_na
1b330 6d 65 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 me()] API if des
1b340 69 72 65 64 2e 20 20 54 68 65 20 69 6e 64 65 78 ired. The index
1b350 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 .** for "?NNN" p
1b360 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 arameters is the
1b370 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a value of NNN..*
1b380 2a 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 * The NNN value
1b390 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 must be between
1b3a0 31 20 61 6e 64 20 74 68 65 20 63 6f 6d 70 69 6c 1 and the compil
1b3b0 65 2d 74 69 6d 65 0a 2a 2a 20 70 61 72 61 6d 65 e-time.** parame
1b3c0 74 65 72 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 ter SQLITE_MAX_V
1b3d0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 28 ARIABLE_NUMBER (
1b3e0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 default value: 9
1b3f0 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 99)..**.** The t
1b400 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 hird argument is
1b410 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 the value to bi
1b420 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 nd to the parame
1b430 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 ter..**.** In th
1b440 6f 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 ose.** routines
1b450 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 that have a four
1b460 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 th argument, its
1b470 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 6e 75 value is the nu
1b480 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a mber of bytes.**
1b490 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 in the paramete
1b4a0 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a r. To be clear:
1b4b0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 the value is th
1b4c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 e number of <u>b
1b4d0 79 74 65 73 3c 2f 75 3e 0a 2a 2a 20 69 6e 20 74 ytes</u>.** in t
1b4e0 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 he value, not th
1b4f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 e number of char
1b500 61 63 74 65 72 73 2e 20 0a 2a 2a 20 49 66 20 74 acters. .** If t
1b510 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
1b520 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c ter is negative,
1b530 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 the length of t
1b540 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 he string is.**
1b550 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
1b560 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 up to the first
1b570 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e zero terminator.
1b580 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 .**.** The fifth
1b590 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
1b5a0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 ite3_bind_blob()
1b5b0 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 , sqlite3_bind_t
1b5c0 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 ext(), and.** sq
1b5d0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 lite3_bind_text1
1b5e0 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63 6() is a destruc
1b5f0 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 tor used to disp
1b600 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 ose of the BLOB
1b610 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 or.** string aft
1b620 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 er SQLite has fi
1b630 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 nished with it.
1b640 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 If the fifth arg
1b650 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 ument is.** the
1b660 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 special value [S
1b670 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 QLITE_STATIC], t
1b680 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d hen SQLite assum
1b690 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 es that the.** i
1b6a0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e nformation is in
1b6b0 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 static, unmanag
1b6c0 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 ed space and doe
1b6d0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 s not need to be
1b6e0 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68 freed..** If th
1b6f0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 e fifth argument
1b700 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b has the value [
1b710 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 SQLITE_TRANSIENT
1b720 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 ], then.** SQLit
1b730 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 e makes its own
1b740 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 private copy of
1b750 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 the data immedia
1b760 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 tely, before.**
1b770 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 the sqlite3_bind
1b780 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 _*() routine ret
1b790 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 urns..**.** The
1b7a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 sqlite3_bind_zer
1b7b0 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 oblob() routine
1b7c0 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 binds a BLOB of
1b7d0 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a length N that.**
1b7e0 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 is filled with
1b7f0 7a 65 72 6f 73 2e 20 20 41 20 7a 65 72 6f 62 6c zeros. A zerobl
1b800 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 ob uses a fixed
1b810 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 amount of memory
1b820 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 .** (just an int
1b830 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 20 eger to hold it
1b840 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 size) while it i
1b850 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 s being processe
1b860 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 d..** Zeroblobs
1b870 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 are intended to
1b880 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 2d 68 serve as place-h
1b890 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 olders for BLOBs
1b8a0 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e whose.** conten
1b8b0 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 t is later writt
1b8c0 65 6e 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 en using .** [sq
1b8d0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 lite3_blob_open
1b8e0 7c 20 69 6e 63 72 65 6d 65 6e 74 20 42 4c 4f 42 | increment BLOB
1b8f0 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 20 I/O] routines.
1b900 41 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 76 61 A negative.** va
1b910 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f lue for the zero
1b920 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 blob results in
1b930 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c a zero-length BL
1b940 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 OB..**.** The sq
1b950 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 lite3_bind_*() r
1b960 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 outines must be
1b970 63 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 called after.**
1b980 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1b990 5f 76 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20 _v2()] (and its
1b9a0 76 61 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 variants) or [sq
1b9b0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 lite3_reset()] a
1b9c0 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 nd.** before [sq
1b9d0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a lite3_step()]..*
1b9e0 2a 20 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e * Bindings are n
1b9f0 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 ot cleared by th
1ba00 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 e [sqlite3_reset
1ba10 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 ()] routine..**
1ba20 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 Unbound paramete
1ba30 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 rs are interpret
1ba40 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a ed as NULL..**.*
1ba50 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
1ba60 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
1ba70 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f OK] on success o
1ba80 72 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 r an error code
1ba90 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 if.** anything g
1baa0 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c oes wrong. [SQL
1bab0 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 ITE_RANGE] is re
1bac0 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 turned if the pa
1bad0 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 rameter.** index
1bae0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 is out of range
1baf0 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d . [SQLITE_NOMEM
1bb00 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 ] is returned if
1bb10 20 6d 61 6c 6c 6f 63 20 66 61 69 6c 73 2e 0a 2a malloc fails..*
1bb20 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 * [SQLITE_MISUSE
1bb30 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 ] might be retur
1bb40 6e 65 64 20 69 66 20 74 68 65 73 65 20 72 6f 75 ned if these rou
1bb50 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 tines are called
1bb60 20 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61 6c on a.** virtual
1bb70 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20 69 73 machine that is
1bb80 20 74 68 65 20 77 72 6f 6e 67 20 73 74 61 74 65 the wrong state
1bb90 20 6f 72 20 77 68 69 63 68 20 68 61 73 20 61 6c or which has al
1bba0 72 65 61 64 79 20 62 65 65 6e 20 66 69 6e 61 6c ready been final
1bbb0 69 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63 74 69 ized..** Detecti
1bbc0 6f 6e 20 6f 66 20 6d 69 73 75 73 65 20 69 73 20 on of misuse is
1bbd0 75 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41 70 70 unreliable. App
1bbe0 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 lications should
1bbf0 20 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a 20 6f not depend.** o
1bc00 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 n SQLITE_MISUSE
1bc10 72 65 74 75 72 6e 73 2e 20 20 53 51 4c 49 54 45 returns. SQLITE
1bc20 5f 4d 49 53 55 53 45 20 69 73 20 69 6e 74 65 6e _MISUSE is inten
1bc30 64 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 ded to indicate
1bc40 61 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65 72 72 a.** a logic err
1bc50 6f 72 20 69 6e 20 74 68 65 20 61 70 70 6c 69 63 or in the applic
1bc60 61 74 69 6f 6e 2e 20 20 46 75 74 75 72 65 20 76 ation. Future v
1bc70 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
1bc80 65 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e 69 63 e might.** panic
1bc90 20 72 61 74 68 65 72 20 74 68 61 6e 20 72 65 74 rather than ret
1bca0 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 urn SQLITE_MISUS
1bcb0 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 E..**.** See als
1bcc0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 o: [sqlite3_bind
1bcd0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 _parameter_count
1bce0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
1bcf0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
1bd00 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 name()], and.**
1bd10 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
1bd20 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d rameter_index()]
1bd30 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
1bd40 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 30 TS:.**.** {F1350
1bd50 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6} The [sqlite3_
1bd60 70 72 65 70 61 72 65 20 7c 20 53 51 4c 20 73 74 prepare | SQL st
1bd70 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 atement compiler
1bd80 5d 20 72 65 63 6f 67 6e 69 7a 65 73 0a 2a 2a 20 ] recognizes.**
1bd90 20 20 20 20 20 20 20 20 20 74 6f 6b 65 6e 73 20 tokens
1bda0 6f 66 20 74 68 65 20 66 6f 72 6d 73 20 22 3f 22 of the forms "?"
1bdb0 2c 20 22 3f 4e 4e 4e 22 2c 20 22 24 56 56 56 22 , "?NNN", "$VVV"
1bdc0 2c 20 22 3a 56 56 56 22 2c 20 61 6e 64 20 22 40 , ":VVV", and "@
1bdd0 56 56 56 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 VVV".**
1bde0 20 61 73 20 53 51 4c 20 70 61 72 61 6d 65 74 65 as SQL paramete
1bdf0 72 73 2c 20 77 68 65 72 65 20 4e 4e 4e 20 69 73 rs, where NNN is
1be00 20 61 6e 79 20 73 65 71 75 65 6e 63 65 20 6f 66 any sequence of
1be10 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 one or more.**
1be20 20 20 20 20 20 20 20 20 20 64 69 67 69 74 73 20 digits
1be30 61 6e 64 20 77 68 65 72 65 20 56 56 56 20 69 73 and where VVV is
1be40 20 61 6e 79 20 73 65 71 75 65 6e 63 65 20 6f 66 any sequence of
1be50 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 0a 2a 2a one or more .**
1be60 20 20 20 20 20 20 20 20 20 20 61 6c 70 68 61 6e alphan
1be70 75 6d 65 72 69 63 20 63 68 61 72 61 63 74 65 72 umeric character
1be80 73 20 6f 72 20 22 3a 3a 22 20 6f 70 74 69 6f 6e s or "::" option
1be90 61 6c 6c 79 20 66 6f 6c 6c 6f 77 65 64 20 62 79 ally followed by
1bea0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 73 .** a s
1beb0 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 tring containing
1bec0 20 6e 6f 20 73 70 61 63 65 73 20 61 6e 64 20 63 no spaces and c
1bed0 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 ontained within
1bee0 70 61 72 65 6e 74 68 65 73 65 73 2e 0a 2a 2a 0a parentheses..**.
1bef0 2a 2a 20 7b 46 31 33 35 30 39 7d 20 54 68 65 20 ** {F13509} The
1bf00 69 6e 69 74 69 61 6c 20 76 61 6c 75 65 20 6f 66 initial value of
1bf10 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 an SQL paramete
1bf20 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a r is NULL..**.**
1bf30 20 7b 46 31 33 35 31 32 7d 20 54 68 65 20 69 6e {F13512} The in
1bf40 64 65 78 20 6f 66 20 61 6e 20 22 3f 22 20 53 51 dex of an "?" SQ
1bf50 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f L parameter is o
1bf60 6e 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 ne larger than t
1bf70 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c he.** l
1bf80 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f 66 20 argest index of
1bf90 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f SQL parameter to
1bfa0 20 74 68 65 20 6c 65 66 74 2c 20 6f 72 20 31 20 the left, or 1
1bfb0 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 if.** t
1bfc0 68 65 20 22 3f 22 20 69 73 20 74 68 65 20 6c 65 he "?" is the le
1bfd0 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d ftmost SQL param
1bfe0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 eter..**.** {F13
1bff0 35 31 35 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 515} The index o
1c000 66 20 61 6e 20 22 3f 4e 4e 4e 22 20 53 51 4c 20 f an "?NNN" SQL
1c010 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
1c020 20 69 6e 74 65 67 65 72 20 4e 4e 4e 2e 0a 2a 2a integer NNN..**
1c030 0a 2a 2a 20 7b 46 31 33 35 31 38 7d 20 54 68 65 .** {F13518} The
1c040 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3a 56 index of an ":V
1c050 56 56 22 2c 20 22 24 56 56 56 22 2c 20 6f 72 20 VV", "$VVV", or
1c060 22 40 56 56 56 22 20 53 51 4c 20 70 61 72 61 6d "@VVV" SQL param
1c070 65 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20 20 eter is.**
1c080 20 20 20 20 74 68 65 20 73 61 6d 65 20 61 73 20 the same as
1c090 74 68 65 20 69 6e 64 65 78 20 6f 66 20 6c 65 66 the index of lef
1c0a0 74 6d 6f 73 74 20 6f 63 63 75 72 61 6e 63 65 73 tmost occurances
1c0b0 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 of the same.**
1c0c0 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 paramet
1c0d0 65 72 2c 20 6f 72 20 6f 6e 65 20 6d 6f 72 65 20 er, or one more
1c0e0 74 68 61 6e 20 74 68 65 20 6c 61 72 67 65 73 74 than the largest
1c0f0 20 69 6e 64 65 78 20 6f 76 65 72 20 61 6c 6c 0a index over all.
1c100 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 ** para
1c110 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 6c 65 meters to the le
1c120 66 74 20 69 66 20 74 68 69 73 20 69 73 20 74 68 ft if this is th
1c130 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 61 6e e first occurran
1c140 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f ce.** o
1c150 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 f this parameter
1c160 2c 20 6f 72 20 31 20 69 66 20 74 68 69 73 20 69 , or 1 if this i
1c170 73 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 70 s the leftmost p
1c180 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 arameter..**.**
1c190 7b 46 31 33 35 32 31 7d 20 54 68 65 20 5b 73 71 {F13521} The [sq
1c1a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 lite3_prepare |
1c1b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f SQL statement co
1c1c0 6d 70 69 6c 65 72 5d 20 66 61 69 6c 20 77 69 74 mpiler] fail wit
1c1d0 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e h.** an
1c1e0 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 [SQLITE_RANGE]
1c1f0 65 72 72 6f 72 20 69 66 20 74 68 65 20 69 6e 64 error if the ind
1c200 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 ex of an SQL par
1c210 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 ameter.**
1c220 20 20 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 is less than
1c230 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 1 or greater tha
1c240 6e 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 n SQLITE_MAX_VAR
1c250 49 41 42 4c 45 5f 4e 55 4d 42 45 52 2e 0a 2a 2a IABLE_NUMBER..**
1c260 0a 2a 2a 20 7b 46 31 33 35 32 34 7d 20 43 61 6c .** {F13524} Cal
1c270 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 ls to [sqlite3_b
1c280 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 ind_text | sqlit
1c290 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 56 2c 2e 2e e3_bind(S,N,V,..
1c2a0 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 .)].**
1c2b0 61 73 73 6f 63 69 61 74 65 20 74 68 65 20 76 61 associate the va
1c2c0 6c 75 65 20 56 20 77 69 74 68 20 61 6c 6c 20 53 lue V with all S
1c2d0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 68 61 QL parameters ha
1c2e0 76 69 6e 67 20 61 6e 0a 2a 2a 20 20 20 20 20 20 ving an.**
1c2f0 20 20 20 20 69 6e 64 65 78 20 6f 66 20 4e 20 69 index of N i
1c300 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 n the [prepared
1c310 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a statement] S..**
1c320 0a 2a 2a 20 7b 46 31 33 35 32 37 7d 20 43 61 6c .** {F13527} Cal
1c330 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 ls to [sqlite3_b
1c340 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 ind_text | sqlit
1c350 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e 2e 2e 29 e3_bind(S,N,...)
1c360 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76 ].** ov
1c370 65 72 72 69 64 65 20 70 72 69 6f 72 20 63 61 6c erride prior cal
1c380 6c 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 ls with the same
1c390 20 76 61 6c 75 65 73 20 6f 66 20 53 20 61 6e 64 values of S and
1c3a0 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 N..**.** {F1353
1c3b0 30 7d 20 42 69 6e 64 69 6e 67 73 20 65 73 74 61 0} Bindings esta
1c3c0 62 6c 69 73 68 65 64 20 62 79 20 5b 73 71 6c 69 blished by [sqli
1c3d0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 te3_bind_text |
1c3e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 2e sqlite3_bind(S,.
1c3f0 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 ..)].**
1c400 20 70 65 72 73 69 73 74 20 61 63 72 6f 73 73 20 persist across
1c410 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
1c420 33 5f 72 65 73 65 74 28 53 29 5d 2e 0a 2a 2a 0a 3_reset(S)]..**.
1c430 2a 2a 20 7b 46 31 33 35 33 33 7d 20 49 6e 20 63 ** {F13533} In c
1c440 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
1c450 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 _bind_blob(S,N,V
1c460 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 ,L,D)],.**
1c470 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e [sqlite3_bin
1c480 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 d_text(S,N,V,L,D
1c490 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 )], or.**
1c4a0 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 [sqlite3_bind
1c4b0 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c _text16(S,N,V,L,
1c4c0 44 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 D)] SQLite binds
1c4d0 20 74 68 65 20 66 69 72 73 74 20 4c 0a 2a 2a 20 the first L.**
1c4e0 20 20 20 20 20 20 20 20 20 62 79 74 65 73 20 6f bytes o
1c4f0 66 20 74 68 65 20 62 6c 6f 62 20 6f 72 20 73 74 f the blob or st
1c500 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 ring pointed to
1c510 62 79 20 56 2c 20 77 68 65 6e 20 4c 0a 2a 2a 20 by V, when L.**
1c520 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d is non-
1c530 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 negative..**.**
1c540 7b 46 31 33 35 33 36 7d 20 49 6e 20 63 61 6c 6c {F13536} In call
1c550 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 s to [sqlite3_bi
1c560 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c nd_text(S,N,V,L,
1c570 44 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 D)] or.**
1c580 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 [sqlite3_bind
1c590 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c _text16(S,N,V,L,
1c5a0 44 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 D)] SQLite binds
1c5b0 20 63 68 61 72 61 63 74 65 72 73 0a 2a 2a 20 20 characters.**
1c5c0 20 20 20 20 20 20 20 20 66 72 6f 6d 20 56 20 74 from V t
1c5d0 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 hrough the first
1c5e0 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 20 zero character
1c5f0 77 68 65 6e 20 4c 20 69 73 20 6e 65 67 61 74 69 when L is negati
1c600 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 ve..**.** {F1353
1c610 39 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 9} In calls to [
1c620 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
1c630 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a b(S,N,V,L,D)],.*
1c640 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
1c650 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c te3_bind_text(S,
1c660 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a N,V,L,D)], or.**
1c670 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
1c680 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 e3_bind_text16(S
1c690 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 ,N,V,L,D)] when
1c6a0 44 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c D is the special
1c6b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e .** con
1c6c0 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 stant [SQLITE_ST
1c6d0 41 54 49 43 5d 2c 20 53 51 4c 69 74 65 20 61 73 ATIC], SQLite as
1c6e0 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 76 sumes that the v
1c6f0 61 6c 75 65 20 56 0a 2a 2a 20 20 20 20 20 20 20 alue V.**
1c700 20 20 20 69 73 20 68 65 6c 64 20 69 6e 20 73 74 is held in st
1c710 61 74 69 63 20 75 6e 6d 61 6e 61 67 65 64 20 73 atic unmanaged s
1c720 70 61 63 65 20 74 68 61 74 20 77 69 6c 6c 20 6e pace that will n
1c730 6f 74 20 63 68 61 6e 67 65 0a 2a 2a 20 20 20 20 ot change.**
1c740 20 20 20 20 20 20 64 75 72 69 6e 67 20 74 68 65 during the
1c750 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 lifetime of the
1c760 20 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 binding..**.**
1c770 7b 46 31 33 35 34 32 7d 20 49 6e 20 63 61 6c 6c {F13542} In call
1c780 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 s to [sqlite3_bi
1c790 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c nd_blob(S,N,V,L,
1c7a0 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 D)],.**
1c7b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 [sqlite3_bind_t
1c7c0 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c ext(S,N,V,L,D)],
1c7d0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 or.**
1c7e0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 [sqlite3_bind_te
1c7f0 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d xt16(S,N,V,L,D)]
1c800 20 77 68 65 6e 20 44 20 69 73 20 74 68 65 20 73 when D is the s
1c810 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 pecial.**
1c820 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c constant [SQL
1c830 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 ITE_TRANSIENT],
1c840 74 68 65 20 72 6f 75 74 69 6e 65 20 6d 61 6b 65 the routine make
1c850 73 20 61 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 s a .**
1c860 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 private copy of
1c870 20 56 20 76 61 6c 75 65 20 62 65 66 6f 72 65 20 V value before
1c880 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a it returns..**.*
1c890 2a 20 7b 46 31 33 35 34 35 7d 20 49 6e 20 63 61 * {F13545} In ca
1c8a0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
1c8b0 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c bind_blob(S,N,V,
1c8c0 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 L,D)],.**
1c8d0 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 [sqlite3_bind
1c8e0 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 _text(S,N,V,L,D)
1c8f0 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 ], or.**
1c900 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f [sqlite3_bind_
1c910 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 text16(S,N,V,L,D
1c920 29 5d 20 77 68 65 6e 20 44 20 69 73 20 61 20 70 )] when D is a p
1c930 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 ointer to.**
1c940 20 20 20 20 20 20 61 20 66 75 6e 63 74 69 6f 6e a function
1c950 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 , SQLite invokes
1c960 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 74 that function t
1c970 6f 20 64 65 73 74 72 6f 79 20 74 68 65 0a 2a 2a o destroy the.**
1c980 20 20 20 20 20 20 20 20 20 20 56 20 76 61 6c 75 V valu
1c990 65 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 e after it has f
1c9a0 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 inished using th
1c9b0 65 20 56 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a e V value..**.**
1c9c0 20 7b 46 31 33 35 34 38 7d 20 49 6e 20 63 61 6c {F13548} In cal
1c9d0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 ls to [sqlite3_b
1c9e0 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 53 2c 4e ind_zeroblob(S,N
1c9f0 2c 56 2c 4c 29 5d 20 74 68 65 20 76 61 6c 75 65 ,V,L)] the value
1ca00 20 62 6f 75 6e 64 0a 2a 2a 20 20 20 20 20 20 20 bound.**
1ca10 20 20 20 69 73 20 61 20 62 6c 6f 62 20 6f 66 20 is a blob of
1ca20 4c 20 62 79 74 65 73 2c 20 6f 72 20 61 20 7a 65 L bytes, or a ze
1ca30 72 6f 2d 6c 65 6e 67 74 68 20 62 6c 6f 62 20 69 ro-length blob i
1ca40 66 20 4c 20 69 73 20 6e 65 67 61 74 69 76 65 2e f L is negative.
1ca50 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 35 31 7d 20 .**.** {F13551}
1ca60 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c In calls to [sql
1ca70 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 ite3_bind_value(
1ca80 53 2c 4e 2c 56 29 5d 20 74 68 65 20 56 20 61 72 S,N,V)] the V ar
1ca90 67 75 6d 65 6e 74 20 6d 61 79 0a 2a 2a 20 20 20 gument may.**
1caa0 20 20 20 20 20 20 20 62 65 20 65 69 74 68 65 72 be either
1cab0 20 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 a [protected sq
1cac0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
1cad0 65 63 74 20 6f 72 20 61 6e 0a 2a 2a 20 20 20 20 ect or an.**
1cae0 20 20 20 20 20 20 5b 75 6e 70 72 6f 74 65 63 74 [unprotect
1caf0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
1cb00 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 ] object..*/.int
1cb10 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c sqlite3_bind_bl
1cb20 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ob(sqlite3_stmt*
1cb30 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 , int, const voi
1cb40 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 d*, int n, void(
1cb50 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 *)(void*));.int
1cb60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 sqlite3_bind_dou
1cb70 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ble(sqlite3_stmt
1cb80 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b *, int, double);
1cb90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
1cba0 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 d_int(sqlite3_st
1cbb0 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a mt*, int, int);.
1cbc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
1cbd0 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 _int64(sqlite3_s
1cbe0 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 tmt*, int, sqlit
1cbf0 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 e3_int64);.int s
1cc00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c qlite3_bind_null
1cc10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
1cc20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 int);.int sqlite
1cc30 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 3_bind_text(sqli
1cc40 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
1cc50 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 const char*, int
1cc60 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 n, void(*)(void
1cc70 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 *));.int sqlite3
1cc80 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c _bind_text16(sql
1cc90 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
1cca0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
1ccb0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a t, void(*)(void*
1ccc0 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f ));.int sqlite3_
1ccd0 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 bind_value(sqlit
1cce0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 e3_stmt*, int, c
1ccf0 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c onst sqlite3_val
1cd00 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 ue*);.int sqlite
1cd10 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 3_bind_zeroblob(
1cd20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
1cd30 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a nt, int n);../*.
1cd40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d ** CAPI3REF: Num
1cd50 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d ber Of SQL Param
1cd60 65 74 65 72 73 20 7b 46 31 33 36 30 30 7d 0a 2a eters {F13600}.*
1cd70 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
1cd80 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f e can be used to
1cd90 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 find the number
1cda0 20 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65 of SQL paramete
1cdb0 72 73 0a 2a 2a 20 69 6e 20 61 20 70 72 65 70 61 rs.** in a prepa
1cdc0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 red statement.
1cdd0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 SQL parameters a
1cde0 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 re tokens of the
1cdf0 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f .** form "?", "?
1ce00 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 NNN", ":AAA", "$
1ce10 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 AAA", or "@AAA"
1ce20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a that serve as.**
1ce30 20 70 6c 61 63 65 2d 68 6f 6c 64 65 72 73 20 66 place-holders f
1ce40 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 or values that a
1ce50 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 re [sqlite3_bind
1ce60 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a _blob | bound].*
1ce70 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 * to the paramet
1ce80 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 ers at a later t
1ce90 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ime..**.** This
1cea0 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 routine actually
1ceb0 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 returns the ind
1cec0 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 ex of the larges
1ced0 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 t parameter..**
1cee0 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 For all forms ex
1cef0 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 cept ?NNN, this
1cf00 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 will correspond
1cf10 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 to the number of
1cf20 0a 2a 2a 20 75 6e 69 71 75 65 20 70 61 72 61 6d .** unique param
1cf30 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d eters. If param
1cf40 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e eters of the ?NN
1cf50 4e 20 61 72 65 20 75 73 65 64 2c 20 74 68 65 72 N are used, ther
1cf60 65 20 6d 61 79 0a 2a 2a 20 62 65 20 67 61 70 73 e may.** be gaps
1cf70 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a in the list..**
1cf80 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
1cf90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
1cfa0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d |sqlite3_bind()]
1cfb0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 ,.** [sqlite3_bi
1cfc0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d nd_parameter_nam
1cfd0 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 e()], and.** [sq
1cfe0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
1cff0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a eter_index()]..*
1d000 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
1d010 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 30 31 7d 20 .**.** {F13601}
1d020 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e The [sqlite3_bin
1d030 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e d_parameter_coun
1d040 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 t(S)] interface
1d050 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 returns.**
1d060 20 20 20 20 74 68 65 20 6c 61 72 67 65 73 74 20 the largest
1d070 69 6e 64 65 78 20 6f 66 20 61 6c 6c 20 53 51 4c index of all SQL
1d080 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 74 parameters in t
1d090 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b he.** [
1d0a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1d0b0 6e 74 5d 20 53 2c 20 6f 72 20 30 20 69 66 20 53 nt] S, or 0 if S
1d0c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e .** con
1d0d0 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 70 61 72 tains no SQL par
1d0e0 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e 74 20 ameters..*/.int
1d0f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
1d100 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c ameter_count(sql
1d110 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a ite3_stmt*);../*
1d120 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 .** CAPI3REF: Na
1d130 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 me Of A Host Par
1d140 61 6d 65 74 65 72 20 7b 46 31 33 36 32 30 7d 0a ameter {F13620}.
1d150 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
1d160 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ne returns a poi
1d170 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 nter to the name
1d180 20 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20 of the n-th.**
1d190 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e SQL parameter in
1d1a0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
1d1b0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20 tement]..** SQL
1d1c0 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 parameters of th
1d1d0 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 e form "?NNN" or
1d1e0 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 ":AAA" or "@AAA
1d1f0 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 " or "$AAA".** h
1d200 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 ave a name which
1d210 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 is the string "
1d220 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 ?NNN" or ":AAA"
1d230 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 or "@AAA" or "$A
1d240 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 AA".** respectiv
1d250 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 ely..** In other
1d260 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 words, the init
1d270 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f ial ":" or "$" o
1d280 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 r "@" or "?".**
1d290 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 is included as p
1d2a0 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e art of the name.
1d2b0 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 73 20 6f .** Parameters o
1d2c0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 f the form "?" w
1d2d0 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 ithout a followi
1d2e0 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 ng integer have
1d2f0 6e 6f 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 no name..**.** T
1d300 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 he first host pa
1d310 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 rameter has an i
1d320 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 ndex of 1, not 0
1d330 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76 ..**.** If the v
1d340 61 6c 75 65 20 6e 20 69 73 20 6f 75 74 20 6f 66 alue n is out of
1d350 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 range or if the
1d360 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 n-th parameter
1d370 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 is.** nameless,
1d380 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 then NULL is ret
1d390 75 72 6e 65 64 2e 20 20 54 68 65 20 72 65 74 75 urned. The retu
1d3a0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a rned string is.*
1d3b0 2a 20 61 6c 77 61 79 73 20 69 6e 20 74 68 65 20 * always in the
1d3c0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 UTF-8 encoding e
1d3d0 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 ven if the named
1d3e0 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a parameter was.*
1d3f0 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 * originally spe
1d400 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 cified as UTF-16
1d410 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 in [sqlite3_pre
1d420 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 pare16()] or.**
1d430 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1d440 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 16_v2()]..**.**
1d450 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
1d460 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c e3_bind_blob|sql
1d470 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a ite3_bind()],.**
1d480 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
1d490 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 arameter_count()
1d4a0 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 ], and.** [sqlit
1d4b0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
1d4c0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a r_index()]..**.*
1d4d0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
1d4e0 0a 2a 2a 20 7b 46 31 33 36 32 31 7d 20 54 68 65 .** {F13621} The
1d4f0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
1d500 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 53 2c arameter_name(S,
1d510 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 N)] interface re
1d520 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 turns.**
1d530 20 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 a UTF-8 render
1d540 69 6e 67 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 ing of the name
1d550 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d of the SQL param
1d560 65 74 65 72 20 69 6e 0a 2a 2a 20 20 20 20 20 20 eter in.**
1d570 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 [prepared st
1d580 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 76 69 6e atement] S havin
1d590 67 20 69 6e 64 65 78 20 4e 2c 20 6f 72 0a 2a 2a g index N, or.**
1d5a0 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 69 NULL i
1d5b0 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 53 51 f there is no SQ
1d5c0 4c 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 L parameter with
1d5d0 20 69 6e 64 65 78 20 4e 20 6f 72 20 69 66 20 74 index N or if t
1d5e0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 he.** p
1d5f0 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 69 6e arameter with in
1d600 64 65 78 20 4e 20 69 73 20 61 6e 20 61 6e 6f 6e dex N is an anon
1d610 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 20 ymous parameter
1d620 22 3f 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 "?"..*/.const ch
1d630 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 ar *sqlite3_bind
1d640 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 _parameter_name(
1d650 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
1d660 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 nt);../*.** CAPI
1d670 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 3REF: Index Of A
1d680 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 Parameter With
1d690 41 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b 46 31 A Given Name {F1
1d6a0 33 36 34 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 3640}.**.** Retu
1d6b0 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 rn the index of
1d6c0 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 an SQL parameter
1d6d0 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e given its name.
1d6e0 20 20 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 The.** index v
1d6f0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 alue returned is
1d700 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 suitable for us
1d710 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a e as the second.
1d720 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 ** parameter to
1d730 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
1d740 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 ob|sqlite3_bind(
1d750 29 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20 69 )]. A zero.** i
1d760 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f s returned if no
1d770 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 matching parame
1d780 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 54 ter is found. T
1d790 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 he parameter.**
1d7a0 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 name must be giv
1d7b0 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e en in UTF-8 even
1d7c0 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c if the original
1d7d0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 statement.** wa
1d7e0 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 s prepared from
1d7f0 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e UTF-16 text usin
1d800 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 g [sqlite3_prepa
1d810 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a re16_v2()]..**.*
1d820 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
1d830 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 ite3_bind_blob|s
1d840 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a qlite3_bind()],.
1d850 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
1d860 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 _parameter_count
1d870 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
1d880 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
1d890 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a ter_index()]..**
1d8a0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
1d8b0 2a 2a 0a 2a 2a 20 7b 46 31 33 36 34 31 7d 20 54 **.** {F13641} T
1d8c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 he [sqlite3_bind
1d8d0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 _parameter_index
1d8e0 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 (S,N)] interface
1d8f0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 returns.**
1d900 20 20 20 20 20 74 68 65 20 69 6e 64 65 78 20 6f the index o
1d910 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 f SQL parameter
1d920 69 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 in [prepared sta
1d930 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 tement].**
1d940 20 20 20 20 53 20 77 68 6f 73 65 20 6e 61 6d 65 S whose name
1d950 20 6d 61 74 63 68 65 73 20 74 68 65 20 55 54 46 matches the UTF
1d960 2d 38 20 73 74 72 69 6e 67 20 4e 2c 20 6f 72 20 -8 string N, or
1d970 30 20 69 66 20 74 68 65 72 65 20 69 73 0a 2a 2a 0 if there is.**
1d980 20 20 20 20 20 20 20 20 20 20 6e 6f 20 6d 61 74 no mat
1d990 63 68 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ch..*/.int sqlit
1d9a0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
1d9b0 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f r_index(sqlite3_
1d9c0 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 stmt*, const cha
1d9d0 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a r *zName);../*.*
1d9e0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 * CAPI3REF: Rese
1d9f0 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f t All Bindings O
1da00 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 n A Prepared Sta
1da10 74 65 6d 65 6e 74 20 7b 46 31 33 36 36 30 7d 0a tement {F13660}.
1da20 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20 74 **.** Contrary t
1da30 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 o the intuition
1da40 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 of many, [sqlite
1da50 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 3_reset()] does
1da60 6e 6f 74 0a 2a 2a 20 72 65 73 65 74 20 74 68 65 not.** reset the
1da70 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
1da80 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 lob | bindings]
1da90 6f 6e 20 61 20 0a 2a 2a 20 5b 70 72 65 70 61 72 on a .** [prepar
1daa0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 ed statement].
1dab0 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 Use this routine
1dac0 20 74 6f 0a 2a 2a 20 72 65 73 65 74 20 61 6c 6c to.** reset all
1dad0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 host parameters
1dae0 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 to NULL..**.**
1daf0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
1db00 2a 20 7b 46 31 33 36 36 31 7d 20 54 68 65 20 5b * {F13661} The [
1db10 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 sqlite3_clear_bi
1db20 6e 64 69 6e 67 73 28 53 29 5d 20 69 6e 74 65 72 ndings(S)] inter
1db30 66 61 63 65 20 72 65 73 65 74 73 20 61 6c 6c 0a face resets all.
1db40 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 ** SQL
1db50 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e parameter bindin
1db60 67 73 20 69 6e 20 5b 70 72 65 70 61 72 65 64 20 gs in [prepared
1db70 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 statement] S.**
1db80 20 20 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f back to
1db90 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 NULL..*/.int sq
1dba0 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 lite3_clear_bind
1dbb0 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d ings(sqlite3_stm
1dbc0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
1dbd0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 3REF: Number Of
1dbe0 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 Columns In A Res
1dbf0 75 6c 74 20 53 65 74 20 7b 46 31 33 37 31 30 7d ult Set {F13710}
1dc00 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 .**.** Return th
1dc10 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 e number of colu
1dc20 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c mns in the resul
1dc30 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 t set returned b
1dc40 79 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 y the .** [prepa
1dc50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 red statement].
1dc60 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 This routine ret
1dc70 75 72 6e 73 20 30 0a 2a 2a 20 69 66 20 70 53 74 urns 0.** if pSt
1dc80 6d 74 20 69 73 20 61 6e 20 53 51 4c 20 73 74 61 mt is an SQL sta
1dc90 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 tement that does
1dca0 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 not return data
1dcb0 20 28 66 6f 72 20 0a 2a 2a 20 65 78 61 6d 70 6c (for .** exampl
1dcc0 65 20 61 6e 20 55 50 44 41 54 45 29 2e 0a 2a 2a e an UPDATE)..**
1dcd0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
1dce0 2a 2a 0a 2a 2a 20 7b 46 31 33 37 31 31 7d 20 54 **.** {F13711} T
1dcf0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 he [sqlite3_colu
1dd00 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 mn_count(S)] int
1dd10 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 erface returns t
1dd20 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 he number of.**
1dd30 20 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 73 columns
1dd40 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 in the result s
1dd50 65 74 20 67 65 6e 65 72 61 74 65 64 20 62 79 20 et generated by
1dd60 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
1dd70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
1dd80 65 6e 74 5d 20 53 2c 20 6f 72 20 30 20 69 66 20 ent] S, or 0 if
1dd90 53 20 64 6f 65 73 20 6e 6f 74 20 67 65 6e 65 72 S does not gener
1dda0 61 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ate.**
1ddb0 61 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2f a result set..*/
1ddc0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c .int sqlite3_col
1ddd0 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 umn_count(sqlite
1dde0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
1ddf0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1de00 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e Column Names In
1de10 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b 46 A Result Set {F
1de20 31 33 37 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 13720}.**.** The
1de30 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 se routines retu
1de40 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 rn the name assi
1de50 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 gned to a partic
1de60 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 ular column.** i
1de70 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 n the result set
1de80 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74 61 of a SELECT sta
1de90 74 65 6d 65 6e 74 2e 20 20 54 68 65 20 73 71 6c tement. The sql
1dea0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
1deb0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 ().** interface
1dec0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
1ded0 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d r to a zero-term
1dee0 69 6e 61 74 65 64 20 55 54 46 38 20 73 74 72 69 inated UTF8 stri
1def0 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 ng.** and sqlite
1df00 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 3_column_name16(
1df10 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e ) returns a poin
1df20 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 ter to a zero-te
1df30 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 31 rminated.** UTF1
1df40 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 66 6 string. The f
1df50 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 irst parameter i
1df60 73 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 s the.** [prepar
1df70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
1df80 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 at implements th
1df90 65 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 e SELECT stateme
1dfa0 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e nt..** The secon
1dfb0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 d parameter is t
1dfc0 68 65 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 he column number
1dfd0 2e 20 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 . The left-most
1dfe0 20 63 6f 6c 75 6d 6e 20 69 73 0a 2a 2a 20 6e 75 column is.** nu
1dff0 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 mber 0..**.** Th
1e000 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e e returned strin
1e010 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c g pointer is val
1e020 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 id until either
1e030 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the .** [prepare
1e040 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 d statement] is
1e050 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 destroyed by [sq
1e060 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
1e070 5d 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 ].** or until th
1e080 65 20 6e 65 78 74 20 63 61 6c 6c 20 73 71 6c 69 e next call sqli
1e090 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 te3_column_name(
1e0a0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c ) or sqlite3_col
1e0b0 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a 2a 20 umn_name16().**
1e0c0 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 on the same colu
1e0d0 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c mn..**.** If sql
1e0e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 ite3_malloc() fa
1e0f0 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 ils during the p
1e100 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 rocessing of eit
1e110 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 her routine.** (
1e120 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 for example duri
1e130 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 ng a conversion
1e140 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 from UTF-8 to UT
1e150 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 F-16) then a.**
1e160 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 NULL pointer is
1e170 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
1e180 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 The name of a re
1e190 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 sult column is t
1e1a0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 he value of the
1e1b0 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a "AS" clause for.
1e1c0 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 ** that column,
1e1d0 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 if there is an A
1e1e0 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 S clause. If th
1e1f0 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 ere is no AS cla
1e200 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 use.** then the
1e210 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 name of the colu
1e220 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 mn is unspecifie
1e230 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 d and may change
1e240 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c from.** one rel
1e250 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 ease of SQLite t
1e260 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a o the next..**.*
1e270 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
1e280 0a 2a 2a 20 7b 46 31 33 37 32 31 7d 20 41 20 73 .** {F13721} A s
1e290 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 uccessful invoca
1e2a0 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c tion of the [sql
1e2b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
1e2c0 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 (S,N)].**
1e2d0 20 20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 interface ret
1e2e0 75 72 6e 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a urns the name.**
1e2f0 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 of the
1e300 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 Nth column (whe
1e310 72 65 20 30 20 69 73 20 74 68 65 20 6c 65 66 74 re 0 is the left
1e320 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f -most column) fo
1e330 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 r the.**
1e340 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 result set of
1e350 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
1e360 65 6e 74 5d 20 53 20 61 73 20 61 0a 2a 2a 20 20 ent] S as a.**
1e370 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 zero-ter
1e380 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 minated UTF-8 st
1e390 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 ring..**.** {F13
1e3a0 37 32 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 723} A successfu
1e3b0 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 l invocation of
1e3c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c the [sqlite3_col
1e3d0 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d umn_name16(S,N)]
1e3e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 .** int
1e3f0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 erface returns t
1e400 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 he name.**
1e410 20 20 20 20 6f 66 20 74 68 65 20 4e 74 68 20 63 of the Nth c
1e420 6f 6c 75 6d 6e 20 28 77 68 65 72 65 20 30 20 69 olumn (where 0 i
1e430 73 20 74 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 s the left-most
1e440 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65 0a column) for the.
1e450 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75 ** resu
1e460 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 lt set of [prepa
1e470 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
1e480 20 61 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 as a.**
1e490 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 zero-terminate
1e4a0 64 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 d UTF-16 string
1e4b0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 in the native by
1e4c0 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 te order..**.**
1e4d0 7b 46 31 33 37 32 34 7d 20 54 68 65 20 5b 73 71 {F13724} The [sq
1e4e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
1e4f0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 e()] and [sqlite
1e500 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 3_column_name16(
1e510 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 )].** i
1e520 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e nterfaces return
1e530 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
1e540 69 66 20 74 68 65 79 20 61 72 65 20 75 6e 61 62 if they are unab
1e550 6c 65 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 le to.**
1e560 20 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 allocate memor
1e570 79 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 y memory to hold
1e580 20 74 68 65 72 65 20 6e 6f 72 6d 61 6c 20 72 65 there normal re
1e590 74 75 72 6e 20 73 74 72 69 6e 67 73 2e 0a 2a 2a turn strings..**
1e5a0 0a 2a 2a 20 7b 46 31 33 37 32 35 7d 20 49 66 20 .** {F13725} If
1e5b0 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 the N parameter
1e5c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to [sqlite3_colu
1e5d0 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f 72 mn_name(S,N)] or
1e5e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
1e5f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
1e600 65 31 36 28 53 2c 4e 29 5d 20 69 73 20 6f 75 74 e16(S,N)] is out
1e610 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 6e 20 of range, then
1e620 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
1e630 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72 interfaces retur
1e640 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ns a NULL pointe
1e650 72 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 33 37 32 r..** .** {F1372
1e660 36 7d 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 6} The strings r
1e670 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 eturned by [sqli
1e680 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 te3_column_name(
1e690 53 2c 4e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 S,N)] and.**
1e6a0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 [sqlite3_c
1e6b0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e olumn_name16(S,N
1e6c0 29 5d 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 )] are valid unt
1e6d0 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 20 il the next.**
1e6e0 20 20 20 20 20 20 20 20 63 61 6c 6c 20 74 6f 20 call to
1e6f0 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 20 77 either routine w
1e700 69 74 68 20 74 68 65 20 73 61 6d 65 20 53 20 61 ith the same S a
1e710 6e 64 20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a nd N parameters.
1e720 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 75 ** or u
1e730 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 ntil [sqlite3_fi
1e740 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 61 nalize(S)] is ca
1e750 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 lled..**.** {F13
1e760 37 32 37 7d 20 57 68 65 6e 20 61 20 72 65 73 75 727} When a resu
1e770 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b lt column of a [
1e780 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
1e790 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 t contains.**
1e7a0 20 20 20 20 20 20 20 61 6e 20 41 53 20 63 6c 61 an AS cla
1e7b0 75 73 65 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 use, the name of
1e7c0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 that column is
1e7d0 74 68 65 20 69 6e 64 65 6e 74 69 66 69 65 72 0a the indentifier.
1e7e0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 ** to t
1e7f0 68 65 20 72 69 67 68 74 20 6f 66 20 74 68 65 20 he right of the
1e800 41 53 20 6b 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63 AS keyword..*/.c
1e810 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
1e820 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 e3_column_name(s
1e830 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
1e840 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 t N);.const void
1e850 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
1e860 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f _name16(sqlite3_
1e870 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a stmt*, int N);..
1e880 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1e890 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 Source Of Data I
1e8a0 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 n A Query Result
1e8b0 20 7b 46 31 33 37 34 30 7d 0a 2a 2a 0a 2a 2a 20 {F13740}.**.**
1e8c0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 These routines p
1e8d0 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 rovide a means t
1e8e0 6f 20 64 65 74 65 72 6d 69 6e 65 20 77 68 61 74 o determine what
1e8f0 20 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a column of what.
1e900 2a 2a 20 74 61 62 6c 65 20 69 6e 20 77 68 69 63 ** table in whic
1e910 68 20 64 61 74 61 62 61 73 65 20 61 20 72 65 73 h database a res
1e920 75 6c 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 ult of a SELECT
1e930 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20 statement comes
1e940 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d from..** The nam
1e950 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 e of the databas
1e960 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f e or table or co
1e970 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 lumn can be retu
1e980 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 rned as.** eithe
1e990 72 20 61 20 55 54 46 38 20 6f 72 20 55 54 46 31 r a UTF8 or UTF1
1e9a0 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 6 string. The _
1e9b0 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e database_ routin
1e9c0 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 es return.** the
1e9d0 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 database name,
1e9e0 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 the _table_ rout
1e9f0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 ines return the
1ea00 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a table name, and.
1ea10 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 ** the origin_ r
1ea20 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 outines return t
1ea30 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a he column name..
1ea40 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 ** The returned
1ea50 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 string is valid
1ea60 75 6e 74 69 6c 0a 2a 2a 20 74 68 65 20 5b 70 72 until.** the [pr
1ea70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1ea80 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 75 ] is destroyed u
1ea90 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 sing.** [sqlite3
1eaa0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 _finalize()] or
1eab0 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 until the same i
1eac0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 nformation is re
1ead0 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e quested.** again
1eae0 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 in a different
1eaf0 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 encoding..**.**
1eb00 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e The names return
1eb10 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 ed are the origi
1eb20 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e nal un-aliased n
1eb30 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 ames of the.** d
1eb40 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 atabase, table,
1eb50 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a and column..**.*
1eb60 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 * The first argu
1eb70 6d 65 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c ment to the foll
1eb80 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61 owing calls is a
1eb90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
1eba0 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 ment]..** These
1ebb0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e functions return
1ebc0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f information abo
1ebd0 75 74 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d ut the Nth colum
1ebe0 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a n returned by .*
1ebf0 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c * the statement,
1ec00 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 where N is the
1ec10 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 second function
1ec20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 argument..**.**
1ec30 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d If the Nth colum
1ec40 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 n returned by th
1ec50 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 e statement is a
1ec60 6e 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 n expression.**
1ec70 6f 72 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 or subquery and
1ec80 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 is not a column
1ec90 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 value, then all
1eca0 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f of these functio
1ecb0 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20 4e 55 4c ns.** return NUL
1ecc0 4c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e L. These routin
1ecd0 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 e might also ret
1ece0 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 urn NULL if a me
1ecf0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 mory.** allocati
1ed00 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e on error occurs.
1ed10 20 20 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 Otherwise, the
1ed20 79 20 72 65 74 75 72 6e 20 74 68 65 20 0a 2a 2a y return the .**
1ed30 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 name of the att
1ed40 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 ached database,
1ed50 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e table and column
1ed60 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75 that query resu
1ed70 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 77 61 73 lt.** column was
1ed80 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e extracted from.
1ed90 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20 61 .**.** As with a
1eda0 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 ll other SQLite
1edb0 41 50 49 73 2c 20 74 68 6f 73 65 20 70 6f 73 74 APIs, those post
1edc0 66 69 78 65 64 20 77 69 74 68 20 22 31 36 22 20 fixed with "16"
1edd0 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 return.** UTF-16
1ede0 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 encoded strings
1edf0 2c 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 , the other func
1ee00 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 tions return UTF
1ee10 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 -8. {END}.**.**
1ee20 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f These APIs are o
1ee30 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 nly available if
1ee40 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 the library was
1ee50 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 compiled with t
1ee60 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e he .** SQLITE_EN
1ee70 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 ABLE_COLUMN_META
1ee80 44 41 54 41 20 70 72 65 70 72 6f 63 65 73 73 6f DATA preprocesso
1ee90 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 r symbol defined
1eea0 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 33 37 35 31 7d ..**.** {U13751}
1eeb0 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f .** If two or mo
1eec0 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 re threads call
1eed0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 one or more of t
1eee0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 hese routines ag
1eef0 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a ainst the same.*
1ef00 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 * prepared state
1ef10 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 ment and column
1ef20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 at the same time
1ef30 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 then the result
1ef40 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e s are.** undefin
1ef50 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 ed..**.** INVARI
1ef60 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 ANTS:.**.** {F13
1ef70 37 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 741} The [sqlite
1ef80 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 3_column_databas
1ef90 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 e_name(S,N)] int
1efa0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 erface returns e
1efb0 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 ither.**
1efc0 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f the UTF-8 zero
1efd0 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 -terminated name
1efe0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
1eff0 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 from which the
1f000 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 .** Nth
1f010 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f result column o
1f020 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 f [prepared stat
1f030 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 ement] S .**
1f040 20 20 20 20 20 20 69 73 20 65 78 74 72 61 63 74 is extract
1f050 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 ed, or NULL if t
1f060 68 65 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d he the Nth colum
1f070 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 n of S is a.**
1f080 20 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 general
1f090 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 expression or if
1f0a0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 unable to alloc
1f0b0 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 ate memory.**
1f0c0 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 to store
1f0d0 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 the name..**
1f0e0 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 .** {F1374
1f0f0 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 2} The [sqlite3_
1f100 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f column_database_
1f110 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 name16(S,N)] int
1f120 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 erface returns e
1f130 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 ither.**
1f140 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 the UTF-16 nat
1f150 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a ive byte order.*
1f160 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d * zero-
1f170 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 terminated name
1f180 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 of the database
1f190 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a from which the .
1f1a0 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 ** Nth
1f1b0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 result column of
1f1c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
1f1d0 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 ment] S .**
1f1e0 20 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65 is extracte
1f1f0 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 d, or NULL if th
1f200 65 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e e the Nth column
1f210 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 of S is a.**
1f220 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65 general e
1f230 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 xpression or if
1f240 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 unable to alloca
1f250 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 te memory.**
1f260 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 to store t
1f270 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 he name..**
1f280 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 33 .** {F13743
1f290 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 } The [sqlite3_c
1f2a0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 olumn_table_name
1f2b0 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 (S,N)] interface
1f2c0 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a returns either.
1f2d0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
1f2e0 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 UTF-8 zero-termi
1f2f0 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 nated name of th
1f300 65 20 74 61 62 6c 65 20 66 72 6f 6d 20 77 68 69 e table from whi
1f310 63 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 ch the .**
1f320 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 Nth result c
1f330 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 olumn of [prepar
1f340 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 ed statement] S
1f350 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 .** is
1f360 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 extracted, or NU
1f370 4c 4c 20 69 66 20 74 68 65 20 74 68 65 20 4e 74 LL if the the Nt
1f380 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 h column of S is
1f390 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67 a.** g
1f3a0 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f eneral expressio
1f3b0 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 n or if unable t
1f3c0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 o allocate memor
1f3d0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f y.** to
1f3e0 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e store the name.
1f3f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a .** .**
1f400 20 7b 46 31 33 37 34 34 7d 20 54 68 65 20 5b 73 {F13744} The [s
1f410 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 qlite3_column_ta
1f420 62 6c 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d ble_name16(S,N)]
1f430 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
1f440 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 ns either.**
1f450 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 the UTF-16
1f460 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
1f470 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a er.** z
1f480 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e ero-terminated n
1f490 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 ame of the table
1f4a0 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 from which the
1f4b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 .** Nth
1f4c0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f result column o
1f4d0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 f [prepared stat
1f4e0 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 ement] S .**
1f4f0 20 20 20 20 20 20 69 73 20 65 78 74 72 61 63 74 is extract
1f500 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 ed, or NULL if t
1f510 68 65 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d he the Nth colum
1f520 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 n of S is a.**
1f530 20 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 general
1f540 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 expression or if
1f550 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 unable to alloc
1f560 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 ate memory.**
1f570 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 to store
1f580 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 the name..**
1f590 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 .** {F1374
1f5a0 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 5} The [sqlite3_
1f5b0 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 column_origin_na
1f5c0 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 me(S,N)] interfa
1f5d0 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 ce returns eithe
1f5e0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 r.** th
1f5f0 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 e UTF-8 zero-ter
1f600 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 minated name of
1f610 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e the table column
1f620 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 from which the
1f630 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 .** Nth
1f640 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f result column o
1f650 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 f [prepared stat
1f660 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 ement] S .**
1f670 20 20 20 20 20 20 69 73 20 65 78 74 72 61 63 74 is extract
1f680 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 ed, or NULL if t
1f690 68 65 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d he the Nth colum
1f6a0 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 n of S is a.**
1f6b0 20 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 general
1f6c0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 expression or if
1f6d0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 unable to alloc
1f6e0 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 ate memory.**
1f6f0 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 to store
1f700 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 the name..**
1f710 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 .** {F1374
1f720 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6} The [sqlite3_
1f730 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 column_origin_na
1f740 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 me16(S,N)] inter
1f750 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 face returns eit
1f760 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 her.**
1f770 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 the UTF-16 nativ
1f780 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 e byte order.**
1f790 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 zero-te
1f7a0 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 rminated name of
1f7b0 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d the table colum
1f7c0 6e 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 n from which the
1f7d0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 .** Nt
1f7e0 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 h result column
1f7f0 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 of [prepared sta
1f800 74 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 tement] S .**
1f810 20 20 20 20 20 20 20 69 73 20 65 78 74 72 61 63 is extrac
1f820 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 ted, or NULL if
1f830 74 68 65 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 the the Nth colu
1f840 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 mn of S is a.**
1f850 20 20 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c general
1f860 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 expression or i
1f870 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f f unable to allo
1f880 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 cate memory.**
1f890 20 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 to store
1f8a0 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 the name..**
1f8b0 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 .** {F137
1f8c0 34 38 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 48} The return v
1f8d0 61 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 20 20 alues from.**
1f8e0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
1f8f0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f column_database_
1f900 6e 61 6d 65 7c 63 6f 6c 75 6d 6e 20 6d 65 74 61 name|column meta
1f910 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d data interfaces]
1f920 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 .** are
1f930 20 76 61 6c 69 64 0a 2a 2a 20 20 20 20 20 20 20 valid.**
1f940 20 20 20 66 6f 72 20 74 68 65 20 6c 69 66 65 74 for the lifet
1f950 69 6d 65 20 6f 66 20 74 68 65 20 5b 70 72 65 70 ime of the [prep
1f960 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a ared statement].
1f970 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 75 ** or u
1f980 6e 74 69 6c 20 74 68 65 20 65 6e 63 6f 64 69 6e ntil the encodin
1f990 67 20 69 73 20 63 68 61 6e 67 65 64 20 62 79 20 g is changed by
1f9a0 61 6e 6f 74 68 65 72 20 6d 65 74 61 64 61 74 61 another metadata
1f9b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 .** int
1f9c0 65 72 66 61 63 65 20 63 61 6c 6c 20 66 6f 72 20 erface call for
1f9d0 74 68 65 20 73 61 6d 65 20 70 72 65 70 61 72 65 the same prepare
1f9e0 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 d statement and
1f9f0 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 4c 49 column..**.** LI
1fa00 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a MITATIONS:.**.**
1fa10 20 7b 55 31 33 37 35 31 7d 20 49 66 20 74 77 6f {U13751} If two
1fa20 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 or more threads
1fa30 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 call one or mor
1fa40 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 e.** [s
1fa50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 qlite3_column_da
1fa60 74 61 62 61 73 65 5f 6e 61 6d 65 7c 63 6f 6c 75 tabase_name|colu
1fa70 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 mn metadata inte
1fa80 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20 rfaces].**
1fa90 20 20 20 20 74 68 65 20 73 61 6d 65 20 5b 70 72 the same [pr
1faa0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1fab0 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c ] and result col
1fac0 75 6d 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 umn.**
1fad0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 at the same time
1fae0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 then the result
1faf0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e s are undefined.
1fb00 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a .*/.const char *
1fb10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
1fb20 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c atabase_name(sql
1fb30 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
1fb40 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
1fb50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 ite3_column_data
1fb60 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 base_name16(sqli
1fb70 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
1fb80 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 const char *sqli
1fb90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 te3_column_table
1fba0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 _name(sqlite3_st
1fbb0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 mt*,int);.const
1fbc0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
1fbd0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 lumn_table_name1
1fbe0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
1fbf0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 int);.const char
1fc00 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
1fc10 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c _origin_name(sql
1fc20 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
1fc30 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
1fc40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 ite3_column_orig
1fc50 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 in_name16(sqlite
1fc60 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 3_stmt*,int);../
1fc70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
1fc80 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 eclared Datatype
1fc90 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 Of A Query Resu
1fca0 6c 74 20 7b 46 31 33 37 36 30 7d 0a 2a 2a 0a 2a lt {F13760}.**.*
1fcb0 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 * The first para
1fcc0 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 meter is a [prep
1fcd0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
1fce0 20 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 .** If this sta
1fcf0 74 65 6d 65 6e 74 20 69 73 20 61 20 53 45 4c 45 tement is a SELE
1fd00 43 54 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 CT statement and
1fd10 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
1fd20 6f 66 20 74 68 65 20 0a 2a 2a 20 72 65 74 75 72 of the .** retur
1fd30 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f ned result set o
1fd40 66 20 74 68 61 74 20 53 45 4c 45 43 54 20 69 73 f that SELECT is
1fd50 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 a table column
1fd60 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 (not an.** expre
1fd70 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 ssion or subquer
1fd80 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c y) then the decl
1fd90 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 ared type of the
1fda0 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e table.** column
1fdb0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 49 is returned. I
1fdc0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e f the Nth column
1fdd0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 of the result s
1fde0 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 et is an.** expr
1fdf0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 ession or subque
1fe00 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 ry, then a NULL
1fe10 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 pointer is retur
1fe20 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 ned..** The retu
1fe30 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 rned string is a
1fe40 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f lways UTF-8 enco
1fe50 64 65 64 2e 20 20 7b 45 4e 44 7d 20 0a 2a 2a 20 ded. {END} .**
1fe60 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 For example, in
1fe70 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 the database sch
1fe80 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 ema:.**.** CREAT
1fe90 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 E TABLE t1(c1 VA
1fea0 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 41 6e RIANT);.**.** An
1feb0 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 d the following
1fec0 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c statement compil
1fed0 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 ed:.**.** SELECT
1fee0 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d c1 + 1, c1 FROM
1fef0 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 54 68 65 6e 20 t1;.**.** Then
1ff00 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 this routine wou
1ff10 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 ld return the st
1ff20 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 ring "VARIANT" f
1ff30 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a or the second.**
1ff40 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 result column (
1ff50 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c i==1), and a NUL
1ff60 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 L pointer for th
1ff70 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 e first result c
1ff80 6f 6c 75 6d 6e 0a 2a 2a 20 28 69 3d 3d 30 29 2e olumn.** (i==0).
1ff90 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 .**.** SQLite us
1ffa0 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 es dynamic run-t
1ffb0 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 53 6f 20 ime typing. So
1ffc0 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63 just because a c
1ffd0 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c olumn.** is decl
1ffe0 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 ared to contain
1fff0 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 a particular typ
20000 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 e does not mean
20010 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 that the.** data
20020 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 stored in that
20030 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 column is of the
20040 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 declared type.
20050 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 SQLite is.** st
20060 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 rongly typed, bu
20070 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 t the typing is
20080 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 dynamic not stat
20090 69 63 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73 20 ic. Type.** is
200a0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
200b0 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 individual value
200c0 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 s, not with the
200d0 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 containers.** us
200e0 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 ed to hold those
200f0 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 values..**.** I
20100 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
20110 20 7b 46 31 33 37 36 31 7d 20 20 41 20 73 75 63 {F13761} A suc
20120 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 cessful call to
20130 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
20140 64 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d 0a 2a decltype(S,N)].*
20150 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75 * retu
20160 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 rns a zero-termi
20170 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 nated UTF-8 stri
20180 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 ng containing th
20190 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 e.** t
201a0 68 65 20 64 65 63 6c 61 72 65 64 20 64 61 74 61 he declared data
201b0 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c type of the tabl
201c0 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 e column that ap
201d0 70 65 61 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 pears.**
201e0 20 20 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f as the Nth co
201f0 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20 66 lumn (numbered f
20200 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65 rom 0) of the re
20210 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65 0a sult set to the.
20220 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 ** [pr
20230 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
20240 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 ] S..**.** {F137
20250 36 32 7d 20 20 41 20 73 75 63 63 65 73 73 66 75 62} A successfu
20260 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 l call to [sqlit
20270 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 e3_column_declty
20280 70 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 pe16(S,N)].**
20290 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 returns
202a0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
202b0 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 d UTF-16 native
202c0 62 79 74 65 20 6f 72 64 65 72 20 73 74 72 69 6e byte order strin
202d0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 g.** c
202e0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 65 ontaining the de
202f0 63 6c 61 72 65 64 20 64 61 74 61 74 79 70 65 20 clared datatype
20300 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c of the table col
20310 75 6d 6e 20 74 68 61 74 20 61 70 70 65 61 72 73 umn that appears
20320 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 73 .** as
20330 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
20340 28 6e 75 6d 62 65 72 65 64 20 66 72 6f 6d 20 30 (numbered from 0
20350 29 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 ) of the result
20360 73 65 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 set to the.**
20370 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 [prepare
20380 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a d statement] S..
20390 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36 33 7d 20 20 **.** {F13763}
203a0 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 If N is less tha
203b0 6e 20 30 20 6f 72 20 4e 20 69 73 20 67 72 65 61 n 0 or N is grea
203c0 74 65 72 20 74 68 61 6e 20 6f 72 20 65 71 75 61 ter than or equa
203d0 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 l to.**
203e0 20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 the number of
203f0 63 6f 6c 75 6d 6e 73 20 69 6e 20 5b 70 72 65 70 columns in [prep
20400 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
20410 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f S.** o
20420 72 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c r if the Nth col
20430 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 6e 20 65 umn of S is an e
20440 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 xpression or sub
20450 71 75 65 72 79 20 72 61 74 68 65 72 0a 2a 2a 20 query rather.**
20460 20 20 20 20 20 20 20 20 20 20 74 68 61 6e 20 61 than a
20470 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 6f 72 table column or
20480 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c if a memory all
20490 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 0a ocation failure.
204a0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 63 63 ** occ
204b0 75 72 73 20 64 75 72 69 6e 67 20 65 6e 63 6f 64 urs during encod
204c0 69 6e 67 20 63 6f 6e 76 65 72 73 69 6f 6e 73 2c ing conversions,
204d0 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 then.**
204e0 20 20 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c calls to [sql
204f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c ite3_column_decl
20500 74 79 70 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a type(S,N)] or.**
20510 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 [sqli
20520 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 te3_column_declt
20530 79 70 65 31 36 28 53 2c 4e 29 5d 20 72 65 74 75 ype16(S,N)] retu
20540 72 6e 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73 rn NULL..*/.cons
20550 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
20560 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 column_decltype(
20570 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
20580 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a t);.const void *
20590 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
205a0 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 ecltype16(sqlite
205b0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 3_stmt*,int);../
205c0 2a 20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 * .** CAPI3REF:
205d0 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c Evaluate An SQL
205e0 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 32 Statement {F132
205f0 30 30 7d 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 00}.**.** After
20600 61 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 an [prepared sta
20610 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e tement] has been
20620 20 70 72 65 70 61 72 65 64 20 77 69 74 68 20 61 prepared with a
20630 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 65 69 74 68 call.** to eith
20640 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 er [sqlite3_prep
20650 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 are_v2()] or [sq
20660 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
20670 76 32 28 29 5d 20 6f 72 20 74 6f 20 6f 6e 65 20 v2()] or to one
20680 6f 66 0a 2a 2a 20 74 68 65 20 6c 65 67 61 63 79 of.** the legacy
20690 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c interfaces [sql
206a0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
206b0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 or [sqlite3_prep
206c0 61 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 74 68 65 are16()],.** the
206d0 6e 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 n this function
206e0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f must be called o
206f0 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 ne or more times
20700 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 to evaluate the
20710 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 0a .** statement..
20720 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c **.** The detail
20730 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f s of the behavio
20740 72 20 6f 66 20 74 68 69 73 20 73 71 6c 69 74 65 r of this sqlite
20750 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 3_step() interfa
20760 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 ce depend.** on
20770 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74 whether the stat
20780 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 ement was prepar
20790 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 ed using the new
207a0 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 er "v2" interfac
207b0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 e.** [sqlite3_pr
207c0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 epare_v2()] and
207d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
207e0 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 16_v2()] or the
207f0 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 older legacy.**
20800 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 interface [sqlit
20810 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e e3_prepare()] an
20820 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 d [sqlite3_prepa
20830 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 re16()]. The us
20840 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 e of the.** new
20850 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 "v2" interface i
20860 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f s recommended fo
20870 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f r new applicatio
20880 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 ns but the legac
20890 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 y.** interface w
208a0 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 ill continue to
208b0 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a be supported..**
208c0 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67 61 63 .** In the legac
208d0 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 y interface, the
208e0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 return value wi
208f0 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 ll be either [SQ
20900 4c 49 54 45 5f 42 55 53 59 5d 2c 20 0a 2a 2a 20 LITE_BUSY], .**
20910 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b [SQLITE_DONE], [
20920 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 SQLITE_ROW], [SQ
20930 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 LITE_ERROR], or
20940 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e [SQLITE_MISUSE].
20950 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 22 76 32 .** With the "v2
20960 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 " interface, any
20970 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 53 of the other [S
20980 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c QLITE_OK | resul
20990 74 20 63 6f 64 65 5d 0a 2a 2a 20 6f 72 20 5b 53 t code].** or [S
209a0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 QLITE_IOERR_READ
209b0 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 | extended resu
209c0 6c 74 20 63 6f 64 65 5d 20 6d 69 67 68 74 20 62 lt code] might b
209d0 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a e returned as.**
209e0 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 well..**.** [SQ
209f0 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 LITE_BUSY] means
20a00 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 that the databa
20a10 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e se engine was un
20a20 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 able to acquire
20a30 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 the.** database
20a40 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 locks it needs t
20a50 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 49 o do its job. I
20a60 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 f the statement
20a70 69 73 20 61 20 43 4f 4d 4d 49 54 0a 2a 2a 20 6f is a COMMIT.** o
20a80 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 r occurs outside
20a90 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 of an explicit
20aa0 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 transaction, the
20ab0 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 n you can retry
20ac0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 the.** statement
20ad0 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d . If the statem
20ae0 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 43 4f 4d ent is not a COM
20af0 4d 49 54 20 61 6e 64 20 6f 63 63 75 72 73 20 77 MIT and occurs w
20b00 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 ithin a.** expli
20b10 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 cit transaction
20b20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 then you should
20b30 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 rollback the tra
20b40 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a nsaction before.
20b50 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a ** continuing..*
20b60 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e *.** [SQLITE_DON
20b70 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 E] means that th
20b80 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 e statement has
20b90 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 finished executi
20ba0 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c ng.** successful
20bb0 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 ly. sqlite3_ste
20bc0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 p() should not b
20bd0 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f e called again o
20be0 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a n this virtual.*
20bf0 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 * machine withou
20c00 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 t first calling
20c10 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
20c20 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 ] to reset the v
20c30 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e irtual.** machin
20c40 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e e back to its in
20c50 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a itial state..**.
20c60 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 ** If the SQL st
20c70 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 atement being ex
20c80 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 ecuted returns a
20c90 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 0a 2a ny data, then .*
20ca0 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 69 * [SQLITE_ROW] i
20cb0 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 s returned each
20cc0 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f time a new row o
20cd0 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 0a f data is ready.
20ce0 2a 2a 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e ** for processin
20cf0 67 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e g by the caller.
20d00 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 The values may
20d10 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e be accessed usin
20d20 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 g.** the [sqlite
20d30 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 63 3_column_int | c
20d40 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e olumn access fun
20d50 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 ctions]..** sqli
20d60 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 te3_step() is ca
20d70 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 lled again to re
20d80 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 trieve the next
20d90 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 20 row of data..**
20da0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f .** [SQLITE_ERRO
20db0 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 R] means that a
20dc0 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 run-time error (
20dd0 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 such as a constr
20de0 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f aint.** violatio
20df0 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e n) has occurred.
20e00 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 sqlite3_step()
20e10 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 should not be c
20e20 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a alled again on.*
20e30 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 * the VM. More i
20e40 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 nformation may b
20e50 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 e found by calli
20e60 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d ng [sqlite3_errm
20e70 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 sg()]..** With t
20e80 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 he legacy interf
20e90 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 ace, a more spec
20ea0 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 ific error code
20eb0 28 65 78 61 6d 70 6c 65 3a 0a 2a 2a 20 5b 53 51 (example:.** [SQ
20ec0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c LITE_INTERRUPT],
20ed0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d [SQLITE_SCHEMA]
20ee0 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 , [SQLITE_CORRUP
20ef0 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 T], and so forth
20f00 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 ).** can be obta
20f10 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 ined by calling
20f20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
20f30 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 ] on the.** [pre
20f40 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
20f50 2e 20 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 . In the "v2" i
20f60 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 nterface,.** the
20f70 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 more specific e
20f80 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 rror code is ret
20f90 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 urned directly b
20fa0 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 y sqlite3_step()
20fb0 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ..**.** [SQLITE_
20fc0 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 MISUSE] means th
20fd0 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 at the this rout
20fe0 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 ine was called i
20ff0 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a nappropriately..
21000 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 ** Perhaps it wa
21010 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 s called on a [p
21020 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
21030 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 t] that has.** a
21040 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c lready been [sql
21050 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 ite3_finalize |
21060 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e finalized] or on
21070 20 6f 6e 65 20 74 68 61 74 20 68 61 64 20 0a 2a one that had .*
21080 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 * previously ret
21090 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 urned [SQLITE_ER
210a0 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f ROR] or [SQLITE_
210b0 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f DONE]. Or it co
210c0 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 uld.** be the ca
210d0 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 se that the same
210e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
210f0 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 tion is being us
21100 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 ed by two or.**
21110 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 more threads at
21120 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 the same moment
21130 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c in time..**.** <
21140 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 b>Goofy Interfac
21150 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 0a 2a 2a 20 e Alert:</b>.**
21160 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e In the legacy in
21170 74 65 72 66 61 63 65 2c 20 0a 2a 2a 20 74 68 65 terface, .** the
21180 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
21190 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 API always retur
211a0 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 ns a generic err
211b0 6f 72 20 63 6f 64 65 2c 0a 2a 2a 20 5b 53 51 4c or code,.** [SQL
211c0 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c ITE_ERROR], foll
211d0 6f 77 69 6e 67 20 61 6e 79 20 65 72 72 6f 72 20 owing any error
211e0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 other than [SQLI
211f0 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 61 6e 64 20 TE_BUSY].** and
21200 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e [SQLITE_MISUSE].
21210 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 20 You must call
21220 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
21230 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ] or.** [sqlite3
21240 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 _finalize()] in
21250 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e order to find on
21260 65 20 6f 66 20 74 68 65 20 73 70 65 63 69 66 69 e of the specifi
21270 63 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 c.** [error code
21280 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 s] that better d
21290 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 escribes the err
212a0 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 or..** We admit
212b0 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 that this is a g
212c0 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 oofy design. Th
212d0 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 e problem has be
212e0 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 en fixed.** with
212f0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 the "v2" interf
21300 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 ace. If you pre
21310 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 pare all of your
21320 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a SQL statements.
21330 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 ** using either
21340 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
21350 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 _v2()] or [sqlit
21360 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
21370 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 )] instead.** of
21380 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c the legacy [sql
21390 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
213a0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 and [sqlite3_pre
213b0 70 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20 pare16()], then
213c0 74 68 65 20 0a 2a 2a 20 6d 6f 72 65 20 73 70 65 the .** more spe
213d0 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 cific [error cod
213e0 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 es] are returned
213f0 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 directly.** by
21400 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 sqlite3_step().
21410 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 The use of the
21420 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 "v2" interface i
21430 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a s recommended..*
21440 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
21450 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 32 30 32 7d 20 .**.** {F13202}
21460 20 49 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 If [prepared st
21470 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 72 65 atement] S is re
21480 61 64 79 20 74 6f 20 62 65 0a 2a 2a 20 20 20 20 ady to be.**
21490 20 20 20 20 20 20 20 72 75 6e 2c 20 74 68 65 6e run, then
214a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 [sqlite3_step(S
214b0 29 5d 20 61 64 76 61 6e 63 65 73 20 74 68 61 74 )] advances that
214c0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
214d0 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ent.**
214e0 20 75 6e 74 69 6c 20 74 6f 20 63 6f 6d 70 6c 65 until to comple
214f0 74 69 6f 6e 20 6f 72 20 75 6e 74 69 6c 20 69 74 tion or until it
21500 20 69 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 is ready to ret
21510 75 72 6e 20 61 6e 6f 74 68 65 72 0a 2a 2a 20 20 urn another.**
21520 20 20 20 20 20 20 20 20 20 72 6f 77 20 6f 66 20 row of
21530 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f the result set o
21540 72 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20 6f r an interrupt o
21550 72 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 r run-time error
21560 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b occurs..**.** {
21570 46 31 35 33 30 34 7d 20 20 57 68 65 6e 20 61 20 F15304} When a
21580 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
21590 5f 73 74 65 70 28 53 29 5d 20 63 61 75 73 65 73 _step(S)] causes
215a0 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 the .**
215b0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 [prepared sta
215c0 74 65 6d 65 6e 74 5d 20 53 20 74 6f 20 72 75 6e tement] S to run
215d0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2c 0a to completion,.
215e0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65 ** the
215f0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e function return
21600 73 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e s [SQLITE_DONE].
21610 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33 30 36 7d 20 .**.** {F15306}
21620 20 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 When a call to
21630 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
21640 5d 20 73 74 6f 70 73 20 62 65 63 61 75 73 65 20 ] stops because
21650 69 74 20 69 73 20 72 65 61 64 79 0a 2a 2a 20 20 it is ready.**
21660 20 20 20 20 20 20 20 20 20 74 6f 20 72 65 74 75 to retu
21670 72 6e 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f rn another row o
21680 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 f the result set
21690 2c 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20 , it returns.**
216a0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 [SQLIT
216b0 45 5f 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 E_ROW]..**.** {F
216c0 31 35 33 30 38 7d 20 20 49 66 20 61 20 63 61 6c 15308} If a cal
216d0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 l to [sqlite3_st
216e0 65 70 28 53 29 5d 20 65 6e 63 6f 75 6e 74 65 72 ep(S)] encounter
216f0 73 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 s an.**
21700 20 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 [sqlite3_inter
21710 72 75 70 74 7c 69 6e 74 65 72 72 75 70 74 5d 20 rupt|interrupt]
21720 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 or a run-time er
21730 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ror,.**
21740 20 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 it returns an
21750 61 70 70 72 6f 70 72 61 69 74 65 20 65 72 72 6f appropraite erro
21760 72 20 63 6f 64 65 20 74 68 61 74 20 69 73 20 6e r code that is n
21770 6f 74 20 6f 6e 65 20 6f 66 0a 2a 2a 20 20 20 20 ot one of.**
21780 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f [SQLITE_O
21790 4b 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d K], [SQLITE_ROW]
217a0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e , or [SQLITE_DON
217b0 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33 31 E]..**.** {F1531
217c0 30 7d 20 20 49 66 20 61 6e 20 5b 73 71 6c 69 74 0} If an [sqlit
217d0 65 33 5f 69 6e 74 65 72 72 75 70 74 7c 69 6e 74 e3_interrupt|int
217e0 65 72 72 75 70 74 5d 20 6f 72 20 72 75 6e 2d 74 errupt] or run-t
217f0 69 6d 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 ime error.**
21800 20 20 20 20 20 20 20 6f 63 63 75 72 73 20 64 75 occurs du
21810 72 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b ring a call to [
21820 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d sqlite3_step(S)]
21830 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 66 6f .** fo
21840 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 r a [prepared st
21850 61 74 65 6d 65 6e 74 5d 20 53 20 63 72 65 61 74 atement] S creat
21860 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 ed using.**
21870 20 20 20 20 20 20 6c 65 67 61 63 79 20 69 6e 74 legacy int
21880 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 erfaces [sqlite3
21890 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a _prepare()] or.*
218a0 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c * [sql
218b0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
218c0 5d 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 ] then the funct
218d0 69 6f 6e 20 72 65 74 75 72 6e 73 20 65 69 74 68 ion returns eith
218e0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 er.**
218f0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 [SQLITE_ERROR],
21900 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 6f [SQLITE_BUSY], o
21910 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 r [SQLITE_MISUSE
21920 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 ]..*/.int sqlite
21930 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 3_step(sqlite3_s
21940 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 tmt*);../*.** CA
21950 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f PI3REF: Number o
21960 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 f columns in a r
21970 65 73 75 6c 74 20 73 65 74 20 7b 46 31 33 37 37 esult set {F1377
21980 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 0}.**.** Return
21990 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 the number of va
219a0 6c 75 65 73 20 69 6e 20 74 68 65 20 63 75 72 72 lues in the curr
219b0 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 ent row of the r
219c0 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a esult set..**.**
219d0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
219e0 2a 2a 20 7b 46 31 33 37 37 31 7d 20 20 41 66 74 ** {F13771} Aft
219f0 65 72 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 er a call to [sq
21a00 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 74 lite3_step(S)] t
21a10 68 61 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 hat returns.**
21a20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 [SQLITE
21a30 5f 52 4f 57 5d 2c 20 74 68 65 20 5b 73 71 6c 69 _ROW], the [sqli
21a40 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 te3_data_count(S
21a50 29 5d 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 20 20 )] routine.**
21a60 20 20 20 20 20 20 20 20 77 69 6c 6c 20 72 65 74 will ret
21a70 75 72 6e 20 74 68 65 20 73 61 6d 65 20 76 61 6c urn the same val
21a80 75 65 20 61 73 20 74 68 65 0a 2a 2a 20 20 20 20 ue as the.**
21a90 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
21aa0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d column_count(S)]
21ab0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a function..**.**
21ac0 20 7b 46 31 33 37 37 32 7d 20 20 41 66 74 65 72 {F13772} After
21ad0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 [sqlite3_step(S
21ae0 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 )] has returned
21af0 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 any value other
21b00 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 than.**
21b10 20 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f [SQLITE_ROW] o
21b20 72 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 r before [sqlite
21b30 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 62 3_step(S)] has b
21b40 65 65 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 een .**
21b50 20 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 called on the
21b60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
21b70 65 6e 74 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 20 ent] for.**
21b80 20 20 20 20 20 20 74 68 65 20 66 69 72 73 74 20 the first
21b90 74 69 6d 65 20 73 69 6e 63 65 20 69 74 20 77 61 time since it wa
21ba0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 s [sqlite3_prepa
21bb0 72 65 7c 70 72 65 70 61 72 65 64 5d 0a 2a 2a 20 re|prepared].**
21bc0 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 or [sq
21bd0 6c 69 74 65 33 5f 72 65 73 65 74 7c 72 65 73 65 lite3_reset|rese
21be0 74 5d 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 t], the [sqlite3
21bf0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 0a _data_count(S)].
21c00 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 6f 75 ** rou
21c10 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 tine returns zer
21c20 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 o..*/.int sqlite
21c30 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 3_data_count(sql
21c40 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
21c50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
21c60 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 EF: Fundamental
21c70 44 61 74 61 74 79 70 65 73 20 7b 46 31 30 32 36 Datatypes {F1026
21c80 35 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 5}.** KEYWORDS:
21c90 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a SQLITE_TEXT.**.*
21ca0 2a 20 7b 46 31 30 32 36 36 7d 45 76 65 72 79 20 * {F10266}Every
21cb0 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 value in SQLite
21cc0 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 has one of five
21cd0 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 fundamental data
21ce0 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c types:.**.** <ul
21cf0 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 >.** <li> 64-bit
21d00 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a signed integer.
21d10 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 ** <li> 64-bit I
21d20 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 EEE floating poi
21d30 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 nt number.** <li
21d40 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e > string.** <li>
21d50 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 BLOB.** <li> NU
21d60 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 LL.** </ul> {END
21d70 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f }.**.** These co
21d80 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 nstants are code
21d90 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 s for each of th
21da0 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a ose types..**.**
21db0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 Note that the S
21dc0 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 QLITE_TEXT const
21dd0 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 ant was also use
21de0 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 d in SQLite vers
21df0 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 ion 2.** for a c
21e00 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 ompletely differ
21e10 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f ent meaning. So
21e20 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b ftware that link
21e30 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a s against both.*
21e40 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e * SQLite version
21e50 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 2 and SQLite ve
21e60 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 rsion 3 should u
21e70 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 se SQLITE3_TEXT
21e80 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 not.** SQLITE_TE
21e90 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 XT..*/.#define S
21ea0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 QLITE_INTEGER 1
21eb0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
21ec0 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 FLOAT 2.#defi
21ed0 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 ne SQLITE_BLOB
21ee0 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 4.#define SQL
21ef0 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 ITE_NULL 5.#
21f00 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 ifdef SQLITE_TEX
21f10 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 T.# undef SQLITE
21f20 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 _TEXT.#else.# de
21f30 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 fine SQLITE_TEXT
21f40 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 3.#endif.#d
21f50 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 efine SQLITE3_TE
21f60 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 XT 3../*.**
21f70 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 CAPI3REF: Result
21f80 73 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 s Values From A
21f90 51 75 65 72 79 20 7b 46 31 33 38 30 30 7d 0a 2a Query {F13800}.*
21fa0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
21fb0 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 nes form the "re
21fc0 73 75 6c 74 20 73 65 74 20 71 75 65 72 79 22 20 sult set query"
21fd0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a interface..**.**
21fe0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
21ff0 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 return informati
22000 6f 6e 20 61 62 6f 75 74 0a 2a 2a 20 61 20 73 69 on about.** a si
22010 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 ngle column of t
22020 68 65 20 63 75 72 72 65 6e 74 20 72 65 73 75 6c he current resul
22030 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 t row of a query
22040 2e 20 20 49 6e 20 65 76 65 72 79 0a 2a 2a 20 63 . In every.** c
22050 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 ase the first ar
22060 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e gument is a poin
22070 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b ter to the .** [
22080 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
22090 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e nt] that is bein
220a0 67 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 28 g.** evaluated (
220b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d the [sqlite3_stm
220c0 74 2a 5d 20 74 68 61 74 20 77 61 73 20 72 65 74 t*] that was ret
220d0 75 72 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b urned from .** [
220e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
220f0 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 v2()] or one of
22100 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 61 6e its variants) an
22110 64 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 d.** the second
22120 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 argument is the
22130 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c index of the col
22140 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e umn for which in
22150 66 6f 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20 73 68 formation .** sh
22160 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 ould be returned
22170 2e 20 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 . The left-most
22180 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 column of the r
22190 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 68 61 73 esult set.** has
221a0 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 30 2e 0a an index of 0..
221b0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c **.** If the SQL
221c0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f statement is no
221d0 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e t currently poin
221e0 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 t to a valid row
221f0 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 74 , or if the.** t
22200 68 65 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 he column index
22210 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c is out of range,
22220 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 the result is u
22230 6e 64 65 66 69 6e 65 64 2e 20 0a 2a 2a 20 54 68 ndefined. .** Th
22240 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 ese routines may
22250 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 only be called
22260 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 when the most re
22270 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 cent call to.**
22280 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
22290 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 has returned [S
222a0 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e QLITE_ROW] and n
222b0 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 either.** [sqlit
222c0 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 e3_reset()] nor
222d0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
222e0 65 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 e()] has been ca
222f0 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e ll subsequently.
22300 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 .** If any of th
22310 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
22320 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 called after [s
22330 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
22340 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 or.** [sqlite3_f
22350 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 inalize()] or af
22360 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 ter [sqlite3_ste
22370 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 p()] has returne
22380 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f d.** something o
22390 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
223a0 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 E_ROW], the resu
223b0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 lts are undefine
223c0 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 d..** If [sqlite
223d0 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 3_step()] or [sq
223e0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f lite3_reset()] o
223f0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c r [sqlite3_final
22400 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 ize()].** are ca
22410 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 lled from a diff
22420 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 erent thread whi
22430 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 le any of these
22440 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 routines.** are
22450 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 pending, then th
22460 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e e results are un
22470 64 65 66 69 6e 65 64 2e 20 20 0a 2a 2a 0a 2a 2a defined. .**.**
22480 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c The sqlite3_col
22490 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 umn_type() routi
224a0 6e 65 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b ne returns .** [
224b0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c SQLITE_INTEGER |
224c0 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 datatype code]
224d0 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 for the initial
224e0 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 data type.** of
224f0 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d the result colum
22500 6e 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 n. The returned
22510 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 value is one of
22520 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 [SQLITE_INTEGER
22530 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c ],.** [SQLITE_FL
22540 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 OAT], [SQLITE_TE
22550 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f XT], [SQLITE_BLO
22560 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e B], or [SQLITE_N
22570 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 ULL]. The value
22580 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 .** returned by
22590 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
225a0 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 ype() is only me
225b0 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 aningful if no t
225c0 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f ype.** conversio
225d0 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 ns have occurred
225e0 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 as described be
225f0 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 low. After a ty
22600 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a pe conversion,.*
22610 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 * the value retu
22620 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
22630 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 column_type() is
22640 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 undefined. Fut
22650 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 ure.** versions
22660 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 of SQLite may ch
22670 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f ange the behavio
22680 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c r of sqlite3_col
22690 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f umn_type().** fo
226a0 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 llowing a type c
226b0 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a onversion..**.**
226c0 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 If the result i
226d0 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d s a BLOB or UTF-
226e0 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 8 string then th
226f0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
22700 5f 62 79 74 65 73 28 29 20 0a 2a 2a 20 72 6f 75 _bytes() .** rou
22710 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 tine returns the
22720 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
22730 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 in that BLOB or
22740 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 74 string..** If t
22750 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 he result is a U
22760 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 TF-16 string, th
22770 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
22780 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 n_bytes() conver
22790 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 ts.** the string
227a0 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 to UTF-8 and th
227b0 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e en returns the n
227c0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a umber of bytes..
227d0 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 ** If the result
227e0 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 is a numeric va
227f0 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 lue then sqlite3
22800 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 _column_bytes()
22810 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 uses.** [sqlite3
22820 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 _snprintf()] to
22830 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c convert that val
22840 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 ue to a UTF-8 st
22850 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 ring and returns
22860 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f .** the number o
22870 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 f bytes in that
22880 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 76 string..** The v
22890 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 64 6f alue returned do
228a0 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 es not include t
228b0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 he zero terminat
228c0 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a or at the end.**
228d0 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 of the string.
228e0 20 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 For clarity: th
228f0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
22900 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
22910 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 f.** bytes in th
22920 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 e string, not th
22930 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 e number of char
22940 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 acters..**.** St
22950 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 rings returned b
22960 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e y sqlite3_column
22970 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 _text() and sqli
22980 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
22990 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 6(),.** even emp
229a0 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 ty strings, are
229b0 61 6c 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d always zero term
229c0 69 6e 61 74 65 64 2e 20 20 54 68 65 20 72 65 74 inated. The ret
229d0 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f urn.** value fro
229e0 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e m sqlite3_column
229f0 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 _blob() for a ze
22a00 72 6f 2d 6c 65 6e 67 74 68 20 62 6c 6f 62 20 69 ro-length blob i
22a10 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 0a 2a s an arbitrary.*
22a20 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69 * pointer, possi
22a30 62 6c 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20 bly even a NULL
22a40 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 pointer..**.** T
22a50 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d he sqlite3_colum
22a60 6e 5f 62 79 74 65 73 31 36 28 29 20 72 6f 75 74 n_bytes16() rout
22a70 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 ine is similar t
22a80 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e o sqlite3_column
22a90 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 _bytes().** but
22aa0 6c 65 61 76 65 73 20 74 68 65 20 72 65 73 75 6c leaves the resul
22ab0 74 20 69 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e t in UTF-16 in n
22ac0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
22ad0 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d instead of UTF-
22ae0 38 2e 20 20 0a 2a 2a 20 54 68 65 20 7a 65 72 6f 8. .** The zero
22af0 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e terminator is n
22b00 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 ot included in t
22b10 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a his count..**.**
22b20 20 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 The object retu
22b30 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 rned by [sqlite3
22b40 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d _column_value()]
22b50 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f is an.** [unpro
22b60 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
22b70 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 alue] object. A
22b80 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 n unprotected sq
22b90 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
22ba0 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 ct.** may only b
22bb0 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c e used with [sql
22bc0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 ite3_bind_value(
22bd0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
22be0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e result_value()].
22bf0 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 .** If the [unpr
22c00 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
22c10 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 value] object re
22c20 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 turned by.** [sq
22c30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c lite3_column_val
22c40 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e ue()] is used in
22c50 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 any other way,
22c60 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a including calls.
22c70 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c ** to routines l
22c80 69 6b 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ike .** [sqlite3
22c90 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b _value_int()], [
22ca0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
22cb0 78 74 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 xt()], or [sqlit
22cc0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 e3_value_bytes()
22cd0 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 ],.** then the b
22ce0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 ehavior is undef
22cf0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ined..**.** Thes
22d00 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d e routines attem
22d10 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 pt to convert th
22d20 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 e value where ap
22d30 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a propriate. For.
22d40 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 ** example, if t
22d50 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 he internal repr
22d60 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c esentation is FL
22d70 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 OAT and a text r
22d80 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 esult.** is requ
22d90 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f ested, [sqlite3_
22da0 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 snprintf()] is u
22db0 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 sed internally t
22dc0 6f 20 64 6f 20 74 68 65 20 63 6f 6e 76 65 72 73 o do the convers
22dd0 69 6f 6e 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 ion.** automatic
22de0 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f ally. The follo
22df0 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 wing table detai
22e00 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f ls the conversio
22e10 6e 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 61 ns that.** are a
22e20 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 pplied:.**.** <b
22e30 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 lockquote>.** <t
22e40 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e able border="1">
22e50 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 .** <tr><th> Int
22e60 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 ernal<br>Type <t
22e70 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e h> Requested<br>
22e80 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 Type <th> Conve
22e90 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e rsion.**.** <tr>
22ea0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 <td> NULL <t
22eb0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 d> INTEGER <td
22ec0 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a > Result is 0.**
22ed0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 <tr><td> NULL
22ee0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 <td> FLOAT
22ef0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 <td> Result is
22f00 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 0.0.** <tr><td>
22f10 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 NULL <td>
22f20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 TEXT <td> Re
22f30 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 sult is NULL poi
22f40 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e nter.** <tr><td>
22f50 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 NULL <td>
22f60 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 BLOB <td> Re
22f70 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 sult is NULL poi
22f80 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e nter.** <tr><td>
22f90 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 INTEGER <td>
22fa0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f FLOAT <td> Co
22fb0 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 nvert from integ
22fc0 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c er to float.** <
22fd0 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 tr><td> INTEGER
22fe0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 <td> TEXT
22ff0 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 <td> ASCII rende
23000 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 ring of the inte
23010 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 ger.** <tr><td>
23020 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 INTEGER <td>
23030 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d BLOB <td> Sam
23040 65 20 61 73 20 66 6f 72 20 49 4e 54 45 47 45 52 e as for INTEGER
23050 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 ->TEXT.** <tr><t
23060 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e d> FLOAT <td>
23070 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 INTEGER <td>
23080 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f Convert from flo
23090 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a at to integer.**
230a0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 <tr><td> FLOAT
230b0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 <td> TEXT
230c0 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e <td> ASCII ren
230d0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c dering of the fl
230e0 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 oat.** <tr><td>
230f0 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 FLOAT <td>
23100 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d BLOB <td> Sam
23110 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 e as FLOAT->TEXT
23120 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 .** <tr><td> TE
23130 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 XT <td> INTEG
23140 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 ER <td> Use at
23150 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e oi().** <tr><td>
23160 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 TEXT <td>
23170 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 FLOAT <td> Us
23180 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e e atof().** <tr>
23190 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 <td> TEXT <t
231a0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 d> BLOB <td
231b0 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c > No change.** <
231c0 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 tr><td> BLOB
231d0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 <td> INTEGER
231e0 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 <td> Convert to
231f0 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 TEXT then use at
23200 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e oi().** <tr><td>
23210 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 BLOB <td>
23220 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f FLOAT <td> Co
23230 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 nvert to TEXT th
23240 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a en use atof().**
23250 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 <tr><td> BLOB
23260 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 <td> TEXT
23270 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 <td> Add a zer
23280 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 o terminator if
23290 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c needed.** </tabl
232a0 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f e>.** </blockquo
232b0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 te>.**.** The ta
232c0 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 ble above makes
232d0 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 reference to sta
232e0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 ndard C library
232f0 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 functions atoi()
23300 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 .** and atof().
23310 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 SQLite does not
23320 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 really use thes
23330 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 e functions. It
23340 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 6e 20 65 has its.** on e
23350 71 75 61 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e quavalent intern
23360 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 al routines. Th
23370 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f e atoi() and ato
23380 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a f() names are.**
23390 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 used in the tab
233a0 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 le for brevity a
233b0 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20 nd because they
233c0 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 are familiar to
233d0 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 most.** C progra
233e0 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 mmers..**.** Not
233f0 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 e that when type
23400 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 conversions occ
23410 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 ur, pointers ret
23420 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a urned by prior.*
23430 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 * calls to sqlit
23440 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 e3_column_blob()
23450 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e , sqlite3_column
23460 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a _text(), and/or.
23470 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ** sqlite3_colum
23480 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 n_text16() may b
23490 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 20 0a e invalidated. .
234a0 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 ** Type conversi
234b0 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 ons and pointer
234c0 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 invalidations mi
234d0 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 ght occur.** in
234e0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 the following ca
234f0 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a ses:.**.** <ul>.
23500 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 ** <li><p> The
23510 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 initial content
23520 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 is a BLOB and sq
23530 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
23540 74 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 t() .**
23550 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 or sqlite3_colu
23560 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 mn_text16() is c
23570 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 alled. A zero-t
23580 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a erminator might.
23590 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 65 64 ** need
235a0 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 to be added to
235b0 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 70 3e 3c the string.</p><
235c0 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c /li>.**.** <li><
235d0 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61 6c 20 p> The initial
235e0 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 content is UTF-8
235f0 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 text and sqlite
23600 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
23610 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 () or.**
23620 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e sqlite3_column
23630 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c _text16() is cal
23640 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e led. The conten
23650 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 t must be conver
23660 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ted.**
23670 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 70 3e 3c 2f to UTF-16.</p></
23680 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 li>.**.** <li><p
23690 3e 20 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 > The initial c
236a0 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 ontent is UTF-16
236b0 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 text and sqlite
236c0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
236d0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 or.**
236e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
236f0 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e ext() is called.
23700 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 The content mu
23710 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a st be converted.
23720 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 55 ** to U
23730 54 46 2d 38 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a TF-8.</p></li>.*
23740 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f * </ul>.**.** Co
23750 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 nversions betwee
23760 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 n UTF-16be and U
23770 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 TF-16le are alwa
23780 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 ys done in place
23790 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 and do.** not i
237a0 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f nvalidate a prio
237b0 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 r pointer, thoug
237c0 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 h of course the
237d0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 content of the b
237e0 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 uffer.** that th
237f0 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 e prior pointer
23800 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 points to will h
23810 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 ave been modifie
23820 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a d. Other kinds.
23830 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e ** of conversion
23840 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 are done in pla
23850 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f ce when it is po
23860 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 ssible, but some
23870 74 69 6d 65 20 69 74 20 69 73 0a 2a 2a 20 6e 6f time it is.** no
23880 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 t possible and i
23890 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 n those cases pr
238a0 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 ior pointers are
238b0 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 20 20 0a invalidated. .
238c0 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 **.** The safest
238d0 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 and easiest to
238e0 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 remember policy
238f0 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 is to invoke the
23900 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 se routines.** i
23910 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c n one of the fol
23920 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a lowing ways:.**.
23930 2a 2a 20 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 ** <ul>.** <li
23940 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f >sqlite3_column_
23950 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 text() followed
23960 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d by sqlite3_colum
23970 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a n_bytes()</li>.*
23980 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 * <li>sqlite3_c
23990 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c olumn_blob() fol
239a0 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 lowed by sqlite3
239b0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c _column_bytes()<
239c0 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c /li>.** <li>sql
239d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
239e0 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 16() followed by
239f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
23a00 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a bytes16()</li>.*
23a10 2a 20 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 * </ul>.**.** I
23a20 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 n other words, y
23a30 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 ou should call s
23a40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
23a50 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f xt(), sqlite3_co
23a60 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 lumn_blob(),.**
23a70 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d or sqlite3_colum
23a80 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 n_text16() first
23a90 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 to force the re
23aa0 73 75 6c 74 20 69 6e 74 6f 20 74 68 65 20 64 65 sult into the de
23ab0 73 69 72 65 64 0a 2a 2a 20 66 6f 72 6d 61 74 2c sired.** format,
23ac0 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c then invoke sql
23ad0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
23ae0 73 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 s() or sqlite3_c
23af0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 olumn_bytes16()
23b00 74 6f 0a 2a 2a 20 66 69 6e 64 20 74 68 65 20 73 to.** find the s
23b10 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c ize of the resul
23b20 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 t. Do not mix c
23b30 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 all to sqlite3_c
23b40 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a olumn_text() or.
23b50 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ** sqlite3_colum
23b60 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 n_blob() with ca
23b70 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 lls to sqlite3_c
23b80 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2e olumn_bytes16().
23b90 20 20 41 6e 64 20 64 6f 20 6e 6f 74 0a 2a 2a 20 And do not.**
23ba0 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c mix calls to sql
23bb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
23bc0 31 36 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 16() with calls
23bd0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d to sqlite3_colum
23be0 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a n_bytes()..**.**
23bf0 20 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 The pointers re
23c00 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 turned are valid
23c10 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f until a type co
23c20 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 nversion occurs
23c30 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 as.** described
23c40 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 above, or until
23c50 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
23c60 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 or [sqlite3_res
23c70 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c et()] or.** [sql
23c80 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
23c90 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 is called. The
23ca0 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 memory space us
23cb0 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e ed to hold strin
23cc0 67 73 0a 2a 2a 20 61 6e 64 20 62 6c 6f 62 73 20 gs.** and blobs
23cd0 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 is freed automat
23ce0 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e ically. Do <b>n
23cf0 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 ot</b> pass the
23d00 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 pointers returne
23d10 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f d.** [sqlite3_co
23d20 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 lumn_blob()], [s
23d30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
23d40 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f xt()], etc. into
23d50 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 .** [sqlite3_fr
23d60 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 ee()]..**.** If
23d70 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 a memory allocat
23d80 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 ion error occurs
23d90 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c during the eval
23da0 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a uation of any.**
23db0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e of these routin
23dc0 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 es, a default va
23dd0 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e lue is returned.
23de0 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 The default va
23df0 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 lue.** is either
23e00 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 the integer 0,
23e10 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 the floating poi
23e20 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f nt number 0.0, o
23e30 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e r a NULL.** poin
23e40 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 ter. Subsequent
23e50 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
23e60 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 e3_errcode()] wi
23e70 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 ll return.** [SQ
23e80 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a LITE_NOMEM]..**.
23e90 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
23ea0 2a 0a 2a 2a 20 7b 46 31 33 38 30 33 7d 20 54 68 *.** {F13803} Th
23eb0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d e [sqlite3_colum
23ec0 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e 74 n_blob(S,N)] int
23ed0 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 erface converts
23ee0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
23ef0 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 Nth column in th
23f00 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 e current row of
23f10 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 the result set
23f20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 for.**
23f30 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
23f40 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 62 6c ent] S into a bl
23f50 6f 62 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 ob and then retu
23f60 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 rns a.**
23f70 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 pointer to the
23f80 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65 converted value
23f90 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30 36 7d ..**.** {F13806}
23fa0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f The [sqlite3_co
23fb0 6c 75 6d 6e 5f 62 79 74 65 73 28 53 2c 4e 29 5d lumn_bytes(S,N)]
23fc0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
23fd0 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 ns the.**
23fe0 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 number of byt
23ff0 65 73 20 69 6e 20 74 68 65 20 62 6c 6f 62 20 6f es in the blob o
24000 72 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 r string (exclus
24010 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 ive of the.**
24020 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d zero term
24030 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 inator on the st
24040 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 ring) that was r
24050 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a eturned by the.*
24060 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 * most
24070 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b recent call to [
24080 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
24090 6c 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 lob(S,N)] or.**
240a0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
240b0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 3_column_text(S,
240c0 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 N)]..**.** {F138
240d0 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 09} The [sqlite3
240e0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
240f0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 S,N)] interface
24100 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 returns the.**
24110 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f number o
24120 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 f bytes in the s
24130 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 tring (exclusive
24140 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 of the.**
24150 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 zero termina
24160 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e tor on the strin
24170 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75 g) that was retu
24180 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 rned by the.**
24190 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 most rec
241a0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ent call to [sql
241b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
241c0 31 36 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 16(S,N)]..**.**
241d0 7b 46 31 33 38 31 32 7d 20 54 68 65 20 5b 73 71 {F13812} The [sq
241e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 lite3_column_dou
241f0 62 6c 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 ble(S,N)] interf
24200 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 ace converts the
24210 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 .** Nth
24220 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 column in the c
24230 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 urrent row of th
24240 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 e result set for
24250 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 .** [pr
24260 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
24270 5d 20 53 20 69 6e 74 6f 20 61 20 66 6c 6f 61 74 ] S into a float
24280 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 ing point value
24290 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 and.**
242a0 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f returns a copy o
242b0 66 20 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a 2a f that value..**
242c0 0a 2a 2a 20 7b 46 31 33 38 31 35 7d 20 54 68 65 .** {F13815} The
242d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
242e0 5f 69 6e 74 28 53 2c 4e 29 5d 20 69 6e 74 65 72 _int(S,N)] inter
242f0 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 face converts th
24300 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 e.** Nt
24310 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 h column in the
24320 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 current row of t
24330 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f he result set fo
24340 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 r.** [p
24350 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
24360 74 5d 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 t] S into a 64-b
24370 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 it signed intege
24380 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 r and.**
24390 20 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c 6f returns the lo
243a0 77 65 72 20 33 32 20 62 69 74 73 20 6f 66 20 74 wer 32 bits of t
243b0 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a hat integer..**.
243c0 2a 2a 20 7b 46 31 33 38 31 38 7d 20 54 68 65 20 ** {F13818} The
243d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
243e0 69 6e 74 36 34 28 53 2c 4e 29 5d 20 69 6e 74 65 int64(S,N)] inte
243f0 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 rface converts t
24400 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e he.** N
24410 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 th column in the
24420 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 current row of
24430 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 the result set f
24440 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b or.** [
24450 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
24460 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 36 34 2d nt] S into a 64-
24470 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 bit signed integ
24480 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 er and.**
24490 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 returns a cop
244a0 79 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 y of that intege
244b0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 31 r..**.** {F13821
244c0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 } The [sqlite3_c
244d0 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d olumn_text(S,N)]
244e0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 interface conve
244f0 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 rts the.**
24500 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 Nth column i
24510 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f n the current ro
24520 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 w of the result
24530 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 set for.**
24540 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 [prepared st
24550 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 atement] S into
24560 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
24570 64 20 55 54 46 2d 38 20 0a 2a 2a 20 20 20 20 20 d UTF-8 .**
24580 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 string and
24590 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
245a0 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 r to that string
245b0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 34 7d ..**.** {F13824}
245c0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f The [sqlite3_co
245d0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29 lumn_text16(S,N)
245e0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 ] interface conv
245f0 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 erts the.**
24600 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 Nth column
24610 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 in the current r
24620 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 ow of the result
24630 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 set for.**
24640 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 [prepared s
24650 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f tatement] S into
24660 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
24670 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 ed 2-byte.**
24680 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 aligned UT
24690 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 F-16 native byte
246a0 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 order.**
246b0 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 string and re
246c0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
246d0 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a to that string..
246e0 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 37 7d 20 54 **.** {F13827} T
246f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 he [sqlite3_colu
24700 6d 6e 5f 74 79 70 65 28 53 2c 4e 29 5d 20 69 6e mn_type(S,N)] in
24710 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a terface returns.
24720 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 65 20 ** one
24730 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d of [SQLITE_NULL]
24740 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 , [SQLITE_INTEGE
24750 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 R], [SQLITE_FLOA
24760 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 T],.**
24770 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f [SQLITE_TEXT], o
24780 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 r [SQLITE_BLOB]
24790 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 as appropriate f
247a0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 or.** t
247b0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e he Nth column in
247c0 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 the current row
247d0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 of the result s
247e0 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 et for.**
247f0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 [prepared sta
24800 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a tement] S..**.**
24810 20 7b 46 31 33 38 33 30 7d 20 54 68 65 20 5b 73 {F13830} The [s
24820 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 qlite3_column_va
24830 6c 75 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 lue(S,N)] interf
24840 61 63 65 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a ace returns a.**
24850 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 pointe
24860 72 20 74 6f 20 61 6e 20 5b 75 6e 70 72 6f 74 65 r to an [unprote
24870 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
24880 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 20 74 ue] object for t
24890 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e he.** N
248a0 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 th column in the
248b0 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 current row of
248c0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 the result set f
248d0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b or.** [
248e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
248f0 6e 74 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 nt] S..*/.const
24900 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
24910 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 lumn_blob(sqlite
24920 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
24930 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f l);.int sqlite3_
24940 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c column_bytes(sql
24950 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
24960 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 iCol);.int sqlit
24970 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
24980 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
24990 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 int iCol);.doub
249a0 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d le sqlite3_colum
249b0 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 n_double(sqlite3
249c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
249d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 );.int sqlite3_c
249e0 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 olumn_int(sqlite
249f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
24a00 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 l);.sqlite3_int6
24a10 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 4 sqlite3_column
24a20 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 _int64(sqlite3_s
24a30 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
24a40 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 .const unsigned
24a50 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
24a60 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 lumn_text(sqlite
24a70 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
24a80 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a l);.const void *
24a90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
24aa0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ext16(sqlite3_st
24ab0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
24ac0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 int sqlite3_colu
24ad0 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f mn_type(sqlite3_
24ae0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
24af0 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 ;.sqlite3_value
24b00 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
24b10 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 value(sqlite3_st
24b20 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
24b30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
24b40 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 Destroy A Prepa
24b50 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 red Statement Ob
24b60 6a 65 63 74 20 7b 46 31 33 33 30 30 7d 0a 2a 2a ject {F13300}.**
24b70 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
24b80 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 finalize() funct
24b90 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f ion is called to
24ba0 20 64 65 6c 65 74 65 20 61 20 0a 2a 2a 20 5b 70 delete a .** [p
24bb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
24bc0 74 5d 2e 20 49 66 20 74 68 65 20 73 74 61 74 65 t]. If the state
24bd0 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 65 78 65 63 ment was.** exec
24be0 75 74 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c uted successfull
24bf0 79 2c 20 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 y, or not execut
24c00 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 20 ed at all, then
24c10 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 SQLITE_OK is ret
24c20 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 65 78 65 urned..** If exe
24c30 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 cution of the st
24c40 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 atement failed t
24c50 68 65 6e 20 61 6e 20 0a 2a 2a 20 5b 65 72 72 6f hen an .** [erro
24c60 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 r code] or [exte
24c70 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d nded error code]
24c80 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e .** is returned.
24c90 20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 .**.** This rou
24ca0 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c tine can be call
24cb0 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 ed at any point
24cc0 64 75 72 69 6e 67 20 74 68 65 20 65 78 65 63 75 during the execu
24cd0 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b tion of the.** [
24ce0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
24cf0 6e 74 5d 2e 20 20 49 66 20 74 68 65 20 76 69 72 nt]. If the vir
24d00 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 tual machine has
24d10 20 6e 6f 74 20 0a 2a 2a 20 63 6f 6d 70 6c 65 74 not .** complet
24d20 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65 ed execution whe
24d30 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 n this routine i
24d40 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 s called, that i
24d50 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e s like.** encoun
24d60 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 tering an error
24d70 6f 72 20 61 6e 20 69 6e 74 65 72 72 75 70 74 2e or an interrupt.
24d80 20 20 28 53 65 65 20 5b 73 71 6c 69 74 65 33 5f (See [sqlite3_
24d90 69 6e 74 65 72 72 75 70 74 28 29 5d 2e 29 20 0a interrupt()].) .
24da0 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 ** Incomplete up
24db0 64 61 74 65 73 20 6d 61 79 20 62 65 20 72 6f 6c dates may be rol
24dc0 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72 61 led back and tra
24dd0 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c nsactions cancel
24de0 6c 65 64 2c 20 20 0a 2a 2a 20 64 65 70 65 6e 64 led, .** depend
24df0 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75 ing on the circu
24e00 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 mstances, and th
24e10 65 20 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 e .** [error cod
24e20 65 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c e] returned will
24e30 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 be [SQLITE_ABOR
24e40 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 T]..**.** INVARI
24e50 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 ANTS:.**.** {F11
24e60 33 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 302} The [sqlite
24e70 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 3_finalize(S)] i
24e80 6e 74 65 72 66 61 63 65 20 64 65 73 74 72 6f 79 nterface destroy
24e90 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 s the.**
24ea0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 [prepared stat
24eb0 65 6d 65 6e 74 5d 20 53 20 61 6e 64 20 72 65 6c ement] S and rel
24ec0 65 61 73 65 73 20 61 6c 6c 0a 2a 2a 20 20 20 20 eases all.**
24ed0 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 61 6e 64 memory and
24ee0 20 66 69 6c 65 20 72 65 73 6f 75 72 63 65 73 20 file resources
24ef0 68 65 6c 64 20 62 79 20 74 68 61 74 20 6f 62 6a held by that obj
24f00 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 ect..**.** {F113
24f10 30 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 04} If the most
24f20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b recent call to [
24f30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d sqlite3_step(S)]
24f40 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 for the.**
24f50 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 [prepared s
24f60 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 tatement] S retu
24f70 72 6e 65 64 20 61 6e 20 65 72 72 6f 72 2c 0a 2a rned an error,.*
24f80 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 * then
24f90 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
24fa0 65 28 53 29 5d 20 72 65 74 75 72 6e 73 20 74 68 e(S)] returns th
24fb0 61 74 20 73 61 6d 65 20 65 72 72 6f 72 2e 0a 2a at same error..*
24fc0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 /.int sqlite3_fi
24fd0 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 nalize(sqlite3_s
24fe0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
24ff0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
25000 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 set A Prepared S
25010 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 tatement Object
25020 7b 46 31 33 33 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 {F13330}.**.** T
25030 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 he sqlite3_reset
25040 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 () function is c
25050 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 alled to reset a
25060 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 .** [prepared s
25070 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 tatement] object
25080 2e 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 69 74 73 ..** back to its
25090 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 initial state,
250a0 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 ready to be re-e
250b0 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 xecuted..** Any
250c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 SQL statement va
250d0 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 riables that had
250e0 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f values bound to
250f0 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 them using.** t
25100 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 he [sqlite3_bind
25110 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f _blob | sqlite3_
25120 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 bind_*() API] re
25130 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 tain their value
25140 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 s..** Use [sqlit
25150 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 e3_clear_binding
25160 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 s()] to reset th
25170 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a e bindings..**.*
25180 2a 20 7b 46 31 31 33 33 32 7d 20 54 68 65 20 5b * {F11332} The [
25190 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 sqlite3_reset(S)
251a0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 ] interface rese
251b0 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 ts the [prepared
251c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a statement] S.**
251d0 20 20 20 20 20 20 20 20 20 20 62 61 63 6b 20 74 back t
251e0 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 o the beginning
251f0 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a of its program..
25200 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 34 7d 20 49 **.** {F11334} I
25210 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e f the most recen
25220 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 t call to [sqlit
25230 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 e3_step(S)] for
25240 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 .** [pr
25250 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
25260 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 ] S returned [SQ
25270 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 LITE_ROW] or [SQ
25280 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 LITE_DONE],.**
25290 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 5b 73 or if [s
252a0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 qlite3_step(S)]
252b0 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 has never before
252c0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 been called on
252d0 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 S,.** t
252e0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 hen [sqlite3_res
252f0 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b et(S)] returns [
25300 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a SQLITE_OK]..**.*
25310 2a 20 7b 46 31 31 33 33 36 7d 20 49 66 20 74 68 * {F11336} If th
25320 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 e most recent ca
25330 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ll to [sqlite3_s
25340 74 65 70 28 53 29 5d 20 66 6f 72 0a 2a 2a 20 20 tep(S)] for.**
25350 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 [prepare
25360 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 d statement] S i
25370 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f ndicated an erro
25380 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 r, then.**
25390 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 [sqlite3_res
253a0 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 et(S)] returns a
253b0 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 n appropriate [e
253c0 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a rror code]..**.*
253d0 2a 20 7b 46 31 31 33 33 38 7d 20 54 68 65 20 5b * {F11338} The [
253e0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 sqlite3_reset(S)
253f0 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 ] interface does
25400 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 not change the
25410 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 values.**
25420 20 20 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 of any [sqlit
25430 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e e3_bind_blob|bin
25440 64 69 6e 67 73 5d 20 6f 6e 20 5b 70 72 65 70 61 dings] on [prepa
25450 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
25460 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
25470 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 _reset(sqlite3_s
25480 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
25490 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 .** CAPI3REF: Cr
254a0 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 eate Or Redefine
254b0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b SQL Functions {
254c0 46 31 36 31 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f F16100}.** KEYWO
254d0 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 RDS: {function c
254e0 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 reation routines
254f0 7d 20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74 } .**.** These t
25500 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f wo functions (co
25510 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e llectively known
25520 20 61 73 0a 2a 2a 20 22 66 75 6e 63 74 69 6f 6e as.** "function
25530 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e creation routin
25540 65 73 22 29 20 61 72 65 20 75 73 65 64 20 74 6f es") are used to
25550 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f add SQL functio
25560 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 ns or aggregates
25570 0a 2a 2a 20 6f 72 20 74 6f 20 72 65 64 65 66 69 .** or to redefi
25580 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 ne the behavior
25590 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 of existing SQL
255a0 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 functions or agg
255b0 72 65 67 61 74 65 73 2e 20 20 54 68 65 0a 2a 2a regates. The.**
255c0 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 6c 79 difference only
255d0 20 62 65 74 77 65 65 6e 20 74 68 65 20 74 77 6f between the two
255e0 20 69 73 20 74 68 61 74 20 74 68 65 20 73 65 63 is that the sec
255f0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74 ond parameter, t
25600 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 he.** name of th
25610 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74 e (scalar) funct
25620 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 ion or aggregate
25630 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 , is encoded in
25640 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c UTF-8 for.** sql
25650 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
25660 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 tion() and UTF-1
25670 36 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 6 for sqlite3_cr
25680 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
25690 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 )..**.** The fir
256a0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 st parameter is
256b0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
256c0 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 nnection] to whi
256d0 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 ch the SQL.** fu
256e0 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 nction is to be
256f0 61 64 64 65 64 2e 20 20 49 66 20 61 20 73 69 6e added. If a sin
25700 67 6c 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 gle.** program u
25710 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e ses more than on
25720 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
25730 65 63 74 69 6f 6e 5d 20 69 6e 74 65 72 6e 61 6c ection] internal
25740 6c 79 2c 20 74 68 65 6e 20 53 51 4c 0a 2a 2a 20 ly, then SQL.**
25750 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 functions must b
25760 65 20 61 64 64 65 64 20 69 6e 64 69 76 69 64 75 e added individu
25770 61 6c 6c 79 20 74 6f 20 65 61 63 68 20 5b 64 61 ally to each [da
25780 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
25790 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 n]..**.** The se
257a0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 cond parameter i
257b0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
257c0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 e SQL function t
257d0 6f 20 62 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 o be created.**
257e0 6f 72 20 72 65 64 65 66 69 6e 65 64 2e 0a 2a 2a or redefined..**
257f0 20 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 The length of t
25800 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 he name is limit
25810 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c ed to 255 bytes,
25820 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 exclusive of th
25830 65 20 0a 2a 2a 20 7a 65 72 6f 2d 74 65 72 6d 69 e .** zero-termi
25840 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 nator. Note tha
25850 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 t the name lengt
25860 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 h limit is in by
25870 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 tes, not.** char
25880 61 63 74 65 72 73 2e 20 20 41 6e 79 20 61 74 74 acters. Any att
25890 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 empt to create a
258a0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 function with a
258b0 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 longer name.**
258c0 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 61 will result in a
258d0 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 65 n SQLITE_ERROR e
258e0 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 rror..**.** The
258f0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
25900 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 is the number of
25910 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 arguments that
25920 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
25930 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 or.** aggregate
25940 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20 takes. If this
25950 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 parameter is neg
25960 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 ative, then the
25970 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a SQL function or.
25980 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 ** aggregate may
25990 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 take any number
259a0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a of arguments..*
259b0 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 *.** The fourth
259c0 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 parameter, eText
259d0 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 Rep, specifies w
259e0 68 61 74 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f hat .** [SQLITE_
259f0 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f UTF8 | text enco
25a00 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 ding] this SQL f
25a10 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 unction prefers
25a20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d for.** its param
25a30 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 eters. Any SQL
25a40 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 function impleme
25a50 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 ntation should b
25a60 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a e able to work.*
25a70 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d * work with UTF-
25a80 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 8, UTF-16le, or
25a90 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 UTF-16be. But s
25aa0 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ome implementati
25ab0 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f ons may be.** mo
25ac0 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 re efficient wit
25ad0 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 h one encoding t
25ae0 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 han another. It
25af0 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a is allowed to.*
25b00 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 * invoke sqlite3
25b10 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
25b20 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 () or sqlite3_cr
25b30 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
25b40 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 ) multiple.** ti
25b50 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d mes with the sam
25b60 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 e function but w
25b70 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 ith different va
25b80 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 lues of eTextRep
25b90 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 ..** When multip
25ba0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
25bb0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 ns of the same f
25bc0 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 unction are avai
25bd0 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a lable, SQLite.**
25be0 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f will pick the o
25bf0 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 ne that involves
25c00 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e the least amoun
25c10 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 t of data conver
25c20 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 sion..** If ther
25c30 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 e is only a sing
25c40 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
25c50 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 n which does not
25c60 20 63 61 72 65 20 77 68 61 74 0a 2a 2a 20 74 65 care what.** te
25c70 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 xt encoding is u
25c80 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f sed, then the fo
25c90 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 urth argument sh
25ca0 6f 75 6c 64 20 62 65 0a 2a 2a 20 5b 53 51 4c 49 ould be.** [SQLI
25cb0 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 TE_ANY]..**.** T
25cc0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 he fifth paramet
25cd0 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 er is an arbitra
25ce0 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 ry pointer. The
25cf0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a implementation.
25d00 2a 2a 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 ** of the functi
25d10 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 on can gain acce
25d20 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 ss to this point
25d30 65 72 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c er using.** [sql
25d40 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 ite3_user_data()
25d50 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 ]..**.** The sev
25d60 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64 enth, eighth and
25d70 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 ninth parameter
25d80 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 s, xFunc, xStep
25d90 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a and xFinal, are.
25da0 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 ** pointers to C
25db0 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 -language functi
25dc0 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 ons that impleme
25dd0 6e 74 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 nt the SQL.** fu
25de0 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 nction or aggreg
25df0 61 74 65 2e 20 41 20 73 63 61 6c 61 72 20 53 51 ate. A scalar SQ
25e00 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 L function requi
25e10 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 res an implement
25e20 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 20 ation of.** the
25e30 78 46 75 6e 63 20 63 61 6c 6c 62 61 63 6b 20 6f xFunc callback o
25e40 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 nly, NULL pointe
25e50 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 rs should be pas
25e60 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 sed as the xStep
25e70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 70 .** and xFinal p
25e80 61 72 61 6d 65 74 65 72 73 2e 20 41 6e 20 61 67 arameters. An ag
25e90 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 gregate SQL func
25ea0 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e tion requires an
25eb0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a implementation.
25ec0 2a 2a 20 6f 66 20 78 53 74 65 70 20 61 6e 64 20 ** of xStep and
25ed0 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 xFinal and NULL
25ee0 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 should be passed
25ef0 20 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20 64 for xFunc. To d
25f00 65 6c 65 74 65 20 61 6e 0a 2a 2a 20 65 78 69 73 elete an.** exis
25f10 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f ting SQL functio
25f20 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 n or aggregate,
25f30 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c pass NULL for al
25f40 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e l three function
25f50 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a .** callback..**
25f60 0a 2a 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74 .** It is permit
25f70 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 ted to register
25f80 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 multiple impleme
25f90 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 ntations of the
25fa0 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e same.** function
25fb0 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 s with the same
25fc0 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 name but with ei
25fd0 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e ther differing n
25fe0 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 umbers of.** arg
25ff0 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 uments or differ
26000 69 6e 67 20 70 65 72 66 65 72 72 65 64 20 74 65 ing perferred te
26010 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 xt encodings. S
26020 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a QLite will use.*
26030 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 * the implementa
26040 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c tion most closel
26050 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 y matches the wa
26060 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a y in which the.*
26070 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 * SQL function i
26080 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e s used..**.** IN
26090 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
260a0 7b 46 31 36 31 30 33 7d 20 54 68 65 20 5b 73 71 {F16103} The [sq
260b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
260c0 63 74 69 6f 6e 31 36 28 29 5d 20 69 6e 74 65 72 ction16()] inter
260d0 66 61 63 65 20 62 65 68 61 76 65 73 20 65 78 61 face behaves exa
260e0 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 ctly.**
260f0 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 63 like [sqlite3_c
26100 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
26110 5d 20 69 6e 20 65 76 65 72 79 20 77 61 79 20 65 ] in every way e
26120 78 63 65 70 74 20 74 68 61 74 20 69 74 0a 2a 2a xcept that it.**
26130 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 70 interp
26140 72 65 74 73 20 74 68 65 20 7a 46 75 6e 63 74 69 rets the zFuncti
26150 6f 6e 4e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 onName argument
26160 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a as.** z
26170 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 ero-terminated U
26180 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 TF-16 native byt
26190 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 e order instead
261a0 6f 66 20 61 73 20 61 0a 2a 2a 20 20 20 20 20 20 of as a.**
261b0 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 zero-termina
261c0 74 65 64 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a ted UTF-8..**.**
261d0 20 7b 46 31 36 31 30 36 7d 20 41 20 73 75 63 63 {F16106} A succ
261e0 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f essful invocatio
261f0 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 n of.**
26200 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 the [sqlite3_cr
26210 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c eate_function(D,
26220 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 20 69 6e 74 65 X,N,E,...)] inte
26230 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 0a rface registers.
26240 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 72 ** or r
26250 65 70 6c 61 63 65 73 20 63 61 6c 6c 62 61 63 6b eplaces callback
26260 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20 5b 64 functions in [d
26270 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
26280 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 on] D.**
26290 20 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d used to implem
262a0 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 ent the SQL func
262b0 74 69 6f 6e 20 6e 61 6d 65 64 20 58 20 77 69 74 tion named X wit
262c0 68 20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a h N parameters.*
262d0 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 68 * and h
262e0 61 76 69 6e 67 20 61 20 70 65 72 66 65 72 72 65 aving a perferre
262f0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 d text encoding
26300 6f 66 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 of E..**.** {F16
26310 31 30 39 7d 20 41 20 73 75 63 63 65 73 73 66 75 109} A successfu
26320 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 l call to [sqlit
26330 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
26340 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 on(D,X,N,E,P,F,S
26350 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 ,L)].**
26360 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 50 2c replaces the P,
26370 20 46 2c 20 53 2c 20 61 6e 64 20 4c 20 76 61 6c F, S, and L val
26380 75 65 73 20 66 72 6f 6d 20 61 6e 79 20 70 72 69 ues from any pri
26390 6f 72 20 63 61 6c 6c 73 20 77 69 74 68 0a 2a 2a or calls with.**
263a0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61 the sa
263b0 6d 65 20 44 2c 20 58 2c 20 4e 2c 20 61 6e 64 20 me D, X, N, and
263c0 45 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 E values..**.**
263d0 7b 46 31 36 31 31 32 7d 20 54 68 65 20 5b 73 71 {F16112} The [sq
263e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
263f0 63 74 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20 ction(D,X,...)]
26400 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 interface fails
26410 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 with.**
26420 20 61 20 72 65 74 75 72 6e 20 63 6f 64 65 20 6f a return code o
26430 66 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d f [SQLITE_ERROR]
26440 20 69 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 if the SQL func
26450 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69 73 0a 2a tion name X is.*
26460 2a 20 20 20 20 20 20 20 20 20 20 6c 6f 6e 67 65 * longe
26470 72 20 74 68 61 6e 20 32 35 35 20 62 79 74 65 73 r than 255 bytes
26480 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 exclusive of th
26490 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f e zero terminato
264a0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 31 38 r..**.** {F16118
264b0 7d 20 45 69 74 68 65 72 20 46 20 6d 75 73 74 20 } Either F must
264c0 62 65 20 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e be NULL and S an
264d0 64 20 4c 20 61 72 65 20 6e 6f 6e 2d 4e 55 4c 4c d L are non-NULL
264e0 20 6f 72 20 65 6c 73 65 20 46 0a 2a 2a 20 20 20 or else F.**
264f0 20 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d 4e 55 is non-NU
26500 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 LL and S and L a
26510 72 65 20 4e 55 4c 4c 2c 20 6f 74 68 65 72 77 69 re NULL, otherwi
26520 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b se.** [
26530 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
26540 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c unction(D,X,N,E,
26550 50 2c 46 2c 53 2c 4c 29 5d 20 72 65 74 75 72 6e P,F,S,L)] return
26560 73 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d s [SQLITE_ERROR]
26570 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 31 7d ..**.** {F16121}
26580 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 The [sqlite3_cr
26590 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c eate_function(D,
265a0 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 ...)] interface
265b0 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a fails with an.**
265c0 20 20 20 20 20 20 20 20 20 20 65 72 72 6f 72 20 error
265d0 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f code of [SQLITE_
265e0 42 55 53 59 5d 20 69 66 20 74 68 65 72 65 20 65 BUSY] if there e
265f0 78 69 73 74 20 5b 70 72 65 70 61 72 65 64 20 73 xist [prepared s
26600 74 61 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20 20 20 tatements].**
26610 20 20 20 20 20 20 20 61 73 73 6f 63 69 61 74 65 associate
26620 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 d with the [data
26630 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
26640 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 D..**.** {F1612
26650 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 4} The [sqlite3_
26660 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
26670 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 20 69 6e 74 65 D,X,N,...)] inte
26680 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 rface fails with
26690 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 an.**
266a0 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 error code of [S
266b0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 QLITE_ERROR] if
266c0 70 61 72 61 6d 65 74 65 72 20 4e 20 28 73 70 65 parameter N (spe
266d0 63 69 66 79 69 6e 67 20 74 68 65 20 6e 75 6d 62 cifying the numb
266e0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f er.** o
266f0 66 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 f arguments to t
26700 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 he SQL function
26710 62 65 69 6e 67 20 72 65 67 69 73 74 65 72 65 64 being registered
26720 29 20 69 73 20 6c 65 73 73 0a 2a 2a 20 20 20 20 ) is less.**
26730 20 20 20 20 20 20 74 68 61 6e 20 2d 31 20 6f 72 than -1 or
26740 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 greater than 12
26750 37 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 37 7..**.** {F16127
26760 7d 20 57 68 65 6e 20 4e 20 69 73 20 6e 6f 6e 2d } When N is non-
26770 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 5b 73 negative, the [s
26780 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
26790 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e nction(D,X,N,...
267a0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 )].** i
267b0 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 nterface causes
267c0 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 callbacks to be
267d0 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 invoked for the
267e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 SQL function.**
267f0 20 20 20 20 20 20 20 20 20 6e 61 6d 65 64 20 58 named X
26800 20 77 68 65 6e 20 74 68 65 20 6e 75 6d 62 65 72 when the number
26810 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 6f of arguments to
26820 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
26830 6e 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 n is.**
26840 20 65 78 61 63 74 6c 79 20 4e 2e 0a 2a 2a 0a 2a exactly N..**.*
26850 2a 20 7b 46 31 36 31 33 30 7d 20 57 68 65 6e 20 * {F16130} When
26860 4e 20 69 73 20 2d 31 2c 20 74 68 65 20 5b 73 71 N is -1, the [sq
26870 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
26880 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 ction(D,X,N,...)
26890 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e ].** in
268a0 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 63 terface causes c
268b0 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69 allbacks to be i
268c0 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 53 nvoked for the S
268d0 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 QL function.**
268e0 20 20 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20 named X
268f0 77 69 74 68 20 61 6e 79 20 6e 75 6d 62 65 72 20 with any number
26900 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a of arguments..**
26910 0a 2a 2a 20 7b 46 31 36 31 33 33 7d 20 57 68 65 .** {F16133} Whe
26920 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 n calls to [sqli
26930 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
26940 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a ion(D,X,N,...)].
26950 2a 2a 20 20 20 20 20 20 20 20 20 20 73 70 65 63 ** spec
26960 69 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 ify multiple imp
26970 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 lementations of
26980 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f the same functio
26990 6e 20 58 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 n X.**
269a0 61 6e 64 20 77 68 65 6e 20 6f 6e 65 20 69 6d 70 and when one imp
269b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 68 61 73 20 lementation has
269c0 4e 3e 3d 30 20 61 6e 64 20 74 68 65 20 6f 74 68 N>=0 and the oth
269d0 65 72 20 68 61 73 20 4e 3d 28 2d 31 29 0a 2a 2a er has N=(-1).**
269e0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 69 6d the im
269f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 plementation wit
26a00 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 4e 20 69 h a non-zero N i
26a10 73 20 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a s preferred..**.
26a20 2a 2a 20 7b 46 31 36 31 33 36 7d 20 57 68 65 6e ** {F16136} When
26a30 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
26a40 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
26a50 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d on(D,X,N,E,...)]
26a60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 70 65 .** spe
26a70 63 69 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d cify multiple im
26a80 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 plementations of
26a90 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 the same functi
26aa0 6f 6e 20 58 20 77 69 74 68 0a 2a 2a 20 20 20 20 on X with.**
26ab0 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 6e the same n
26ac0 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e umber of argumen
26ad0 74 73 20 4e 20 62 75 74 20 77 69 74 68 20 64 69 ts N but with di
26ae0 66 66 65 72 65 6e 74 0a 2a 2a 20 20 20 20 20 20 fferent.**
26af0 20 20 20 20 65 6e 63 6f 64 69 6e 67 73 20 45 2c encodings E,
26b00 20 74 68 65 6e 20 74 68 65 20 69 6d 70 6c 65 6d then the implem
26b10 65 6e 74 61 74 69 6f 6e 20 77 68 65 72 65 20 45 entation where E
26b20 20 6d 61 74 63 68 65 73 20 74 68 65 0a 2a 2a 20 matches the.**
26b30 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73 databas
26b40 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 70 72 e encoding is pr
26b50 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b eferred..**.** {
26b60 46 31 36 31 33 39 7d 20 46 6f 72 20 61 6e 20 61 F16139} For an a
26b70 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e ggregate SQL fun
26b80 63 74 69 6f 6e 20 63 72 65 61 74 65 64 20 75 73 ction created us
26b90 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ing.**
26ba0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
26bb0 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 function(D,X,N,E
26bc0 2c 50 2c 30 2c 53 2c 4c 29 5d 20 74 68 65 20 66 ,P,0,S,L)] the f
26bd0 69 6e 69 61 6c 69 7a 65 72 0a 2a 2a 20 20 20 20 inializer.**
26be0 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 4c function L
26bf0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 62 65 20 will always be
26c00 69 6e 76 6f 6b 65 64 20 65 78 61 63 74 6c 79 20 invoked exactly
26c10 6f 6e 63 65 20 69 66 20 74 68 65 0a 2a 2a 20 20 once if the.**
26c20 20 20 20 20 20 20 20 20 73 74 65 70 20 66 75 6e step fun
26c30 63 74 69 6f 6e 20 53 20 69 73 20 63 61 6c 6c 65 ction S is calle
26c40 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 d one or more ti
26c50 6d 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 mes..**.** {F161
26c60 34 32 7d 20 57 68 65 6e 20 53 51 4c 69 74 65 20 42} When SQLite
26c70 69 6e 76 6f 6b 65 73 20 65 69 74 68 65 72 20 74 invokes either t
26c80 68 65 20 78 46 75 6e 63 20 6f 72 20 78 53 74 65 he xFunc or xSte
26c90 70 20 66 75 6e 63 74 69 6f 6e 20 6f 66 0a 2a 2a p function of.**
26ca0 20 20 20 20 20 20 20 20 20 20 61 6e 20 61 70 70 an app
26cb0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
26cc0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 SQL function or
26cd0 20 61 67 67 72 65 67 61 74 65 20 63 72 65 61 74 aggregate creat
26ce0 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 ed.** b
26cf0 79 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 y [sqlite3_creat
26d00 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 6f 72 e_function()] or
26d10 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
26d20 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 0a _function16()],.
26d30 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e ** then
26d40 20 74 68 65 20 61 72 72 61 79 20 6f 66 20 5b 73 the array of [s
26d50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
26d60 6a 65 63 74 73 20 70 61 73 73 65 64 20 61 73 20 jects passed as
26d70 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
26d80 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
26d90 61 72 65 20 61 6c 77 61 79 73 20 5b 70 72 6f 74 are always [prot
26da0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
26db0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f lue] objects..*/
26dc0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 .int sqlite3_cre
26dd0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 ate_function(.
26de0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 sqlite3 *db,. c
26df0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 onst char *zFunc
26e00 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 tionName,. int
26e10 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 nArg,. int eTex
26e20 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 tRep,. void *pA
26e30 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 pp,. void (*xFu
26e40 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 nc)(sqlite3_cont
26e50 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
26e60 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
26e70 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 d (*xStep)(sqlit
26e80 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c e3_context*,int,
26e90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 sqlite3_value**)
26ea0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 ,. void (*xFina
26eb0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 l)(sqlite3_conte
26ec0 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 xt*).);.int sqli
26ed0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
26ee0 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 ion16(. sqlite3
26ef0 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f *db,. const vo
26f00 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d id *zFunctionNam
26f10 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 e,. int nArg,.
26f20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 int eTextRep,.
26f30 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 void *pApp,. v
26f40 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c oid (*xFunc)(sql
26f50 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e ite3_context*,in
26f60 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t,sqlite3_value*
26f70 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 *),. void (*xSt
26f80 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ep)(sqlite3_cont
26f90 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
26fa0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
26fb0 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 d (*xFinal)(sqli
26fc0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b te3_context*).);
26fd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
26fe0 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 : Text Encodings
26ff0 20 7b 46 31 30 32 36 37 7d 0a 2a 2a 0a 2a 2a 20 {F10267}.**.**
27000 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 These constant d
27010 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f efine integer co
27020 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 des that represe
27030 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a nt the various.*
27040 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 * text encodings
27050 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 supported by SQ
27060 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 Lite..*/.#define
27070 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 SQLITE_UTF8
27080 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 1.#define
27090 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 SQLITE_UTF16LE
270a0 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 2.#define
270b0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 SQLITE_UTF16BE
270c0 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 3.#define
270d0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 SQLITE_UTF16
270e0 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 4 /* U
270f0 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f se native byte o
27100 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rder */.#define
27110 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 SQLITE_ANY
27120 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 5 /* sq
27130 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
27140 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 ction only */.#d
27150 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 efine SQLITE_UTF
27160 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 16_ALIGNED 8
27170 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 /* sqlite3_crea
27180 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c te_collation onl
27190 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 y */../*.** CAPI
271a0 33 52 45 46 3a 20 4f 62 73 6f 6c 65 74 65 20 46 3REF: Obsolete F
271b0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 unctions.**.** T
271c0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 hese functions a
271d0 72 65 20 61 6c 6c 20 6e 6f 77 20 6f 62 73 6f 6c re all now obsol
271e0 65 74 65 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 ete. In order t
271f0 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 o maintain.** ba
27200 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 ckwards compatib
27210 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 ility with older
27220 20 63 6f 64 65 2c 20 77 65 20 63 6f 6e 74 69 6e code, we contin
27230 75 65 20 74 6f 20 73 75 70 70 6f 72 74 0a 2a 2a ue to support.**
27240 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 these functions
27250 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 . However, new
27260 64 65 76 65 6c 6f 70 6d 65 6e 74 20 70 72 6f 6a development proj
27270 65 63 74 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 ects should avoi
27280 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 d.** the use of
27290 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e these functions.
272a0 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 To help encour
272b0 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 age people to av
272c0 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 oid.** using the
272d0 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 se functions, we
272e0 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 are not going t
272f0 6f 20 74 65 6c 6c 20 79 6f 75 20 77 61 6e 74 20 o tell you want
27300 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 69 6e 74 20 they do..*/.int
27310 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
27320 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f e_count(sqlite3_
27330 63 6f 6e 74 65 78 74 2a 29 3b 0a 69 6e 74 20 73 context*);.int s
27340 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 qlite3_expired(s
27350 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 qlite3_stmt*);.i
27360 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 nt sqlite3_trans
27370 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c fer_bindings(sql
27380 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 ite3_stmt*, sqli
27390 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 te3_stmt*);.int
273a0 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 sqlite3_global_r
273b0 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 76 6f ecover(void);.vo
273c0 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 id sqlite3_threa
273d0 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b d_cleanup(void);
273e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d .int sqlite3_mem
273f0 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a ory_alarm(void(*
27400 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f )(void*,sqlite3_
27410 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a int64,int),void*
27420 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b ,sqlite3_int64);
27430 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
27440 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 : Obtaining SQL
27450 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 Function Paramet
27460 65 72 20 56 61 6c 75 65 73 20 7b 46 31 35 31 30 er Values {F1510
27470 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 0}.**.** The C-l
27480 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e anguage implemen
27490 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 tation of SQL fu
274a0 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 nctions and aggr
274b0 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 egates uses.** t
274c0 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 his set of inter
274d0 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f face routines to
274e0 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 access the para
274f0 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a meter values on.
27500 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 ** the function
27510 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a or aggregate..**
27520 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 .** The xFunc (f
27530 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 or scalar functi
27540 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 ons) or xStep (f
27550 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70 or aggregates) p
27560 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 arameters.** to
27570 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
27580 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 function()] and
27590 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
275a0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a function16()].**
275b0 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b define callback
275c0 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 s that implement
275d0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
275e0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 ns and aggregate
275f0 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61 s..** The 4th pa
27600 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 rameter to these
27610 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e callbacks is an
27620 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 array of pointe
27630 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 rs to.** [protec
27640 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
27650 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 e] objects. The
27660 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 re is one [sqlit
27670 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
27680 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 for.** each par
27690 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 ameter to the SQ
276a0 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 L function. The
276b0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
276c0 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 used to.** extra
276d0 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 ct values from t
276e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 he [sqlite3_valu
276f0 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a e] objects..**.*
27700 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
27710 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 work only with
27720 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 [protected sqlit
27730 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
27740 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 s..** Any attemp
27750 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 t to use these r
27760 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 outines on an [u
27770 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
27780 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a e3_value].** obj
27790 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 ect results in u
277a0 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f ndefined behavio
277b0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 r..**.** These r
277c0 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 outines work jus
277d0 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 t like the corre
277e0 73 70 6f 6e 64 69 6e 67 20 0a 2a 2a 20 5b 73 71 sponding .** [sq
277f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
27800 62 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 b | sqlite3_colu
27810 6d 6e 5f 2a 20 72 6f 75 74 69 6e 65 73 5d 20 65 mn_* routines] e
27820 78 63 65 70 74 20 74 68 61 74 20 0a 2a 2a 20 74 xcept that .** t
27830 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 hese routines ta
27840 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f ke a single [pro
27850 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
27860 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 70 6f 69 alue] object poi
27870 6e 74 65 72 0a 2a 2a 20 69 6e 73 74 65 61 64 20 nter.** instead
27880 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 73 of an [sqlite3_s
27890 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e tmt*] pointer an
278a0 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c d an integer col
278b0 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a umn number..**.*
278c0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 * The sqlite3_va
278d0 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 lue_text16() int
278e0 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 erface extracts
278f0 61 20 55 54 46 31 36 20 73 74 72 69 6e 67 0a 2a a UTF16 string.*
27900 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 * in the native
27910 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 byte-order of th
27920 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 e host machine.
27930 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f The.** sqlite3_
27940 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 value_text16be()
27950 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c and sqlite3_val
27960 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e ue_text16le() in
27970 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 terfaces.** extr
27980 61 63 74 20 55 54 46 31 36 20 73 74 72 69 6e 67 act UTF16 string
27990 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 s as big-endian
279a0 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 and little-endia
279b0 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a n respectively..
279c0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
279d0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 3_value_numeric_
279e0 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 type() interface
279f0 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 attempts to app
27a00 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 ly.** numeric af
27a10 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 finity to the va
27a20 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 lue. This means
27a30 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 that an attempt
27a40 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 is.** made to c
27a50 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 onvert the value
27a60 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f to an integer o
27a70 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 r floating point
27a80 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 . If.** such a
27a90 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f conversion is po
27aa0 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c ssible without l
27ab0 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 oss of informati
27ac0 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 on (in other.**
27ad0 77 6f 72 64 73 20 69 66 20 74 68 65 20 76 61 6c words if the val
27ae0 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 ue is a string t
27af0 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 hat looks like a
27b00 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e number).** then
27b10 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 the conversion
27b20 69 73 20 64 6f 6e 65 2e 20 20 4f 74 68 65 72 77 is done. Otherw
27b30 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f ise no conversio
27b40 6e 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 0a n occurs. The .
27b50 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 ** [SQLITE_INTEG
27b60 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 ER | datatype] a
27b70 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 fter conversion
27b80 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
27b90 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 ** Please pay pa
27ba0 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 rticular attenti
27bb0 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 on to the fact t
27bc0 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 hat the pointer
27bd0 74 68 61 74 0a 2a 2a 20 69 73 20 72 65 74 75 72 that.** is retur
27be0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ned from [sqlite
27bf0 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 3_value_blob()],
27c00 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
27c10 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b text()], or.** [
27c20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
27c30 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 xt16()] can be i
27c40 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 nvalidated by a
27c50 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 subsequent call
27c60 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 to.** [sqlite3_v
27c70 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b alue_bytes()], [
27c80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
27c90 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 tes16()], [sqlit
27ca0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d e3_value_text()]
27cb0 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 ,.** or [sqlite3
27cc0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d _value_text16()]
27cd0 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 . .**.** These
27ce0 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 routines must be
27cf0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 called from the
27d00 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a same thread as.
27d10 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 ** the SQL funct
27d20 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 ion that supplie
27d30 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 d the [sqlite3_v
27d40 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 alue*] parameter
27d50 73 2e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 s..**.**.** INVA
27d60 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 RIANTS:.**.** {F
27d70 31 35 31 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 15103} The [sqli
27d80 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56 te3_value_blob(V
27d90 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e )] interface con
27da0 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 verts the.**
27db0 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 [protected
27dc0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
27dd0 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 object V into a
27de0 62 6c 6f 62 20 61 6e 64 20 74 68 65 6e 20 72 65 blob and then re
27df0 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 turns a.**
27e00 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 pointer to t
27e10 68 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c he converted val
27e20 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 30 ue..**.** {F1510
27e30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6} The [sqlite3_
27e40 76 61 6c 75 65 5f 62 79 74 65 73 28 56 29 5d 20 value_bytes(V)]
27e50 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
27e60 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 s the.**
27e70 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 number of byte
27e80 73 20 69 6e 20 74 68 65 20 62 6c 6f 62 20 6f 72 s in the blob or
27e90 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 string (exclusi
27ea0 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 ve of the.**
27eb0 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 zero termi
27ec0 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 nator on the str
27ed0 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65 ing) that was re
27ee0 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a turned by the.**
27ef0 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 most r
27f00 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 ecent call to [s
27f10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f qlite3_value_blo
27f20 62 28 56 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 b(V)] or.**
27f30 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61 [sqlite3_va
27f40 6c 75 65 5f 74 65 78 74 28 56 29 5d 2e 0a 2a 2a lue_text(V)]..**
27f50 0a 2a 2a 20 7b 46 31 35 31 30 39 7d 20 54 68 65 .** {F15109} The
27f60 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
27f70 62 79 74 65 73 31 36 28 56 29 5d 20 69 6e 74 65 bytes16(V)] inte
27f80 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 rface returns th
27f90 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 e.** nu
27fa0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e mber of bytes in
27fb0 20 74 68 65 20 73 74 72 69 6e 67 20 28 65 78 63 the string (exc
27fc0 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a lusive of the.**
27fd0 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 zero t
27fe0 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 erminator on the
27ff0 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 string) that wa
28000 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 s returned by th
28010 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f e.** mo
28020 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 st recent call t
28030 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 o [sqlite3_value
28040 5f 74 65 78 74 31 36 28 56 29 5d 2c 0a 2a 2a 20 _text16(V)],.**
28050 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
28060 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 3_value_text16be
28070 28 56 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 (V)], or [sqlite
28080 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 3_value_text16le
28090 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 (V)]..**.** {F15
280a0 31 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 112} The [sqlite
280b0 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 56 3_value_double(V
280c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e )] interface con
280d0 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 verts the.**
280e0 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 [protected
280f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
28100 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 object V into a
28110 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 floating point v
28120 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 alue and.**
28130 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 returns a c
28140 6f 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75 opy of that valu
28150 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 31 35 e..**.** {F15115
28160 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 } The [sqlite3_v
28170 61 6c 75 65 5f 69 6e 74 28 56 29 5d 20 69 6e 74 alue_int(V)] int
28180 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 erface converts
28190 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
281a0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 [protected sqlit
281b0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
281c0 20 56 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 V into a 64-bit
281d0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 signed integer
281e0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 and.**
281f0 72 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 returns the lowe
28200 72 20 33 32 20 62 69 74 73 20 6f 66 20 74 68 61 r 32 bits of tha
28210 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a t integer..**.**
28220 20 7b 46 31 35 31 31 38 7d 20 54 68 65 20 5b 73 {F15118} The [s
28230 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 qlite3_value_int
28240 36 34 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 64(V)] interface
28250 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a converts the.**
28260 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 [prote
28270 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
28280 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 ue] object V int
28290 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 o a 64-bit signe
282a0 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a d integer and.**
282b0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e return
282c0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 s a copy of that
282d0 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 integer..**.**
282e0 7b 46 31 35 31 32 31 7d 20 54 68 65 20 5b 73 71 {F15121} The [sq
282f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
28300 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 (V)] interface c
28310 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 onverts the.**
28320 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 [protect
28330 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
28340 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 ] object V into
28350 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
28360 64 20 55 54 46 2d 38 20 0a 2a 2a 20 20 20 20 20 d UTF-8 .**
28370 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 string and
28380 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
28390 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 r to that string
283a0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 32 34 7d ..**.** {F15124}
283b0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 The [sqlite3_va
283c0 6c 75 65 5f 74 65 78 74 31 36 28 56 29 5d 20 69 lue_text16(V)] i
283d0 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 nterface convert
283e0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 s the.**
283f0 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c [protected sql
28400 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
28410 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f ct V into a zero
28420 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 -terminated 2-by
28430 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 te.** a
28440 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 ligned UTF-16 na
28450 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a tive byte order.
28460 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 ** stri
28470 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 ng and returns a
28480 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 pointer to that
28490 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b string..**.** {
284a0 46 31 35 31 32 37 7d 20 54 68 65 20 5b 73 71 6c F15127} The [sql
284b0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
284c0 36 62 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 6be(V)] interfac
284d0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a e converts the.*
284e0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 * [prot
284f0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
28500 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e lue] object V in
28510 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e to a zero-termin
28520 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 ated 2-byte.**
28530 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 aligned
28540 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 UTF-16 big-endia
28550 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 n.** st
28560 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 ring and returns
28570 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
28580 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a at string..**.**
28590 20 7b 46 31 35 31 33 30 7d 20 54 68 65 20 5b 73 {F15130} The [s
285a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
285b0 74 31 36 6c 65 28 56 29 5d 20 69 6e 74 65 72 66 t16le(V)] interf
285c0 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 ace converts the
285d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 .** [pr
285e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
285f0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 value] object V
28600 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d into a zero-term
28610 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a inated 2-byte.**
28620 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 aligne
28630 64 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d d UTF-16 little-
28640 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 endian.**
28650 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 string and re
28660 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
28670 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a to that string..
28680 2a 2a 0a 2a 2a 20 7b 46 31 35 31 33 33 7d 20 54 **.** {F15133} T
28690 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 he [sqlite3_valu
286a0 65 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 65 72 e_type(V)] inter
286b0 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 face returns.**
286c0 20 20 20 20 20 20 20 20 20 6f 6e 65 20 6f 66 20 one of
286d0 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b [SQLITE_NULL], [
286e0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c SQLITE_INTEGER],
286f0 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c [SQLITE_FLOAT],
28700 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 .** [SQ
28710 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b LITE_TEXT], or [
28720 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 SQLITE_BLOB] as
28730 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 0a appropriate for.
28740 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
28750 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 [sqlite3_value]
28760 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 object V..**.**
28770 7b 46 31 35 31 33 36 7d 20 54 68 65 20 5b 73 71 {F15136} The [sq
28780 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 lite3_value_nume
28790 72 69 63 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 ric_type(V)] int
287a0 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 0a erface converts.
287b0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
287c0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 [protected sqlit
287d0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
287e0 20 56 20 69 6e 74 6f 20 65 69 74 68 65 72 20 61 V into either a
287f0 6e 20 69 6e 74 65 67 65 72 20 6f 72 0a 2a 2a 20 n integer or.**
28800 20 20 20 20 20 20 20 20 20 61 20 66 6c 6f 61 74 a float
28810 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 ing point value
28820 69 66 20 69 74 20 63 61 6e 20 64 6f 20 73 6f 20 if it can do so
28830 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 0a without loss of.
28840 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 66 6f ** info
28850 72 6d 61 74 69 6f 6e 2c 20 61 6e 64 20 72 65 74 rmation, and ret
28860 75 72 6e 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c urns one of [SQL
28870 49 54 45 5f 4e 55 4c 4c 5d 2c 0a 2a 2a 20 20 20 ITE_NULL],.**
28880 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 [SQLITE_I
28890 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 NTEGER], [SQLITE
288a0 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 _FLOAT], [SQLITE
288b0 5f 54 45 58 54 5d 2c 20 6f 72 0a 2a 2a 20 20 20 _TEXT], or.**
288c0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 42 [SQLITE_B
288d0 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 LOB] as appropri
288e0 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 ate for.**
288f0 20 20 20 20 74 68 65 20 5b 70 72 6f 74 65 63 74 the [protect
28900 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
28910 5d 20 6f 62 6a 65 63 74 20 56 20 61 66 74 65 72 ] object V after
28920 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 the conversion
28930 61 74 74 65 6d 70 74 2e 0a 2a 2f 0a 63 6f 6e 73 attempt..*/.cons
28940 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
28950 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 value_blob(sqlit
28960 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 e3_value*);.int
28970 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
28980 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 tes(sqlite3_valu
28990 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 e*);.int sqlite3
289a0 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 _value_bytes16(s
289b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
289c0 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 double sqlite3_v
289d0 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 alue_double(sqli
289e0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 te3_value*);.int
289f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 sqlite3_value_i
28a00 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt(sqlite3_value
28a10 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 *);.sqlite3_int6
28a20 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 4 sqlite3_value_
28a30 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 int64(sqlite3_va
28a40 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 lue*);.const uns
28a50 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 igned char *sqli
28a60 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 te3_value_text(s
28a70 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
28a80 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
28a90 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
28aa0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
28ab0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 ;.const void *sq
28ac0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
28ad0 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 16le(sqlite3_val
28ae0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 ue*);.const void
28af0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f *sqlite3_value_
28b00 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 text16be(sqlite3
28b10 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 _value*);.int sq
28b20 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 lite3_value_type
28b30 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
28b40 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 ;.int sqlite3_va
28b50 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 lue_numeric_type
28b60 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
28b70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
28b80 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 F: Obtain Aggreg
28b90 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e ate Function Con
28ba0 74 65 78 74 20 7b 46 31 36 32 31 30 7d 0a 2a 2a text {F16210}.**
28bb0 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e .** The implemen
28bc0 74 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 67 tation of aggreg
28bd0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ate SQL function
28be0 73 20 75 73 65 20 74 68 69 73 20 72 6f 75 74 69 s use this routi
28bf0 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a ne to allocate.*
28c00 2a 20 61 20 73 74 72 75 63 74 75 72 65 20 66 6f * a structure fo
28c10 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 r storing their
28c20 73 74 61 74 65 2e 20 20 0a 2a 2a 20 54 68 65 20 state. .** The
28c30 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 first time the s
28c40 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
28c50 5f 63 6f 6e 74 65 78 74 28 29 20 72 6f 75 74 69 _context() routi
28c60 6e 65 20 69 73 0a 2a 2a 20 69 73 20 63 61 6c 6c ne is.** is call
28c70 65 64 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 ed for a particu
28c80 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c 20 53 lar aggregate, S
28c90 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65 73 20 QLite allocates
28ca0 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 nBytes of memory
28cb0 0a 2a 2a 20 7a 65 72 6f 73 20 74 68 61 74 20 6d .** zeros that m
28cc0 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 emory, and retur
28cd0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
28ce0 69 74 2e 0a 2a 2a 20 4f 6e 20 73 65 63 6f 6e 64 it..** On second
28cf0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 and subsequent
28d00 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
28d10 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
28d20 78 74 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 xt().** for the
28d30 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 same aggregate f
28d40 75 6e 63 74 69 6f 6e 20 69 6e 64 65 78 2c 20 74 unction index, t
28d50 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 he same buffer i
28d60 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 s returned..** T
28d70 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
28d80 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 61 67 67 72 n.** of the aggr
28d90 65 67 61 74 65 20 63 61 6e 20 75 73 65 20 74 68 egate can use th
28da0 65 20 72 65 74 75 72 6e 65 64 20 62 75 66 66 65 e returned buffe
28db0 72 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 65 20 r to accumulate
28dc0 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 data..**.** SQLi
28dd0 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 te automatically
28de0 20 66 72 65 65 73 20 74 68 65 20 61 6c 6c 6f 63 frees the alloc
28df0 61 74 65 64 20 62 75 66 66 65 72 20 77 68 65 6e ated buffer when
28e00 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a the aggregate.*
28e10 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 * query conclude
28e20 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 s..**.** The fir
28e30 73 74 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f st parameter sho
28e40 75 6c 64 20 62 65 20 61 20 63 6f 70 79 20 6f 66 uld be a copy of
28e50 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 the .** [sqlite
28e60 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 3_context | SQL
28e70 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 function context
28e80 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69 ] that is the fi
28e90 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 rst.** parameter
28ea0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
28eb0 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d routine that im
28ec0 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 plements the agg
28ed0 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 regate.** functi
28ee0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 on..**.** This r
28ef0 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 outine must be c
28f00 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 alled from the s
28f10 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 ame thread in wh
28f20 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 ich.** the aggre
28f30 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f gate SQL functio
28f40 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a n is running..**
28f50 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
28f60 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31 31 7d 20 54 **.** {F16211} T
28f70 68 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74 he first invocat
28f80 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f ion of [sqlite3_
28f90 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
28fa0 74 28 43 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20 20 t(C,N)] for.**
28fb0 20 20 20 20 20 20 20 20 61 20 70 61 72 74 69 63 a partic
28fc0 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 ular instance of
28fd0 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 66 75 an aggregate fu
28fe0 6e 63 74 69 6f 6e 20 28 66 6f 72 20 61 20 70 61 nction (for a pa
28ff0 72 74 69 63 75 6c 61 72 0a 2a 2a 20 20 20 20 20 rticular.**
29000 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 29 20 context C)
29010 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f causes SQLite to
29020 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 4e 20 62 79 allocation N by
29030 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a 2a tes of memory,.*
29040 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 * zero
29050 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 that memory, and
29060 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 return a pointe
29070 72 20 74 6f 20 74 68 65 20 61 6c 6c 6f 63 61 74 r to the allocat
29080 69 6f 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 ioned.**
29090 20 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 memory..**.**
290a0 7b 46 31 36 32 31 33 7d 20 49 66 20 61 20 6d 65 {F16213} If a me
290b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
290c0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 error occurs dur
290d0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ing.**
290e0 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 [sqlite3_aggrega
290f0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d te_context(C,N)]
29100 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 then the functi
29110 6f 6e 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a on returns 0..**
29120 0a 2a 2a 20 7b 46 31 36 32 31 35 7d 20 53 65 63 .** {F16215} Sec
29130 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 ond and subseque
29140 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f nt invocations o
29150 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 f.** [s
29160 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
29170 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 _context(C,N)] f
29180 6f 72 20 74 68 65 20 73 61 6d 65 20 63 6f 6e 74 or the same cont
29190 65 78 74 20 70 6f 69 6e 74 65 72 20 43 0a 2a 2a ext pointer C.**
291a0 20 20 20 20 20 20 20 20 20 20 69 67 6e 6f 72 65 ignore
291b0 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 the N parameter
291c0 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f and return a po
291d0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 61 6d inter to the sam
291e0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 6c e.** bl
291f0 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 72 65 ock of memory re
29200 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 66 69 turned by the fi
29210 72 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a rst invocation..
29220 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31 37 7d 20 54 **.** {F16217} T
29230 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
29240 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ted by [sqlite3_
29250 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
29260 74 28 43 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20 20 t(C,N)] is.**
29270 20 20 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63 automatic
29280 61 6c 6c 79 20 66 72 65 65 64 20 6f 6e 20 74 68 ally freed on th
29290 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 20 5b e next call to [
292a0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
292b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 .** or
292c0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
292d0 65 28 29 5d 20 66 6f 72 20 74 68 65 20 5b 70 72 e()] for the [pr
292e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
292f0 5d 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 ] containing.**
29300 20 20 20 20 20 20 20 20 20 74 68 65 20 61 67 67 the agg
29310 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 regate function
29320 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
29330 63 6f 6e 74 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f context C..*/.vo
29340 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 id *sqlite3_aggr
29350 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 egate_context(sq
29360 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
29370 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a int nBytes);../*
29380 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 .** CAPI3REF: Us
29390 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 er Data For Func
293a0 74 69 6f 6e 73 20 7b 46 31 36 32 34 30 7d 0a 2a tions {F16240}.*
293b0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
293c0 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 _user_data() int
293d0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
293e0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 copy of.** the
293f0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 pointer that was
29400 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70 the pUserData p
29410 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 arameter (the 5t
29420 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 h parameter).**
29430 6f 66 20 74 68 65 20 74 68 65 20 5b 73 71 6c 69 of the the [sqli
29440 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
29450 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 ion()].** and [s
29460 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
29470 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 nction16()] rout
29480 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e ines that origin
29490 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 ally.** register
294a0 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ed the applicati
294b0 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on defined funct
294c0 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a ion. {END}.**.**
294d0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 This routine mu
294e0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f st be called fro
294f0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 m the same threa
29500 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 d in which.** th
29510 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
29520 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 fined function i
29530 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a s running..**.**
29540 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
29550 2a 2a 20 7b 46 31 36 32 34 33 7d 20 54 68 65 20 ** {F16243} The
29560 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 [sqlite3_user_da
29570 74 61 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 ta(C)] interface
29580 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 returns a copy
29590 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 of the.**
295a0 20 20 20 50 20 70 6f 69 6e 74 65 72 20 66 72 6f P pointer fro
295b0 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 m the [sqlite3_c
295c0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 reate_function(D
295d0 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d ,X,N,E,P,F,S,L)]
295e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 .** or
295f0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
29600 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e function16(D,X,N
29610 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c ,E,P,F,S,L)] cal
29620 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 l that.**
29630 20 20 20 72 65 67 69 73 74 65 72 65 64 20 74 68 registered th
29640 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 e SQL function a
29650 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a ssociated with .
29660 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
29670 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e ite3_context] C.
29680 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 .*/.void *sqlite
29690 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 3_user_data(sqli
296a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a te3_context*);..
296b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
296c0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 Database Connect
296d0 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e ion For Function
296e0 73 20 7b 46 31 36 32 35 30 7d 0a 2a 2a 0a 2a 2a s {F16250}.**.**
296f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e The sqlite3_con
29700 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 text_db_handle()
29710 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
29720 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 ns a copy of.**
29730 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 the pointer to t
29740 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
29750 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 nection] (the 1s
29760 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 t parameter).**
29770 6f 66 20 74 68 65 20 74 68 65 20 5b 73 71 6c 69 of the the [sqli
29780 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
29790 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 ion()].** and [s
297a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
297b0 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 nction16()] rout
297c0 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e ines that origin
297d0 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 ally.** register
297e0 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ed the applicati
297f0 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on defined funct
29800 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 ion..**.** INVAR
29810 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 IANTS:.**.** {F1
29820 36 32 35 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 6253} The [sqlit
29830 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 e3_context_db_ha
29840 6e 64 6c 65 28 43 29 5d 20 69 6e 74 65 72 66 61 ndle(C)] interfa
29850 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 ce returns a cop
29860 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 y of the.**
29870 20 20 20 20 20 44 20 70 6f 69 6e 74 65 72 20 66 D pointer f
29880 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 rom the [sqlite3
29890 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
298a0 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c (D,X,N,E,P,F,S,L
298b0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f )].** o
298c0 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 r [sqlite3_creat
298d0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 e_function16(D,X
298e0 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 ,N,E,P,F,S,L)] c
298f0 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 all that.**
29900 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20 registered
29910 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
29920 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
29930 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 .** [s
29940 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 qlite3_context]
29950 43 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 C..*/.sqlite3 *s
29960 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 qlite3_context_d
29970 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 b_handle(sqlite3
29980 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a _context*);../*.
29990 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e ** CAPI3REF: Fun
299a0 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 ction Auxiliary
299b0 44 61 74 61 20 7b 46 31 36 32 37 30 7d 0a 2a 2a Data {F16270}.**
299c0 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e .** The followin
299d0 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 g two functions
299e0 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73 may be used by s
299f0 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 calar SQL functi
29a00 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 ons to.** associ
29a10 61 74 65 20 6d 65 74 61 2d 64 61 74 61 20 77 69 ate meta-data wi
29a20 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 th argument valu
29a30 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 es. If the same
29a40 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 value is passed
29a50 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 to.** multiple i
29a60 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 nvocations of th
29a70 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 e same SQL funct
29a80 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 ion during query
29a90 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 execution, unde
29aa0 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d r.** some circum
29ab0 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f stances the asso
29ac0 63 69 61 74 65 64 20 6d 65 74 61 2d 64 61 74 61 ciated meta-data
29ad0 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 may be preserve
29ae0 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 d. This may.** b
29af0 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d e used, for exam
29b00 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 ple, to add a re
29b10 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e gular-expression
29b20 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 matching scalar
29b30 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 .** function. Th
29b40 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 e compiled versi
29b50 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 on of the regula
29b60 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 r expression is
29b70 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 stored as.** met
29b80 61 2d 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 a-data associate
29b90 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 d with the SQL v
29ba0 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 alue passed as t
29bb0 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 he regular expre
29bc0 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e ssion.** pattern
29bd0 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 . The compiled
29be0 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 regular expressi
29bf0 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 on can be reused
29c00 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 on multiple.**
29c10 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 invocations of t
29c20 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e he same function
29c30 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 so that the ori
29c40 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 ginal pattern st
29c50 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 ring.** does not
29c60 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f need to be reco
29c70 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 mpiled on each i
29c80 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a nvocation..**.**
29c90 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 The sqlite3_get
29ca0 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 _auxdata() inter
29cb0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 face returns a p
29cc0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 ointer to the me
29cd0 74 61 2d 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 ta-data.** assoc
29ce0 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c iated by the sql
29cf0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 ite3_set_auxdata
29d00 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 () function with
29d10 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e the Nth argumen
29d20 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 t.** value to th
29d30 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
29d40 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a fined function..
29d50 2a 2a 20 49 66 20 6e 6f 20 6d 65 74 61 2d 64 61 ** If no meta-da
29d60 74 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 ta has been ever
29d70 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 been set for th
29d80 65 20 4e 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e e Nth.** argumen
29d90 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f t of the functio
29da0 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f 6f n, or if the coo
29db0 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 responding funct
29dc0 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a ion parameter.**
29dd0 20 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e has changed sin
29de0 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 ce the meta-data
29df0 20 77 61 73 20 73 65 74 2c 20 74 68 65 6e 20 73 was set, then s
29e00 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 qlite3_get_auxda
29e10 74 61 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 ta().** returns
29e20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a a NULL pointer..
29e30 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
29e40 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 3_set_auxdata()
29e50 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20 interface saves
29e60 74 68 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a 2a the meta-data.**
29e70 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 pointed to by i
29e80 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 ts 3rd parameter
29e90 20 61 73 20 74 68 65 20 6d 65 74 61 2d 64 61 74 as the meta-dat
29ea0 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a a for the N-th.*
29eb0 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 * argument of th
29ec0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
29ed0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 fined function.
29ee0 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 Subsequent.** c
29ef0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
29f00 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 get_auxdata() mi
29f10 67 68 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 ght return this
29f20 64 61 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a data, if it has.
29f30 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 ** not been dest
29f40 72 6f 79 65 64 2e 20 0a 2a 2a 20 49 66 20 69 74 royed. .** If it
29f50 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 is not NULL, SQ
29f60 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 Lite will invoke
29f70 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 the destructor
29f80 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 .** function giv
29f90 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 70 61 en by the 4th pa
29fa0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
29fb0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 e3_set_auxdata()
29fc0 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 2d on.** the meta-
29fd0 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f data when the co
29fe0 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 rresponding func
29ff0 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 tion parameter c
2a000 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 hanges.** or whe
2a010 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d n the SQL statem
2a020 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 ent completes, w
2a030 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 hichever comes f
2a040 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 irst..**.** SQLi
2a050 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 te is free to ca
2a060 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f ll the destructo
2a070 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 2d r and drop meta-
2a080 64 61 74 61 20 6f 6e 0a 2a 2a 20 61 6e 79 20 70 data on.** any p
2a090 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 arameter of any
2a0a0 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 function at any
2a0b0 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 time. The only
2a0c0 67 75 61 72 61 6e 74 65 65 0a 2a 2a 20 69 73 20 guarantee.** is
2a0d0 74 68 61 74 20 74 68 65 20 64 65 73 74 72 75 63 that the destruc
2a0e0 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c tor will be call
2a0f0 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 ed before the me
2a100 74 61 64 61 74 61 20 69 73 0a 2a 2a 20 64 72 6f tadata is.** dro
2a110 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 pped..**.** In p
2a120 72 61 63 74 69 63 65 2c 20 6d 65 74 61 2d 64 61 ractice, meta-da
2a130 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20 ta is preserved
2a140 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e between function
2a150 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 calls for.** ex
2a160 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 pressions that a
2a170 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 re constant at c
2a180 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 ompile time. Thi
2a190 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 s includes liter
2a1a0 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 al.** values and
2a1b0 20 53 51 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a SQL variables..
2a1c0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
2a1d0 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c ines must be cal
2a1e0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d led from the sam
2a1f0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 e thread in whic
2a200 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e h.** the SQL fun
2a210 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 ction is running
2a220 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
2a230 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 TS:.**.** {F1627
2a240 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 2} The [sqlite3_
2a250 67 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 get_auxdata(C,N)
2a260 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ] interface retu
2a270 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a rns a pointer.**
2a280 20 20 20 20 20 20 20 20 20 20 74 6f 20 6d 65 74 to met
2a290 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 adata associated
2a2a0 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 70 61 with the Nth pa
2a2b0 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 53 rameter of the S
2a2c0 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 QL function.**
2a2d0 20 20 20 20 20 20 20 20 77 68 6f 73 65 20 63 6f whose co
2a2e0 6e 74 65 78 74 20 69 73 20 43 2c 20 6f 72 20 4e ntext is C, or N
2a2f0 55 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 ULL if there is
2a300 6e 6f 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f no metadata asso
2a310 63 69 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 ciated.**
2a320 20 20 20 77 69 74 68 20 74 68 61 74 20 70 61 72 with that par
2a330 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 ameter..**.** {F
2a340 31 36 32 37 34 7d 20 54 68 65 20 5b 73 71 6c 69 16274} The [sqli
2a350 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 te3_set_auxdata(
2a360 43 2c 4e 2c 50 2c 44 29 5d 20 69 6e 74 65 72 66 C,N,P,D)] interf
2a370 61 63 65 20 61 73 73 69 67 6e 73 20 61 20 6d 65 ace assigns a me
2a380 74 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 tadata.**
2a390 20 20 20 70 6f 69 6e 74 65 72 20 50 20 74 6f 20 pointer P to
2a3a0 74 68 65 20 4e 74 68 20 70 61 72 61 6d 65 74 65 the Nth paramete
2a3b0 72 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e r of the SQL fun
2a3c0 63 74 69 6f 6e 20 77 69 74 68 20 63 6f 6e 74 65 ction with conte
2a3d0 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 xt.** C
2a3e0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 36 7d ..**.** {F16276}
2a3f0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 SQLite will inv
2a400 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 oke the destruct
2a410 6f 72 20 44 20 77 69 74 68 20 61 20 73 69 6e 67 or D with a sing
2a420 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 le argument.**
2a430 20 20 20 20 20 20 20 20 77 68 69 63 68 20 69 73 which is
2a440 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 70 6f the metadata po
2a450 69 6e 74 65 72 20 50 20 66 6f 6c 6c 6f 77 69 6e inter P followin
2a460 67 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 g a call to.**
2a470 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
2a480 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e _set_auxdata(C,N
2a490 2c 50 2c 44 29 5d 20 77 68 65 6e 20 53 51 4c 69 ,P,D)] when SQLi
2a4a0 74 65 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c te ceases to hol
2a4b0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 d.** th
2a4c0 65 20 6d 65 74 61 64 61 74 61 2e 0a 2a 2a 0a 2a e metadata..**.*
2a4d0 2a 20 7b 46 31 36 32 37 37 7d 20 53 51 4c 69 74 * {F16277} SQLit
2a4e0 65 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 e ceases to hold
2a4f0 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 61 6e metadata for an
2a500 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 61 SQL function pa
2a510 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 rameter.**
2a520 20 20 20 20 77 68 65 6e 20 74 68 65 20 76 61 6c when the val
2a530 75 65 20 6f 66 20 74 68 61 74 20 70 61 72 61 6d ue of that param
2a540 65 74 65 72 20 63 68 61 6e 67 65 73 2e 0a 2a 2a eter changes..**
2a550 0a 2a 2a 20 7b 46 31 36 32 37 38 7d 20 57 68 65 .** {F16278} Whe
2a560 6e 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 n [sqlite3_set_a
2a570 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d uxdata(C,N,P,D)]
2a580 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 is invoked, the
2a590 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 20 destructor.**
2a5a0 20 20 20 20 20 20 20 20 69 73 20 63 61 6c 6c 65 is calle
2a5b0 64 20 66 6f 72 20 61 6e 79 20 70 72 69 6f 72 20 d for any prior
2a5c0 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 metadata associa
2a5d0 74 65 64 20 77 69 74 68 20 74 68 65 20 73 61 6d ted with the sam
2a5e0 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 e function.**
2a5f0 20 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 context C
2a600 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20 4e and parameter N
2a610 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 39 7d ..**.** {F16279}
2a620 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 63 61 6c SQLite will cal
2a630 6c 20 64 65 73 74 72 75 63 74 6f 72 73 20 66 6f l destructors fo
2a640 72 20 61 6e 79 20 6d 65 74 61 64 61 74 61 20 69 r any metadata i
2a650 74 20 69 73 20 68 6f 6c 64 69 6e 67 0a 2a 2a 20 t is holding.**
2a660 20 20 20 20 20 20 20 20 20 69 6e 20 61 20 70 61 in a pa
2a670 72 74 69 63 75 6c 61 72 20 5b 70 72 65 70 61 72 rticular [prepar
2a680 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 ed statement] S
2a690 77 68 65 6e 20 65 69 74 68 65 72 0a 2a 2a 20 20 when either.**
2a6a0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
2a6b0 5f 72 65 73 65 74 28 53 29 5d 20 6f 72 20 5b 73 _reset(S)] or [s
2a6c0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2a6d0 53 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a S)] is called..*
2a6e0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f /.void *sqlite3_
2a6f0 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 get_auxdata(sqli
2a700 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
2a710 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 t N);.void sqlit
2a720 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 e3_set_auxdata(s
2a730 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
2a740 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 int N, void*, v
2a750 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b oid (*)(void*));
2a760 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 .../*.** CAPI3RE
2a770 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 F: Constants Def
2a780 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 ining Special De
2a790 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f structor Behavio
2a7a0 72 20 7b 46 31 30 32 38 30 7d 0a 2a 2a 0a 2a 2a r {F10280}.**.**
2a7b0 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 These are speci
2a7c0 61 6c 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 al value for the
2a7d0 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 destructor that
2a7e0 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 is passed in as
2a7f0 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 the.** final ar
2a800 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e gument to routin
2a810 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 es like [sqlite3
2a820 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e _result_blob()].
2a830 20 20 49 66 20 74 68 65 20 64 65 73 74 72 75 63 If the destruc
2a840 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 tor.** argument
2a850 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 is SQLITE_STATIC
2a860 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 , it means that
2a870 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e the content poin
2a880 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a ter is constant.
2a890 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 ** and will neve
2a8a0 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f r change. It do
2a8b0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 es not need to b
2a8c0 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 54 68 e destroyed. Th
2a8d0 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 e .** SQLITE_TRA
2a8e0 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 NSIENT value mea
2a8f0 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 ns that the cont
2a900 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 ent will likely
2a910 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 change in.** the
2a920 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 near future and
2a930 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f that SQLite sho
2a940 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e uld make its own
2a950 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 private copy of
2a960 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 .** the content
2a970 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 before returning
2a980 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 ..**.** The type
2a990 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 def is necessary
2a9a0 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 to work around
2a9b0 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 problems in cert
2a9c0 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 ain.** C++ compi
2a9d0 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 lers. See ticke
2a9e0 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 t #2191..*/.type
2a9f0 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 def void (*sqlit
2aa00 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 e3_destructor_ty
2aa10 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 pe)(void*);.#def
2aa20 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 ine SQLITE_STATI
2aa30 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 C ((sqlite3
2aa40 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 _destructor_type
2aa50 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 )0).#define SQLI
2aa60 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 TE_TRANSIENT (
2aa70 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 (sqlite3_destruc
2aa80 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a tor_type)-1)../*
2aa90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 .** CAPI3REF: Se
2aaa0 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 tting The Result
2aab0 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 Of An SQL Funct
2aac0 69 6f 6e 20 7b 46 31 36 34 30 30 7d 0a 2a 2a 0a ion {F16400}.**.
2aad0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
2aae0 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68 s are used by th
2aaf0 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 e xFunc or xFina
2ab00 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 l callbacks that
2ab10 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 .** implement SQ
2ab20 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 L functions and
2ab30 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 aggregates. See
2ab40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 .** [sqlite3_cre
2ab50 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 ate_function()]
2ab60 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 and [sqlite3_cre
2ab70 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 ate_function16()
2ab80 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f ].** for additio
2ab90 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e nal information.
2aba0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e .**.** These fun
2abb0 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 ctions work very
2abc0 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 0a much like the .
2abd0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
2abe0 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f _blob | sqlite3_
2abf0 62 69 6e 64 5f 2a 5d 20 66 61 6d 69 6c 79 20 6f bind_*] family o
2ac00 66 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 f functions used
2ac10 0a 2a 2a 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 .** to bind valu
2ac20 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d es to host param
2ac30 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 eters in prepare
2ac40 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a d statements..**
2ac50 20 52 65 66 65 72 20 74 6f 20 74 68 65 0a 2a 2a Refer to the.**
2ac60 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
2ac70 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 lob | sqlite3_bi
2ac80 6e 64 5f 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 nd_* documentati
2ac90 6f 6e 5d 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 on] for.** addit
2aca0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f ional informatio
2acb0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c n..**.** The sql
2acc0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 ite3_result_blob
2acd0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 () interface set
2ace0 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f s the result fro
2acf0 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 m.** an applicat
2ad00 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 ion defined func
2ad10 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 tion to be the B
2ad20 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e LOB whose conten
2ad30 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 t is pointed.**
2ad40 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 to by the second
2ad50 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 parameter and w
2ad60 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 hich is N bytes
2ad70 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 long where N is
2ad80 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 the.** third par
2ad90 61 6d 65 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 ameter. .** The
2ada0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a sqlite3_result_z
2adb0 65 72 6f 62 6c 6f 62 28 29 20 69 6e 65 72 66 61 eroblob() inerfa
2adc0 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 ces set the resu
2add0 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 lt of.** the app
2ade0 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 lication defined
2adf0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
2ae00 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e a BLOB containin
2ae10 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 g all zero.** by
2ae20 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 tes and N bytes
2ae30 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e in size, where N
2ae40 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 is the value of
2ae50 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
2ae60 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 er..**.** The sq
2ae70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 lite3_result_dou
2ae80 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 ble() interface
2ae90 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 sets the result
2aea0 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 from.** an appli
2aeb0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 cation defined f
2aec0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 unction to be a
2aed0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 floating point v
2aee0 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a alue specified.*
2aef0 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 * by its 2nd arg
2af00 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ument..**.** The
2af10 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
2af20 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 error() and sqli
2af30 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
2af40 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 16() functions.*
2af50 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c * cause the impl
2af60 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 emented SQL func
2af70 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e tion to throw an
2af80 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53 exception..** S
2af90 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 QLite uses the s
2afa0 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f tring pointed to
2afb0 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 by the.** 2nd p
2afc0 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 arameter of sqli
2afd0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
2afe0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 () or sqlite3_re
2aff0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a sult_error16().*
2b000 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 * as the text of
2b010 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 an error messag
2b020 65 2e 20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 e. SQLite inter
2b030 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a prets the error.
2b040 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e ** message strin
2b050 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 g from sqlite3_r
2b060 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 esult_error() as
2b070 20 55 54 46 38 2e 20 53 51 4c 69 74 65 0a 2a 2a UTF8. SQLite.**
2b080 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 interprets the
2b090 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 string from sqli
2b0a0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
2b0b0 31 36 28 29 20 61 73 20 55 54 46 31 36 20 69 6e 16() as UTF16 in
2b0c0 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 native.** byte
2b0d0 6f 72 64 65 72 2e 20 20 49 66 20 74 68 65 20 74 order. If the t
2b0e0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 hird parameter t
2b0f0 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 o sqlite3_result
2b100 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 _error().** or s
2b110 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
2b120 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 ror16() is negat
2b130 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 ive then SQLite
2b140 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 takes as the err
2b150 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c or.** message al
2b160 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 l text up throug
2b170 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f h the first zero
2b180 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 character..** I
2b190 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 f the third para
2b1a0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
2b1b0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 _result_error()
2b1c0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 or.** sqlite3_re
2b1d0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 sult_error16() i
2b1e0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 s non-negative t
2b1f0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 hen SQLite takes
2b200 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 that many.** by
2b210 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 tes (not charact
2b220 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e ers) from the 2n
2b230 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 d parameter as t
2b240 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 he error message
2b250 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 ..** The sqlite3
2b260 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 _result_error()
2b270 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 and sqlite3_resu
2b280 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 lt_error16().**
2b290 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 routines make a
2b2a0 63 6f 70 79 20 70 72 69 76 61 74 65 20 63 6f 70 copy private cop
2b2b0 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d y of the error m
2b2c0 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f essage text befo
2b2d0 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 re.** they retur
2b2e0 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 n. Hence, the c
2b2f0 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 alling function
2b300 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f can deallocate o
2b310 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 r.** modify the
2b320 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 text after they
2b330 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 return without h
2b340 61 72 6d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 arm..** The sqli
2b350 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
2b360 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e _code() function
2b370 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 changes the err
2b380 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 or code.** retur
2b390 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 ned by SQLite as
2b3a0 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 a result of an
2b3b0 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 error in a funct
2b3c0 69 6f 6e 2e 20 20 42 79 20 64 65 66 61 75 6c 74 ion. By default
2b3d0 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 ,.** the error c
2b3e0 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 ode is SQLITE_ER
2b3f0 52 4f 52 2e 20 20 41 20 73 75 62 73 65 71 75 65 ROR. A subseque
2b400 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 nt call to sqlit
2b410 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
2b420 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f ).** or sqlite3_
2b430 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 result_error16()
2b440 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f resets the erro
2b450 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 r code to SQLITE
2b460 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 _ERROR..**.** Th
2b470 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
2b480 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 _toobig() interf
2b490 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 ace causes SQLit
2b4a0 65 0a 2a 2a 20 74 6f 20 74 68 72 6f 77 20 61 6e e.** to throw an
2b4b0 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e error indicatin
2b4c0 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 g that a string
2b4d0 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f or BLOB is to lo
2b4e0 6e 67 0a 2a 2a 20 74 6f 20 72 65 70 72 65 73 65 ng.** to represe
2b4f0 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 nt. The sqlite3
2b500 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 _result_nomem()
2b510 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 63 61 75 interface.** cau
2b520 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 ses SQLite to th
2b530 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e row an exception
2b540 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 indicating that
2b550 20 74 68 65 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 the a.** memory
2b560 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c allocation fail
2b570 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ed..**.** The sq
2b580 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 lite3_result_int
2b590 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 () interface set
2b5a0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c s the return val
2b5b0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 ue.** of the app
2b5c0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
2b5d0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
2b5e0 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 the 32-bit signe
2b5f0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c d integer.** val
2b600 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 ue given in the
2b610 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 2nd argument..**
2b620 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 The sqlite3_res
2b630 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 ult_int64() inte
2b640 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 rface sets the r
2b650 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f eturn value.** o
2b660 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
2b670 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
2b680 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d on to be the 64-
2b690 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 bit signed integ
2b6a0 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 er.** value give
2b6b0 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 n in the 2nd arg
2b6c0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ument..**.** The
2b6d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
2b6e0 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 null() interface
2b6f0 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e sets the return
2b700 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 value.** of the
2b710 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
2b720 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f ined function to
2b730 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 be NULL..**.**
2b740 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
2b750 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 lt_text(), sqlit
2b760 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
2b770 28 29 2c 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f (), .** sqlite3_
2b780 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 result_text16le(
2b790 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 ), and sqlite3_r
2b7a0 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 esult_text16be()
2b7b0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 interfaces.** s
2b7c0 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 et the return va
2b7d0 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 lue of the appli
2b7e0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
2b7f0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a unction to be.**
2b800 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 a text string w
2b810 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e hich is represen
2b820 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 ted as UTF-8, UT
2b830 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 F-16 native byte
2b840 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 order,.** UTF-1
2b850 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 6 little endian,
2b860 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 or UTF-16 big e
2b870 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 ndian, respectiv
2b880 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 74 ely..** SQLite t
2b890 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65 akes the text re
2b8a0 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 sult from the ap
2b8b0 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a plication from.*
2b8c0 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 * the 2nd parame
2b8d0 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 ter of the sqlit
2b8e0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 e3_result_text*
2b8f0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 49 interfaces..** I
2b900 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 f the 3rd parame
2b910 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ter to the sqlit
2b920 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 e3_result_text*
2b930 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 interfaces.** is
2b940 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 negative, then
2b950 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 SQLite takes res
2b960 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 ult text from th
2b970 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 e 2nd parameter
2b980 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 .** through the
2b990 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 first zero chara
2b9a0 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 cter..** If the
2b9b0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 3rd parameter to
2b9c0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 the sqlite3_res
2b9d0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 ult_text* interf
2b9e0 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e aces.** is non-n
2b9f0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 egative, then as
2ba00 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 many bytes (not
2ba10 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 characters) of
2ba20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e the text.** poin
2ba30 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e ted to by the 2n
2ba40 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 d parameter are
2ba50 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 taken as the app
2ba60 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
2ba70 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 .** function res
2ba80 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 ult..** If the 4
2ba90 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
2baa0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 the sqlite3_resu
2bab0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 lt_text* interfa
2bac0 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 ces.** or sqlite
2bad0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 3_result_blob is
2bae0 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e a non-NULL poin
2baf0 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 ter, then SQLite
2bb00 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 calls that.** f
2bb10 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 unction as the d
2bb20 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 estructor on the
2bb30 20 74 65 78 74 20 6f 72 20 62 6c 6f 62 20 72 65 text or blob re
2bb40 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 sult when it has
2bb50 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 .** finished usi
2bb60 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a ng that result..
2bb70 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61 ** If the 4th pa
2bb80 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 rameter to the s
2bb90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
2bba0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a xt* interfaces.*
2bbb0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 * or sqlite3_res
2bbc0 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 ult_blob is the
2bbd0 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 special constant
2bbe0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 SQLITE_STATIC,
2bbf0 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 then.** SQLite a
2bc00 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 ssumes that the
2bc10 74 65 78 74 20 6f 72 20 62 6c 6f 62 20 72 65 73 text or blob res
2bc20 75 6c 74 20 69 73 20 63 6f 6e 73 74 61 6e 74 20 ult is constant
2bc30 73 70 61 63 65 20 61 6e 64 0a 2a 2a 20 64 6f 65 space and.** doe
2bc40 73 20 6e 6f 74 20 63 6f 70 79 20 74 68 65 20 73 s not copy the s
2bc50 70 61 63 65 20 6f 72 20 63 61 6c 6c 20 61 20 64 pace or call a d
2bc60 65 73 74 72 75 63 74 6f 72 20 77 68 65 6e 20 69 estructor when i
2bc70 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 t has.** finishe
2bc80 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 d using that res
2bc90 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 ult..** If the 4
2bca0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
2bcb0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 the sqlite3_resu
2bcc0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 lt_text* interfa
2bcd0 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 ces.** or sqlite
2bce0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 3_result_blob is
2bcf0 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e the special con
2bd00 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 stant SQLITE_TRA
2bd10 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 NSIENT.** then S
2bd20 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f QLite makes a co
2bd30 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 py of the result
2bd40 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 into space obta
2bd50 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f ined from.** fro
2bd60 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f m [sqlite3_mallo
2bd70 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 c()] before it r
2bd80 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 eturns..**.** Th
2bd90 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
2bda0 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 _value() interfa
2bdb0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 ce sets the resu
2bdc0 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 lt of.** the app
2bdd0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
2bde0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
2bdf0 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 a copy the.** [u
2be00 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
2be10 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
2be20 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 specified by th
2be30 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e e 2nd parameter.
2be40 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 The.** sqlite3
2be50 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 _result_value()
2be60 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 interface makes
2be70 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 a copy of the [s
2be80 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a qlite3_value].**
2be90 20 73 6f 20 74 68 61 74 20 5b 73 71 6c 69 74 65 so that [sqlite
2bea0 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 3_value] specifi
2beb0 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 ed in the parame
2bec0 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f ter may change o
2bed0 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 r.** be dealloca
2bee0 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 ted after sqlite
2bef0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 3_result_value()
2bf00 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 returns without
2bf10 20 68 61 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72 6f harm..** A [pro
2bf20 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
2bf30 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 alue] object may
2bf40 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 always be used
2bf50 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 where an.** [unp
2bf60 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
2bf70 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 _value] object i
2bf80 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 s required, so e
2bf90 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 ither.** kind of
2bfa0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d [sqlite3_value]
2bfb0 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 object can be u
2bfc0 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e sed with this in
2bfd0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 terface..**.** I
2bfe0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
2bff0 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d are called from
2c000 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 within the diff
2c010 65 72 65 6e 74 20 74 68 72 65 61 64 20 0a 2a 2a erent thread .**
2c020 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f than the one co
2c030 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 ntaining the app
2c040 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
2c050 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 function that r
2c060 65 63 69 65 76 65 64 0a 2a 2a 20 74 68 65 20 5b ecieved.** the [
2c070 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d sqlite3_context]
2c080 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 pointer, the re
2c090 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 sults are undefi
2c0a0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 ned..**.** INVAR
2c0b0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 IANTS:.**.** {F1
2c0c0 36 34 30 33 7d 20 54 68 65 20 64 65 66 61 75 6c 6403} The defaul
2c0d0 74 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 t return value f
2c0e0 72 6f 6d 20 61 6e 79 20 53 51 4c 20 66 75 6e 63 rom any SQL func
2c0f0 74 69 6f 6e 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a tion is NULL..**
2c100 0a 2a 2a 20 7b 46 31 36 34 30 36 7d 20 54 68 65 .** {F16406} The
2c110 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
2c120 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 20 _blob(C,V,N,D)]
2c130 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 interface change
2c140 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 s the.**
2c150 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f return value o
2c160 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 f function C to
2c170 62 65 20 61 20 62 6c 6f 62 20 74 68 61 74 20 69 be a blob that i
2c180 73 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 s N bytes.**
2c190 20 20 20 20 20 20 69 6e 20 6c 65 6e 67 74 68 20 in length
2c1a0 61 6e 64 20 77 69 74 68 20 63 6f 6e 74 65 6e 74 and with content
2c1b0 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 56 pointed to by V
2c1c0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 39 7d ..**.** {F16409}
2c1d0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 The [sqlite3_re
2c1e0 73 75 6c 74 5f 64 6f 75 62 6c 65 28 43 2c 56 29 sult_double(C,V)
2c1f0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e ] interface chan
2c200 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 ges the.**
2c210 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 return value
2c220 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 of function C t
2c230 6f 20 62 65 20 74 68 65 20 66 6c 6f 61 74 69 6e o be the floatin
2c240 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 56 2e g point value V.
2c250 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 31 32 7d 20 .**.** {F16412}
2c260 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 The [sqlite3_res
2c270 75 6c 74 5f 65 72 72 6f 72 28 43 2c 56 2c 4e 29 ult_error(C,V,N)
2c280 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e ] interface chan
2c290 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a ges the return.*
2c2a0 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 * value
2c2b0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 of function C t
2c2c0 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f o be an exceptio
2c2d0 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 n with error cod
2c2e0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 e.** [S
2c2f0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 QLITE_ERROR] and
2c300 20 61 20 55 54 46 38 20 65 72 72 6f 72 20 6d 65 a UTF8 error me
2c310 73 73 61 67 65 20 63 6f 70 69 65 64 20 66 72 6f ssage copied fro
2c320 6d 20 56 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a m V up to the.**
2c330 20 20 20 20 20 20 20 20 20 20 66 69 72 73 74 20 first
2c340 7a 65 72 6f 20 62 79 74 65 20 6f 72 20 75 6e 74 zero byte or unt
2c350 69 6c 20 4e 20 62 79 74 65 73 20 61 72 65 20 72 il N bytes are r
2c360 65 61 64 20 69 66 20 4e 20 69 73 20 70 6f 73 69 ead if N is posi
2c370 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 tive..**.** {F16
2c380 34 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 415} The [sqlite
2c390 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
2c3a0 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61 (C,V,N)] interfa
2c3b0 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 ce changes the r
2c3c0 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 eturn.**
2c3d0 20 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 value of funct
2c3e0 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 ion C to be an e
2c3f0 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 xception with er
2c400 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 ror code.**
2c410 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 [SQLITE_ERR
2c420 4f 52 5d 20 61 6e 64 20 61 20 55 54 46 31 36 20 OR] and a UTF16
2c430 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
2c440 72 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a r error message.
2c450 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 70 69 ** copi
2c460 65 64 20 66 72 6f 6d 20 56 20 75 70 20 74 6f 20 ed from V up to
2c470 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 the first zero t
2c480 65 72 6d 69 6e 61 74 6f 72 20 6f 72 20 75 6e 74 erminator or unt
2c490 69 6c 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 il N bytes.**
2c4a0 20 20 20 20 20 20 20 61 72 65 20 72 65 61 64 20 are read
2c4b0 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 if N is positive
2c4c0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 31 38 7d ..**.** {F16418}
2c4d0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 The [sqlite3_re
2c4e0 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 sult_error_toobi
2c4f0 67 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 g(C)] interface
2c500 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 changes the retu
2c510 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 rn.** v
2c520 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 alue of the func
2c530 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 tion C to be an
2c540 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 exception with e
2c550 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 rror code.**
2c560 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 4f [SQLITE_TO
2c570 4f 42 49 47 5d 20 61 6e 64 20 61 6e 20 61 70 70 OBIG] and an app
2c580 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d ropriate error m
2c590 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 essage..**.** {F
2c5a0 31 36 34 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 16421} The [sqli
2c5b0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
2c5c0 5f 6e 6f 6d 65 6d 28 43 29 5d 20 69 6e 74 65 72 _nomem(C)] inter
2c5d0 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 face changes the
2c5e0 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 return.**
2c5f0 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 value of the
2c600 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 function C to b
2c610 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 e an exception w
2c620 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a ith error code.*
2c630 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 * [SQLI
2c640 54 45 5f 4e 4f 4d 45 4d 5d 20 61 6e 64 20 61 6e TE_NOMEM] and an
2c650 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 appropriate err
2c660 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a or message..**.*
2c670 2a 20 7b 46 31 36 34 32 34 7d 20 54 68 65 20 5b * {F16424} The [
2c680 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
2c690 72 72 6f 72 5f 63 6f 64 65 28 43 2c 45 29 5d 20 rror_code(C,E)]
2c6a0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 interface change
2c6b0 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 s the return.**
2c6c0 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f value o
2c6d0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 f the function C
2c6e0 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 to be an except
2c6f0 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 ion with error c
2c700 6f 64 65 20 45 2e 0a 2a 2a 20 20 20 20 20 20 20 ode E..**
2c710 20 20 20 54 68 65 20 65 72 72 6f 72 20 6d 65 73 The error mes
2c720 73 61 67 65 20 74 65 78 74 20 69 73 20 75 6e 63 sage text is unc
2c730 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 hanged..**.** {F
2c740 31 36 34 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 16427} The [sqli
2c750 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 43 te3_result_int(C
2c760 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 ,V)] interface c
2c770 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 hanges the.**
2c780 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 return va
2c790 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 lue of function
2c7a0 43 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 C to be the 32-b
2c7b0 69 74 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 it integer value
2c7c0 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 V..**.** {F1643
2c7d0 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 0} The [sqlite3_
2c7e0 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 43 2c 56 result_int64(C,V
2c7f0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 )] interface cha
2c800 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 nges the.**
2c810 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 return valu
2c820 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 e of function C
2c830 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 to be the 64-bit
2c840 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56 integer value V
2c850 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 33 7d ..**.** {F16433}
2c860 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 The [sqlite3_re
2c870 73 75 6c 74 5f 6e 75 6c 6c 28 43 29 5d 20 69 6e sult_null(C)] in
2c880 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 terface changes
2c890 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
2c8a0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
2c8b0 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 function C to be
2c8c0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 NULL..**.** {F1
2c8d0 36 34 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 6436} The [sqlit
2c8e0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 e3_result_text(C
2c8f0 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 ,V,N,D)] interfa
2c900 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a ce changes the.*
2c910 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 * retur
2c920 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 n value of funct
2c930 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 ion C to be the
2c940 55 54 46 38 20 73 74 72 69 6e 67 0a 2a 2a 20 20 UTF8 string.**
2c950 20 20 20 20 20 20 20 20 56 20 75 70 20 74 6f 20 V up to
2c960 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 the first zero i
2c970 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a f N is negative.
2c980 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 ** or t
2c990 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 he first N bytes
2c9a0 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f of V if N is no
2c9b0 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a n-negative..**.*
2c9c0 2a 20 7b 46 31 36 34 33 39 7d 20 54 68 65 20 5b * {F16439} The [
2c9d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
2c9e0 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 20 ext16(C,V,N,D)]
2c9f0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 interface change
2ca00 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 s the.**
2ca10 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f return value o
2ca20 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 f function C to
2ca30 62 65 20 74 68 65 20 55 54 46 31 36 20 6e 61 74 be the UTF16 nat
2ca40 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a ive byte order.*
2ca50 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e * strin
2ca60 67 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 g V up to the fi
2ca70 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 rst zero if N is
2ca80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 67 .** neg
2ca90 61 74 69 76 65 20 6f 72 20 74 68 65 20 66 69 72 ative or the fir
2caa0 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 st N bytes of V
2cab0 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 if N is non-nega
2cac0 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 tive..**.** {F16
2cad0 34 34 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 442} The [sqlite
2cae0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 3_result_text16b
2caf0 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 e(C,V,N,D)] inte
2cb00 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 rface changes th
2cb10 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 e.** re
2cb20 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 turn value of fu
2cb30 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 nction C to be t
2cb40 68 65 20 55 54 46 31 36 20 62 69 67 2d 65 6e 64 he UTF16 big-end
2cb50 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ian.**
2cb60 73 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 string V up to t
2cb70 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 he first zero if
2cb80 20 4e 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 N is.**
2cb90 20 20 69 73 20 6e 65 67 61 74 69 76 65 20 6f 72 is negative or
2cba0 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 the first N byt
2cbb0 65 73 20 6f 72 20 56 20 69 66 20 4e 20 69 73 20 es or V if N is
2cbc0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a non-negative..**
2cbd0 0a 2a 2a 20 7b 46 31 36 34 34 35 7d 20 54 68 65 .** {F16445} The
2cbe0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
2cbf0 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c _text16le(C,V,N,
2cc00 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 D)] interface ch
2cc10 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 anges the.**
2cc20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c return val
2cc30 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 ue of function C
2cc40 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 31 36 to be the UTF16
2cc50 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a little-endian.*
2cc60 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e * strin
2cc70 67 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 g V up to the fi
2cc80 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 rst zero if N is
2cc90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 67 .** neg
2cca0 61 74 69 76 65 20 6f 72 20 74 68 65 20 66 69 72 ative or the fir
2ccb0 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 st N bytes of V
2ccc0 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 if N is non-nega
2ccd0 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 tive..**.** {F16
2cce0 34 34 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 448} The [sqlite
2ccf0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 43 3_result_value(C
2cd00 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 ,V)] interface c
2cd10 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 hanges the.**
2cd20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 return va
2cd30 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 lue of function
2cd40 43 20 74 6f 20 62 65 20 5b 75 6e 70 72 6f 74 65 C to be [unprote
2cd50 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
2cd60 75 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ue].**
2cd70 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 object V..**.**
2cd80 7b 46 31 36 34 35 31 7d 20 54 68 65 20 5b 73 71 {F16451} The [sq
2cd90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 lite3_result_zer
2cda0 6f 62 6c 6f 62 28 43 2c 4e 29 5d 20 69 6e 74 65 oblob(C,N)] inte
2cdb0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 rface changes th
2cdc0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 e.** re
2cdd0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 turn value of fu
2cde0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 nction C to be a
2cdf0 6e 20 4e 2d 62 79 74 65 20 62 6c 6f 62 20 6f 66 n N-byte blob of
2ce00 20 61 6c 6c 20 7a 65 72 6f 73 2e 0a 2a 2a 0a 2a all zeros..**.*
2ce10 2a 20 7b 46 31 36 34 35 34 7d 20 54 68 65 20 5b * {F16454} The [
2ce20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
2ce30 72 72 6f 72 28 29 5d 20 61 6e 64 20 5b 73 71 6c rror()] and [sql
2ce40 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
2ce50 72 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 r16()].**
2ce60 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 interfaces ma
2ce70 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 ke a copy of the
2ce80 69 72 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 ir error message
2ce90 20 73 74 72 69 6e 67 73 20 62 65 66 6f 72 65 0a strings before.
2cea0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 ** retu
2ceb0 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 rning..**.** {F1
2cec0 36 34 35 37 7d 20 49 66 20 74 68 65 20 44 20 64 6457} If the D d
2ced0 65 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 estructor parame
2cee0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
2cef0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c result_blob(C,V,
2cf00 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 N,D)],.**
2cf10 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 [sqlite3_resu
2cf20 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 lt_text(C,V,N,D)
2cf30 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 ], [sqlite3_resu
2cf40 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c lt_text16(C,V,N,
2cf50 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 D)],.**
2cf60 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
2cf70 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c _text16be(C,V,N,
2cf80 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 D)], or.**
2cf90 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 [sqlite3_res
2cfa0 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 ult_text16le(C,V
2cfb0 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63 6f ,N,D)] is the co
2cfc0 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 nstant [SQLITE_S
2cfd0 54 41 54 49 43 5d 0a 2a 2a 20 20 20 20 20 20 20 TATIC].**
2cfe0 20 20 20 74 68 65 6e 20 6e 6f 20 64 65 73 74 72 then no destr
2cff0 75 63 74 6f 72 20 69 73 20 65 76 65 72 20 63 61 uctor is ever ca
2d000 6c 6c 65 64 20 6f 6e 20 74 68 65 20 70 6f 69 6e lled on the poin
2d010 74 65 72 20 56 20 61 6e 64 20 53 51 4c 69 74 65 ter V and SQLite
2d020 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 73 .** ass
2d030 75 6d 65 73 20 74 68 61 74 20 56 20 69 73 20 69 umes that V is i
2d040 6d 6d 75 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 mmutable..**.**
2d050 7b 46 31 36 34 36 30 7d 20 49 66 20 74 68 65 20 {F16460} If the
2d060 44 20 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 D destructor par
2d070 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 ameter to [sqlit
2d080 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 e3_result_blob(C
2d090 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 ,V,N,D)],.**
2d0a0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 [sqlite3_r
2d0b0 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e esult_text(C,V,N
2d0c0 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 ,D)], [sqlite3_r
2d0d0 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 esult_text16(C,V
2d0e0 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 ,N,D)],.**
2d0f0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 [sqlite3_res
2d100 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 ult_text16be(C,V
2d110 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 ,N,D)], or.**
2d120 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
2d130 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 result_text16le(
2d140 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65 C,V,N,D)] is the
2d150 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 20 20 20 constant.**
2d160 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 52 [SQLITE_TR
2d170 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e 20 74 68 ANSIENT] then th
2d180 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b e interfaces mak
2d190 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 es a copy of the
2d1a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e .** con
2d1b0 74 65 6e 74 20 6f 66 20 56 20 61 6e 64 20 72 65 tent of V and re
2d1c0 74 61 69 6e 73 20 74 68 65 20 63 6f 70 79 2e 0a tains the copy..
2d1d0 2a 2a 0a 2a 2a 20 7b 46 31 36 34 36 33 7d 20 49 **.** {F16463} I
2d1e0 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63 74 f the D destruct
2d1f0 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 or parameter to
2d200 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
2d210 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a blob(C,V,N,D)],.
2d220 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
2d230 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
2d240 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c (C,V,N,D)], [sql
2d250 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
2d260 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 16(C,V,N,D)],.**
2d270 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
2d280 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
2d290 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 be(C,V,N,D)], or
2d2a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
2d2b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
2d2c0 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 t16le(C,V,N,D)]
2d2d0 69 73 20 73 6f 6d 65 20 76 61 6c 75 65 20 6f 74 is some value ot
2d2e0 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 her than.**
2d2f0 20 20 20 20 20 74 68 65 20 63 6f 6e 73 74 61 6e the constan
2d300 74 73 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 ts [SQLITE_STATI
2d310 43 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 54 C] and [SQLITE_T
2d320 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e 20 0a RANSIENT] then .
2d330 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 69 ** SQLi
2d340 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 te will invoke t
2d350 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 he destructor D
2d360 77 69 74 68 20 56 20 61 73 20 69 74 73 20 6f 6e with V as its on
2d370 6c 79 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 ly argument.**
2d380 20 20 20 20 20 20 20 20 77 68 65 6e 20 69 74 20 when it
2d390 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 has finished wit
2d3a0 68 20 74 68 65 20 56 20 76 61 6c 75 65 2e 0a 2a h the V value..*
2d3b0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 /.void sqlite3_r
2d3c0 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 esult_blob(sqlit
2d3d0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
2d3e0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 st void*, int, v
2d3f0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
2d400 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
2d410 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 ult_double(sqlit
2d420 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 e3_context*, dou
2d430 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 ble);.void sqlit
2d440 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
2d450 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
2d460 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 , const char*, i
2d470 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 nt);.void sqlite
2d480 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
2d490 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
2d4a0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 *, const void*,
2d4b0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 int);.void sqlit
2d4c0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f e3_result_error_
2d4d0 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 toobig(sqlite3_c
2d4e0 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 ontext*);.void s
2d4f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
2d500 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 ror_nomem(sqlite
2d510 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 3_context*);.voi
2d520 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
2d530 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 _error_code(sqli
2d540 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
2d550 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 t);.void sqlite3
2d560 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 _result_int(sqli
2d570 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
2d580 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 t);.void sqlite3
2d590 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 _result_int64(sq
2d5a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
2d5b0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a sqlite3_int64);.
2d5c0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
2d5d0 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 ult_null(sqlite3
2d5e0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 _context*);.void
2d5f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
2d600 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e text(sqlite3_con
2d610 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 text*, const cha
2d620 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 r*, int, void(*)
2d630 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 (void*));.void s
2d640 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
2d650 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e xt16(sqlite3_con
2d660 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 text*, const voi
2d670 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 d*, int, void(*)
2d680 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 (void*));.void s
2d690 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
2d6a0 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 xt16le(sqlite3_c
2d6b0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 ontext*, const v
2d6c0 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a oid*, int,void(*
2d6d0 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 )(void*));.void
2d6e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
2d6f0 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f ext16be(sqlite3_
2d700 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
2d710 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 void*, int,void(
2d720 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 *)(void*));.void
2d730 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
2d740 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f value(sqlite3_co
2d750 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f ntext*, sqlite3_
2d760 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 value*);.void sq
2d770 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 lite3_result_zer
2d780 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f oblob(sqlite3_co
2d790 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a ntext*, int n);.
2d7a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2d7b0 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c Define New Coll
2d7c0 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 20 ating Sequences
2d7d0 7b 46 31 36 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 {F16600}.**.** T
2d7e0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 hese functions a
2d7f0 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e re used to add n
2d800 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 ew collation seq
2d810 75 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a uences to the.**
2d820 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 [sqlite3*] hand
2d830 6c 65 20 73 70 65 63 69 66 69 65 64 20 61 73 20 le specified as
2d840 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
2d850 6e 74 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e nt. .**.** The n
2d860 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63 ame of the new c
2d870 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 ollation sequenc
2d880 65 20 69 73 20 73 70 65 63 69 66 69 65 64 20 61 e is specified a
2d890 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 s a UTF-8 string
2d8a0 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f .** for sqlite3_
2d8b0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
2d8c0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 () and sqlite3_c
2d8d0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f reate_collation_
2d8e0 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 v2().** and a UT
2d8f0 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20 F-16 string for
2d900 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
2d910 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49 6e ollation16(). In
2d920 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 all cases.** th
2d930 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64 e name is passed
2d940 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 as the second f
2d950 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 unction argument
2d960 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 ..**.** The thir
2d970 64 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 d argument may b
2d980 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e e one of the con
2d990 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 stants [SQLITE_U
2d9a0 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 TF8],.** [SQLITE
2d9b0 5f 55 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53 51 _UTF16LE] or [SQ
2d9c0 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 LITE_UTF16BE], i
2d9d0 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 ndicating that t
2d9e0 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 he user-supplied
2d9f0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65 .** routine expe
2da00 63 74 73 20 74 6f 20 62 65 20 70 61 73 73 65 64 cts to be passed
2da10 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 pointers to str
2da20 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69 ings encoded usi
2da30 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 ng UTF-8,.** UTF
2da40 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 -16 little-endia
2da50 6e 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d n or UTF-16 big-
2da60 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 endian respectiv
2da70 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 ely. The.** thir
2da80 64 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 d argument might
2da90 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 also be [SQLITE
2daa0 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 _UTF16_ALIGNED]
2dab0 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 to indicate that
2dac0 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 .** the routine
2dad0 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 expects pointers
2dae0 20 74 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20 to 16-bit word
2daf0 61 6c 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a aligned strings.
2db00 2a 2a 20 6f 66 20 55 54 46 31 36 20 69 6e 20 74 ** of UTF16 in t
2db10 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f he native byte o
2db20 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 rder of the host
2db30 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a computer..**.**
2db40 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 A pointer to th
2db50 65 20 75 73 65 72 20 73 75 70 70 6c 69 65 64 20 e user supplied
2db60 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 routine must be
2db70 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 passed as the fi
2db80 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e fth.** argument.
2db90 20 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c If it is NULL,
2dba0 20 74 68 69 73 20 69 73 20 74 68 65 20 73 61 6d this is the sam
2dbb0 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68 e as deleting th
2dbc0 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 e collation.** s
2dbd0 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74 equence (so that
2dbe0 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 SQLite cannot c
2dbf0 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e all it anymore).
2dc00 0a 2a 2a 20 45 61 63 68 20 74 69 6d 65 20 74 68 .** Each time th
2dc10 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a e application.**
2dc20 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74 69 supplied functi
2dc30 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 on is invoked, i
2dc40 74 20 69 73 20 70 61 73 73 65 64 20 61 20 63 6f t is passed a co
2dc50 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 py of the void*
2dc60 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 passed as.** the
2dc70 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 fourth argument
2dc80 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 to sqlite3_crea
2dc90 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f te_collation() o
2dca0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 r.** sqlite3_cre
2dcb0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 ate_collation16(
2dcc0 29 20 61 73 20 69 74 73 20 66 69 72 73 74 20 70 ) as its first p
2dcd0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 arameter..**.**
2dce0 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 The remaining ar
2dcf0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 61 guments to the a
2dd00 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c pplication-suppl
2dd10 69 65 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 ied routine are
2dd20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 two strings,.**
2dd30 65 61 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 each represented
2dd40 20 62 79 20 61 20 28 6c 65 6e 67 74 68 2c 20 64 by a (length, d
2dd50 61 74 61 29 20 70 61 69 72 20 61 6e 64 20 65 6e ata) pair and en
2dd60 63 6f 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 coded in the enc
2dd70 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 oding.** that wa
2dd80 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 s passed as the
2dd90 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 third argument w
2dda0 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f hen the collatio
2ddb0 6e 20 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a n sequence was.*
2ddc0 2a 20 72 65 67 69 73 74 65 72 65 64 2e 20 7b 45 * registered. {E
2ddd0 4e 44 7d 20 54 68 65 20 61 70 70 6c 69 63 61 74 ND} The applicat
2dde0 69 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c ion defined coll
2ddf0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 ation routine sh
2de00 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e ould.** return n
2de10 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 egative, zero or
2de20 20 70 6f 73 69 74 69 76 65 20 69 66 0a 2a 2a 20 positive if.**
2de30 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 the first string
2de40 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 is less than, e
2de50 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 qual to, or grea
2de60 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 ter than the sec
2de70 6f 6e 64 0a 2a 2a 20 73 74 72 69 6e 67 2e 20 69 ond.** string. i
2de80 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53 .e. (STRING1 - S
2de90 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 TRING2)..**.** T
2dea0 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 he sqlite3_creat
2deb0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 e_collation_v2()
2dec0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 works like sqli
2ded0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
2dee0 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 61 70 74 tion().** excapt
2def0 20 74 68 61 74 20 69 74 20 74 61 6b 65 73 20 61 that it takes a
2df00 6e 20 65 78 74 72 61 20 61 72 67 75 6d 65 6e 74 n extra argument
2df10 20 77 68 69 63 68 20 69 73 20 61 20 64 65 73 74 which is a dest
2df20 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 ructor for.** th
2df30 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 e collation. Th
2df40 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 e destructor is
2df50 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 called when the
2df60 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 collation is.**
2df70 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 69 73 destroyed and is
2df80 20 70 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f passed a copy o
2df90 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 f the fourth par
2dfa0 61 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 ameter void* poi
2dfb0 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 nter.** of the s
2dfc0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
2dfd0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a llation_v2()..**
2dfe0 20 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 Collations are
2dff0 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e 0a 2a destroyed when.*
2e000 2a 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 * they are overr
2e010 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63 idden by later c
2e020 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c alls to the coll
2e030 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 ation creation f
2e040 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6f 72 20 77 unctions.** or w
2e050 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 hen the [sqlite3
2e060 2a 5d 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 *] database hand
2e070 6c 65 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 le is closed usi
2e080 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 ng [sqlite3_clos
2e090 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 e()]..**.** INVA
2e0a0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 RIANTS:.**.** {F
2e0b0 31 36 36 30 33 7d 20 41 20 73 75 63 63 65 73 73 16603} A success
2e0c0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a ful call to the.
2e0d0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
2e0e0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
2e0f0 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 ation_v2(B,X,E,P
2e100 2c 46 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 ,F,D)] interface
2e110 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 .** reg
2e120 69 73 74 65 72 73 20 66 75 6e 63 74 69 6f 6e 20 isters function
2e130 46 20 61 73 20 74 68 65 20 63 6f 6d 70 61 72 69 F as the compari
2e140 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 75 73 65 son function use
2e150 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 d to.**
2e160 20 69 6d 70 6c 65 6d 65 6e 74 20 63 6f 6c 6c 61 implement colla
2e170 74 69 6f 6e 20 58 20 6f 6e 20 5b 64 61 74 61 62 tion X on [datab
2e180 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
2e190 42 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 B for.**
2e1a0 20 20 64 61 74 61 62 61 73 65 73 20 68 61 76 69 databases havi
2e1b0 6e 67 20 65 6e 63 6f 64 69 6e 67 20 45 2e 0a 2a ng encoding E..*
2e1c0 2a 0a 2a 2a 20 7b 46 31 36 36 30 34 7d 20 53 51 *.** {F16604} SQ
2e1d0 4c 69 74 65 20 75 6e 64 65 72 73 74 61 6e 64 73 Lite understands
2e1e0 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 72 the X parameter
2e1f0 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 to.**
2e200 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
2e210 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 collation_v2(B,X
2e220 2c 45 2c 50 2c 46 2c 44 29 5d 20 61 73 20 61 20 ,E,P,F,D)] as a
2e230 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a zero-terminated.
2e240 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 2d ** UTF-
2e250 38 20 73 74 72 69 6e 67 20 69 6e 20 77 68 69 63 8 string in whic
2e260 68 20 63 61 73 65 20 69 73 20 69 67 6e 6f 72 65 h case is ignore
2e270 64 20 66 6f 72 20 41 53 43 49 49 20 63 68 61 72 d for ASCII char
2e280 61 63 74 65 72 73 20 61 6e 64 0a 2a 2a 20 20 20 acters and.**
2e290 20 20 20 20 20 20 20 69 73 20 73 69 67 6e 69 66 is signif
2e2a0 69 63 61 6e 74 20 66 6f 72 20 6e 6f 6e 2d 41 53 icant for non-AS
2e2b0 43 49 49 20 63 68 61 72 61 63 74 65 72 73 2e 0a CII characters..
2e2c0 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 36 7d 20 53 **.** {F16606} S
2e2d0 75 63 63 65 73 73 69 76 65 20 63 61 6c 6c 73 20 uccessive calls
2e2e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 to [sqlite3_crea
2e2f0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 te_collation_v2(
2e300 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a B,X,E,P,F,D)].**
2e310 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20 74 with t
2e320 68 65 20 73 61 6d 65 20 76 61 6c 75 65 73 20 66 he same values f
2e330 6f 72 20 42 2c 20 58 2c 20 61 6e 64 20 45 2c 20 or B, X, and E,
2e340 6f 76 65 72 72 69 64 65 20 70 72 69 6f 72 20 76 override prior v
2e350 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 alues.**
2e360 20 20 6f 66 20 50 2c 20 46 2c 20 61 6e 64 20 44 of P, F, and D
2e370 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 39 7d ..**.** {F16609}
2e380 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 The destructor
2e390 44 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72 D in [sqlite3_cr
2e3a0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 eate_collation_v
2e3b0 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2(B,X,E,P,F,D)].
2e3c0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e ** is n
2e3d0 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 69 74 20 ot NULL then it
2e3e0 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 is called with a
2e3f0 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 20 74 rgument P when t
2e400 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 he.** c
2e410 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f ollating functio
2e420 6e 20 69 73 20 64 72 6f 70 70 65 64 20 62 79 20 n is dropped by
2e430 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 SQLite..**.** {F
2e440 31 36 36 31 32 7d 20 41 20 63 6f 6c 6c 61 74 69 16612} A collati
2e450 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 ng function is d
2e460 72 6f 70 70 65 64 20 77 68 65 6e 20 69 74 20 69 ropped when it i
2e470 73 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a s overloaded..**
2e480 0a 2a 2a 20 7b 46 31 36 36 31 35 7d 20 41 20 63 .** {F16615} A c
2e490 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f ollating functio
2e4a0 6e 20 69 73 20 64 72 6f 70 70 65 64 20 77 68 65 n is dropped whe
2e4b0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
2e4c0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 onnection.**
2e4d0 20 20 20 20 20 20 69 73 20 63 6c 6f 73 65 64 20 is closed
2e4e0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 using [sqlite3_c
2e4f0 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b lose()]..**.** {
2e500 46 31 36 36 31 38 7d 20 54 68 65 20 70 6f 69 6e F16618} The poin
2e510 74 65 72 20 50 20 69 6e 20 5b 73 71 6c 69 74 65 ter P in [sqlite
2e520 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
2e530 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c on_v2(B,X,E,P,F,
2e540 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 D)].**
2e550 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 is passed throug
2e560 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70 h as the first p
2e570 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
2e580 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 comparison.**
2e590 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 function
2e5a0 46 20 66 6f 72 20 61 6c 6c 20 73 75 62 73 65 71 F for all subseq
2e5b0 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 uent invocations
2e5c0 20 6f 66 20 46 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 of F..**.** {F1
2e5d0 36 36 32 31 7d 20 41 20 63 61 6c 6c 20 74 6f 20 6621} A call to
2e5e0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
2e5f0 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c collation(B,X,E,
2e600 50 2c 46 29 5d 20 69 73 20 65 78 61 63 74 6c 79 P,F)] is exactly
2e610 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
2e620 20 73 61 6d 65 20 61 73 20 61 20 63 61 6c 6c 20 same as a call
2e630 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 to [sqlite3_crea
2e640 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 te_collation_v2(
2e650 29 5d 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 )] with.**
2e660 20 20 20 20 74 68 65 20 73 61 6d 65 20 70 61 72 the same par
2e670 61 6d 65 74 65 72 73 20 61 6e 64 20 61 20 4e 55 ameters and a NU
2e680 4c 4c 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a LL destructor..*
2e690 2a 0a 2a 2a 20 7b 46 31 36 36 32 34 7d 20 46 6f *.** {F16624} Fo
2e6a0 6c 6c 6f 77 69 6e 67 20 61 20 5b 73 71 6c 69 74 llowing a [sqlit
2e6b0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
2e6c0 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 ion_v2(B,X,E,P,F
2e6d0 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 ,D)],.**
2e6e0 20 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 SQLite uses th
2e6f0 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e e comparison fun
2e700 63 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c 20 ction F for all
2e710 74 65 78 74 20 63 6f 6d 70 61 72 69 73 6f 6e 0a text comparison.
2e720 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 70 65 72 ** oper
2e730 61 74 69 6f 6e 73 20 6f 6e 20 5b 64 61 74 61 62 ations on [datab
2e740 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
2e750 42 20 6f 6e 20 74 65 78 74 20 76 61 6c 75 65 73 B on text values
2e760 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 that.**
2e770 20 20 75 73 65 20 74 68 65 20 63 6f 6c 6c 61 74 use the collat
2e780 69 6e 67 20 73 65 71 75 65 6e 63 65 20 6e 61 6d ing sequence nam
2e790 65 20 58 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 e X..**.** {F166
2e7a0 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 27} The [sqlite3
2e7b0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
2e7c0 6e 31 36 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 n16(B,X,E,P,F)]
2e7d0 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 0a 2a works the same.*
2e7e0 2a 20 20 20 20 20 20 20 20 20 20 61 73 20 5b 73 * as [s
2e7f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
2e800 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c llation(B,X,E,P,
2e810 46 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 F)] except that
2e820 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
2e830 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 58 collation name X
2e840 20 69 73 20 75 6e 64 65 72 73 74 6f 6f 64 20 61 is understood a
2e850 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 s UTF-16 in nati
2e860 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a ve byte order.**
2e870 20 20 20 20 20 20 20 20 20 20 69 6e 73 74 65 61 instea
2e880 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a d of UTF-8..**.*
2e890 2a 20 7b 46 31 36 36 33 30 7d 20 57 68 65 6e 20 * {F16630} When
2e8a0 6d 75 6c 74 69 70 6c 65 20 63 6f 6d 70 61 72 69 multiple compari
2e8b0 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 son functions ar
2e8c0 65 20 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 e available for
2e8d0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 the same.**
2e8e0 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73 collating s
2e8f0 65 71 75 65 6e 63 65 2c 20 53 51 4c 69 74 65 20 equence, SQLite
2e900 63 68 6f 6f 73 65 73 20 74 68 65 20 6f 6e 65 20 chooses the one
2e910 77 68 6f 73 65 20 74 65 78 74 20 65 6e 63 6f 64 whose text encod
2e920 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ing.**
2e930 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 requires the lea
2e940 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e st amount of con
2e950 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 74 68 65 version from the
2e960 20 64 65 66 61 75 6c 74 0a 2a 2a 20 20 20 20 20 default.**
2e970 20 20 20 20 20 74 65 78 74 20 65 6e 63 6f 64 69 text encodi
2e980 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 ng of the databa
2e990 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 se..*/.int sqlit
2e9a0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
2e9b0 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c ion(. sqlite3*,
2e9c0 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a . const char *
2e9d0 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 zName, . int eT
2e9e0 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a extRep, . void*
2e9f0 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 ,. int(*xCompar
2ea00 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e e)(void*,int,con
2ea10 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e st void*,int,con
2ea20 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 st void*).);.int
2ea30 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
2ea40 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 collation_v2(.
2ea50 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e sqlite3*, . con
2ea60 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
2ea70 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c . int eTextRep,
2ea80 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 . void*,. int
2ea90 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 (*xCompare)(void
2eaa0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 *,int,const void
2eab0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 *,int,const void
2eac0 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 *),. void(*xDes
2ead0 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a troy)(void*).);.
2eae0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 int sqlite3_crea
2eaf0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a te_collation16(.
2eb00 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 sqlite3*, . c
2eb10 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
2eb20 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 , . int eTextRe
2eb30 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 p, . void*,. i
2eb40 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f nt(*xCompare)(vo
2eb50 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f id*,int,const vo
2eb60 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f id*,int,const vo
2eb70 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 id*).);../*.** C
2eb80 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 API3REF: Collati
2eb90 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 on Needed Callba
2eba0 63 6b 73 20 7b 46 31 36 37 30 30 7d 0a 2a 2a 0a cks {F16700}.**.
2ebb0 2a 2a 20 54 6f 20 61 76 6f 69 64 20 68 61 76 69 ** To avoid havi
2ebc0 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 ng to register a
2ebd0 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 ll collation seq
2ebe0 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 uences before a
2ebf0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 database.** can
2ec00 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c be used, a singl
2ec10 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
2ec20 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 ion may be regis
2ec30 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a tered with the.*
2ec40 2a 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c * database handl
2ec50 65 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 20 77 e to be called w
2ec60 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 henever an undef
2ec70 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 ined collation s
2ec80 65 71 75 65 6e 63 65 20 69 73 0a 2a 2a 20 72 65 equence is.** re
2ec90 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 quired..**.** If
2eca0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 the function is
2ecb0 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e registered usin
2ecc0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f g the sqlite3_co
2ecd0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 llation_needed()
2ece0 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 API,.** then it
2ecf0 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e is passed the n
2ed00 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 ames of undefine
2ed10 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 d collation sequ
2ed20 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 ences as strings
2ed30 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 .** encoded in U
2ed40 54 46 2d 38 2e 20 7b 46 31 36 37 30 33 7d 20 49 TF-8. {F16703} I
2ed50 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 f sqlite3_collat
2ed60 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 ion_needed16() i
2ed70 73 20 75 73 65 64 2c 20 74 68 65 20 6e 61 6d 65 s used, the name
2ed80 73 0a 2a 2a 20 61 72 65 20 70 61 73 73 65 64 20 s.** are passed
2ed90 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 as UTF-16 in mac
2eda0 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 hine native byte
2edb0 20 6f 72 64 65 72 2e 20 41 20 63 61 6c 6c 20 74 order. A call t
2edc0 6f 20 65 69 74 68 65 72 0a 2a 2a 20 66 75 6e 63 o either.** func
2edd0 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61 6e tion replaces an
2ede0 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c 62 y existing callb
2edf0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 ack..**.** When
2ee00 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 the callback is
2ee10 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 invoked, the fir
2ee20 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 st argument pass
2ee30 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 ed is a copy.**
2ee40 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 of the second ar
2ee50 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
2ee60 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 3_collation_need
2ee70 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 ed() or.** sqlit
2ee80 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 e3_collation_nee
2ee90 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 ded16(). The se
2eea0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 cond argument is
2eeb0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a the database.**
2eec0 20 68 61 6e 64 6c 65 2e 20 20 54 68 65 20 74 68 handle. The th
2eed0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ird argument is
2eee0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 one of [SQLITE_U
2eef0 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 TF8],.** [SQLITE
2ef00 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 _UTF16BE], or [S
2ef10 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 QLITE_UTF16LE],
2ef20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d indicating the m
2ef30 6f 73 74 0a 2a 2a 20 64 65 73 69 72 61 62 6c 65 ost.** desirable
2ef40 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c form of the col
2ef50 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 lation sequence
2ef60 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 function require
2ef70 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 d..** The fourth
2ef80 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
2ef90 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a e name of the.**
2efa0 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 required collat
2efb0 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a 2a ion sequence..**
2efc0 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b .** The callback
2efd0 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 function should
2efe0 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65 register the de
2eff0 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 sired collation
2f000 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 using.** [sqlite
2f010 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
2f020 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f on()], [sqlite3_
2f030 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
2f040 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 16()], or.** [sq
2f050 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
2f060 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a lation_v2()]..**
2f070 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
2f080 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30 32 7d 20 41 **.** {F16702} A
2f090 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c successful call
2f0a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c to [sqlite3_col
2f0b0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 44 2c lation_needed(D,
2f0c0 50 2c 46 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 P,F)].**
2f0d0 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 6f or [sqlite3_co
2f0e0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 llation_needed16
2f0f0 28 44 2c 50 2c 46 29 5d 20 63 61 75 73 65 73 0a (D,P,F)] causes.
2f100 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
2f110 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2f120 74 69 6f 6e 5d 20 44 20 74 6f 20 69 6e 76 6f 6b tion] D to invok
2f130 65 20 63 61 6c 6c 62 61 63 6b 20 46 20 77 69 74 e callback F wit
2f140 68 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 h first.**
2f150 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 50 20 parameter P
2f160 77 68 65 6e 65 76 65 72 20 69 74 20 6e 65 65 64 whenever it need
2f170 73 20 61 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 s a comparison f
2f180 75 6e 63 74 69 6f 6e 20 66 6f 72 20 61 0a 2a 2a unction for a.**
2f190 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 collat
2f1a0 69 6e 67 20 73 65 71 75 65 6e 63 65 20 74 68 61 ing sequence tha
2f1b0 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 6b 6e t it does not kn
2f1c0 6f 77 20 61 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a 20 ow about..**.**
2f1d0 7b 46 31 36 37 30 34 7d 20 45 61 63 68 20 73 75 {F16704} Each su
2f1e0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f ccessful call to
2f1f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 [sqlite3_collat
2f200 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 6f 72 ion_needed()] or
2f210 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
2f220 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
2f230 6e 65 65 64 65 64 31 36 28 29 5d 20 6f 76 65 72 needed16()] over
2f240 72 69 64 65 73 20 74 68 65 20 63 61 6c 6c 62 61 rides the callba
2f250 63 6b 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a ck registered.**
2f260 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65 on the
2f270 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 same [database
2f280 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 62 79 20 70 connection] by p
2f290 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 65 69 rior calls to ei
2f2a0 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 ther.**
2f2b0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a interface..**.*
2f2c0 2a 20 7b 46 31 36 37 30 36 7d 20 54 68 65 20 6e * {F16706} The n
2f2d0 61 6d 65 20 6f 66 20 74 68 65 20 72 65 71 75 65 ame of the reque
2f2e0 73 74 65 64 20 63 6f 6c 6c 61 74 69 6e 67 20 66 sted collating f
2f2f0 75 6e 63 74 69 6f 6e 20 70 61 73 73 65 64 20 69 unction passed i
2f300 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 n the.**
2f310 20 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 4th parameter
2f320 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
2f330 69 73 20 69 6e 20 55 54 46 2d 38 20 69 66 20 74 is in UTF-8 if t
2f340 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 he callback.**
2f350 20 20 20 20 20 20 20 20 77 61 73 20 72 65 67 69 was regi
2f360 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71 stered using [sq
2f370 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
2f380 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 0a 2a 2a needed()] and.**
2f390 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 20 is in
2f3a0 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 UTF-16 native by
2f3b0 74 65 20 6f 72 64 65 72 20 69 66 20 74 68 65 20 te order if the
2f3c0 63 61 6c 6c 62 61 63 6b 20 77 61 73 0a 2a 2a 20 callback was.**
2f3d0 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 registe
2f3e0 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 red using [sqlit
2f3f0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 e3_collation_nee
2f400 64 65 64 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 ded16()]..**.**
2f410 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
2f420 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 collation_needed
2f430 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 (. sqlite3*, .
2f440 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 void*, . void(
2f450 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 *)(void*,sqlite3
2f460 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 *,int eTextRep,c
2f470 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 onst char*).);.i
2f480 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 nt sqlite3_colla
2f490 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 tion_needed16(.
2f4a0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f sqlite3*, . vo
2f4b0 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 id*,. void(*)(v
2f4c0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e oid*,sqlite3*,in
2f4d0 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 t eTextRep,const
2f4e0 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a void*).);../*.*
2f4f0 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 * Specify the ke
2f500 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 y for an encrypt
2f510 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 ed database. Th
2f520 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c is routine shoul
2f530 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 d be.** called r
2f540 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 ight after sqlit
2f550 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a e3_open()..**.**
2f560 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 The code to imp
2f570 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 lement this API
2f580 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 is not available
2f590 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 in the public r
2f5a0 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c elease.** of SQL
2f5b0 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ite..*/.int sqli
2f5c0 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 te3_key(. sqlit
2f5d0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
2f5e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
2f5f0 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 abase to be reke
2f600 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 yed */. const v
2f610 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e oid *pKey, int n
2f620 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b Key /* The k
2f630 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ey */.);../*.**
2f640 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f Change the key o
2f650 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 n an open databa
2f660 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 se. If the curr
2f670 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20 ent database is
2f680 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 not.** encrypted
2f690 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 , this routine w
2f6a0 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 ill encrypt it.
2f6b0 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e If pNew==0 or n
2f6c0 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 New==0, the.** d
2f6d0 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79 atabase is decry
2f6e0 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 pted..**.** The
2f6f0 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e code to implemen
2f700 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f t this API is no
2f710 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 t available in t
2f720 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 he public releas
2f730 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a e.** of SQLite..
2f740 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 */.int sqlite3_r
2f750 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 ekey(. sqlite3
2f760 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
2f770 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
2f780 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 se to be rekeyed
2f790 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 */. const void
2f7a0 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 *pKey, int nKey
2f7b0 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 /* The new
2f7c0 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a key */.);../*.**
2f7d0 20 43 41 50 49 33 52 45 46 3a 20 20 53 75 73 70 CAPI3REF: Susp
2f7e0 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f end Execution Fo
2f7f0 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 20 7b r A Short Time {
2f800 46 31 30 35 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 F10530}.**.** Th
2f810 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 e sqlite3_sleep(
2f820 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 ) function.** ca
2f830 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 uses the current
2f840 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 thread to suspe
2f850 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 nd execution.**
2f860 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e for at least a n
2f870 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 umber of millise
2f880 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 conds specified
2f890 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 in its parameter
2f8a0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f ..**.** If the o
2f8b0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 perating system
2f8c0 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 does not support
2f8d0 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 sleep requests
2f8e0 77 69 74 68 20 0a 2a 2a 20 6d 69 6c 6c 69 73 65 with .** millise
2f8f0 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 cond time resolu
2f900 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 tion, then the t
2f910 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e ime will be roun
2f920 64 65 64 20 75 70 20 74 6f 20 0a 2a 2a 20 74 68 ded up to .** th
2f930 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 e nearest second
2f940 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 . The number of
2f950 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 milliseconds of
2f960 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 20 0a sleep actually .
2f970 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f ** requested fro
2f980 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 m the operating
2f990 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e system is return
2f9a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 ed..**.** SQLite
2f9b0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 implements this
2f9c0 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 interface by ca
2f9d0 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 lling the xSleep
2f9e0 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 ().** method of
2f9f0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c the default [sql
2fa00 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
2fa10 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
2fa20 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 33 TS:.**.** {F1053
2fa30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 3} The [sqlite3_
2fa40 73 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65 72 66 sleep(M)] interf
2fa50 61 63 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 ace invokes the
2fa60 78 53 6c 65 65 70 0a 2a 2a 20 20 20 20 20 20 20 xSleep.**
2fa70 20 20 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 method of the
2fa80 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 default [sqlite
2fa90 33 5f 76 66 73 7c 56 46 53 5d 20 69 6e 20 6f 72 3_vfs|VFS] in or
2faa0 64 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 der to.**
2fab0 20 20 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 suspend execu
2fac0 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 tion of the curr
2fad0 65 6e 74 20 74 68 72 65 61 64 20 66 6f 72 20 61 ent thread for a
2fae0 74 20 6c 65 61 73 74 0a 2a 2a 20 20 20 20 20 20 t least.**
2faf0 20 20 20 20 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e M millisecon
2fb00 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 33 ds..**.** {F1053
2fb10 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6} The [sqlite3_
2fb20 73 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65 72 66 sleep(M)] interf
2fb30 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ace returns the
2fb40 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 number of.**
2fb50 20 20 20 20 20 20 6d 69 6c 6c 69 73 65 63 6f 6e millisecon
2fb60 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 ds of sleep actu
2fb70 61 6c 6c 79 20 72 65 71 75 65 73 74 65 64 20 6f ally requested o
2fb80 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 0a f the operating.
2fb90 2a 2a 20 20 20 20 20 20 20 20 20 20 73 79 73 74 ** syst
2fba0 65 6d 2c 20 77 68 69 63 68 20 6d 69 67 68 74 20 em, which might
2fbb0 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 be larger than t
2fbc0 68 65 20 70 61 72 61 6d 65 74 65 72 20 4d 2e 0a he parameter M..
2fbd0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 */.int sqlite3_s
2fbe0 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a leep(int);../*.*
2fbf0 2a 20 43 41 50 49 33 52 45 46 3a 20 20 4e 61 6d * CAPI3REF: Nam
2fc00 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 e Of The Folder
2fc10 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 Holding Temporar
2fc20 79 20 46 69 6c 65 73 20 7b 46 31 30 33 31 30 7d y Files {F10310}
2fc30 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20 67 .**.** If this g
2fc40 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 lobal variable i
2fc50 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 s made to point
2fc60 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 to a string whic
2fc70 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 h is.** the name
2fc80 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e of a folder (a.
2fc90 6b 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 ka. directory),
2fca0 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 then all tempora
2fcb0 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 ry files.** crea
2fcc0 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 69 ted by SQLite wi
2fcd0 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 ll be placed in
2fce0 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 20 that directory.
2fcf0 20 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c If this variabl
2fd00 65 0a 2a 2a 20 69 73 20 4e 55 4c 4c 20 70 6f 69 e.** is NULL poi
2fd10 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 nter, then SQLit
2fd20 65 20 64 6f 65 73 20 61 20 73 65 61 72 63 68 20 e does a search
2fd30 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 for an appropria
2fd40 74 65 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 te temporary.**
2fd50 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a file directory..
2fd60 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 **.** It is not
2fd70 73 61 66 65 20 74 6f 20 6d 6f 64 69 66 79 20 74 safe to modify t
2fd80 68 69 73 20 76 61 72 69 61 62 6c 65 20 6f 6e 63 his variable onc
2fd90 65 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e e a database con
2fda0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 68 61 73 20 62 nection.** has b
2fdb0 65 65 6e 20 6f 70 65 6e 65 64 2e 20 20 49 74 20 een opened. It
2fdc0 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 is intended that
2fdd0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 this variable b
2fde0 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 e set once.** as
2fdf0 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 part of process
2fe00 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
2fe10 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 and before any S
2fe20 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a QLite interface.
2fe30 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 ** routines have
2fe40 20 62 65 65 6e 20 63 61 6c 6c 20 61 6e 64 20 72 been call and r
2fe50 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 emain unchanged
2fe60 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2f 0a 53 thereafter..*/.S
2fe70 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 QLITE_EXTERN cha
2fe80 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f r *sqlite3_temp_
2fe90 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a directory;../*.*
2fea0 2a 20 43 41 50 49 33 52 45 46 3a 20 20 54 65 73 * CAPI3REF: Tes
2feb0 74 20 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 t To See If The
2fec0 44 61 74 61 62 61 73 65 20 49 73 20 49 6e 20 41 Database Is In A
2fed0 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 20 uto-Commit Mode
2fee0 7b 46 31 32 39 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 {F12930}.**.** T
2fef0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 he sqlite3_get_a
2ff00 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 utocommit() inte
2ff10 72 66 61 63 65 73 20 72 65 74 75 72 6e 73 20 6e rfaces returns n
2ff20 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 on-zero or.** ze
2ff30 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 ro if the given
2ff40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2ff50 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 ion is or is not
2ff60 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d in autocommit m
2ff70 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 ode,.** respecti
2ff80 76 65 6c 79 2e 20 20 20 41 75 74 6f 63 6f 6d 6d vely. Autocomm
2ff90 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 0a 2a 2a it mode is on.**
2ffa0 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 41 75 by default. Au
2ffb0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 tocommit mode is
2ffc0 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b disabled by a [
2ffd0 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 BEGIN] statement
2ffe0 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 ..** Autocommit
2fff0 6d 6f 64 65 20 69 73 20 72 65 65 6e 61 62 6c 65 mode is reenable
30000 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 d by a [COMMIT]
30010 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a or [ROLLBACK]..*
30020 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 *.** If certain
30030 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 kinds of errors
30040 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 occur on a state
30050 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 ment within a mu
30060 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a lti-statement.**
30070 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 28 65 transactions (e
30080 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 rrors including
30090 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b [SQLITE_FULL], [
300a0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 20 0a SQLITE_IOERR], .
300b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d ** [SQLITE_NOMEM
300c0 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d ], [SQLITE_BUSY]
300d0 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e , and [SQLITE_IN
300e0 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 TERRUPT]) then t
300f0 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f he.** transactio
30100 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 n might be rolle
30110 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 d back automatic
30120 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 ally. The only
30130 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f way to.** find o
30140 75 74 20 69 66 20 53 51 4c 69 74 65 20 61 75 74 ut if SQLite aut
30150 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 omatically rolle
30160 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 d back the trans
30170 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 action after.**
30180 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 an error is to u
30190 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e se this function
301a0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
301b0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 TS:.**.** {F1293
301c0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 1} The [sqlite3_
301d0 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 44 get_autocommit(D
301e0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
301f0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 urns non-zero or
30200 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 .** zer
30210 6f 20 69 66 20 74 68 65 20 5b 64 61 74 61 62 61 o if the [databa
30220 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
30230 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e is or is not in
30240 20 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 20 autocommit.**
30250 20 20 20 20 20 20 20 20 6d 6f 64 65 2c 20 72 65 mode, re
30260 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a spectively..**.*
30270 2a 20 7b 46 31 32 39 33 32 7d 20 41 75 74 6f 63 * {F12932} Autoc
30280 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e ommit mode is on
30290 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a by default..**.
302a0 2a 2a 20 7b 46 31 32 39 33 33 7d 20 41 75 74 6f ** {F12933} Auto
302b0 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 commit mode is d
302c0 69 73 61 62 6c 65 64 20 62 79 20 61 20 73 75 63 isabled by a suc
302d0 63 65 73 73 66 75 6c 20 5b 42 45 47 49 4e 5d 20 cessful [BEGIN]
302e0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a statement..**.**
302f0 20 7b 46 31 32 39 33 34 7d 20 41 75 74 6f 63 6f {F12934} Autoco
30300 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 65 6e 61 mmit mode is ena
30310 62 6c 65 64 20 62 79 20 61 20 73 75 63 63 65 73 bled by a succes
30320 73 66 75 6c 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 sful [COMMIT] or
30330 20 5b 52 4f 4c 4c 42 41 43 4b 5d 0a 2a 2a 20 20 [ROLLBACK].**
30340 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e statemen
30350 74 2e 0a 2a 2a 20 0a 2a 2a 0a 2a 2a 20 4c 49 4d t..** .**.** LIM
30360 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 2a 0a 2a 2a ITATIONS:.***.**
30370 20 7b 55 31 32 39 33 36 7d 20 49 66 20 61 6e 6f {U12936} If ano
30380 74 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e ther thread chan
30390 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d ges the autocomm
303a0 69 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 it status of the
303b0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 20 database.**
303c0 20 20 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e connection
303d0 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 while this rout
303e0 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 ine is running,
303f0 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 then the return
30400 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 value.**
30410 20 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a is undefined..
30420 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 */.int sqlite3_g
30430 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 et_autocommit(sq
30440 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
30450 43 41 50 49 33 52 45 46 3a 20 20 46 69 6e 64 20 CAPI3REF: Find
30460 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e The Database Han
30470 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 dle Of A Prepare
30480 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 d Statement {F13
30490 31 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 120}.**.** The s
304a0 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 qlite3_db_handle
304b0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 interface.** re
304c0 74 75 72 6e 73 20 74 68 65 20 5b 73 71 6c 69 74 turns the [sqlit
304d0 65 33 2a 5d 20 64 61 74 61 62 61 73 65 20 68 61 e3*] database ha
304e0 6e 64 6c 65 20 74 6f 20 77 68 69 63 68 20 61 0a ndle to which a.
304f0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
30500 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e tement] belongs.
30510 0a 2a 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 .** The database
30520 20 68 61 6e 64 6c 65 20 72 65 74 75 72 6e 65 64 handle returned
30530 20 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 by sqlite3_db_h
30540 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 74 68 65 20 andle.** is the
30550 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 68 61 same database ha
30560 6e 64 6c 65 20 74 68 61 74 20 77 61 73 0a 2a 2a ndle that was.**
30570 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
30580 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 ent to the [sqli
30590 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
305a0 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 ] or its variant
305b0 73 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 75 73 s.** that was us
305c0 65 64 20 74 6f 20 63 72 65 61 74 65 20 74 68 65 ed to create the
305d0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 statement in th
305e0 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a e first place..*
305f0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
30600 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 32 33 7d 20 .**.** {F13123}
30610 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f The [sqlite3_db_
30620 68 61 6e 64 6c 65 28 53 29 5d 20 69 6e 74 65 72 handle(S)] inter
30630 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 face returns a p
30640 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 ointer.**
30650 20 20 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 to the [datab
30660 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
30670 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a associated with.
30680 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 ** [pre
30690 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
306a0 20 53 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a S..*/.sqlite3 *
306b0 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c sqlite3_db_handl
306c0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 e(sqlite3_stmt*)
306d0 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 ;.../*.** CAPI3R
306e0 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 EF: Commit And R
306f0 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 ollback Notifica
30700 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b tion Callbacks {
30710 46 31 32 39 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 F12950}.**.** Th
30720 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 e sqlite3_commit
30730 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 _hook() interfac
30740 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 e registers a ca
30750 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 llback.** functi
30760 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 on to be invoked
30770 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e whenever a tran
30780 73 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 saction is commi
30790 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c tted..** Any cal
307a0 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 lback set by a p
307b0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 revious call to
307c0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 sqlite3_commit_h
307d0 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 ook().** for the
307e0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 same database c
307f0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 onnection is ove
30800 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 rridden..** The
30810 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b sqlite3_rollback
30820 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 _hook() interfac
30830 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 e registers a ca
30840 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 llback.** functi
30850 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 on to be invoked
30860 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e whenever a tran
30870 73 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 saction is commi
30880 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c tted..** Any cal
30890 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 lback set by a p
308a0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 revious call to
308b0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 sqlite3_commit_h
308c0 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 ook().** for the
308d0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 same database c
308e0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 onnection is ove
308f0 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 rridden..** The
30900 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 pArg argument is
30910 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 0a passed through.
30920 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 ** to the callba
30930 63 6b 2e 20 20 49 66 20 74 68 65 20 63 61 6c 6c ck. If the call
30940 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 back on a commit
30950 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 0a hook function .
30960 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a ** returns non-z
30970 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 63 6f ero, then the co
30980 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65 mmit is converte
30990 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 d into a rollbac
309a0 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 k..**.** If anot
309b0 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 her function was
309c0 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 previously regi
309d0 73 74 65 72 65 64 2c 20 69 74 73 0a 2a 2a 20 70 stered, its.** p
309e0 41 72 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 Arg value is ret
309f0 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 urned. Otherwis
30a00 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e e NULL is return
30a10 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 ed..**.** Regist
30a20 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e ering a NULL fun
30a30 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 ction disables t
30a40 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a he callback..**.
30a50 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f ** For the purpo
30a60 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c ses of this API,
30a70 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 a transaction i
30a80 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 s said to have b
30a90 65 65 6e 20 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 een .** rolled b
30aa0 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 ack if an explic
30ab0 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 it "ROLLBACK" st
30ac0 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 atement is execu
30ad0 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 ted, or.** an er
30ae0 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e ror or constrain
30af0 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c t causes an impl
30b00 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f icit rollback to
30b10 20 6f 63 63 75 72 2e 0a 2a 2a 20 54 68 65 20 72 occur..** The r
30b20 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b ollback callback
30b30 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 is not invoked
30b40 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e if a transaction
30b50 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 is.** automatic
30b60 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b ally rolled back
30b70 20 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74 because the dat
30b80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
30b90 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 54 is closed..** T
30ba0 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c he rollback call
30bb0 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f back is not invo
30bc0 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 ked if a transac
30bd0 74 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65 tion is.** rolle
30be0 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 61 d back because a
30bf0 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b commit callback
30c00 20 72 65 74 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65 returned non-ze
30c10 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68 ro..** <todo> Ch
30c20 65 63 6b 20 6f 6e 20 74 68 69 73 20 3c 2f 74 6f eck on this </to
30c30 64 6f 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 do>.**.** These
30c40 61 72 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c are experimental
30c50 20 69 6e 74 65 72 66 61 63 65 73 20 61 6e 64 20 interfaces and
30c60 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 are subject to c
30c70 68 61 6e 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 hange..**.** INV
30c80 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
30c90 46 31 32 39 35 31 7d 20 54 68 65 20 5b 73 71 6c F12951} The [sql
30ca0 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b ite3_commit_hook
30cb0 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 (D,F,P)] interfa
30cc0 63 65 20 72 65 67 69 73 74 65 72 73 20 74 68 65 ce registers the
30cd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c .** cal
30ce0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46 lback function F
30cf0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 to be invoked w
30d00 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 ith argument P w
30d10 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 henever.**
30d20 20 20 20 20 61 20 74 72 61 6e 73 61 63 74 69 6f a transactio
30d30 6e 20 63 6f 6d 6d 69 74 73 20 6f 6e 20 5b 64 61 n commits on [da
30d40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
30d50 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 n] D..**.** {F12
30d60 39 35 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 952} The [sqlite
30d70 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 3_commit_hook(D,
30d80 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 F,P)] interface
30d90 72 65 74 75 72 6e 73 20 74 68 65 20 50 0a 2a 2a returns the P.**
30da0 20 20 20 20 20 20 20 20 20 20 61 72 67 75 6d 65 argume
30db0 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 nt from the prev
30dc0 69 6f 75 73 20 63 61 6c 6c 20 77 69 74 68 20 74 ious call with t
30dd0 68 65 20 73 61 6d 65 20 0a 2a 2a 20 20 20 20 20 he same .**
30de0 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 [database c
30df0 6f 6e 6e 65 63 74 69 6f 6e 20 5d 20 44 20 2c 20 onnection ] D ,
30e00 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66 or NULL on the f
30e10 69 72 73 74 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 irst call.**
30e20 20 20 20 20 20 20 66 6f 72 20 61 20 70 61 72 74 for a part
30e30 69 63 75 6c 61 72 20 5b 64 61 74 61 62 61 73 65 icular [database
30e40 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a connection] D..
30e50 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 33 7d 20 45 **.** {F12953} E
30e60 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ach call to [sql
30e70 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b ite3_commit_hook
30e80 28 29 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74 ()] overwrites t
30e90 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 he callback.**
30ea0 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 register
30eb0 65 64 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c ed by prior call
30ec0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 34 s..**.** {F12954
30ed0 7d 20 49 66 20 74 68 65 20 46 20 61 72 67 75 6d } If the F argum
30ee0 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ent to [sqlite3_
30ef0 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c commit_hook(D,F,
30f00 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 P)] is NULL.**
30f10 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 then the
30f20 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c commit hook cal
30f30 6c 62 61 63 6b 20 69 73 20 63 61 6e 63 65 6c 6c lback is cancell
30f40 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62 61 ed and no callba
30f50 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 ck.** i
30f60 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 s invoked when a
30f70 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d transaction com
30f80 6d 69 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 mits..**.** {F12
30f90 39 35 35 7d 20 49 66 20 74 68 65 20 63 6f 6d 6d 955} If the comm
30fa0 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 it callback retu
30fb0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 74 68 65 rns non-zero the
30fc0 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 0a n the commit is.
30fd0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 76 ** conv
30fe0 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c erted into a rol
30ff0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 lback..**.** {F1
31000 32 39 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 2961} The [sqlit
31010 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b e3_rollback_hook
31020 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 (D,F,P)] interfa
31030 63 65 20 72 65 67 69 73 74 65 72 73 20 74 68 65 ce registers the
31040 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c .** cal
31050 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46 lback function F
31060 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 to be invoked w
31070 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 ith argument P w
31080 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 henever.**
31090 20 20 20 20 61 20 74 72 61 6e 73 61 63 74 69 6f a transactio
310a0 6e 20 72 6f 6c 6c 73 20 62 61 63 6b 20 6f 6e 20 n rolls back on
310b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
310c0 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b tion] D..**.** {
310d0 46 31 32 39 36 32 7d 20 54 68 65 20 5b 73 71 6c F12962} The [sql
310e0 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f ite3_rollback_ho
310f0 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 ok(D,F,P)] inter
31100 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 face returns the
31110 20 50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 P.** a
31120 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 rgument from the
31130 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 77 previous call w
31140 69 74 68 20 74 68 65 20 73 61 6d 65 20 0a 2a 2a ith the same .**
31150 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 [datab
31160 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 5d ase connection ]
31170 20 44 20 2c 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20 D , or NULL on
31180 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 0a 2a the first call.*
31190 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 61 * for a
311a0 20 70 61 72 74 69 63 75 6c 61 72 20 5b 64 61 74 particular [dat
311b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
311c0 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 ] D..**.** {F129
311d0 36 33 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 63} Each call to
311e0 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 [sqlite3_rollba
311f0 63 6b 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77 ck_hook()] overw
31200 72 69 74 65 73 20 74 68 65 20 63 61 6c 6c 62 61 rites the callba
31210 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 ck.** r
31220 65 67 69 73 74 65 72 65 64 20 62 79 20 70 72 69 egistered by pri
31230 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 or calls..**.**
31240 7b 46 31 32 39 36 34 7d 20 49 66 20 74 68 65 20 {F12964} If the
31250 46 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 F argument to [s
31260 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f qlite3_rollback_
31270 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20 hook(D,F,P)] is
31280 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 NULL.**
31290 20 74 68 65 6e 20 74 68 65 20 72 6f 6c 6c 62 61 then the rollba
312a0 63 6b 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b ck hook callback
312b0 20 69 73 20 63 61 6e 63 65 6c 6c 65 64 20 61 6e is cancelled an
312c0 64 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a d no callback.**
312d0 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 76 is inv
312e0 6f 6b 65 64 20 77 68 65 6e 20 61 20 74 72 61 6e oked when a tran
312f0 73 61 63 74 69 6f 6e 20 72 6f 6c 6c 73 20 62 61 saction rolls ba
31300 63 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c ck..*/.void *sql
31310 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b ite3_commit_hook
31320 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a (sqlite3*, int(*
31330 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 )(void*), void*)
31340 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f ;.void *sqlite3_
31350 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 rollback_hook(sq
31360 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 lite3*, void(*)(
31370 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b void *), void*);
31380 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
31390 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f : Data Change No
313a0 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 tification Callb
313b0 61 63 6b 73 20 7b 46 31 32 39 37 30 7d 0a 2a 2a acks {F12970}.**
313c0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
313d0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e update_hook() in
313e0 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 67 69 73 terface.** regis
313f0 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 ters a callback
31400 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 function with th
31410 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
31420 63 74 69 6f 6e 20 69 64 65 6e 74 69 66 69 65 64 ction identified
31430 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 72 73 by the .** firs
31440 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 62 65 t argument to be
31450 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 invoked wheneve
31460 72 20 61 20 72 6f 77 20 69 73 20 75 70 64 61 74 r a row is updat
31470 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 ed, inserted or
31480 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 deleted..** Any
31490 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 callback set by
314a0 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 a previous call
314b0 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e to this function
314c0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 0a 2a for the same .*
314d0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
314e0 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 ction is overrid
314f0 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 den..**.** The s
31500 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 econd argument i
31510 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 s a pointer to t
31520 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 he function to i
31530 6e 76 6f 6b 65 20 77 68 65 6e 20 61 20 0a 2a 2a nvoke when a .**
31540 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c row is updated,
31550 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c inserted or del
31560 65 74 65 64 2e 20 0a 2a 2a 20 54 68 65 20 66 69 eted. .** The fi
31570 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
31580 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a the callback is.
31590 2a 2a 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 ** a copy of the
315a0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 third argument
315b0 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 to sqlite3_updat
315c0 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65 e_hook()..** The
315d0 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b second callback
315e0 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 .** argument is
315f0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f one of [SQLITE_
31600 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 INSERT], [SQLITE
31610 5f 44 45 4c 45 54 45 5d 20 6f 72 20 5b 53 51 4c _DELETE] or [SQL
31620 49 54 45 5f 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 ITE_UPDATE],.**
31630 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 depending on the
31640 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 operation that
31650 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 caused the callb
31660 61 63 6b 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 ack to be invoke
31670 64 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 d..** The third
31680 61 6e 64 20 0a 2a 2a 20 66 6f 75 72 74 68 20 61 and .** fourth a
31690 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 rguments to the
316a0 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e callback contain
316b0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 pointers to the
316c0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 0a 2a database and .*
316d0 2a 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e * table name con
316e0 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 taining the affe
316f0 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 54 68 65 cted row..** The
31700 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 final callback
31710 70 61 72 61 6d 65 74 65 72 20 69 73 20 0a 2a 2a parameter is .**
31720 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 the rowid of th
31730 65 20 72 6f 77 2e 0a 2a 2a 20 49 6e 20 74 68 65 e row..** In the
31740 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61 case of an upda
31750 74 65 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 te, this is the
31760 72 6f 77 69 64 20 61 66 74 65 72 20 0a 2a 2a 20 rowid after .**
31770 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65 73 the update takes
31780 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 place..**.** Th
31790 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 e update hook is
317a0 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 not invoked whe
317b0 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 n internal syste
317c0 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 m tables are.**
317d0 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 modified (i.e. s
317e0 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 qlite_master and
317f0 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 sqlite_sequence
31800 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 )..**.** If anot
31810 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 her function was
31820 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 previously regi
31830 73 74 65 72 65 64 2c 20 69 74 73 20 70 41 72 67 stered, its pArg
31840 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 72 65 74 value.** is ret
31850 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 urned. Otherwis
31860 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e e NULL is return
31870 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 ed..**.** INVARI
31880 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 ANTS:.**.** {F12
31890 39 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 971} The [sqlite
318a0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 3_update_hook(D,
318b0 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 F,P)] interface
318c0 63 61 75 73 65 73 20 63 61 6c 6c 62 61 63 6b 0a causes callback.
318d0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 ** func
318e0 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e 76 tion F to be inv
318f0 6f 6b 65 64 20 77 69 74 68 20 66 69 72 73 74 20 oked with first
31900 70 61 72 61 6d 65 74 65 72 20 50 20 77 68 65 6e parameter P when
31910 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 ever.**
31920 20 61 20 74 61 62 6c 65 20 72 6f 77 20 69 73 20 a table row is
31930 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74 modified, insert
31940 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 6f ed, or deleted o
31950 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 n.** [d
31960 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
31970 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 on] D..**.** {F1
31980 32 39 37 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 2973} The [sqlit
31990 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 e3_update_hook(D
319a0 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 ,F,P)] interface
319b0 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c returns the val
319c0 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f ue.** o
319d0 66 20 50 20 66 6f 72 20 74 68 65 20 70 72 65 76 f P for the prev
319e0 69 6f 75 73 20 63 61 6c 6c 20 6f 6e 20 74 68 65 ious call on the
319f0 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 same [database
31a00 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 0a 2a connection] D,.*
31a10 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 * or NU
31a20 4c 4c 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 LL for the first
31a30 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 call..**.** {F1
31a40 32 39 37 35 7d 20 49 66 20 74 68 65 20 75 70 64 2975} If the upd
31a50 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 ate hook callbac
31a60 6b 20 46 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f k F in [sqlite3_
31a70 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c update_hook(D,F,
31a80 50 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 P)].**
31a90 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 is NULL then the
31aa0 20 6e 6f 20 75 70 64 61 74 65 20 63 61 6c 6c 62 no update callb
31ab0 61 63 6b 73 20 61 72 65 20 6d 61 64 65 2e 0a 2a acks are made..*
31ac0 2a 0a 2a 2a 20 7b 46 31 32 39 37 37 7d 20 45 61 *.** {F12977} Ea
31ad0 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 ch call to [sqli
31ae0 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 te3_update_hook(
31af0 44 2c 46 2c 50 29 5d 20 6f 76 65 72 72 69 64 65 D,F,P)] override
31b00 73 20 70 72 69 6f 72 20 63 61 6c 6c 73 0a 2a 2a s prior calls.**
31b10 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 to the
31b20 20 73 61 6d 65 20 69 6e 74 65 72 66 61 63 65 20 same interface
31b30 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 on the same [dat
31b40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
31b50 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 ] D..**.** {F129
31b60 37 39 7d 20 54 68 65 20 75 70 64 61 74 65 20 68 79} The update h
31b70 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ook callback is
31b80 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e not invoked when
31b90 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d internal system
31ba0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 61 62 .** tab
31bb0 6c 65 73 20 73 75 63 68 20 61 73 20 73 71 6c 69 les such as sqli
31bc0 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 te_master and sq
31bd0 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 20 61 72 lite_sequence ar
31be0 65 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a e modified..**.*
31bf0 2a 20 7b 46 31 32 39 38 31 7d 20 54 68 65 20 73 * {F12981} The s
31c00 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
31c10 74 6f 20 74 68 65 20 75 70 64 61 74 65 20 63 61 to the update ca
31c20 6c 6c 62 61 63 6b 20 0a 2a 2a 20 20 20 20 20 20 llback .**
31c30 20 20 20 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 is one of [S
31c40 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b QLITE_INSERT], [
31c50 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 6f SQLITE_DELETE] o
31c60 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 r [SQLITE_UPDATE
31c70 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 ],.** d
31c80 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 epending on the
31c90 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 operation that c
31ca0 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 aused the callba
31cb0 63 6b 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 ck to be invoked
31cc0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 38 33 7d ..**.** {F12983}
31cd0 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 The third and f
31ce0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 ourth arguments
31cf0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
31d00 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 contain pointers
31d10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 .** to
31d20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
31d30 55 54 46 2d 38 20 73 74 72 69 6e 67 73 20 77 68 UTF-8 strings wh
31d40 69 63 68 20 61 72 65 20 74 68 65 20 6e 61 6d 65 ich are the name
31d50 73 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 s of the.**
31d60 20 20 20 20 20 64 61 74 61 62 61 73 65 20 61 6e database an
31d70 64 20 74 61 62 6c 65 20 74 68 61 74 20 69 73 20 d table that is
31d80 62 65 69 6e 67 20 75 70 64 61 74 65 64 2e 0a 0a being updated...
31d90 2a 2a 20 7b 46 31 32 39 38 35 7d 20 54 68 65 20 ** {F12985} The
31da0 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 final callback p
31db0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 arameter is the
31dc0 72 6f 77 69 64 20 6f 66 20 74 68 65 20 72 6f 77 rowid of the row
31dd0 20 61 66 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 after.**
31de0 20 20 20 74 68 65 20 63 68 61 6e 67 65 20 6f 63 the change oc
31df0 63 75 72 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 curs..*/.void *s
31e00 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f qlite3_update_ho
31e10 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 ok(. sqlite3*,
31e20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 . void(*)(void
31e30 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 *,int ,char cons
31e40 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a t *,char const *
31e50 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c ,sqlite3_int64),
31e60 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a . void*.);../*.
31e70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 6e ** CAPI3REF: En
31e80 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 able Or Disable
31e90 53 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63 Shared Pager Cac
31ea0 68 65 20 7b 46 31 30 33 33 30 7d 0a 2a 2a 0a 2a he {F10330}.**.*
31eb0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 * This routine e
31ec0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c nables or disabl
31ed0 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f es the sharing o
31ee0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 f the database c
31ef0 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 ache.** and sche
31f00 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72 ma data structur
31f10 65 73 20 62 65 74 77 65 65 6e 20 63 6f 6e 6e 65 es between conne
31f20 63 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 73 61 ctions to the sa
31f30 6d 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 20 me database..**
31f40 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c Sharing is enabl
31f50 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 ed if the argume
31f60 6e 74 20 69 73 20 74 72 75 65 20 61 6e 64 20 64 nt is true and d
31f70 69 73 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 isabled if the a
31f80 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 66 61 rgument.** is fa
31f90 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 43 61 63 68 65 lse..**.** Cache
31fa0 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 sharing is enab
31fb0 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64 led and disabled
31fc0 0a 2a 2a 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 .** for an entir
31fd0 65 20 70 72 6f 63 65 73 73 2e 20 7b 45 4e 44 7d e process. {END}
31fe0 20 54 68 69 73 20 69 73 20 61 20 63 68 61 6e 67 This is a chang
31ff0 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20 76 e as of SQLite v
32000 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 0a 2a 2a ersion 3.5.0..**
32010 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f In prior versio
32020 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 20 73 68 ns of SQLite, sh
32030 61 72 69 6e 67 20 77 61 73 0a 2a 2a 20 65 6e 61 aring was.** ena
32040 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 bled or disabled
32050 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 for each thread
32060 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a separately..**.
32070 2a 2a 20 54 68 65 20 63 61 63 68 65 20 73 68 61 ** The cache sha
32080 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79 ring mode set by
32090 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 this interface
320a0 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73 effects all subs
320b0 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 equent.** calls
320c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e to [sqlite3_open
320d0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ()], [sqlite3_op
320e0 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 en_v2()], and [s
320f0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
32100 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61 ..** Existing da
32110 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
32120 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 ns continue use
32130 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 the sharing mode
32140 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20 .** that was in
32150 65 66 66 65 63 74 20 61 74 20 74 68 65 20 74 69 effect at the ti
32160 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 65 me they were ope
32170 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 ned..**.** Virtu
32180 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f 74 al tables cannot
32190 20 62 65 20 75 73 65 64 20 77 69 74 68 20 61 20 be used with a
321a0 73 68 61 72 65 64 20 63 61 63 68 65 2e 20 20 20 shared cache.
321b0 57 68 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63 When shared.** c
321c0 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c ache is enabled,
321d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 the [sqlite3_cr
321e0 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41 eate_module()] A
321f0 50 49 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 PI used to regis
32200 74 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 ter.** virtual t
32210 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61 79 ables will alway
32220 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f s return an erro
32230 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f r..**.** This ro
32240 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 utine returns [S
32250 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 QLITE_OK] if sha
32260 72 65 64 20 63 61 63 68 65 20 77 61 73 0a 2a 2a red cache was.**
32270 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 enabled or disa
32280 62 6c 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c bled successfull
32290 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f y. An [error co
322a0 64 65 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e de].** is return
322b0 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a ed otherwise..**
322c0 0a 2a 2a 20 53 68 61 72 65 64 20 63 61 63 68 65 .** Shared cache
322d0 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 is disabled by
322e0 64 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69 default. But thi
322f0 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 s might change i
32300 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65 n.** future rele
32310 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 ases of SQLite.
32320 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 Applications th
32330 61 74 20 63 61 72 65 20 61 62 6f 75 74 20 73 68 at care about sh
32340 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 ared.** cache se
32350 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 tting should set
32360 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a it explicitly..
32370 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
32380 3a 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 30 33 33 31 :.** .** {F10331
32390 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 } A successful i
323a0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 nvocation of [sq
323b0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 lite3_enable_sha
323c0 72 65 64 5f 63 61 63 68 65 28 42 29 5d 0a 2a 2a red_cache(B)].**
323d0 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20 65 will e
323e0 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 nable or disable
323f0 20 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f shared cache mo
32400 64 65 20 66 6f 72 20 61 6e 79 20 73 75 62 73 65 de for any subse
32410 71 75 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20 quently.**
32420 20 20 20 20 63 72 65 61 74 65 64 20 5b 64 61 74 created [dat
32430 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
32440 5d 20 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 ] in the same pr
32450 6f 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 ocess..**.** {F1
32460 30 33 33 36 7d 20 57 68 65 6e 20 73 68 61 72 65 0336} When share
32470 64 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c d cache is enabl
32480 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 ed, the [sqlite3
32490 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 _create_module()
324a0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e ].** in
324b0 74 65 72 66 61 63 65 20 77 69 6c 6c 20 61 6c 77 terface will alw
324c0 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72 ays return an er
324d0 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33 ror..**.** {F103
324e0 33 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 37} The [sqlite3
324f0 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 _enable_shared_c
32500 61 63 68 65 28 42 29 5d 20 69 6e 74 65 72 66 61 ache(B)] interfa
32510 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 ce returns.**
32520 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f [SQLITE_O
32530 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63 K] if shared cac
32540 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f he was enabled o
32550 72 20 64 69 73 61 62 6c 65 64 20 73 75 63 63 65 r disabled succe
32560 73 73 66 75 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b ssfully..**.** {
32570 46 31 30 33 33 39 7d 20 53 68 61 72 65 64 20 63 F10339} Shared c
32580 61 63 68 65 20 69 73 20 64 69 73 61 62 6c 65 64 ache is disabled
32590 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2f 0a by default..*/.
325a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 int sqlite3_enab
325b0 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 le_shared_cache(
325c0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 int);../*.** CAP
325d0 49 33 52 45 46 3a 20 20 41 74 74 65 6d 70 74 20 I3REF: Attempt
325e0 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d To Free Heap Mem
325f0 6f 72 79 20 7b 46 31 37 33 34 30 7d 0a 2a 2a 0a ory {F17340}.**.
32600 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 ** The sqlite3_r
32610 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 elease_memory()
32620 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 interface attemp
32630 74 73 20 74 6f 0a 2a 2a 20 66 72 65 65 20 4e 20 ts to.** free N
32640 62 79 74 65 73 20 6f 66 20 68 65 61 70 20 6d 65 bytes of heap me
32650 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 mory by dealloca
32660 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 ting non-essenti
32670 61 6c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c al memory.** all
32680 6f 63 61 74 69 6f 6e 73 20 68 65 6c 64 20 62 79 ocations held by
32690 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 61 the database la
326a0 62 72 61 72 79 2e 20 7b 45 4e 44 7d 20 20 4d 65 brary. {END} Me
326b0 6d 6f 72 79 20 75 73 65 64 0a 2a 2a 20 74 6f 20 mory used.** to
326c0 63 61 63 68 65 20 64 61 74 61 62 61 73 65 20 70 cache database p
326d0 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 ages to improve
326e0 70 65 72 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 performance is a
326f0 6e 20 65 78 61 6d 70 6c 65 20 6f 66 0a 2a 2a 20 n example of.**
32700 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 non-essential me
32710 6d 6f 72 79 2e 20 20 53 71 6c 69 74 65 33 5f 72 mory. Sqlite3_r
32720 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 elease_memory()
32730 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e returns.** the n
32740 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 61 umber of bytes a
32750 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 20 77 ctually freed, w
32760 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f hich might be mo
32770 72 65 20 6f 72 20 6c 65 73 73 0a 2a 2a 20 74 68 re or less.** th
32780 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 an the amount re
32790 71 75 65 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 quested..**.** I
327a0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
327b0 20 7b 46 31 37 33 34 31 7d 20 54 68 65 20 5b 73 {F17341} The [s
327c0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d qlite3_release_m
327d0 65 6d 6f 72 79 28 4e 29 5d 20 69 6e 74 65 72 66 emory(N)] interf
327e0 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 0a ace attempts to.
327f0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 65 65 ** free
32800 20 4e 20 62 79 74 65 73 20 6f 66 20 68 65 61 70 N bytes of heap
32810 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c memory by deall
32820 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 ocating non-esse
32830 6e 74 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 ntial.**
32840 20 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 memory allocat
32850 69 6f 6e 73 20 68 65 6c 64 20 62 79 20 74 68 65 ions held by the
32860 20 64 61 74 61 62 61 73 65 20 6c 61 62 72 61 72 database labrar
32870 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 34 32 y..**.** {F16342
32880 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 } The [sqlite3_r
32890 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 4e 29 elease_memory(N)
328a0 5d 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 ] returns the nu
328b0 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 mber.**
328c0 20 6f 66 20 62 79 74 65 73 20 61 63 74 75 61 6c of bytes actual
328d0 6c 79 20 66 72 65 65 64 2c 20 77 68 69 63 68 20 ly freed, which
328e0 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 might be more or
328f0 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 less.**
32900 20 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e than the amoun
32910 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2f 0a t requested..*/.
32920 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 int sqlite3_rele
32930 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b ase_memory(int);
32940 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
32950 3a 20 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 : Impose A Limi
32960 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 20 7b t On Heap Size {
32970 46 31 37 33 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 F17350}.**.** Th
32980 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 e sqlite3_soft_h
32990 65 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65 eap_limit() inte
329a0 72 66 61 63 65 0a 2a 2a 20 70 6c 61 63 65 73 20 rface.** places
329b0 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 20 6f a "soft" limit o
329c0 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 n the amount of
329d0 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 heap memory that
329e0 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 may be allocate
329f0 64 0a 2a 2a 20 62 79 20 53 51 4c 69 74 65 2e 20 d.** by SQLite.
32a00 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 If an internal a
32a10 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 71 llocation is req
32a20 75 65 73 74 65 64 20 0a 2a 2a 20 74 68 61 74 20 uested .** that
32a30 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 65 would exceed the
32a40 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 soft heap limit
32a50 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 , [sqlite3_relea
32a60 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 0a se_memory()] is.
32a70 2a 2a 20 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f ** invoked one o
32a80 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 r more times to
32a90 66 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70 61 free up some spa
32aa0 63 65 20 62 65 66 6f 72 65 20 74 68 65 20 61 6c ce before the al
32ab0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6d location.** is m
32ac0 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c ade..**.** The l
32ad0 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22 imit is called "
32ae0 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65 20 69 soft", because i
32af0 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 f.** [sqlite3_re
32b00 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 lease_memory()]
32b10 63 61 6e 6e 6f 74 0a 2a 2a 20 66 72 65 65 20 73 cannot.** free s
32b20 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 ufficient memory
32b30 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20 to prevent the
32b40 6c 69 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 limit from being
32b50 20 65 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 exceeded,.** th
32b60 65 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f e memory is allo
32b70 63 61 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64 cated anyway and
32b80 20 74 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65 the current ope
32b90 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e ration proceeds.
32ba0 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 .**.** A negativ
32bb0 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 e or zero value
32bc0 66 6f 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 for N means that
32bd0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 there is no sof
32be0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 t heap limit and
32bf0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c .** [sqlite3_rel
32c00 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 ease_memory()] w
32c10 69 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c ill only be call
32c20 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 ed when memory i
32c30 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 s exhausted..**
32c40 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 The default valu
32c50 65 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 e for the soft h
32c60 65 61 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 eap limit is zer
32c70 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 o..**.** SQLite
32c80 6d 61 6b 65 73 20 61 20 62 65 73 74 20 65 66 66 makes a best eff
32c90 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 ort to honor the
32ca0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 soft heap limit
32cb0 2e 20 20 0a 2a 2a 20 42 75 74 20 69 66 20 74 68 . .** But if th
32cc0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 e soft heap limi
32cd0 74 20 63 61 6e 6e 6f 74 20 68 6f 6e 6f 72 65 64 t cannot honored
32ce0 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c , execution will
32cf0 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 .** continue wit
32d00 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f hout error or no
32d10 74 69 66 69 63 61 74 69 6f 6e 2e 20 20 54 68 69 tification. Thi
32d20 73 20 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d s is why the lim
32d30 69 74 20 69 73 20 0a 2a 2a 20 63 61 6c 6c 65 64 it is .** called
32d40 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e a "soft" limit.
32d50 20 20 49 74 20 69 73 20 61 64 76 69 73 6f 72 79 It is advisory
32d60 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 only..**.** Pri
32d70 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 or to SQLite ver
32d80 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 sion 3.5.0, this
32d90 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f routine only co
32da0 6e 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 nstrained the me
32db0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 mory.** allocate
32dc0 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 d by a single th
32dd0 72 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 read - the same
32de0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 thread in which
32df0 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 this routine.**
32e00 72 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 runs. Beginning
32e10 20 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 with SQLite ver
32e20 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 sion 3.5.0, the
32e30 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 soft heap limit
32e40 69 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f is.** applied to
32e50 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68 all threads. Th
32e60 65 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 e value specifie
32e70 64 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 d for the soft h
32e80 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 eap limit.** is
32e90 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f an upper bound o
32ea0 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f n the total memo
32eb0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f ry allocation fo
32ec0 72 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 r all threads. I
32ed0 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 n.** version 3.5
32ee0 2e 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d .0 there is no m
32ef0 65 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d echanism for lim
32f00 69 74 69 6e 67 20 74 68 65 20 68 65 61 70 20 75 iting the heap u
32f10 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 sage for.** indi
32f20 76 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a vidual threads..
32f30 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
32f40 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 31 7d :.**.** {F16351}
32f50 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f The [sqlite3_so
32f60 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 4e 29 ft_heap_limit(N)
32f70 5d 20 69 6e 74 65 72 66 61 63 65 20 70 6c 61 63 ] interface plac
32f80 65 73 20 61 20 73 6f 66 74 20 6c 69 6d 69 74 0a es a soft limit.
32f90 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 4e ** of N
32fa0 20 62 79 74 65 73 20 6f 6e 20 74 68 65 20 61 6d bytes on the am
32fb0 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d ount of heap mem
32fc0 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 ory that may be
32fd0 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20 20 20 20 allocated.**
32fe0 20 20 20 20 20 20 75 73 69 6e 67 20 5b 73 71 6c using [sql
32ff0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f ite3_malloc()] o
33000 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c r [sqlite3_reall
33010 6f 63 28 29 5d 20 61 74 20 61 6e 79 20 70 6f 69 oc()] at any poi
33020 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 nt.** i
33030 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 n time..**.** {F
33040 31 36 33 35 32 7d 20 49 66 20 61 20 63 61 6c 6c 16352} If a call
33050 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c to [sqlite3_mal
33060 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 loc()] or [sqlit
33070 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 77 6f e3_realloc()] wo
33080 75 6c 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 uld.**
33090 63 61 75 73 65 20 74 68 65 20 74 6f 74 61 6c 20 cause the total
330a0 61 6d 6f 75 6e 74 20 6f 66 20 61 6c 6c 6f 63 61 amount of alloca
330b0 74 65 64 20 6d 65 6d 6f 72 79 20 74 6f 20 65 78 ted memory to ex
330c0 63 65 65 64 20 74 68 65 0a 2a 2a 20 20 20 20 20 ceed the.**
330d0 20 20 20 20 20 73 6f 66 74 20 68 65 61 70 20 6c soft heap l
330e0 69 6d 69 74 2c 20 74 68 65 6e 20 5b 73 71 6c 69 imit, then [sqli
330f0 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f te3_release_memo
33100 72 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 ry()] is invoked
33110 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 .** in
33120 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 an attempt to re
33130 64 75 63 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 duce the memory
33140 75 73 61 67 65 20 70 72 69 6f 72 20 74 6f 20 70 usage prior to p
33150 72 6f 63 65 65 64 69 6e 67 0a 2a 2a 20 20 20 20 roceeding.**
33160 20 20 20 20 20 20 77 69 74 68 20 74 68 65 20 6d with the m
33170 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
33180 20 61 74 74 65 6d 70 74 2e 0a 2a 2a 0a 2a 2a 20 attempt..**.**
33190 7b 46 31 36 33 35 33 7d 20 43 61 6c 6c 73 20 74 {F16353} Calls t
331a0 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f o [sqlite3_mallo
331b0 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 c()] or [sqlite3
331c0 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 _realloc()] that
331d0 20 74 72 69 67 67 65 72 0a 2a 2a 20 20 20 20 20 trigger.**
331e0 20 20 20 20 20 61 74 74 65 6d 70 74 73 20 74 6f attempts to
331f0 20 72 65 64 75 63 65 20 6d 65 6d 6f 72 79 20 75 reduce memory u
33200 73 61 67 65 20 74 68 72 6f 75 67 68 20 74 68 65 sage through the
33210 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 soft heap limit
33220 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 63 .** mec
33230 68 61 6e 69 73 6d 20 63 6f 6e 74 69 6e 75 65 20 hanism continue
33240 65 76 65 6e 20 69 66 20 74 68 65 20 61 74 74 65 even if the atte
33250 6d 70 74 20 74 6f 20 72 65 64 75 63 65 20 6d 65 mpt to reduce me
33260 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 mory.**
33270 20 75 73 61 67 65 20 69 73 20 75 6e 73 75 63 63 usage is unsucc
33280 65 73 73 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 essful..**.** {F
33290 31 36 33 35 34 7d 20 41 20 6e 65 67 61 74 69 76 16354} A negativ
332a0 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 e or zero value
332b0 66 6f 72 20 4e 20 69 6e 20 61 20 63 61 6c 6c 20 for N in a call
332c0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b to.** [
332d0 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 sqlite3_soft_hea
332e0 70 5f 6c 69 6d 69 74 28 4e 29 5d 20 6d 65 61 6e p_limit(N)] mean
332f0 73 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20 s that there is
33300 6e 6f 20 73 6f 66 74 0a 2a 2a 20 20 20 20 20 20 no soft.**
33310 20 20 20 20 68 65 61 70 20 6c 69 6d 69 74 20 61 heap limit a
33320 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 nd [sqlite3_rele
33330 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 ase_memory()] wi
33340 6c 6c 20 6f 6e 6c 79 20 62 65 0a 2a 2a 20 20 20 ll only be.**
33350 20 20 20 20 20 20 20 63 61 6c 6c 65 64 20 77 68 called wh
33360 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 63 6f 6d en memory is com
33370 70 6c 65 74 65 6c 79 20 65 78 68 61 75 73 74 65 pletely exhauste
33380 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 35 d..**.** {F16355
33390 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 } The default va
333a0 6c 75 65 20 66 6f 72 20 74 68 65 20 73 6f 66 74 lue for the soft
333b0 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 7a heap limit is z
333c0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 ero..**.** {F163
333d0 35 38 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 58} Each call to
333e0 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 [sqlite3_soft_h
333f0 65 61 70 5f 6c 69 6d 69 74 28 4e 29 5d 20 6f 76 eap_limit(N)] ov
33400 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 20 errides the.**
33410 20 20 20 20 20 20 20 20 76 61 6c 75 65 73 20 73 values s
33420 65 74 20 62 79 20 61 6c 6c 20 70 72 69 6f 72 20 et by all prior
33430 63 61 6c 6c 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 calls..*/.void s
33440 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 qlite3_soft_heap
33450 5f 6c 69 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a _limit(int);../*
33460 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 .** CAPI3REF: E
33470 78 74 72 61 63 74 20 4d 65 74 61 64 61 74 61 20 xtract Metadata
33480 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f About A Column O
33490 66 20 41 20 54 61 62 6c 65 20 7b 46 31 32 38 35 f A Table {F1285
334a0 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 0}.**.** This ro
334b0 75 74 69 6e 65 0a 2a 2a 20 72 65 74 75 72 6e 73 utine.** returns
334c0 20 6d 65 74 61 2d 64 61 74 61 20 61 62 6f 75 74 meta-data about
334d0 20 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75 a specific colu
334e0 6d 6e 20 6f 66 20 61 20 73 70 65 63 69 66 69 63 mn of a specific
334f0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 database.** tab
33500 6c 65 20 61 63 63 65 73 73 69 62 6c 65 20 75 73 le accessible us
33510 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 ing the connecti
33520 6f 6e 20 68 61 6e 64 6c 65 20 70 61 73 73 65 64 on handle passed
33530 20 61 73 20 74 68 65 20 66 69 72 73 74 20 66 75 as the first fu
33540 6e 63 74 69 6f 6e 20 0a 2a 2a 20 61 72 67 75 6d nction .** argum
33550 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 ent..**.** The c
33560 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 olumn is identif
33570 69 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e ied by the secon
33580 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 d, third and fou
33590 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 rth parameters t
335a0 6f 20 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 o .** this funct
335b0 69 6f 6e 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 ion. The second
335c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 65 69 74 parameter is eit
335d0 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 her the name of
335e0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 the database.**
335f0 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 (i.e. "main", "t
33600 65 6d 70 22 20 6f 72 20 61 6e 20 61 74 74 61 63 emp" or an attac
33610 68 65 64 20 64 61 74 61 62 61 73 65 29 20 63 6f hed database) co
33620 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65 ntaining the spe
33630 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 cified.** table
33640 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 69 74 20 69 or NULL. If it i
33650 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c s NULL, then all
33660 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 attached databa
33670 73 65 73 20 61 72 65 20 73 65 61 72 63 68 65 64 ses are searched
33680 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c .** for the tabl
33690 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 e using the same
336a0 20 61 6c 67 6f 72 69 74 68 6d 20 61 73 20 74 68 algorithm as th
336b0 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e e database engin
336c0 65 20 75 73 65 73 20 74 6f 20 0a 2a 2a 20 72 65 e uses to .** re
336d0 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65 solve unqualifie
336e0 64 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 d table referenc
336f0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 es..**.** The th
33700 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 ird and fourth p
33710 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 arameters to thi
33720 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 s function are t
33730 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c he table and col
33740 75 6d 6e 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 umn .** name of
33750 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 the desired colu
33760 6d 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 mn, respectively
33770 2e 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 . Neither of the
33780 73 65 20 70 61 72 61 6d 65 74 65 72 73 20 0a 2a se parameters .*
33790 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a * may be NULL..*
337a0 2a 0a 2a 2a 20 4d 65 74 61 20 69 6e 66 6f 72 6d *.** Meta inform
337b0 61 74 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 ation is returne
337c0 64 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20 d by writing to
337d0 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 the memory locat
337e0 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73 0a 2a ions passed as.*
337f0 2a 20 74 68 65 20 35 74 68 20 61 6e 64 20 73 75 * the 5th and su
33800 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74 bsequent paramet
33810 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 ers to this func
33820 74 69 6f 6e 2e 20 41 6e 79 20 6f 66 20 74 68 65 tion. Any of the
33830 73 65 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 se .** arguments
33840 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2c 20 69 6e may be NULL, in
33850 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 which case the
33860 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c corresponding el
33870 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 20 0a 2a ement of meta .*
33880 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 * information is
33890 20 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a ommitted..**.**
338a0 20 3c 70 72 65 3e 0a 2a 2a 20 50 61 72 61 6d 65 <pre>.** Parame
338b0 74 65 72 20 20 20 20 20 4f 75 74 70 75 74 20 54 ter Output T
338c0 79 70 65 20 20 20 20 20 20 44 65 73 63 72 69 70 ype Descrip
338d0 74 69 6f 6e 0a 2a 2a 20 2d 2d 2d 2d 2d 2d 2d 2d tion.** --------
338e0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
338f0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 0a 2a -----------.**.*
33900 2a 20 20 20 35 74 68 20 20 20 20 20 20 20 20 20 * 5th
33910 63 6f 6e 73 74 20 63 68 61 72 2a 20 20 20 20 20 const char*
33920 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 20 20 Data type.**
33930 36 74 68 20 20 20 20 20 20 20 20 20 63 6f 6e 73 6th cons
33940 74 20 63 68 61 72 2a 20 20 20 20 20 20 4e 61 6d t char* Nam
33950 65 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 e of the default
33960 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 collation seque
33970 6e 63 65 20 0a 2a 2a 20 20 20 37 74 68 20 20 20 nce .** 7th
33980 20 20 20 20 20 20 69 6e 74 20 20 20 20 20 20 20 int
33990 20 20 20 20 20 20 20 54 72 75 65 20 69 66 20 74 True if t
339a0 68 65 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 he column has a
339b0 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 NOT NULL constra
339c0 69 6e 74 0a 2a 2a 20 20 20 38 74 68 20 20 20 20 int.** 8th
339d0 20 20 20 20 20 69 6e 74 20 20 20 20 20 20 20 20 int
339e0 20 20 20 20 20 20 54 72 75 65 20 69 66 20 74 68 True if th
339f0 65 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 e column is part
33a00 20 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 of the PRIMARY
33a10 4b 45 59 0a 2a 2a 20 20 20 39 74 68 20 20 20 20 KEY.** 9th
33a20 20 20 20 20 20 69 6e 74 20 20 20 20 20 20 20 20 int
33a30 20 20 20 20 20 20 54 72 75 65 20 69 66 20 74 68 True if th
33a40 65 20 63 6f 6c 75 6d 6e 20 69 73 20 41 55 54 4f e column is AUTO
33a50 49 4e 43 52 45 4d 45 4e 54 0a 2a 2a 20 3c 2f 70 INCREMENT.** </p
33a60 72 65 3e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 re>.**.**.** The
33a70 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 memory pointed
33a80 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 61 63 to by the charac
33a90 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74 ter pointers ret
33aa0 75 72 6e 65 64 20 66 6f 72 20 74 68 65 20 0a 2a urned for the .*
33ab0 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 * declaration ty
33ac0 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e pe and collation
33ad0 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c sequence is val
33ae0 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 id only until th
33af0 65 20 6e 65 78 74 20 0a 2a 2a 20 63 61 6c 6c 20 e next .** call
33b00 74 6f 20 61 6e 79 20 73 71 6c 69 74 65 20 41 50 to any sqlite AP
33b10 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a I function..**.*
33b20 2a 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69 * If the specifi
33b30 65 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75 ed table is actu
33b40 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 74 68 65 ally a view, the
33b50 6e 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 n an error is re
33b60 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 turned..**.** If
33b70 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63 the specified c
33b80 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 olumn is "rowid"
33b90 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 , "oid" or "_row
33ba0 69 64 5f 22 20 61 6e 64 20 61 6e 20 0a 2a 2a 20 id_" and an .**
33bb0 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 INTEGER PRIMARY
33bc0 4b 45 59 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62 KEY column has b
33bd0 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64 een explicitly d
33be0 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68 eclared, then th
33bf0 65 20 6f 75 74 70 75 74 20 0a 2a 2a 20 70 61 72 e output .** par
33c00 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 ameters are set
33c10 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 for the explicit
33c20 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 ly declared colu
33c30 6d 6e 2e 20 49 66 20 74 68 65 72 65 20 69 73 20 mn. If there is
33c40 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79 no.** explicitly
33c50 20 64 65 63 6c 61 72 65 64 20 49 50 4b 20 63 6f declared IPK co
33c60 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f lumn, then the o
33c70 75 74 70 75 74 20 70 61 72 61 6d 65 74 65 72 73 utput parameters
33c80 20 61 72 65 20 73 65 74 20 61 73 20 0a 2a 2a 20 are set as .**
33c90 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c follows:.**.** <
33ca0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 pre>.** data
33cb0 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52 22 type: "INTEGER"
33cc0 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f .** collatio
33cd0 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49 4e n sequence: "BIN
33ce0 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 ARY".** not
33cf0 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 null: 0.** p
33d00 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a rimary key: 1.**
33d10 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65 6d auto increm
33d20 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e ent: 0.** </pre>
33d30 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 .**.** This func
33d40 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e tion may load on
33d50 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d 61 e or more schema
33d60 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20 s from database
33d70 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 files. If an.**
33d80 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 error occurs dur
33d90 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73 73 ing this process
33da0 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 71 75 , or if the requ
33db0 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20 63 ested table or c
33dc0 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 olumn.** cannot
33dd0 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 53 51 4c be found, an SQL
33de0 49 54 45 20 65 72 72 6f 72 20 63 6f 64 65 20 69 ITE error code i
33df0 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61 s returned and a
33e00 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a n error message.
33e10 2a 2a 20 6c 65 66 74 20 69 6e 20 74 68 65 20 64 ** left in the d
33e20 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 28 atabase handle (
33e30 74 6f 20 62 65 20 72 65 74 72 69 65 76 65 64 20 to be retrieved
33e40 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 using sqlite3_er
33e50 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a 2a 20 54 rmsg())..**.** T
33e60 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 his API is only
33e70 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 available if the
33e80 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d library was com
33e90 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a piled with the.*
33ea0 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f * SQLITE_ENABLE_
33eb0 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 20 COLUMN_METADATA
33ec0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d preprocessor sym
33ed0 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a bol defined..*/.
33ee0 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c int sqlite3_tabl
33ef0 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 e_column_metadat
33f00 61 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 a(. sqlite3 *db
33f10 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
33f20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 /* Connection h
33f30 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
33f40 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 char *zDbName,
33f50 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
33f60 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 se name or NULL
33f70 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
33f80 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 *zTableName,
33f90 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a /* Table name *
33fa0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
33fb0 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 zColumnName,
33fc0 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a /* Column name *
33fd0 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a /. char const *
33fe0 2a 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 *pzDataType,
33ff0 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 /* OUTPUT: Decla
34000 72 65 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f red data type */
34010 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a . char const **
34020 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f pzCollSeq, /
34030 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 * OUTPUT: Collat
34040 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d ion sequence nam
34050 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 e */. int *pNot
34060 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 Null,
34070 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 /* OUTPUT: Tr
34080 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 ue if NOT NULL c
34090 6f 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 onstraint exists
340a0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d */. int *pPrim
340b0 61 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 aryKey,
340c0 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 /* OUTPUT: Tru
340d0 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 e if column part
340e0 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 of PK */. int
340f0 2a 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 *pAutoinc
34100 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 /* OUTPU
34110 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d T: True if colum
34120 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d n is auto-increm
34130 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a ent */.);../*.**
34140 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 CAPI3REF: Load
34150 41 6e 20 45 78 74 65 6e 73 69 6f 6e 20 7b 46 31 An Extension {F1
34160 32 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 2600}.**.** {F12
34170 36 30 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 601} The sqlite3
34180 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 _load_extension(
34190 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 61 ) interface.** a
341a0 74 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 ttempts to load
341b0 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 an SQLite extens
341c0 69 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 ion library cont
341d0 61 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c ained in the fil
341e0 65 0a 2a 2a 20 7a 46 69 6c 65 2e 20 7b 46 31 32 e.** zFile. {F12
341f0 36 30 32 7d 20 54 68 65 20 65 6e 74 72 79 20 70 602} The entry p
34200 6f 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 20 7b oint is zProc. {
34210 46 31 32 36 30 33 7d 20 7a 50 72 6f 63 20 6d 61 F12603} zProc ma
34220 79 20 62 65 20 30 0a 2a 2a 20 69 6e 20 77 68 69 y be 0.** in whi
34230 63 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 ch case the name
34240 20 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f of the entry po
34250 69 6e 74 20 64 65 66 61 75 6c 74 73 0a 2a 2a 20 int defaults.**
34260 74 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 to "sqlite3_exte
34270 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 0a nsion_init"..**.
34280 2a 2a 20 7b 46 31 32 36 30 34 7d 20 54 68 65 20 ** {F12604} The
34290 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 sqlite3_load_ext
342a0 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 ension() interfa
342b0 63 65 20 73 68 61 6c 6c 0a 2a 2a 20 72 65 74 75 ce shall.** retu
342c0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f rn [SQLITE_OK] o
342d0 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 n success and [S
342e0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 QLITE_ERROR] if
342f0 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 something goes w
34300 72 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 rong..**.** {F12
34310 36 30 35 7d 0a 2a 2a 20 49 66 20 61 6e 20 65 72 605}.** If an er
34320 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70 ror occurs and p
34330 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 zErrMsg is not 0
34340 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 73 71 , then the.** sq
34350 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e lite3_load_exten
34360 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 sion() interface
34370 20 73 68 61 6c 6c 20 61 74 74 65 6d 70 74 20 74 shall attempt t
34380 6f 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 o fill *pzErrMsg
34390 20 77 69 74 68 20 0a 2a 2a 20 65 72 72 6f 72 20 with .** error
343a0 6d 65 73 73 61 67 65 20 74 65 78 74 20 73 74 6f message text sto
343b0 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 red in memory ob
343c0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c tained from [sql
343d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a ite3_malloc()]..
343e0 2a 2a 20 7b 45 4e 44 7d 20 20 54 68 65 20 63 61 ** {END} The ca
343f0 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 lling function s
34400 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 hould free this
34410 6d 65 6d 6f 72 79 0a 2a 2a 20 62 79 20 63 61 6c memory.** by cal
34420 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 ling [sqlite3_fr
34430 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 ee()]..**.** {F1
34440 32 36 30 36 7d 0a 2a 2a 20 45 78 74 65 6e 73 69 2606}.** Extensi
34450 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 on loading must
34460 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 be enabled using
34470 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 [sqlite3_enable
34480 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 _load_extension(
34490 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 )].** prior to c
344a0 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 20 alling this API
344b0 6f 72 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c or an error will
344c0 20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f be returned..*/
344d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 .int sqlite3_loa
344e0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 d_extension(. s
344f0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
34500 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 /* Load the
34510 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 extension into
34520 74 68 69 73 20 64 61 74 61 62 61 73 65 20 63 6f this database co
34530 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f nnection */. co
34540 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c nst char *zFile,
34550 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 /* Name of t
34560 68 65 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 he shared librar
34570 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 y containing ext
34580 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 ension */. cons
34590 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 t char *zProc,
345a0 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 /* Entry point
345b0 2e 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 . Derived from
345c0 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 zFile if 0 */.
345d0 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 char **pzErrMsg
345e0 20 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 /* Put err
345f0 6f 72 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 or message here
34600 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a if not 0 */.);..
34610 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
34620 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 Enable Or Disab
34630 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 le Extension Loa
34640 64 69 6e 67 20 7b 46 31 32 36 32 30 7d 0a 2a 2a ding {F12620}.**
34650 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f 74 20 74 6f .** So as not to
34660 20 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20 68 open security h
34670 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61 70 oles in older ap
34680 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 plications that
34690 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72 65 are.** unprepare
346a0 64 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 65 d to deal with e
346b0 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 xtension loading
346c0 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e 73 , and as a means
346d0 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a 2a of disabling.**
346e0 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 extension loadi
346f0 6e 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 ng while evaluat
34700 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65 64 ing user-entered
34710 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 SQL, the follow
34720 69 6e 67 0a 2a 2a 20 41 50 49 20 69 73 20 70 72 ing.** API is pr
34730 6f 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20 74 ovided to turn t
34740 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 he [sqlite3_load
34750 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d 65 _extension()] me
34760 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 0a 2a chanism on and.*
34770 2a 20 6f 66 66 2e 20 20 7b 46 31 32 36 32 32 7d * off. {F12622}
34780 20 49 74 20 69 73 20 6f 66 66 20 62 79 20 64 65 It is off by de
34790 66 61 75 6c 74 2e 20 7b 45 4e 44 7d 20 53 65 65 fault. {END} See
347a0 20 74 69 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a ticket #1863..*
347b0 2a 0a 2a 2a 20 7b 46 31 32 36 32 31 7d 20 43 61 *.** {F12621} Ca
347c0 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 ll the sqlite3_e
347d0 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e nable_load_exten
347e0 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a sion() routine.*
347f0 2a 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 20 * with onoff==1
34800 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f to turn extensio
34810 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 0a 2a 2a 20 n loading on.**
34820 61 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 and call it with
34830 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 onoff==0 to tur
34840 6e 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67 n it back off ag
34850 61 69 6e 2e 20 7b 45 4e 44 7d 0a 2a 2f 0a 69 6e ain. {END}.*/.in
34860 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 t sqlite3_enable
34870 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 _load_extension(
34880 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e 74 sqlite3 *db, int
34890 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 onoff);../*.**
348a0 43 41 50 49 33 52 45 46 3a 20 4d 61 6b 65 20 41 CAPI3REF: Make A
348b0 72 72 61 6e 67 65 6d 65 6e 74 73 20 54 6f 20 41 rrangements To A
348c0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 utomatically Loa
348d0 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 20 7b d An Extension {
348e0 46 31 32 36 34 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 F12640}.**.** {F
348f0 31 32 36 34 31 7d 20 54 68 69 73 20 66 75 6e 63 12641} This func
34900 74 69 6f 6e 0a 2a 2a 20 72 65 67 69 73 74 65 72 tion.** register
34910 73 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 65 s an extension e
34920 6e 74 72 79 20 70 6f 69 6e 74 20 74 68 61 74 20 ntry point that
34930 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 is automatically
34940 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e invoked.** when
34950 65 76 65 72 20 61 20 6e 65 77 20 64 61 74 61 62 ever a new datab
34960 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
34970 73 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 0a 2a s opened using.*
34980 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 * [sqlite3_open(
34990 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
349a0 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 n16()], or [sqli
349b0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 te3_open_v2()].
349c0 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 {END}.**.** This
349d0 20 41 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f API can be invo
349e0 6b 65 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73 ked at program s
349f0 74 61 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20 tartup in order
34a00 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f to register.** o
34a10 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69 ne or more stati
34a20 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74 cally linked ext
34a30 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c ensions that wil
34a40 6c 20 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a l be available.*
34a50 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 64 61 74 * to all new dat
34a60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
34a70 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34 32 s..**.** {F12642
34a80 7d 20 44 75 70 6c 69 63 61 74 65 20 65 78 74 65 } Duplicate exte
34a90 6e 73 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63 nsions are detec
34aa0 74 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 ted so calling t
34ab0 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 6c 74 his routine mult
34ac0 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 iple.** times wi
34ad0 74 68 20 74 68 65 20 73 61 6d 65 20 65 78 74 65 th the same exte
34ae0 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73 nsion is harmles
34af0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34 33 s..**.** {F12643
34b00 7d 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 } This routine s
34b10 74 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20 tores a pointer
34b20 74 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e to the extension
34b30 20 69 6e 20 61 6e 20 61 72 72 61 79 0a 2a 2a 20 in an array.**
34b40 74 68 61 74 20 69 73 20 6f 62 74 61 69 6e 65 64 that is obtained
34b50 20 66 72 6f 6d 20 73 71 6c 69 74 65 5f 6d 61 6c from sqlite_mal
34b60 6c 6f 63 28 29 2e 20 7b 45 4e 44 7d 20 49 66 20 loc(). {END} If
34b70 79 6f 75 20 72 75 6e 20 61 20 6d 65 6d 6f 72 79 you run a memory
34b80 20 6c 65 61 6b 0a 2a 2a 20 63 68 65 63 6b 65 72 leak.** checker
34b90 20 6f 6e 20 79 6f 75 72 20 70 72 6f 67 72 61 6d on your program
34ba0 20 61 6e 64 20 69 74 20 72 65 70 6f 72 74 73 20 and it reports
34bb0 61 20 6c 65 61 6b 20 62 65 63 61 75 73 65 20 6f a leak because o
34bc0 66 20 74 68 69 73 0a 2a 2a 20 61 72 72 61 79 2c f this.** array,
34bd0 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 5b 73 71 then invoke [sq
34be0 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f lite3_reset_auto
34bf0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 _extension()] pr
34c00 69 6f 72 0a 2a 2a 20 74 6f 20 73 68 75 74 64 6f ior.** to shutdo
34c10 77 6e 20 74 6f 20 66 72 65 65 20 74 68 65 20 6d wn to free the m
34c20 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 emory..**.** {F1
34c30 32 36 34 34 7d 20 41 75 74 6f 6d 61 74 69 63 20 2644} Automatic
34c40 65 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 extensions apply
34c50 20 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 across all thre
34c60 61 64 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a ads. {END}.**.**
34c70 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 This interface
34c80 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 is experimental
34c90 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 and is subject t
34ca0 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 o change or.** r
34cb0 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 emoval in future
34cc0 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c releases of SQL
34cd0 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ite..*/.int sqli
34ce0 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 te3_auto_extensi
34cf0 6f 6e 28 76 6f 69 64 20 2a 78 45 6e 74 72 79 50 on(void *xEntryP
34d00 6f 69 6e 74 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 oint);.../*.** C
34d10 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 API3REF: Reset A
34d20 75 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73 69 utomatic Extensi
34d30 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b 46 31 32 36 on Loading {F126
34d40 36 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 36 60}.**.** {F1266
34d50 31 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 1} This function
34d60 20 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 70 72 disables all pr
34d70 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 eviously registe
34d80 72 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 red.** automatic
34d90 20 65 78 74 65 6e 73 69 6f 6e 73 2e 20 7b 45 4e extensions. {EN
34da0 44 7d 20 20 54 68 69 73 0a 2a 2a 20 72 6f 75 74 D} This.** rout
34db0 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 ine undoes the e
34dc0 66 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 ffect of all pri
34dd0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f or [sqlite3_auto
34de0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a _extension()].**
34df0 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 calls..**.** {F
34e00 31 32 36 36 32 7d 20 54 68 69 73 20 63 61 6c 6c 12662} This call
34e10 20 64 69 73 61 62 6c 65 64 20 61 75 74 6f 6d 61 disabled automa
34e20 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 tic extensions i
34e30 6e 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 7b n all threads. {
34e40 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 END}.**.** This
34e50 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70 interface is exp
34e60 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 erimental and is
34e70 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e subject to chan
34e80 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c ge or.** removal
34e90 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 in future relea
34ea0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a ses of SQLite..*
34eb0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 /.void sqlite3_r
34ec0 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 eset_auto_extens
34ed0 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 0a 2f 2a 0a ion(void);.../*.
34ee0 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e ****** EXPERIMEN
34ef0 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f TAL - subject to
34f00 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 change without
34f10 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a notice *********
34f20 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 *****.**.** The
34f30 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 interface to the
34f40 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d virtual-table m
34f50 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 echanism is curr
34f60 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 ently considered
34f70 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 .** to be experi
34f80 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 mental. The int
34f90 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 erface might cha
34fa0 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 nge in incompati
34fb0 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 ble ways..** If
34fc0 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 this is a proble
34fd0 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f m for you, do no
34fe0 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 t use the interf
34ff0 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 ace at this time
35000 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 ..**.** When the
35010 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d virtual-table m
35020 65 63 68 61 6e 69 73 6d 20 73 74 61 62 6c 69 7a echanism stabliz
35030 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c es, we will decl
35040 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 are the.** inter
35050 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 face fixed, supp
35060 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 ort it indefinit
35070 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 ely, and remove
35080 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f this comment..*/
35090 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 ../*.** Structur
350a0 65 73 20 75 73 65 64 20 62 79 20 74 68 65 20 76 es used by the v
350b0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 irtual table int
350c0 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 erface.*/.typede
350d0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
350e0 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 _vtab sqlite3_vt
350f0 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 ab;.typedef stru
35100 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 ct sqlite3_index
35110 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e _info sqlite3_in
35120 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 dex_info;.typede
35130 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
35140 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c _vtab_cursor sql
35150 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 ite3_vtab_cursor
35160 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 ;.typedef struct
35170 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 sqlite3_module
35180 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a sqlite3_module;.
35190 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
351a0 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4f Virtual Table O
351b0 62 6a 65 63 74 20 7b 46 31 38 30 30 30 7d 0a 2a bject {F18000}.*
351c0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 * KEYWORDS: sqli
351d0 74 65 33 5f 6d 6f 64 75 6c 65 0a 2a 2a 0a 2a 2a te3_module.**.**
351e0 20 41 20 6d 6f 64 75 6c 65 20 69 73 20 61 20 63 A module is a c
351f0 6c 61 73 73 20 6f 66 20 76 69 72 74 75 61 6c 20 lass of virtual
35200 74 61 62 6c 65 73 2e 20 20 45 61 63 68 20 6d 6f tables. Each mo
35210 64 75 6c 65 20 69 73 20 64 65 66 69 6e 65 64 0a dule is defined.
35220 2a 2a 20 62 79 20 61 6e 20 69 6e 73 74 61 6e 63 ** by an instanc
35230 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 e of the followi
35240 6e 67 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 ng structure. T
35250 68 69 73 20 73 74 72 75 63 74 75 72 65 20 63 6f his structure co
35260 6e 73 69 73 74 73 0a 2a 2a 20 6d 6f 73 74 6c 79 nsists.** mostly
35270 20 6f 66 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 of methods for
35280 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a 73 the module..*/.s
35290 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f truct sqlite3_mo
352a0 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56 65 dule {. int iVe
352b0 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 rsion;. int (*x
352c0 43 72 65 61 74 65 29 28 73 71 6c 69 74 65 33 2a Create)(sqlite3*
352d0 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 , void *pAux,.
352e0 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 int
352f0 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 argc, const cha
35300 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 r *const*argv,.
35310 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 sq
35320 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 lite3_vtab **ppV
35330 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 Tab, char**);.
35340 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29 28 int (*xConnect)(
35350 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a sqlite3*, void *
35360 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 pAux,.
35370 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 int argc, c
35380 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 onst char *const
35390 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 *argv,.
353a0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 sqlite3_vt
353b0 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 ab **ppVTab, cha
353c0 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 r**);. int (*xB
353d0 65 73 74 49 6e 64 65 78 29 28 73 71 6c 69 74 65 estIndex)(sqlite
353e0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 3_vtab *pVTab, s
353f0 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 qlite3_index_inf
35400 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 69 o*);. int (*xDi
35410 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 sconnect)(sqlite
35420 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 3_vtab *pVTab);.
35430 20 20 69 6e 74 20 28 2a 78 44 65 73 74 72 6f 79 int (*xDestroy
35440 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a )(sqlite3_vtab *
35450 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a pVTab);. int (*
35460 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 xOpen)(sqlite3_v
35470 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 tab *pVTab, sqli
35480 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 te3_vtab_cursor
35490 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20 20 69 **ppCursor);. i
354a0 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c nt (*xClose)(sql
354b0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 ite3_vtab_cursor
354c0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c *);. int (*xFil
354d0 74 65 72 29 28 73 71 6c 69 74 65 33 5f 76 74 61 ter)(sqlite3_vta
354e0 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20 69 b_cursor*, int i
354f0 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68 61 dxNum, const cha
35500 72 20 2a 69 64 78 53 74 72 2c 0a 20 20 20 20 20 r *idxStr,.
35510 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 int a
35520 72 67 63 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c rgc, sqlite3_val
35530 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69 6e ue **argv);. in
35540 74 20 28 2a 78 4e 65 78 74 29 28 73 71 6c 69 74 t (*xNext)(sqlit
35550 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 e3_vtab_cursor*)
35560 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66 29 28 ;. int (*xEof)(
35570 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 sqlite3_vtab_cur
35580 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 sor*);. int (*x
35590 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33 5f Column)(sqlite3_
355a0 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 vtab_cursor*, sq
355b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
355c0 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 int);. int (*xR
355d0 6f 77 69 64 29 28 73 71 6c 69 74 65 33 5f 76 74 owid)(sqlite3_vt
355e0 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 ab_cursor*, sqli
355f0 74 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69 te3_int64 *pRowi
35600 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70 64 d);. int (*xUpd
35610 61 74 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 ate)(sqlite3_vta
35620 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 b *, int, sqlite
35630 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 3_value **, sqli
35640 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20 20 te3_int64 *);.
35650 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 28 73 71 int (*xBegin)(sq
35660 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 lite3_vtab *pVTa
35670 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e b);. int (*xSyn
35680 63 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 c)(sqlite3_vtab
35690 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 *pVTab);. int (
356a0 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74 65 *xCommit)(sqlite
356b0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 3_vtab *pVTab);.
356c0 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 int (*xRollbac
356d0 6b 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 k)(sqlite3_vtab
356e0 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 *pVTab);. int (
356f0 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29 28 *xFindFunction)(
35700 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 sqlite3_vtab *pV
35710 74 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20 63 tab, int nArg, c
35720 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
35730 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,.
35740 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 28 2a void (*
35750 2a 70 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 *pxFunc)(sqlite3
35760 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 _context*,int,sq
35770 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a lite3_value**),.
35780 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
35790 20 20 20 20 20 20 20 76 6f 69 64 20 2a 2a 70 70 void **pp
357a0 41 72 67 29 3b 0a 0a 20 20 69 6e 74 20 28 2a 78 Arg);.. int (*x
357b0 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f Rename)(sqlite3_
357c0 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e vtab *pVtab, con
357d0 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a st char *zNew);.
357e0 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 };../*.** CAPI3R
357f0 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c EF: Virtual Tabl
35800 65 20 49 6e 64 65 78 69 6e 67 20 49 6e 66 6f 72 e Indexing Infor
35810 6d 61 74 69 6f 6e 20 7b 46 31 38 31 30 30 7d 0a mation {F18100}.
35820 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c ** KEYWORDS: sql
35830 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a ite3_index_info.
35840 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
35850 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 3_index_info str
35860 75 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 ucture and its s
35870 75 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20 ubstructures is
35880 75 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20 used to.** pass
35890 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f information into
358a0 20 61 6e 64 20 72 65 63 65 69 76 65 20 74 68 65 and receive the
358b0 20 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 reply from the
358c0 78 42 65 73 74 49 6e 64 65 78 0a 2a 2a 20 6d 65 xBestIndex.** me
358d0 74 68 6f 64 20 6f 66 20 61 6e 20 73 71 6c 69 74 thod of an sqlit
358e0 65 33 5f 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 e3_module. The
358f0 66 69 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 fields under **I
35900 6e 70 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a nputs** are the.
35910 2a 2a 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65 ** inputs to xBe
35920 73 74 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20 stIndex and are
35930 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 read-only. xBes
35940 74 49 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69 tIndex inserts i
35950 74 73 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e ts.** results in
35960 74 6f 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 to the **Outputs
35970 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a ** fields..**.**
35980 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 The aConstraint
35990 5b 5d 20 61 72 72 61 79 20 72 65 63 6f 72 64 73 [] array records
359a0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f WHERE clause co
359b0 6e 73 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65 nstraints of the
359c0 0a 2a 2a 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 .** form:.**.**
359d0 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 20 4f column O
359e0 50 20 65 78 70 72 0a 2a 2a 0a 2a 2a 20 57 68 65 P expr.**.** Whe
359f0 72 65 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b re OP is =, <
35a00 2c 20 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f , <=, >, o
35a10 72 20 26 67 74 3b 3d 2e 20 20 0a 2a 2a 20 54 68 r >=. .** Th
35a20 65 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65 e particular ope
35a30 72 61 74 6f 72 20 69 73 20 73 74 6f 72 65 64 0a rator is stored.
35a40 2a 2a 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e ** in aConstrain
35a50 74 5b 5d 2e 6f 70 2e 20 20 54 68 65 20 69 6e 64 t[].op. The ind
35a60 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e ex of the column
35a70 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 0a 2a is stored in .*
35a80 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e * aConstraint[].
35a90 69 43 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73 74 iColumn. aConst
35aa0 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69 raint[].usable i
35ab0 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a s TRUE if the.**
35ac0 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67 expr on the rig
35ad0 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e ht-hand side can
35ae0 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 61 be evaluated (a
35af0 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73 nd thus the cons
35b00 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61 traint.** is usa
35b10 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69 ble) and false i
35b20 66 20 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a f it cannot..**.
35b30 2a 2a 20 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 ** The optimizer
35b40 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 automatically i
35b50 6e 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20 nverts terms of
35b60 74 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f the form "expr O
35b70 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 P column".** and
35b80 20 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d makes other sim
35b90 70 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 6f 20 plifications to
35ba0 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 the WHERE clause
35bb0 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74 in an attempt t
35bc0 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 o.** get as many
35bd0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 WHERE clause te
35be0 72 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 rms into the for
35bf0 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 m shown above as
35c00 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 54 68 possible..** Th
35c10 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 e aConstraint[]
35c20 61 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 array only repor
35c30 74 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 ts WHERE clause
35c40 74 65 72 6d 73 20 69 6e 20 74 68 65 20 63 6f 72 terms in the cor
35c50 72 65 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 68 61 rect.** form tha
35c60 74 20 72 65 66 65 72 20 74 6f 20 74 68 65 20 70 t refer to the p
35c70 61 72 74 69 63 75 6c 61 72 20 76 69 72 74 75 61 articular virtua
35c80 6c 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75 l table being qu
35c90 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66 eried..**.** Inf
35ca0 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 ormation about t
35cb0 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 he ORDER BY clau
35cc0 73 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 se is stored in
35cd0 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 45 aOrderBy[]..** E
35ce0 61 63 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 64 ach term of aOrd
35cf0 65 72 42 79 20 72 65 63 6f 72 64 73 20 61 20 63 erBy records a c
35d00 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44 olumn of the ORD
35d10 45 52 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a ER BY clause..**
35d20 0a 2a 2a 20 54 68 65 20 78 42 65 73 74 49 6e 64 .** The xBestInd
35d30 65 78 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 66 ex method must f
35d40 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 ill aConstraintU
35d50 73 61 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f sage[] with info
35d60 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 rmation.** about
35d70 20 77 68 61 74 20 70 61 72 61 6d 65 74 65 72 73 what parameters
35d80 20 74 6f 20 70 61 73 73 20 74 6f 20 78 46 69 6c to pass to xFil
35d90 74 65 72 2e 20 20 49 66 20 61 72 67 76 49 6e 64 ter. If argvInd
35da0 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 ex>0 then.** the
35db0 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 right-hand side
35dc0 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f of the correspo
35dd0 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e nding aConstrain
35de0 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64 t[] is evaluated
35df0 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 .** and becomes
35e00 74 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68 the argvIndex-th
35e10 20 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20 entry in argv.
35e20 20 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 If aConstraintU
35e30 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 sage[].omit.** i
35e40 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 s true, then the
35e50 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61 constraint is a
35e60 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c ssumed to be ful
35e70 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68 ly handled by th
35e80 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 e.** virtual tab
35e90 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 le and is not ch
35ea0 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53 ecked again by S
35eb0 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 QLite..**.** The
35ec0 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 50 idxNum and idxP
35ed0 74 72 20 76 61 6c 75 65 73 20 61 72 65 20 72 65 tr values are re
35ee0 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73 65 corded and passe
35ef0 64 20 69 6e 74 6f 20 78 46 69 6c 74 65 72 2e 0a d into xFilter..
35f00 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 ** sqlite3_free(
35f10 29 20 69 73 20 75 73 65 64 20 74 6f 20 66 72 65 ) is used to fre
35f20 65 20 69 64 78 50 74 72 20 69 66 20 6e 65 65 64 e idxPtr if need
35f30 54 6f 46 72 65 65 49 64 78 50 74 72 20 69 73 20 ToFreeIdxPtr is
35f40 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 true..**.** The
35f50 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 20 orderByConsumed
35f60 6d 65 61 6e 73 20 74 68 61 74 20 6f 75 74 70 75 means that outpu
35f70 74 20 66 72 6f 6d 20 78 46 69 6c 74 65 72 20 77 t from xFilter w
35f80 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 ill occur in.**
35f90 74 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 the correct orde
35fa0 72 20 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 r to satisfy the
35fb0 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 ORDER BY clause
35fc0 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61 so that no sepa
35fd0 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 rate.** sorting
35fe0 73 74 65 70 20 69 73 20 72 65 71 75 69 72 65 64 step is required
35ff0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 73 74 69 ..**.** The esti
36000 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20 matedCost value
36010 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f is an estimate o
36020 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f f the cost of do
36030 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 ing the.** parti
36040 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 cular lookup. A
36050 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 full scan of a
36060 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 table with N ent
36070 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 ries should have
36080 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e .** a cost of N.
36090 20 20 41 20 62 69 6e 61 72 79 20 73 65 61 72 63 A binary searc
360a0 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20 h of a table of
360b0 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 N entries should
360c0 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 have a.** cost
360d0 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 of approximately
360e0 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 log(N)..*/.stru
360f0 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 ct sqlite3_index
36100 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 _info {. /* Inp
36110 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f uts */. int nCo
36120 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 nstraint;
36130 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 /* Number of
36140 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e entries in aCon
36150 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 straint */. str
36160 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 uct sqlite3_inde
36170 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 x_constraint {.
36180 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b int iColumn;
36190 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
361a0 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d Column on left-
361b0 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e hand side of con
361c0 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 straint */.
361d0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 unsigned char op
361e0 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e ; /* Con
361f0 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 straint operator
36200 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 */. unsigne
36210 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 d char usable;
36220 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 /* True if th
36230 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 is constraint is
36240 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 usable */.
36250 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b int iTermOffset;
36260 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 /* Use
36270 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 d internally - x
36280 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 BestIndex should
36290 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a ignore */. } *
362a0 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 aConstraint;
362b0 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 /* Table
362c0 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 of WHERE clause
362d0 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a constraints */.
362e0 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 int nOrderBy;
362f0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
36300 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 Number of terms
36310 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 in the ORDER BY
36320 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 clause */. stru
36330 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 ct sqlite3_index
36340 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20 _orderby {.
36350 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 int iColumn;
36360 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c /* Col
36370 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 umn number */.
36380 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 unsigned char
36390 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 desc; /*
363a0 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20 True for DESC.
363b0 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a False for ASC. *
363c0 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b /. } *aOrderBy;
363d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
363e0 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59 20 63 * The ORDER BY c
363f0 6c 61 75 73 65 20 2a 2f 0a 0a 20 20 2f 2a 20 4f lause */.. /* O
36400 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 utputs */. stru
36410 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 ct sqlite3_index
36420 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 _constraint_usag
36430 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76 e {. int argv
36440 49 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20 20 Index;
36450 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 /* if >0, const
36460 72 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66 raint is part of
36470 20 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72 argv to xFilter
36480 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 */. unsigned
36490 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 char omit;
364a0 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 /* Do not code
364b0 61 20 74 65 73 74 20 66 6f 72 20 74 68 69 73 20 a test for this
364c0 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 constraint */.
364d0 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 } *aConstraintUs
364e0 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 age;. int idxNu
364f0 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 m;
36500 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 /* Number used
36510 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65 to identify the
36520 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 index */. char
36530 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20 20 *idxStr;
36540 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 /* String
36550 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 , possibly obtai
36560 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 ned from sqlite3
36570 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 _malloc */. int
36580 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 needToFreeIdxSt
36590 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 r; /* Free
365a0 69 64 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c idxStr using sql
365b0 69 74 65 33 5f 66 72 65 65 28 29 20 69 66 20 74 ite3_free() if t
365c0 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 rue */. int ord
365d0 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 erByConsumed;
365e0 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f /* True if o
365f0 75 74 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 utput is already
36600 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f ordered */. do
36610 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f uble estimatedCo
36620 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69 st; /* Esti
36630 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73 mated cost of us
36640 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a ing this index *
36650 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c /.};.#define SQL
36660 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 ITE_INDEX_CONSTR
36670 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65 AINT_EQ 2.#de
36680 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 fine SQLITE_INDE
36690 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 X_CONSTRAINT_GT
366a0 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 4.#define SQL
366b0 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 ITE_INDEX_CONSTR
366c0 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 AINT_LE 8.#de
366d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 fine SQLITE_INDE
366e0 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 X_CONSTRAINT_LT
366f0 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 16.#define SQ
36700 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 LITE_INDEX_CONST
36710 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 RAINT_GE 32.#
36720 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
36730 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d DEX_CONSTRAINT_M
36740 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 ATCH 64../*.** C
36750 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 API3REF: Registe
36760 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c r A Virtual Tabl
36770 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e Implementation
36780 20 7b 46 31 38 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 {F18200}.**.**
36790 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 This routine is
367a0 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 used to register
367b0 20 61 20 6e 65 77 20 6d 6f 64 75 6c 65 20 6e 61 a new module na
367c0 6d 65 20 77 69 74 68 20 61 6e 20 53 51 4c 69 74 me with an SQLit
367d0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e e.** connection.
367e0 20 20 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d Module names m
367f0 75 73 74 20 62 65 20 72 65 67 69 73 74 65 72 65 ust be registere
36800 64 20 62 65 66 6f 72 65 20 63 72 65 61 74 69 6e d before creatin
36810 67 20 6e 65 77 0a 2a 2a 20 76 69 72 74 75 61 6c g new.** virtual
36820 20 74 61 62 6c 65 73 20 6f 6e 20 74 68 65 20 6d tables on the m
36830 6f 64 75 6c 65 2c 20 6f 72 20 62 65 66 6f 72 65 odule, or before
36840 20 75 73 69 6e 67 20 70 72 65 65 78 69 73 74 69 using preexisti
36850 6e 67 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 ng virtual.** ta
36860 62 6c 65 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 bles of the modu
36870 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 le..*/.int sqlit
36880 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 e3_create_module
36890 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
368a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
368b0 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 * SQLite connect
368c0 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 ion to register
368d0 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 module with */.
368e0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
368f0 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e me, /* N
36900 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c ame of the modul
36910 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c e */. const sql
36920 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 ite3_module *,
36930 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 /* Methods for
36940 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 the module */.
36950 20 76 6f 69 64 20 2a 20 20 20 20 20 20 20 20 20 void *
36960 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 /* C
36970 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 lient data for x
36980 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 Create/xConnect
36990 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.);../*.** CAP
369a0 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 I3REF: Register
369b0 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 A Virtual Table
369c0 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 7b Implementation {
369d0 46 31 38 32 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 F18210}.**.** Th
369e0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 64 is routine is id
369f0 65 6e 74 69 63 61 6c 20 74 6f 20 74 68 65 20 73 entical to the s
36a00 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f qlite3_create_mo
36a10 64 75 6c 65 28 29 20 6d 65 74 68 6f 64 20 61 62 dule() method ab
36a20 6f 76 65 2c 0a 2a 2a 20 65 78 63 65 70 74 20 74 ove,.** except t
36a30 68 61 74 20 69 74 20 61 6c 6c 6f 77 73 20 61 20 hat it allows a
36a40 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 destructor funct
36a50 69 6f 6e 20 74 6f 20 62 65 20 73 70 65 63 69 66 ion to be specif
36a60 69 65 64 2e 20 49 74 20 69 73 0a 2a 2a 20 65 76 ied. It is.** ev
36a70 65 6e 20 6d 6f 72 65 20 65 78 70 65 72 69 6d 65 en more experime
36a80 6e 74 61 6c 20 74 68 61 6e 20 74 68 65 20 72 65 ntal than the re
36a90 73 74 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 st of the virtua
36aa0 6c 20 74 61 62 6c 65 73 20 41 50 49 2e 0a 2a 2f l tables API..*/
36ab0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 .int sqlite3_cre
36ac0 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 ate_module_v2(.
36ad0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
36ae0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 /* S
36af0 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e QLite connection
36b00 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 to register mod
36b10 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f ule with */. co
36b20 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
36b30 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 /* Name
36b40 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a of the module *
36b50 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 /. const sqlite
36b60 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 20 20 2f 3_module *, /
36b70 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 * Methods for th
36b80 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f e module */. vo
36b90 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 id *,
36ba0 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 /* Clie
36bb0 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 nt data for xCre
36bc0 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a ate/xConnect */.
36bd0 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 void(*xDestroy
36be0 29 28 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 )(void*) /*
36bf0 4d 6f 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f Module destructo
36c00 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b r function */.);
36c10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
36c20 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 : Virtual Table
36c30 49 6e 73 74 61 6e 63 65 20 4f 62 6a 65 63 74 20 Instance Object
36c40 7b 46 31 38 30 31 30 7d 0a 2a 2a 20 4b 45 59 57 {F18010}.** KEYW
36c50 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 ORDS: sqlite3_vt
36c60 61 62 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 6d ab.**.** Every m
36c70 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 odule implementa
36c80 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 tion uses a subc
36c90 6c 61 73 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c lass of the foll
36ca0 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 0a owing structure.
36cb0 2a 2a 20 74 6f 20 64 65 73 63 72 69 62 65 20 61 ** to describe a
36cc0 20 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 particular inst
36cd0 61 6e 63 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 ance of the modu
36ce0 6c 65 2e 20 20 45 61 63 68 20 73 75 62 63 6c 61 le. Each subcla
36cf0 73 73 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 ss will.** be ta
36d00 69 6c 6f 72 65 64 20 74 6f 20 74 68 65 20 73 70 ilored to the sp
36d10 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 20 ecific needs of
36d20 74 68 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 the module imple
36d30 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 20 54 68 65 mentation. The
36d40 0a 2a 2a 20 70 75 72 70 6f 73 65 20 6f 66 20 74 .** purpose of t
36d50 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 69 his superclass i
36d60 73 20 74 6f 20 64 65 66 69 6e 65 20 63 65 72 74 s to define cert
36d70 61 69 6e 20 66 69 65 6c 64 73 20 74 68 61 74 20 ain fields that
36d80 61 72 65 20 63 6f 6d 6d 6f 6e 0a 2a 2a 20 74 6f are common.** to
36d90 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c all module impl
36da0 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a ementations..**.
36db0 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 ** Virtual table
36dc0 73 20 6d 65 74 68 6f 64 73 20 63 61 6e 20 73 65 s methods can se
36dd0 74 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 t an error messa
36de0 67 65 20 62 79 20 61 73 73 69 67 6e 69 6e 67 20 ge by assigning
36df0 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74 61 a.** string obta
36e00 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 ined from sqlite
36e10 33 5f 6d 70 72 69 6e 74 66 28 29 20 74 6f 20 7a 3_mprintf() to z
36e20 45 72 72 4d 73 67 2e 20 20 54 68 65 20 6d 65 74 ErrMsg. The met
36e30 68 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 hod should.** ta
36e40 6b 65 20 63 61 72 65 20 74 68 61 74 20 61 6e 79 ke care that any
36e50 20 70 72 69 6f 72 20 73 74 72 69 6e 67 20 69 73 prior string is
36e60 20 66 72 65 65 64 20 62 79 20 61 20 63 61 6c 6c freed by a call
36e70 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 to sqlite3_free
36e80 28 29 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 ().** prior to a
36e90 73 73 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 ssigning a new s
36ea0 74 72 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 tring to zErrMsg
36eb0 2e 20 20 41 66 74 65 72 20 74 68 65 20 65 72 72 . After the err
36ec0 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 or message.** is
36ed0 20 64 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f delivered up to
36ee0 20 74 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c the client appl
36ef0 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 ication, the str
36f00 69 6e 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f ing will be auto
36f10 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 matically.** fre
36f20 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72 ed by sqlite3_fr
36f30 65 65 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72 ee() and the zEr
36f40 72 4d 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 rMsg field will
36f50 62 65 20 7a 65 72 6f 65 64 2e 20 20 4e 6f 74 65 be zeroed. Note
36f60 0a 2a 2a 20 74 68 61 74 20 73 71 6c 69 74 65 33 .** that sqlite3
36f70 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 _mprintf() and s
36f80 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61 72 qlite3_free() ar
36f90 65 20 75 73 65 64 20 6f 6e 20 74 68 65 20 7a 45 e used on the zE
36fa0 72 72 4d 73 67 20 66 69 65 6c 64 0a 2a 2a 20 73 rrMsg field.** s
36fb0 69 6e 63 65 20 76 69 72 74 75 61 6c 20 74 61 62 ince virtual tab
36fc0 6c 65 73 20 61 72 65 20 63 6f 6d 6d 6f 6e 6c 79 les are commonly
36fd0 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 implemented in
36fe0 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 loadable extensi
36ff0 6f 6e 73 20 77 68 69 63 68 0a 2a 2a 20 64 6f 20 ons which.** do
37000 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 20 not have access
37010 74 6f 20 73 71 6c 69 74 65 33 4d 50 72 69 6e 74 to sqlite3MPrint
37020 66 28 29 20 6f 72 20 73 71 6c 69 74 65 33 46 72 f() or sqlite3Fr
37030 65 65 28 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 ee()..*/.struct
37040 73 71 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 sqlite3_vtab {.
37050 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d const sqlite3_m
37060 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 odule *pModule;
37070 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 /* The module f
37080 6f 72 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 or this virtual
37090 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e table */. int n
370a0 52 65 66 3b 20 20 20 20 20 20 20 20 20 20 20 20 Ref;
370b0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 /* Us
370c0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2a 2f ed internally */
370d0 0a 20 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 . char *zErrMsg
370e0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ;
370f0 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 /* Error mess
37100 61 67 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 age from sqlite3
37110 5f 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 _mprintf() */.
37120 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 /* Virtual table
37130 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
37140 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 will typically
37150 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 add additional f
37160 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a ields */.};../*.
37170 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 ** CAPI3REF: Vir
37180 74 75 61 6c 20 54 61 62 6c 65 20 43 75 72 73 6f tual Table Curso
37190 72 20 4f 62 6a 65 63 74 20 20 7b 46 31 38 30 32 r Object {F1802
371a0 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 0}.** KEYWORDS:
371b0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 sqlite3_vtab_cur
371c0 73 6f 72 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 sor.**.** Every
371d0 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 module implement
371e0 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 ation uses a sub
371f0 63 6c 61 73 73 20 6f 66 20 74 68 65 20 66 6f 6c class of the fol
37200 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 lowing structure
37210 0a 2a 2a 20 74 6f 20 64 65 73 63 72 69 62 65 20 .** to describe
37220 63 75 72 73 6f 72 73 20 74 68 61 74 20 70 6f 69 cursors that poi
37230 6e 74 20 69 6e 74 6f 20 74 68 65 20 76 69 72 74 nt into the virt
37240 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 61 72 ual table and ar
37250 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f e used.** to loo
37260 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 76 69 p through the vi
37270 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 rtual table. Cu
37280 72 73 6f 72 73 20 61 72 65 20 63 72 65 61 74 65 rsors are create
37290 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 78 d using the.** x
372a0 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 Open method of t
372b0 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 he module. Each
372c0 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e module implemen
372d0 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69 tation will defi
372e0 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e ne.** the conten
372f0 74 20 6f 66 20 61 20 63 75 72 73 6f 72 20 73 74 t of a cursor st
37300 72 75 63 74 75 72 65 20 74 6f 20 73 75 69 74 20 ructure to suit
37310 69 74 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a its own needs..*
37320 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70 65 72 63 *.** This superc
37330 6c 61 73 73 20 65 78 69 73 74 73 20 69 6e 20 6f lass exists in o
37340 72 64 65 72 20 74 6f 20 64 65 66 69 6e 65 20 66 rder to define f
37350 69 65 6c 64 73 20 6f 66 20 74 68 65 20 63 75 72 ields of the cur
37360 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 sor that.** are
37370 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d common to all im
37380 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a plementations..*
37390 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 /.struct sqlite3
373a0 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 _vtab_cursor {.
373b0 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 sqlite3_vtab *p
373c0 56 74 61 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 Vtab; /* Vi
373d0 72 74 75 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 rtual table of t
373e0 68 69 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 his cursor */.
373f0 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 /* Virtual table
37400 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
37410 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 will typically
37420 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 add additional f
37430 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a ields */.};../*.
37440 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 ** CAPI3REF: Dec
37450 6c 61 72 65 20 54 68 65 20 53 63 68 65 6d 61 20 lare The Schema
37460 4f 66 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 Of A Virtual Tab
37470 6c 65 20 7b 46 31 38 32 38 30 7d 0a 2a 2a 0a 2a le {F18280}.**.*
37480 2a 20 54 68 65 20 78 43 72 65 61 74 65 20 61 6e * The xCreate an
37490 64 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f d xConnect metho
374a0 64 73 20 6f 66 20 61 20 6d 6f 64 75 6c 65 20 75 ds of a module u
374b0 73 65 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 se the following
374c0 20 41 50 49 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 API.** to decla
374d0 72 65 20 74 68 65 20 66 6f 72 6d 61 74 20 28 74 re the format (t
374e0 68 65 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 he names and dat
374f0 61 74 79 70 65 73 20 6f 66 20 74 68 65 20 63 6f atypes of the co
37500 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 lumns) of.** the
37510 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 virtual tables
37520 74 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a they implement..
37530 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 */.int sqlite3_d
37540 65 63 6c 61 72 65 5f 76 74 61 62 28 73 71 6c 69 eclare_vtab(sqli
37550 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 te3*, const char
37560 20 2a 7a 43 72 65 61 74 65 54 61 62 6c 65 29 3b *zCreateTable);
37570 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
37580 3a 20 4f 76 65 72 6c 6f 61 64 20 41 20 46 75 6e : Overload A Fun
37590 63 74 69 6f 6e 20 46 6f 72 20 41 20 56 69 72 74 ction For A Virt
375a0 75 61 6c 20 54 61 62 6c 65 20 7b 46 31 38 33 30 ual Table {F1830
375b0 30 7d 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 0}.**.** Virtual
375c0 20 74 61 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 tables can prov
375d0 69 64 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 ide alternative
375e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
375f0 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 of functions.**
37600 75 73 69 6e 67 20 74 68 65 20 78 46 69 6e 64 46 using the xFindF
37610 75 6e 63 74 69 6f 6e 20 6d 65 74 68 6f 64 2e 20 unction method.
37620 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 But global vers
37630 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66 75 ions of those fu
37640 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 nctions.** must
37650 65 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20 74 exist in order t
37660 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e o be overloaded.
37670 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 .**.** This API
37680 6d 61 6b 65 73 20 73 75 72 65 20 61 20 67 6c 6f makes sure a glo
37690 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 bal version of a
376a0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 function with a
376b0 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e particular.** n
376c0 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f ame and number o
376d0 66 20 70 61 72 61 6d 65 74 65 72 73 20 65 78 69 f parameters exi
376e0 73 74 73 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 sts. If no such
376f0 20 66 75 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 function exists
37700 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20 .** before this
37710 41 50 49 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 API is called, a
37720 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 new function is
37730 20 63 72 65 61 74 65 64 2e 20 20 54 68 65 20 69 created. The i
37740 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a mplementation.**
37750 20 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63 of the new func
37760 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73 tion always caus
37770 65 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 es an exception
37780 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 to be thrown. S
37790 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e o.** the new fun
377a0 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f ction is not goo
377b0 64 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 d for anything b
377c0 79 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f y itself. Its o
377d0 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 nly.** purpose i
377e0 73 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65 2d s to be a place-
377f0 68 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 holder function
37800 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 that can be over
37810 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20 76 69 72 loaded.** by vir
37820 74 75 61 6c 20 74 61 62 6c 65 73 2e 0a 2a 2a 0a tual tables..**.
37830 2a 2a 20 54 68 69 73 20 41 50 49 20 73 68 6f 75 ** This API shou
37840 6c 64 20 62 65 20 63 6f 6e 73 69 64 65 72 65 64 ld be considered
37850 20 70 61 72 74 20 6f 66 20 74 68 65 20 76 69 72 part of the vir
37860 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 tual table inter
37870 66 61 63 65 2c 0a 2a 2a 20 77 68 69 63 68 20 69 face,.** which i
37880 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 s experimental a
37890 6e 64 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 nd subject to ch
378a0 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c ange..*/.int sql
378b0 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 ite3_overload_fu
378c0 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c nction(sqlite3*,
378d0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 const char *zFu
378e0 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67 ncName, int nArg
378f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e );../*.** The in
37900 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 terface to the v
37910 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 irtual-table mec
37920 68 61 6e 69 73 6d 20 64 65 66 69 6e 65 64 20 61 hanism defined a
37930 62 6f 76 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a bove (back up.**
37940 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65 to a comment re
37950 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72 markably similar
37960 20 74 6f 20 74 68 69 73 20 6f 6e 65 29 20 69 73 to this one) is
37970 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 currently consi
37980 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 dered.** to be e
37990 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 xperimental. Th
379a0 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 e interface migh
379b0 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f t change in inco
379c0 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a mpatible ways..*
379d0 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70 * If this is a p
379e0 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 roblem for you,
379f0 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 do not use the i
37a00 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73 nterface at this
37a10 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 time..**.** Whe
37a20 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 n the virtual-ta
37a30 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 ble mechanism st
37a40 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c abilizes, we wil
37a50 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a l declare the.**
37a60 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 interface fixed
37a70 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 , support it ind
37a80 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 efinitely, and r
37a90 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 emove this comme
37aa0 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 nt..**.****** EX
37ab0 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 PERIMENTAL - sub
37ac0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 ject to change w
37ad0 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a ithout notice **
37ae0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a ************.*/.
37af0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
37b00 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20 A Handle To An
37b10 4f 70 65 6e 20 42 4c 4f 42 20 7b 46 31 37 38 30 Open BLOB {F1780
37b20 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 0}.**.** An inst
37b30 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a ance of this obj
37b40 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 ect represents a
37b50 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 n open BLOB on w
37b60 68 69 63 68 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e hich.** incremen
37b70 74 61 6c 20 49 2f 4f 20 63 61 6e 20 62 65 20 70 tal I/O can be p
37b80 72 65 66 6f 72 6d 65 64 2e 0a 2a 2a 20 4f 62 6a reformed..** Obj
37b90 65 63 74 73 20 6f 66 20 74 68 69 73 20 74 79 70 ects of this typ
37ba0 65 20 61 72 65 20 63 72 65 61 74 65 64 20 62 79 e are created by
37bb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f .** [sqlite3_blo
37bc0 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 64 65 b_open()] and de
37bd0 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 stroyed by [sqli
37be0 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 te3_blob_close()
37bf0 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 ]..** The [sqlit
37c00 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 e3_blob_read()]
37c10 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f and [sqlite3_blo
37c20 62 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72 b_write()] inter
37c30 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 faces.** can be
37c40 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20 used to read or
37c50 77 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 write small subs
37c60 65 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 ections of the b
37c70 6c 6f 62 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c lob..** The [sql
37c80 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 ite3_blob_bytes(
37c90 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
37ca0 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 urns the size of
37cb0 20 74 68 65 0a 2a 2a 20 62 6c 6f 62 20 69 6e 20 the.** blob in
37cc0 62 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 bytes..*/.typede
37cd0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
37ce0 5f 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c _blob sqlite3_bl
37cf0 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 ob;../*.** CAPI3
37d00 52 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 REF: Open A BLOB
37d10 20 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c For Incremental
37d20 20 49 2f 4f 20 7b 46 31 37 38 31 30 7d 0a 2a 2a I/O {F17810}.**
37d30 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 .** This interfa
37d40 63 65 73 20 6f 70 65 6e 73 20 61 20 68 61 6e 64 ces opens a hand
37d50 6c 65 20 74 6f 20 74 68 65 20 62 6c 6f 62 20 6c le to the blob l
37d60 6f 63 61 74 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 ocated.** in row
37d70 20 69 52 6f 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43 iRow, column zC
37d80 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 20 7a 54 61 olumn, table zTa
37d90 62 6c 65 20 69 6e 20 64 61 74 61 62 61 73 65 20 ble in database
37da0 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65 72 zDb;.** in other
37db0 20 77 6f 72 64 73 2c 20 20 74 68 65 20 73 61 6d words, the sam
37dc0 65 20 62 6c 6f 62 20 74 68 61 74 20 77 6f 75 6c e blob that woul
37dd0 64 20 62 65 20 73 65 6c 65 63 74 65 64 20 62 79 d be selected by
37de0 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a :.**.** <pre>.**
37df0 20 20 20 20 20 53 45 4c 45 43 54 20 7a 43 6f 6c SELECT zCol
37e00 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 umn FROM zDb.zTa
37e10 62 6c 65 20 57 48 45 52 45 20 72 6f 77 69 64 20 ble WHERE rowid
37e20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 = iRow;.** </pre
37e30 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 > {END}.**.** If
37e40 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d the flags param
37e50 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f eter is non-zero
37e60 2c 20 74 68 65 20 62 6c 6f 62 20 69 73 20 6f 70 , the blob is op
37e70 65 6e 65 64 20 66 6f 72 20 0a 2a 2a 20 72 65 61 ened for .** rea
37e80 64 20 61 6e 64 20 77 72 69 74 65 20 61 63 63 65 d and write acce
37e90 73 73 2e 20 49 66 20 69 74 20 69 73 20 7a 65 72 ss. If it is zer
37ea0 6f 2c 20 74 68 65 20 62 6c 6f 62 20 69 73 20 6f o, the blob is o
37eb0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 20 0a pened for read .
37ec0 2a 2a 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a ** access..**.**
37ed0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 64 Note that the d
37ee0 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 atabase name is
37ef0 6e 6f 74 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 not the filename
37f00 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 0a 2a that contains.*
37f10 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 * the database b
37f20 75 74 20 72 61 74 68 65 72 20 74 68 65 20 73 79 ut rather the sy
37f30 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 6f 66 20 74 mbolic name of t
37f40 68 65 20 64 61 74 61 62 61 73 65 20 74 68 61 74 he database that
37f50 0a 2a 2a 20 69 73 20 61 73 73 69 67 6e 65 64 20 .** is assigned
37f60 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 when the databas
37f70 65 20 69 73 20 63 6f 6e 6e 65 63 74 65 64 20 75 e is connected u
37f80 73 69 6e 67 20 5b 41 54 54 41 43 48 5d 2e 0a 2a sing [ATTACH]..*
37f90 2a 20 46 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 * For the main d
37fa0 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68 atabase file, th
37fb0 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 e database name
37fc0 69 73 20 22 6d 61 69 6e 22 2e 20 20 46 6f 72 0a is "main". For.
37fd0 2a 2a 20 54 45 4d 50 20 74 61 62 6c 65 73 2c 20 ** TEMP tables,
37fe0 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d the database nam
37ff0 65 20 69 73 20 22 74 65 6d 70 22 2e 0a 2a 2a 0a e is "temp"..**.
38000 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b ** On success, [
38010 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 SQLITE_OK] is re
38020 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65 20 6e turned and the n
38030 65 77 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ew .** [sqlite3_
38040 62 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61 6e 64 blob | blob hand
38050 6c 65 5d 20 69 73 20 77 72 69 74 74 65 6e 20 74 le] is written t
38060 6f 20 2a 70 70 42 6c 6f 62 2e 20 0a 2a 2a 20 4f o *ppBlob. .** O
38070 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f therwise an erro
38080 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e r code is return
38090 65 64 20 61 6e 64 20 0a 2a 2a 20 61 6e 79 20 76 ed and .** any v
380a0 61 6c 75 65 20 77 72 69 74 74 65 6e 20 74 6f 20 alue written to
380b0 2a 70 70 42 6c 6f 62 20 73 68 6f 75 6c 64 20 6e *ppBlob should n
380c0 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 74 68 ot be used by th
380d0 65 20 63 61 6c 6c 65 72 2e 0a 2a 2a 20 54 68 69 e caller..** Thi
380e0 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 s function sets
380f0 74 68 65 20 64 61 74 61 62 61 73 65 2d 68 61 6e the database-han
38100 64 6c 65 20 65 72 72 6f 72 20 63 6f 64 65 20 61 dle error code a
38110 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61 63 nd message.** ac
38120 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71 cessible via [sq
38130 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d lite3_errcode()]
38140 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 and [sqlite3_er
38150 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 0a 2a 2a 20 rmsg()]..** .**
38160 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
38170 2a 20 7b 46 31 37 38 31 33 7d 20 41 20 73 75 63 * {F17813} A suc
38180 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 cessful invocati
38190 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 on of the [sqlit
381a0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 44 2c 42 e3_blob_open(D,B
381b0 2c 54 2c 43 2c 52 2c 46 2c 50 29 5d 0a 2a 2a 20 ,T,C,R,F,P)].**
381c0 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 interfa
381d0 63 65 20 6f 70 65 6e 73 20 61 6e 20 5b 73 71 6c ce opens an [sql
381e0 69 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63 ite3_blob] objec
381f0 74 20 50 20 6f 6e 20 74 68 65 20 62 6c 6f 62 0a t P on the blob.
38200 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 63 ** in c
38210 6f 6c 75 6d 6e 20 43 20 6f 66 20 74 61 62 6c 65 olumn C of table
38220 20 54 20 69 6e 20 64 61 74 61 62 61 73 65 20 42 T in database B
38230 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f on [database co
38240 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a nnection] D..**.
38250 2a 2a 20 7b 46 31 37 38 31 34 7d 20 41 20 73 75 ** {F17814} A su
38260 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 ccessful invocat
38270 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f ion of [sqlite3_
38280 62 6c 6f 62 5f 6f 70 65 6e 28 44 2c 2e 2e 2e 29 blob_open(D,...)
38290 5d 20 73 74 61 72 74 73 0a 2a 2a 20 20 20 20 20 ] starts.**
382a0 20 20 20 20 20 61 20 6e 65 77 20 74 72 61 6e 73 a new trans
382b0 61 63 74 69 6f 6e 20 6f 6e 20 5b 64 61 74 61 62 action on [datab
382c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
382d0 44 20 69 66 20 74 68 61 74 20 63 6f 6e 6e 65 63 D if that connec
382e0 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 tion.**
382f0 20 69 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 is not already
38300 69 6e 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e in a transaction
38310 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 31 36 7d ..**.** {F17816}
38320 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c The [sqlite3_bl
38330 6f 62 5f 6f 70 65 6e 28 44 2c 42 2c 54 2c 43 2c ob_open(D,B,T,C,
38340 52 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 R,F,P)] interfac
38350 65 20 6f 70 65 6e 73 20 74 68 65 20 62 6c 6f 62 e opens the blob
38360 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 .** for
38370 20 72 65 61 64 20 61 6e 64 20 77 72 69 74 65 20 read and write
38380 61 63 63 65 73 73 20 69 66 20 61 6e 64 20 6f 6e access if and on
38390 6c 79 20 69 66 20 74 68 65 20 46 20 70 61 72 61 ly if the F para
383a0 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 meter.**
383b0 20 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a is non-zero..*
383c0 2a 0a 2a 2a 20 7b 46 31 37 38 31 39 7d 20 54 68 *.** {F17819} Th
383d0 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f e [sqlite3_blob_
383e0 6f 70 65 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 open()] interfac
383f0 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 e returns [SQLIT
38400 45 5f 4f 4b 5d 20 6f 6e 20 0a 2a 2a 20 20 20 20 E_OK] on .**
38410 20 20 20 20 20 20 73 75 63 63 65 73 73 20 61 6e success an
38420 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 d an appropriate
38430 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e [error code] on
38440 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 failure..**.**
38450 7b 46 31 37 38 32 31 7d 20 49 66 20 61 6e 20 65 {F17821} If an e
38460 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 rror occurs duri
38470 6e 67 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 ng evaluation of
38480 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f [sqlite3_blob_o
38490 70 65 6e 28 44 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 pen(D,...)].**
384a0 20 20 20 20 20 20 20 20 74 68 65 6e 20 73 75 62 then sub
384b0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f sequent calls to
384c0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 [sqlite3_errcod
384d0 65 28 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 e(D)],.**
384e0 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d [sqlite3_errm
384f0 73 67 28 44 29 5d 2c 20 61 6e 64 20 5b 73 71 6c sg(D)], and [sql
38500 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 44 29 ite3_errmsg16(D)
38510 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a ] will return.**
38520 20 20 20 20 20 20 20 20 20 20 69 6e 66 6f 72 6d inform
38530 61 74 69 6f 6e 20 61 70 70 72 6f 70 72 61 74 65 ation approprate
38540 20 66 6f 72 20 74 68 61 74 20 65 72 72 6f 72 2e for that error.
38550 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
38560 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c blob_open(. sql
38570 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 ite3*,. const c
38580 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 har *zDb,. cons
38590 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a t char *zTable,.
385a0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 const char *zC
385b0 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33 olumn,. sqlite3
385c0 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20 69 _int64 iRow,. i
385d0 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69 nt flags,. sqli
385e0 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f te3_blob **ppBlo
385f0 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 b.);../*.** CAPI
38600 33 52 45 46 3a 20 20 43 6c 6f 73 65 20 41 20 42 3REF: Close A B
38610 4c 4f 42 20 48 61 6e 64 6c 65 20 7b 46 31 37 38 LOB Handle {F178
38620 33 30 7d 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 20 30}.**.** Close
38630 61 6e 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 an open [sqlite3
38640 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 20 68 61 6e _blob | blob han
38650 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 dle]..**.** Clos
38660 69 6e 67 20 61 20 42 4c 4f 42 20 73 68 61 6c 6c ing a BLOB shall
38670 20 63 61 75 73 65 20 74 68 65 20 63 75 72 72 65 cause the curre
38680 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 nt transaction t
38690 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20 74 o commit.** if t
386a0 68 65 72 65 20 61 72 65 20 6e 6f 20 6f 74 68 65 here are no othe
386b0 72 20 42 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e 64 r BLOBs, no pend
386c0 69 6e 67 20 70 72 65 70 61 72 65 64 20 73 74 61 ing prepared sta
386d0 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 74 68 65 tements, and the
386e0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
386f0 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20 61 75 nection is in au
38700 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2e 0a 2a tocommit mode..*
38710 2a 20 49 66 20 61 6e 79 20 77 72 69 74 65 73 20 * If any writes
38720 77 65 72 65 20 6d 61 64 65 20 74 6f 20 74 68 65 were made to the
38730 20 42 4c 4f 42 2c 20 74 68 65 79 20 6d 69 67 68 BLOB, they migh
38740 74 20 62 65 20 68 65 6c 64 20 69 6e 20 63 61 63 t be held in cac
38750 68 65 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20 he.** until the
38760 63 6c 6f 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 close operation
38770 69 66 20 74 68 65 79 20 77 69 6c 6c 20 66 69 74 if they will fit
38780 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 43 6c 6f 73 69 . {END}.** Closi
38790 6e 67 20 74 68 65 20 42 4c 4f 42 20 6f 66 74 65 ng the BLOB ofte
387a0 6e 20 66 6f 72 63 65 73 20 74 68 65 20 63 68 61 n forces the cha
387b0 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 64 nges.** out to d
387c0 69 73 6b 20 61 6e 64 20 73 6f 20 69 66 20 61 6e isk and so if an
387d0 79 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f 63 63 y I/O errors occ
387e0 75 72 2c 20 74 68 65 79 20 77 69 6c 6c 20 6c 69 ur, they will li
387f0 6b 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 61 74 kely occur.** at
38800 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 20 74 the time when t
38810 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 he BLOB is close
38820 64 2e 20 20 7b 46 31 37 38 33 33 7d 20 41 6e 79 d. {F17833} Any
38830 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 errors that occ
38840 75 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f ur during.** clo
38850 73 69 6e 67 20 61 72 65 20 72 65 70 6f 72 74 65 sing are reporte
38860 64 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 d as a non-zero
38870 72 65 74 75 72 6e 20 76 61 6c 75 65 2e 0a 2a 2a return value..**
38880 0a 2a 2a 20 54 68 65 20 42 4c 4f 42 20 69 73 20 .** The BLOB is
38890 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69 74 69 closed unconditi
388a0 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20 69 66 onally. Even if
388b0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 this routine re
388c0 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 6f turns.** an erro
388d0 72 20 63 6f 64 65 2c 20 74 68 65 20 42 4c 4f 42 r code, the BLOB
388e0 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73 65 64 is still closed
388f0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
38900 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 33 TS:.**.** {F1783
38910 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 3} The [sqlite3_
38920 62 6c 6f 62 5f 63 6c 6f 73 65 28 50 29 5d 20 69 blob_close(P)] i
38930 6e 74 65 72 66 61 63 65 20 63 6c 6f 73 65 73 20 nterface closes
38940 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b an.** [
38950 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 sqlite3_blob] ob
38960 6a 65 63 74 20 50 20 70 72 65 76 69 6f 75 73 6c ject P previousl
38970 79 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 0a 2a y opened using.*
38980 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
38990 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d te3_blob_open()]
389a0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 33 36 7d ..**.** {F17836}
389b0 20 43 6c 6f 73 69 6e 67 20 61 6e 20 5b 73 71 6c Closing an [sql
389c0 69 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63 ite3_blob] objec
389d0 74 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 t using.**
389e0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f [sqlite3_blo
389f0 62 5f 63 6c 6f 73 65 28 29 5d 20 73 68 61 6c 6c b_close()] shall
38a00 20 63 61 75 73 65 20 74 68 65 20 63 75 72 72 65 cause the curre
38a10 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 nt transaction t
38a20 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f o.** co
38a30 6d 6d 69 74 20 69 66 20 74 68 65 72 65 20 61 72 mmit if there ar
38a40 65 20 6e 6f 20 6f 74 68 65 72 20 6f 70 65 6e 20 e no other open
38a50 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 6f [sqlite3_blob] o
38a60 62 6a 65 63 74 73 0a 2a 2a 20 20 20 20 20 20 20 bjects.**
38a70 20 20 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 or [prepared
38a80 73 74 61 74 65 6d 65 6e 74 73 5d 20 6f 6e 20 74 statements] on t
38a90 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 he same [databas
38aa0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e e connection] an
38ab0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 d.** th
38ac0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
38ad0 65 63 74 69 6f 6e 5d 20 69 73 20 69 6e 0a 2a 2a ection] is in.**
38ae0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
38af0 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 e3_get_autocommi
38b00 74 20 7c 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d t | autocommit m
38b10 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 ode]..**.** {F17
38b20 38 33 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 839} The [sqlite
38b30 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 50 29 5d 3_blob_close(P)]
38b40 20 69 6e 74 65 72 66 61 63 65 73 20 63 6c 6f 73 interfaces clos
38b50 65 73 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 es the .**
38b60 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f [sqlite3_blo
38b70 62 5d 20 6f 62 6a 65 63 74 20 50 20 75 6e 63 6f b] object P unco
38b80 6e 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 65 76 65 nditionally, eve
38b90 6e 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 n if.**
38ba0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 [sqlite3_blob_c
38bb0 6c 6f 73 65 28 50 29 5d 20 72 65 74 75 72 6e 73 lose(P)] returns
38bc0 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 something other
38bd0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b than [SQLITE_OK
38be0 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a ]..** .
38bf0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 */.int sqlite3_b
38c00 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 lob_close(sqlite
38c10 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 3_blob *);../*.*
38c20 2a 20 43 41 50 49 33 52 45 46 3a 20 20 52 65 74 * CAPI3REF: Ret
38c30 75 72 6e 20 54 68 65 20 53 69 7a 65 20 4f 66 20 urn The Size Of
38c40 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 20 7b 46 31 An Open BLOB {F1
38c50 37 38 34 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 7840}.**.** Retu
38c60 72 6e 20 74 68 65 20 73 69 7a 65 20 69 6e 20 62 rn the size in b
38c70 79 74 65 73 20 6f 66 20 74 68 65 20 62 6c 6f 62 ytes of the blob
38c80 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 accessible via
38c90 74 68 65 20 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 the open .** [sq
38ca0 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 lite3_blob] obje
38cb0 63 74 20 69 6e 20 69 74 73 20 6f 6e 6c 79 20 61 ct in its only a
38cc0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 rgument..**.** I
38cd0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
38ce0 20 7b 46 31 37 38 34 33 7d 20 54 68 65 20 5b 73 {F17843} The [s
38cf0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 qlite3_blob_byte
38d00 73 28 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 s(P)] interface
38d10 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 returns the size
38d20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 .** in
38d30 62 79 74 65 73 20 6f 66 20 74 68 65 20 42 4c 4f bytes of the BLO
38d40 42 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 B that the [sqli
38d50 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63 74 te3_blob] object
38d60 20 50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 P.** r
38d70 65 66 65 72 73 20 74 6f 2e 0a 2a 2f 0a 69 6e 74 efers to..*/.int
38d80 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 sqlite3_blob_by
38d90 74 65 73 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 tes(sqlite3_blob
38da0 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 *);../*.** CAPI
38db0 33 52 45 46 3a 20 20 52 65 61 64 20 44 61 74 61 3REF: Read Data
38dc0 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63 From A BLOB Inc
38dd0 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 46 31 37 38 rementally {F178
38de0 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 50}.**.** This f
38df0 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20 unction is used
38e00 74 6f 20 72 65 61 64 20 64 61 74 61 20 66 72 6f to read data fro
38e10 6d 20 61 6e 20 6f 70 65 6e 20 0a 2a 2a 20 5b 73 m an open .** [s
38e20 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c qlite3_blob | bl
38e30 6f 62 2d 68 61 6e 64 6c 65 5d 20 69 6e 74 6f 20 ob-handle] into
38e40 61 20 63 61 6c 6c 65 72 20 73 75 70 70 6c 69 65 a caller supplie
38e50 64 20 62 75 66 66 65 72 2e 0a 2a 2a 20 4e 20 62 d buffer..** N b
38e60 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72 65 ytes of data are
38e70 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 62 75 66 copied into buf
38e80 66 65 72 0a 2a 2a 20 5a 20 66 72 6f 6d 20 74 68 fer.** Z from th
38e90 65 20 6f 70 65 6e 20 62 6c 6f 62 2c 20 73 74 61 e open blob, sta
38ea0 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20 rting at offset
38eb0 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 iOffset..**.** I
38ec0 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 f offset iOffset
38ed0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 4e 20 is less than N
38ee0 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20 65 bytes from the e
38ef0 6e 64 20 6f 66 20 74 68 65 20 62 6c 6f 62 2c 20 nd of the blob,
38f00 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f .** [SQLITE_ERRO
38f10 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 R] is returned a
38f20 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65 nd no data is re
38f30 61 64 2e 20 20 49 66 20 4e 20 6f 72 20 69 4f 66 ad. If N or iOf
38f40 66 73 65 74 20 69 73 0a 2a 2a 20 6c 65 73 73 20 fset is.** less
38f50 74 68 61 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54 than zero [SQLIT
38f60 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 E_ERROR] is retu
38f70 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 rned and no data
38f80 20 69 73 20 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 is read..**.**
38f90 4f 6e 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49 On success, SQLI
38fa0 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 TE_OK is returne
38fb0 64 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e d. Otherwise, an
38fc0 20 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 .** [error code
38fd0 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 ] or an [extende
38fe0 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 d error code] is
38ff0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
39000 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
39010 2a 2a 20 7b 46 31 37 38 35 33 7d 20 54 68 65 20 ** {F17853} The
39020 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 [sqlite3_blob_re
39030 61 64 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69 6e 74 ad(P,Z,N,X)] int
39040 65 72 66 61 63 65 20 72 65 61 64 73 20 4e 20 62 erface reads N b
39050 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 ytes.**
39060 20 62 65 67 69 6e 6e 69 6e 67 20 61 74 20 6f 66 beginning at of
39070 66 73 65 74 20 58 20 66 72 6f 6d 0a 2a 2a 20 20 fset X from.**
39080 20 20 20 20 20 20 20 20 74 68 65 20 62 6c 6f 62 the blob
39090 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 62 that [sqlite3_b
390a0 6c 6f 62 5d 20 6f 62 6a 65 63 74 20 50 20 72 65 lob] object P re
390b0 66 65 72 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 fers to.**
390c0 20 20 20 20 61 6e 64 20 77 72 69 74 65 73 20 74 and writes t
390d0 68 6f 73 65 20 4e 20 62 79 74 65 73 20 69 6e 74 hose N bytes int
390e0 6f 20 62 75 66 66 65 72 20 5a 2e 0a 2a 2a 0a 2a o buffer Z..**.*
390f0 2a 20 7b 46 31 37 38 35 36 7d 20 49 6e 20 5b 73 * {F17856} In [s
39100 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 qlite3_blob_read
39110 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69 66 20 74 68 (P,Z,N,X)] if th
39120 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 6c e size of the bl
39130 6f 62 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 ob.** i
39140 73 20 6c 65 73 73 20 74 68 61 6e 20 4e 2b 58 20 s less than N+X
39150 62 79 74 65 73 2c 20 74 68 65 6e 20 74 68 65 20 bytes, then the
39160 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
39170 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 0a [SQLITE_ERROR].
39180 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 ** and
39190 6e 6f 74 68 69 6e 67 20 69 73 20 72 65 61 64 20 nothing is read
391a0 66 72 6f 6d 20 74 68 65 20 62 6c 6f 62 2e 0a 2a from the blob..*
391b0 2a 0a 2a 2a 20 7b 46 31 37 38 35 39 7d 20 49 6e *.** {F17859} In
391c0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 [sqlite3_blob_r
391d0 65 61 64 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69 66 ead(P,Z,N,X)] if
391e0 20 58 20 6f 72 20 4e 20 69 73 20 6c 65 73 73 20 X or N is less
391f0 74 68 61 6e 20 7a 65 72 6f 0a 2a 2a 20 20 20 20 than zero.**
39200 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 66 then the f
39210 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
39220 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 0a 2a [SQLITE_ERROR].*
39230 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 6e * and n
39240 6f 74 68 69 6e 67 20 69 73 20 72 65 61 64 20 66 othing is read f
39250 72 6f 6d 20 74 68 65 20 62 6c 6f 62 2e 0a 2a 2a rom the blob..**
39260 0a 2a 2a 20 7b 46 31 37 38 36 32 7d 20 54 68 65 .** {F17862} The
39270 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 [sqlite3_blob_r
39280 65 61 64 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69 6e ead(P,Z,N,X)] in
39290 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
392a0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 20 [SQLITE_OK].**
392b0 20 20 20 20 20 20 20 20 69 66 20 4e 20 62 79 74 if N byt
392c0 65 73 20 77 68 65 72 65 20 73 75 63 63 65 73 73 es where success
392d0 66 75 6c 6c 79 20 72 65 61 64 20 69 6e 74 6f 20 fully read into
392e0 62 75 66 66 65 72 20 5a 2e 0a 2a 2a 0a 2a 2a 20 buffer Z..**.**
392f0 7b 46 31 37 38 36 35 7d 20 49 66 20 74 68 65 20 {F17865} If the
39300 72 65 71 75 65 73 74 65 64 20 72 65 61 64 20 63 requested read c
39310 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 6f 6d 70 ould not be comp
39320 6c 65 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 leted,.**
39330 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f the [sqlite3_
39340 62 6c 6f 62 5f 72 65 61 64 28 50 2c 5a 2c 4e 2c blob_read(P,Z,N,
39350 58 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 X)] interface re
39360 74 75 72 6e 73 20 61 6e 0a 2a 2a 20 20 20 20 20 turns an.**
39370 20 20 20 20 20 61 70 70 72 6f 70 72 69 61 74 65 appropriate
39380 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 [error code] or
39390 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 [extended error
393a0 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 code]..**.** {F
393b0 31 37 38 36 38 7d 20 49 66 20 61 6e 20 65 72 72 17868} If an err
393c0 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 or occurs during
393d0 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 5b evaluation of [
393e0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 sqlite3_blob_rea
393f0 64 28 50 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 d(P,...)].**
39400 20 20 20 20 20 20 74 68 65 6e 20 73 75 62 73 65 then subse
39410 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b quent calls to [
39420 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
39430 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 D)],.**
39440 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
39450 28 44 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 (D)], and [sqlit
39460 65 33 5f 65 72 72 6d 73 67 31 36 28 44 29 5d 20 e3_errmsg16(D)]
39470 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 will return.**
39480 20 20 20 20 20 20 20 20 69 6e 66 6f 72 6d 61 74 informat
39490 69 6f 6e 20 61 70 70 72 6f 70 72 61 74 65 20 66 ion approprate f
394a0 6f 72 20 74 68 61 74 20 65 72 72 6f 72 2c 20 77 or that error, w
394b0 68 65 72 65 20 44 20 69 73 20 74 68 65 0a 2a 2a here D is the.**
394c0 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61 databa
394d0 73 65 20 68 61 6e 64 6c 65 20 74 68 61 74 20 77 se handle that w
394e0 61 73 20 75 73 65 64 20 74 6f 20 6f 70 65 6e 20 as used to open
394f0 62 6c 6f 62 20 68 61 6e 64 6c 65 20 50 2e 0a 2a blob handle P..*
39500 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c /.int sqlite3_bl
39510 6f 62 5f 72 65 61 64 28 73 71 6c 69 74 65 33 5f ob_read(sqlite3_
39520 62 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 5a 2c blob *, void *Z,
39530 20 69 6e 74 20 4e 2c 20 69 6e 74 20 69 4f 66 66 int N, int iOff
39540 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 set);../*.** CAP
39550 49 33 52 45 46 3a 20 20 57 72 69 74 65 20 44 61 I3REF: Write Da
39560 74 61 20 49 6e 74 6f 20 41 20 42 4c 4f 42 20 49 ta Into A BLOB I
39570 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 46 31 ncrementally {F1
39580 37 38 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 7870}.**.** This
39590 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 function is use
395a0 64 20 74 6f 20 77 72 69 74 65 20 64 61 74 61 20 d to write data
395b0 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 0a 2a 2a into an open .**
395c0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c [sqlite3_blob |
395d0 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 66 72 blob-handle] fr
395e0 6f 6d 20 61 20 75 73 65 72 20 73 75 70 70 6c 69 om a user suppli
395f0 65 64 20 62 75 66 66 65 72 2e 0a 2a 2a 20 6e 20 ed buffer..** n
39600 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72 bytes of data ar
39610 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 74 68 e copied from th
39620 65 20 62 75 66 66 65 72 0a 2a 2a 20 70 6f 69 6e e buffer.** poin
39630 74 65 64 20 74 6f 20 62 79 20 7a 20 69 6e 74 6f ted to by z into
39640 20 74 68 65 20 6f 70 65 6e 20 62 6c 6f 62 2c 20 the open blob,
39650 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73 starting at offs
39660 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a et iOffset..**.*
39670 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 * If the [sqlite
39680 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61 3_blob | blob-ha
39690 6e 64 6c 65 5d 20 70 61 73 73 65 64 20 61 73 20 ndle] passed as
396a0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
396b0 6e 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 70 nt.** was not op
396c0 65 6e 65 64 20 66 6f 72 20 77 72 69 74 69 6e 67 ened for writing
396d0 20 28 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 (the flags para
396e0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 meter to [sqlite
396f0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a 3_blob_open()].*
39700 2a 2a 20 77 61 73 20 7a 65 72 6f 29 2c 20 74 68 ** was zero), th
39710 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 is function retu
39720 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 rns [SQLITE_READ
39730 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 ONLY]..**.** Thi
39740 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6f s function may o
39750 6e 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 63 nly modify the c
39760 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 65 20 62 ontents of the b
39770 6c 6f 62 3b 20 69 74 20 69 73 0a 2a 2a 20 6e 6f lob; it is.** no
39780 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e t possible to in
39790 63 72 65 61 73 65 20 74 68 65 20 73 69 7a 65 20 crease the size
397a0 6f 66 20 61 20 62 6c 6f 62 20 75 73 69 6e 67 20 of a blob using
397b0 74 68 69 73 20 41 50 49 2e 0a 2a 2a 20 49 66 20 this API..** If
397c0 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 20 69 offset iOffset i
397d0 73 20 6c 65 73 73 20 74 68 61 6e 20 6e 20 62 79 s less than n by
397e0 74 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 tes from the end
397f0 20 6f 66 20 74 68 65 20 62 6c 6f 62 2c 20 0a 2a of the blob, .*
39800 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d * [SQLITE_ERROR]
39810 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 is returned and
39820 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69 74 no data is writ
39830 74 65 6e 2e 20 20 49 66 20 6e 20 69 73 0a 2a 2a ten. If n is.**
39840 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 20 less than zero
39850 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 [SQLITE_ERROR] i
39860 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e s returned and n
39870 6f 20 64 61 74 61 20 69 73 20 77 72 69 74 74 65 o data is writte
39880 6e 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 n..**.** On succ
39890 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 ess, SQLITE_OK i
398a0 73 20 72 65 74 75 72 6e 65 64 2e 20 4f 74 68 65 s returned. Othe
398b0 72 77 69 73 65 2c 20 61 6e 20 0a 2a 2a 20 5b 65 rwise, an .** [e
398c0 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e rror code] or an
398d0 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 [extended error
398e0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e code] is return
398f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 ed..**.** INVARI
39900 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 ANTS:.**.** {F17
39910 38 37 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 873} The [sqlite
39920 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 50 2c 5a 3_blob_write(P,Z
39930 2c 4e 2c 58 29 5d 20 69 6e 74 65 72 66 61 63 65 ,N,X)] interface
39940 20 77 72 69 74 65 73 20 4e 20 62 79 74 65 73 0a writes N bytes.
39950 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d ** from
39960 20 62 75 66 66 65 72 20 5a 20 69 6e 74 6f 0a 2a buffer Z into.*
39970 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62 * the b
39980 6c 6f 62 20 74 68 61 74 20 5b 73 71 6c 69 74 65 lob that [sqlite
39990 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63 74 20 50 3_blob] object P
399a0 20 72 65 66 65 72 73 20 74 6f 0a 2a 2a 20 20 20 refers to.**
399b0 20 20 20 20 20 20 20 62 65 67 69 6e 6e 69 6e 67 beginning
399c0 20 61 74 20 61 6e 20 6f 66 66 73 65 74 20 6f 66 at an offset of
399d0 20 58 20 69 6e 74 6f 20 74 68 65 20 62 6c 6f 62 X into the blob
399e0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 37 35 7d ..**.** {F17875}
399f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c The [sqlite3_bl
39a00 6f 62 5f 77 72 69 74 65 28 50 2c 5a 2c 4e 2c 58 ob_write(P,Z,N,X
39a10 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
39a20 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 urns.**
39a30 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c [SQLITE_READONL
39a40 59 5d 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 Y] if the [sqlit
39a50 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63 74 20 e3_blob] object
39a60 50 20 77 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 P was.**
39a70 20 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f [sqlite3_blob_
39a80 6f 70 65 6e 20 7c 20 6f 70 65 6e 65 64 5d 20 66 open | opened] f
39a90 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 2e or reading only.
39aa0 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 37 36 7d 20 .**.** {F17876}
39ab0 49 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 In [sqlite3_blob
39ac0 5f 77 72 69 74 65 28 50 2c 5a 2c 4e 2c 58 29 5d _write(P,Z,N,X)]
39ad0 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 if the size of
39ae0 74 68 65 20 62 6c 6f 62 0a 2a 2a 20 20 20 20 20 the blob.**
39af0 20 20 20 20 20 69 73 20 6c 65 73 73 20 74 68 61 is less tha
39b00 6e 20 4e 2b 58 20 62 79 74 65 73 2c 20 74 68 65 n N+X bytes, the
39b10 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 n the function r
39b20 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 45 eturns [SQLITE_E
39b30 52 52 4f 52 5d 0a 2a 2a 20 20 20 20 20 20 20 20 RROR].**
39b40 20 20 61 6e 64 20 6e 6f 74 68 69 6e 67 20 69 73 and nothing is
39b50 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 written into th
39b60 65 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 7b 46 e blob..**.** {F
39b70 31 37 38 37 39 7d 20 49 6e 20 5b 73 71 6c 69 74 17879} In [sqlit
39b80 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 50 2c e3_blob_write(P,
39b90 5a 2c 4e 2c 58 29 5d 20 69 66 20 58 20 6f 72 20 Z,N,X)] if X or
39ba0 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a N is less than z
39bb0 65 72 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ero.**
39bc0 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f then the functio
39bd0 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 n returns [SQLIT
39be0 45 5f 45 52 52 4f 52 5d 0a 2a 2a 20 20 20 20 20 E_ERROR].**
39bf0 20 20 20 20 20 61 6e 64 20 6e 6f 74 68 69 6e 67 and nothing
39c00 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f is written into
39c10 20 74 68 65 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a the blob..**.**
39c20 20 7b 46 31 37 38 38 32 7d 20 54 68 65 20 5b 73 {F17882} The [s
39c30 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 qlite3_blob_writ
39c40 65 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69 6e 74 65 e(P,Z,N,X)] inte
39c50 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 5b 53 rface returns [S
39c60 51 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 20 20 20 QLITE_OK].**
39c70 20 20 20 20 20 20 69 66 20 4e 20 62 79 74 65 73 if N bytes
39c80 20 77 68 65 72 65 20 73 75 63 63 65 73 73 66 75 where successfu
39c90 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f lly written into
39ca0 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 blob..**.** {F1
39cb0 37 38 38 35 7d 20 49 66 20 74 68 65 20 72 65 71 7885} If the req
39cc0 75 65 73 74 65 64 20 77 72 69 74 65 20 63 6f 75 uested write cou
39cd0 6c 64 20 6e 6f 74 20 62 65 20 63 6f 6d 70 6c 65 ld not be comple
39ce0 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ted,.**
39cf0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c the [sqlite3_bl
39d00 6f 62 5f 77 72 69 74 65 28 50 2c 5a 2c 4e 2c 58 ob_write(P,Z,N,X
39d10 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
39d20 75 72 6e 73 20 61 6e 0a 2a 2a 20 20 20 20 20 20 urns an.**
39d30 20 20 20 20 61 70 70 72 6f 70 72 69 61 74 65 20 appropriate
39d40 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 [error code] or
39d50 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 [extended error
39d60 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 code]..**.** {F1
39d70 37 38 38 38 7d 20 49 66 20 61 6e 20 65 72 72 6f 7888} If an erro
39d80 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 r occurs during
39d90 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 5b 73 evaluation of [s
39da0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 qlite3_blob_writ
39db0 65 28 44 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 e(D,...)].**
39dc0 20 20 20 20 20 20 74 68 65 6e 20 73 75 62 73 65 then subse
39dd0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b quent calls to [
39de0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
39df0 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 D)],.**
39e00 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
39e10 28 44 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 (D)], and [sqlit
39e20 65 33 5f 65 72 72 6d 73 67 31 36 28 44 29 5d 20 e3_errmsg16(D)]
39e30 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 will return.**
39e40 20 20 20 20 20 20 20 20 69 6e 66 6f 72 6d 61 74 informat
39e50 69 6f 6e 20 61 70 70 72 6f 70 72 61 74 65 20 66 ion approprate f
39e60 6f 72 20 74 68 61 74 20 65 72 72 6f 72 2e 0a 2a or that error..*
39e70 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c /.int sqlite3_bl
39e80 6f 62 5f 77 72 69 74 65 28 73 71 6c 69 74 65 33 ob_write(sqlite3
39e90 5f 62 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76 _blob *, const v
39ea0 6f 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 oid *z, int n, i
39eb0 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a nt iOffset);../*
39ec0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 56 .** CAPI3REF: V
39ed0 69 72 74 75 61 6c 20 46 69 6c 65 20 53 79 73 74 irtual File Syst
39ee0 65 6d 20 4f 62 6a 65 63 74 73 20 7b 46 31 31 32 em Objects {F112
39ef0 30 30 7d 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 00}.**.** A virt
39f00 75 61 6c 20 66 69 6c 65 73 79 73 74 65 6d 20 28 ual filesystem (
39f10 56 46 53 29 20 69 73 20 61 6e 20 5b 73 71 6c 69 VFS) is an [sqli
39f20 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a te3_vfs] object.
39f30 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 75 ** that SQLite u
39f40 73 65 73 20 74 6f 20 69 6e 74 65 72 61 63 74 0a ses to interact.
39f50 2a 2a 20 77 69 74 68 20 74 68 65 20 75 6e 64 65 ** with the unde
39f60 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 rlying operating
39f70 20 73 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20 53 system. Most S
39f80 51 4c 69 74 65 20 62 75 69 6c 64 73 20 63 6f 6d QLite builds com
39f90 65 20 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67 e with a.** sing
39fa0 6c 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 74 le default VFS t
39fb0 68 61 74 20 69 73 20 61 70 70 72 6f 70 72 69 61 hat is appropria
39fc0 74 65 20 66 6f 72 20 74 68 65 20 68 6f 73 74 20 te for the host
39fd0 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 computer..** New
39fe0 20 56 46 53 65 73 20 63 61 6e 20 62 65 20 72 65 VFSes can be re
39ff0 67 69 73 74 65 72 65 64 20 61 6e 64 20 65 78 69 gistered and exi
3a000 73 74 69 6e 67 20 56 46 53 65 73 20 63 61 6e 20 sting VFSes can
3a010 62 65 20 75 6e 72 65 67 69 73 74 65 72 65 64 2e be unregistered.
3a020 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e .** The followin
3a030 67 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 g interfaces are
3a040 20 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a provided..**.**
3a050 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 The sqlite3_vfs
3a060 5f 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61 63 _find() interfac
3a070 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e e returns a poin
3a080 74 65 72 20 74 6f 20 0a 2a 2a 20 61 20 56 46 53 ter to .** a VFS
3a090 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e given its name.
3a0a0 20 20 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65 Names are case
3a0b0 20 73 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 4e sensitive..** N
3a0c0 61 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d 74 65 ames are zero-te
3a0d0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 rminated UTF-8 s
3a0e0 74 72 69 6e 67 73 2e 0a 2a 2a 20 49 66 20 74 68 trings..** If th
3a0f0 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c ere is no match,
3a100 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 a NULL.** point
3a110 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 er is returned.
3a120 20 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 20 If zVfsName is
3a130 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 65 NULL then the de
3a140 66 61 75 6c 74 20 0a 2a 2a 20 56 46 53 20 69 73 fault .** VFS is
3a150 20 72 65 74 75 72 6e 65 64 2e 20 0a 2a 2a 0a 2a returned. .**.*
3a160 2a 20 4e 65 77 20 56 46 53 65 73 20 61 72 65 20 * New VFSes are
3a170 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 registered with
3a180 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 sqlite3_vfs_regi
3a190 73 74 65 72 28 29 2e 0a 2a 2a 20 45 61 63 68 20 ster()..** Each
3a1a0 6e 65 77 20 56 46 53 20 62 65 63 6f 6d 65 73 20 new VFS becomes
3a1b0 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 the default VFS
3a1c0 69 66 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 if the makeDflt
3a1d0 66 6c 61 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20 flag is set..**
3a1e0 54 68 65 20 73 61 6d 65 20 56 46 53 20 63 61 6e The same VFS can
3a1f0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d be registered m
3a200 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 ultiple times wi
3a210 74 68 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a thout injury..**
3a220 20 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69 73 To make an exis
3a230 74 69 6e 67 20 56 46 53 20 69 6e 74 6f 20 74 68 ting VFS into th
3a240 65 20 64 65 66 61 75 6c 74 20 56 46 53 2c 20 72 e default VFS, r
3a250 65 67 69 73 74 65 72 20 69 74 20 61 67 61 69 6e egister it again
3a260 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6d 61 6b .** with the mak
3a270 65 44 66 6c 74 20 66 6c 61 67 20 73 65 74 2e 20 eDflt flag set.
3a280 20 49 66 20 74 77 6f 20 64 69 66 66 65 72 65 6e If two differen
3a290 74 20 56 46 53 65 73 20 77 69 74 68 20 74 68 65 t VFSes with the
3a2a0 0a 2a 2a 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 .** same name ar
3a2b0 65 20 72 65 67 69 73 74 65 72 65 64 2c 20 74 68 e registered, th
3a2c0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e e behavior is un
3a2d0 64 65 66 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a defined. If a.*
3a2e0 2a 20 56 46 53 20 69 73 20 72 65 67 69 73 74 65 * VFS is registe
3a2f0 72 65 64 20 77 69 74 68 20 61 20 6e 61 6d 65 20 red with a name
3a300 74 68 61 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20 that is NULL or
3a310 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c an empty string,
3a320 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 .** then the beh
3a330 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e avior is undefin
3a340 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 55 6e 72 65 67 ed..** .** Unreg
3a350 69 73 74 65 72 20 61 20 56 46 53 20 77 69 74 68 ister a VFS with
3a360 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 the sqlite3_vfs
3a370 5f 75 6e 72 65 67 69 73 74 65 72 28 29 20 69 6e _unregister() in
3a380 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 66 20 74 terface..** If t
3a390 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 he default VFS i
3a3a0 73 20 75 6e 72 65 67 69 73 74 65 72 65 64 2c 20 s unregistered,
3a3b0 61 6e 6f 74 68 65 72 20 56 46 53 20 69 73 20 63 another VFS is c
3a3c0 68 6f 73 65 6e 20 61 73 0a 2a 2a 20 74 68 65 20 hosen as.** the
3a3d0 64 65 66 61 75 6c 74 2e 20 20 54 68 65 20 63 68 default. The ch
3a3e0 6f 69 63 65 20 66 6f 72 20 74 68 65 20 6e 65 77 oice for the new
3a3f0 20 56 46 53 20 69 73 20 61 72 62 69 74 72 61 72 VFS is arbitrar
3a400 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 y..**.** INVARIA
3a410 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 32 NTS:.**.** {F112
3a420 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 03} The [sqlite3
3a430 5f 76 66 73 5f 66 69 6e 64 28 4e 29 5d 20 69 6e _vfs_find(N)] in
3a440 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
3a450 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
3a460 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 .** reg
3a470 69 73 74 65 72 65 64 20 5b 73 71 6c 69 74 65 33 istered [sqlite3
3a480 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 77 68 6f _vfs] object who
3a490 73 65 20 6e 61 6d 65 20 65 78 61 63 74 6c 79 20 se name exactly
3a4a0 6d 61 74 63 68 65 73 0a 2a 2a 20 20 20 20 20 20 matches.**
3a4b0 20 20 20 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 the zero-ter
3a4c0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 minated UTF-8 st
3a4d0 72 69 6e 67 20 4e 2c 20 6f 72 20 69 74 20 72 65 ring N, or it re
3a4e0 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 0a 2a 2a turns NULL if.**
3a4f0 20 20 20 20 20 20 20 20 20 20 74 68 65 72 65 20 there
3a500 69 73 20 6e 6f 20 6d 61 74 63 68 2e 0a 2a 2a 0a is no match..**.
3a510 2a 2a 20 7b 46 31 31 32 30 36 7d 20 49 66 20 74 ** {F11206} If t
3a520 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 he N parameter t
3a530 6f 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 o [sqlite3_vfs_f
3a540 69 6e 64 28 4e 29 5d 20 69 73 20 4e 55 4c 4c 20 ind(N)] is NULL
3a550 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 then.**
3a560 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 the function re
3a570 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
3a580 74 6f 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b to the default [
3a590 73 71 6c 69 74 65 33 5f 76 66 73 5d 0a 2a 2a 20 sqlite3_vfs].**
3a5a0 20 20 20 20 20 20 20 20 20 6f 62 6a 65 63 74 20 object
3a5b0 69 66 20 74 68 65 72 65 20 69 73 20 6f 6e 65 2c if there is one,
3a5c0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 72 or NULL if ther
3a5d0 65 20 69 73 20 6e 6f 20 64 65 66 61 75 6c 74 20 e is no default
3a5e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
3a5f0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
3a600 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 32 30 39 t..**.** {F11209
3a610 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 } The [sqlite3_v
3a620 66 73 5f 72 65 67 69 73 74 65 72 28 50 2c 46 29 fs_register(P,F)
3a630 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 ] interface regi
3a640 73 74 65 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 sters the.**
3a650 20 20 20 20 20 20 77 65 6c 6c 2d 66 6f 72 6d 65 well-forme
3a660 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 d [sqlite3_vfs]
3a670 6f 62 6a 65 63 74 20 50 20 75 73 69 6e 67 20 74 object P using t
3a680 68 65 20 6e 61 6d 65 20 67 69 76 65 6e 0a 2a 2a he name given.**
3a690 20 20 20 20 20 20 20 20 20 20 62 79 20 74 68 65 by the
3a6a0 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 6f 66 20 zName field of
3a6b0 74 68 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a the object..**.*
3a6c0 2a 20 7b 46 31 31 32 31 32 7d 20 55 73 69 6e 67 * {F11212} Using
3a6d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 the [sqlite3_vf
3a6e0 73 5f 72 65 67 69 73 74 65 72 28 50 2c 46 29 5d s_register(P,F)]
3a6f0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 72 65 interface to re
3a700 67 69 73 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 gister.**
3a710 20 20 20 74 68 65 20 73 61 6d 65 20 5b 73 71 6c the same [sql
3a720 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
3a730 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 multiple times
3a740 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f is a harmless no
3a750 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 32 -op..**.** {F112
3a760 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 15} The [sqlite3
3a770 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 50 2c _vfs_register(P,
3a780 46 29 5d 20 69 6e 74 65 72 66 61 63 65 20 6d 61 F)] interface ma
3a790 6b 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 kes the.**
3a7a0 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 the [sqlite3
3a7b0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 50 20 74 _vfs] object P t
3a7c0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 he default [sqli
3a7d0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a te3_vfs] object.
3a7e0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 46 ** if F
3a7f0 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a is non-zero..**
3a800 0a 2a 2a 20 7b 46 31 31 32 31 38 7d 20 54 68 65 .** {F11218} The
3a810 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e [sqlite3_vfs_un
3a820 72 65 67 69 73 74 65 72 28 50 29 5d 20 69 6e 74 register(P)] int
3a830 65 72 66 61 63 65 20 75 6e 72 65 67 69 73 74 65 erface unregiste
3a840 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 rs the.**
3a850 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d [sqlite3_vfs]
3a860 20 6f 62 6a 65 63 74 20 50 20 73 6f 20 74 68 61 object P so tha
3a870 74 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 t it is no longe
3a880 72 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a r returned by.**
3a890 20 20 20 20 20 20 20 20 20 20 73 75 62 73 65 71 subseq
3a8a0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 uent calls to [s
3a8b0 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 qlite3_vfs_find(
3a8c0 29 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 )]..*/.sqlite3_v
3a8d0 66 73 20 2a 73 71 6c 69 74 65 33 5f 76 66 73 5f fs *sqlite3_vfs_
3a8e0 66 69 6e 64 28 63 6f 6e 73 74 20 63 68 61 72 20 find(const char
3a8f0 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 69 6e 74 20 *zVfsName);.int
3a900 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 sqlite3_vfs_regi
3a910 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73 ster(sqlite3_vfs
3a920 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 66 6c 74 29 *, int makeDflt)
3a930 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 ;.int sqlite3_vf
3a940 73 5f 75 6e 72 65 67 69 73 74 65 72 28 73 71 6c s_unregister(sql
3a950 69 74 65 33 5f 76 66 73 2a 29 3b 0a 0a 2f 2a 0a ite3_vfs*);../*.
3a960 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 ** CAPI3REF: Mut
3a970 65 78 65 73 20 7b 46 31 37 30 30 30 7d 0a 2a 2a exes {F17000}.**
3a980 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 .** The SQLite c
3a990 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 72 ore uses these r
3a9a0 6f 75 74 69 6e 65 73 20 66 6f 72 20 74 68 72 65 outines for thre
3a9b0 61 64 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e 69 7a ad.** synchroniz
3a9c0 61 74 69 6f 6e 2e 20 20 54 68 6f 75 67 68 20 74 ation. Though t
3a9d0 68 65 79 20 61 72 65 20 69 6e 74 65 6e 64 65 64 hey are intended
3a9e0 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a for internal.**
3a9f0 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 2c 20 use by SQLite,
3aa00 63 6f 64 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 code that links
3aa10 61 67 61 69 6e 73 74 20 53 51 4c 69 74 65 20 69 against SQLite i
3aa20 73 0a 2a 2a 20 70 65 72 6d 69 74 74 65 64 20 74 s.** permitted t
3aa30 6f 20 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65 o use any of the
3aa40 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a se routines..**.
3aa50 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 73 6f ** The SQLite so
3aa60 75 72 63 65 20 63 6f 64 65 20 63 6f 6e 74 61 69 urce code contai
3aa70 6e 73 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c ns multiple impl
3aa80 65 6d 65 6e 74 61 74 69 6f 6e 73 20 0a 2a 2a 20 ementations .**
3aa90 6f 66 20 74 68 65 73 65 20 6d 75 74 65 78 20 72 of these mutex r
3aaa0 6f 75 74 69 6e 65 73 2e 20 20 41 6e 20 61 70 70 outines. An app
3aab0 72 6f 70 72 69 61 74 65 20 69 6d 70 6c 65 6d 65 ropriate impleme
3aac0 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 ntation.** is se
3aad0 6c 65 63 74 65 64 20 61 75 74 6f 6d 61 74 69 63 lected automatic
3aae0 61 6c 6c 79 20 61 74 20 63 6f 6d 70 69 6c 65 2d ally at compile-
3aaf0 74 69 6d 65 2e 20 20 54 68 65 20 66 6f 6c 6c 6f time. The follo
3ab00 77 69 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e wing.** implemen
3ab10 74 61 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69 tations are avai
3ab20 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 53 51 4c lable in the SQL
3ab30 69 74 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 ite core:.**.**
3ab40 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 <ul>.** <li> S
3ab50 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 0a QLITE_MUTEX_OS2.
3ab60 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 ** <li> SQLITE
3ab70 5f 4d 55 54 45 58 5f 50 54 48 52 45 41 44 0a 2a _MUTEX_PTHREAD.*
3ab80 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f * <li> SQLITE_
3ab90 4d 55 54 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69 MUTEX_W32.** <li
3aba0 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 > SQLITE_MUTEX
3abb0 5f 4e 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a _NOOP.** </ul>.*
3abc0 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f *.** The SQLITE_
3abd0 4d 55 54 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 MUTEX_NOOP imple
3abe0 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 20 73 mentation is a s
3abf0 65 74 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 0a et of routines .
3ac00 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 20 ** that does no
3ac10 72 65 61 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 real locking and
3ac20 20 69 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 is appropriate
3ac30 66 6f 72 20 75 73 65 20 69 6e 20 0a 2a 2a 20 61 for use in .** a
3ac40 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 single-threaded
3ac50 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 application. T
3ac60 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f he SQLITE_MUTEX_
3ac70 4f 53 32 2c 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d OS2,.** SQLITE_M
3ac80 55 54 45 58 5f 50 54 48 52 45 41 44 2c 20 61 6e UTEX_PTHREAD, an
3ac90 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 d SQLITE_MUTEX_W
3aca0 33 32 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 32 implementatio
3acb0 6e 73 0a 2a 2a 20 61 72 65 20 61 70 70 72 6f 70 ns.** are approp
3acc0 72 69 61 74 65 20 66 6f 72 20 75 73 65 20 6f 6e riate for use on
3acd0 20 6f 73 2f 32 2c 20 75 6e 69 78 2c 20 61 6e 64 os/2, unix, and
3ace0 20 77 69 6e 64 6f 77 73 2e 0a 2a 2a 20 0a 2a 2a windows..** .**
3acf0 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f If SQLite is co
3ad00 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 mpiled with the
3ad10 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 SQLITE_MUTEX_APP
3ad20 44 45 46 20 70 72 65 70 72 6f 63 65 73 73 6f 72 DEF preprocessor
3ad30 0a 2a 2a 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 .** macro define
3ad40 64 20 28 77 69 74 68 20 22 2d 44 53 51 4c 49 54 d (with "-DSQLIT
3ad50 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 3d 31 E_MUTEX_APPDEF=1
3ad60 22 29 2c 20 74 68 65 6e 20 6e 6f 20 6d 75 74 65 "), then no mute
3ad70 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 x.** implementat
3ad80 69 6f 6e 20 69 73 20 69 6e 63 6c 75 64 65 64 20 ion is included
3ad90 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 with the library
3ada0 2e 20 20 54 68 65 0a 2a 2a 20 6d 75 74 65 78 20 . The.** mutex
3adb0 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e interface routin
3adc0 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 20 es defined here
3add0 62 65 63 6f 6d 65 20 65 78 74 65 72 6e 61 6c 0a become external.
3ade0 2a 2a 20 72 65 66 65 72 65 6e 63 65 73 20 69 6e ** references in
3adf0 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 the SQLite libr
3ae00 61 72 79 20 66 6f 72 20 77 68 69 63 68 20 69 6d ary for which im
3ae10 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a plementations.**
3ae20 20 6d 75 73 74 20 62 65 20 70 72 6f 76 69 64 65 must be provide
3ae30 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 d by the applica
3ae40 74 69 6f 6e 2e 20 20 54 68 69 73 20 66 61 63 69 tion. This faci
3ae50 6c 69 74 79 20 61 6c 6c 6f 77 73 20 61 6e 0a 2a lity allows an.*
3ae60 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 * application th
3ae70 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 at links against
3ae80 20 53 51 4c 69 74 65 20 74 6f 20 70 72 6f 76 69 SQLite to provi
3ae90 64 65 20 69 74 73 20 6f 77 6e 20 6d 75 74 65 78 de its own mutex
3aea0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
3aeb0 6f 6e 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e on without havin
3aec0 67 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 g to modify the
3aed0 53 51 4c 69 74 65 20 63 6f 72 65 2e 0a 2a 2a 0a SQLite core..**.
3aee0 2a 2a 20 7b 46 31 37 30 31 31 7d 20 54 68 65 20 ** {F17011} The
3aef0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c sqlite3_mutex_al
3af00 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 61 6c loc() routine al
3af10 6c 6f 63 61 74 65 73 20 61 20 6e 65 77 0a 2a 2a locates a new.**
3af20 20 6d 75 74 65 78 20 61 6e 64 20 72 65 74 75 72 mutex and retur
3af30 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
3af40 69 74 2e 20 7b 46 31 37 30 31 32 7d 20 49 66 20 it. {F17012} If
3af50 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 0a it returns NULL.
3af60 2a 2a 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 ** that means th
3af70 61 74 20 61 20 6d 75 74 65 78 20 63 6f 75 6c 64 at a mutex could
3af80 20 6e 6f 74 20 62 65 20 61 6c 6c 6f 63 61 74 65 not be allocate
3af90 64 2e 20 7b 46 31 37 30 31 33 7d 20 53 51 4c 69 d. {F17013} SQLi
3afa0 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77 69 6e te.** will unwin
3afb0 64 20 69 74 73 20 73 74 61 63 6b 20 61 6e 64 20 d its stack and
3afc0 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e return an error.
3afd0 20 7b 46 31 37 30 31 34 7d 20 54 68 65 20 61 72 {F17014} The ar
3afe0 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c gument.** to sql
3aff0 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 ite3_mutex_alloc
3b000 28 29 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 () is one of the
3b010 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 se integer const
3b020 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ants:.**.** <ul>
3b030 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 .** <li> SQLITE
3b040 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 3c _MUTEX_FAST.** <
3b050 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 li> SQLITE_MUTE
3b060 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 3c X_RECURSIVE.** <
3b070 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 li> SQLITE_MUTE
3b080 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 0a X_STATIC_MASTER.
3b090 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f ** <li> SQLITE_
3b0a0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d MUTEX_STATIC_MEM
3b0b0 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 .** <li> SQLITE
3b0c0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 _MUTEX_STATIC_ME
3b0d0 4d 32 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 M2.** <li> SQLI
3b0e0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
3b0f0 50 52 4e 47 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 PRNG.** <li> SQ
3b100 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
3b110 43 5f 4c 52 55 0a 2a 2a 20 3c 6c 69 3e 20 20 53 C_LRU.** <li> S
3b120 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 QLITE_MUTEX_STAT
3b130 49 43 5f 4c 52 55 32 0a 2a 2a 20 3c 2f 75 6c 3e IC_LRU2.** </ul>
3b140 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 {END}.**.** {F1
3b150 37 30 31 35 7d 20 54 68 65 20 66 69 72 73 74 20 7015} The first
3b160 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 two constants ca
3b170 75 73 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 use sqlite3_mute
3b180 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20 63 72 65 x_alloc() to cre
3b190 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20 6d 75 74 ate.** a new mut
3b1a0 65 78 2e 20 20 54 68 65 20 6e 65 77 20 6d 75 74 ex. The new mut
3b1b0 65 78 20 69 73 20 72 65 63 75 72 73 69 76 65 20 ex is recursive
3b1c0 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 when SQLITE_MUTE
3b1d0 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 69 X_RECURSIVE.** i
3b1e0 73 20 75 73 65 64 20 62 75 74 20 6e 6f 74 20 6e s used but not n
3b1f0 65 63 65 73 73 61 72 69 6c 79 20 73 6f 20 77 68 ecessarily so wh
3b200 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f en SQLITE_MUTEX_
3b210 46 41 53 54 20 69 73 20 75 73 65 64 2e 20 7b 45 FAST is used. {E
3b220 4e 44 7d 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 ND}.** The mutex
3b230 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
3b240 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f does not need to
3b250 20 6d 61 6b 65 20 61 20 64 69 73 74 69 6e 63 74 make a distinct
3b260 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 ion.** between S
3b270 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 QLITE_MUTEX_RECU
3b280 52 53 49 56 45 20 61 6e 64 20 53 51 4c 49 54 45 RSIVE and SQLITE
3b290 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 66 20 69 _MUTEX_FAST if i
3b2a0 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 t does.** not wa
3b2b0 6e 74 20 74 6f 2e 20 20 7b 46 31 37 30 31 36 7d nt to. {F17016}
3b2c0 20 42 75 74 20 53 51 4c 69 74 65 20 77 69 6c 6c But SQLite will
3b2d0 20 6f 6e 6c 79 20 72 65 71 75 65 73 74 20 61 20 only request a
3b2e0 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 20 recursive mutex
3b2f0 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77 68 65 72 in.** cases wher
3b300 65 20 69 74 20 72 65 61 6c 6c 79 20 6e 65 65 64 e it really need
3b310 73 20 6f 6e 65 2e 20 20 7b 45 4e 44 7d 20 49 66 s one. {END} If
3b320 20 61 20 66 61 73 74 65 72 20 6e 6f 6e 2d 72 65 a faster non-re
3b330 63 75 72 73 69 76 65 20 6d 75 74 65 78 0a 2a 2a cursive mutex.**
3b340 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
3b350 69 73 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 is available on
3b360 74 68 65 20 68 6f 73 74 20 70 6c 61 74 66 6f 72 the host platfor
3b370 6d 2c 20 74 68 65 20 6d 75 74 65 78 20 73 75 62 m, the mutex sub
3b380 73 79 73 74 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 system.** might
3b390 72 65 74 75 72 6e 20 73 75 63 68 20 61 20 6d 75 return such a mu
3b3a0 74 65 78 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 tex in response
3b3b0 74 6f 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f to SQLITE_MUTEX_
3b3c0 46 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 FAST..**.** {F17
3b3d0 30 31 37 7d 20 54 68 65 20 6f 74 68 65 72 20 61 017} The other a
3b3e0 6c 6c 6f 77 65 64 20 70 61 72 61 6d 65 74 65 72 llowed parameter
3b3f0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 s to sqlite3_mut
3b400 65 78 5f 61 6c 6c 6f 63 28 29 20 65 61 63 68 20 ex_alloc() each
3b410 72 65 74 75 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e return.** a poin
3b420 74 65 72 20 74 6f 20 61 20 73 74 61 74 69 63 20 ter to a static
3b430 70 72 65 65 78 69 73 74 69 6e 67 20 6d 75 74 65 preexisting mute
3b440 78 2e 20 7b 45 4e 44 7d 20 20 46 6f 75 72 20 73 x. {END} Four s
3b450 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72 tatic mutexes ar
3b460 65 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 68 65 e.** used by the
3b470 20 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f 6e current version
3b480 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 46 75 74 of SQLite. Fut
3b490 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 ure versions of
3b4a0 53 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20 61 64 SQLite.** may ad
3b4b0 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 d additional sta
3b4c0 74 69 63 20 6d 75 74 65 78 65 73 2e 20 20 53 74 tic mutexes. St
3b4d0 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72 65 atic mutexes are
3b4e0 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a for internal.**
3b4f0 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 20 6f use by SQLite o
3b500 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f nly. Applicatio
3b510 6e 73 20 74 68 61 74 20 75 73 65 20 53 51 4c 69 ns that use SQLi
3b520 74 65 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c te mutexes shoul
3b530 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20 74 68 d.** use only th
3b540 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65 e dynamic mutexe
3b550 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 s returned by SQ
3b560 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 LITE_MUTEX_FAST
3b570 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 or.** SQLITE_MUT
3b580 45 58 5f 52 45 43 55 52 53 49 56 45 2e 0a 2a 2a EX_RECURSIVE..**
3b590 0a 2a 2a 20 7b 46 31 37 30 31 38 7d 20 4e 6f 74 .** {F17018} Not
3b5a0 65 20 74 68 61 74 20 69 66 20 6f 6e 65 20 6f 66 e that if one of
3b5b0 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 the dynamic mut
3b5c0 65 78 20 70 61 72 61 6d 65 74 65 72 73 20 28 53 ex parameters (S
3b5d0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 QLITE_MUTEX_FAST
3b5e0 0a 2a 2a 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55 .** or SQLITE_MU
3b5f0 54 45 58 5f 52 45 43 55 52 53 49 56 45 29 20 69 TEX_RECURSIVE) i
3b600 73 20 75 73 65 64 20 74 68 65 6e 20 73 71 6c 69 s used then sqli
3b610 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 te3_mutex_alloc(
3b620 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 64 ).** returns a d
3b630 69 66 66 65 72 65 6e 74 20 6d 75 74 65 78 20 6f ifferent mutex o
3b640 6e 20 65 76 65 72 79 20 63 61 6c 6c 2e 20 20 7b n every call. {
3b650 46 31 37 30 33 34 7d 20 42 75 74 20 66 6f 72 20 F17034} But for
3b660 74 68 65 20 73 74 61 74 69 63 20 0a 2a 2a 20 6d the static .** m
3b670 75 74 65 78 20 74 79 70 65 73 2c 20 74 68 65 20 utex types, the
3b680 73 61 6d 65 20 6d 75 74 65 78 20 69 73 20 72 65 same mutex is re
3b690 74 75 72 6e 65 64 20 6f 6e 20 65 76 65 72 79 20 turned on every
3b6a0 63 61 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a 2a call that has.**
3b6b0 20 74 68 65 20 73 61 6d 65 20 74 79 70 65 20 6e the same type n
3b6c0 75 6d 62 65 72 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a umber. {END}.**.
3b6d0 2a 2a 20 7b 46 31 37 30 31 39 7d 20 54 68 65 20 ** {F17019} The
3b6e0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 sqlite3_mutex_fr
3b6f0 65 65 28 29 20 72 6f 75 74 69 6e 65 20 64 65 61 ee() routine dea
3b700 6c 6c 6f 63 61 74 65 73 20 61 20 70 72 65 76 69 llocates a previ
3b710 6f 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 ously.** allocat
3b720 65 64 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 ed dynamic mutex
3b730 2e 20 7b 46 31 37 30 32 30 7d 20 53 51 4c 69 74 . {F17020} SQLit
3b740 65 20 69 73 20 63 61 72 65 66 75 6c 20 74 6f 20 e is careful to
3b750 64 65 61 6c 6c 6f 63 61 74 65 20 65 76 65 72 79 deallocate every
3b760 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 .** dynamic mute
3b770 78 20 74 68 61 74 20 69 74 20 61 6c 6c 6f 63 61 x that it alloca
3b780 74 65 73 2e 20 7b 55 31 37 30 32 31 7d 20 54 68 tes. {U17021} Th
3b790 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65 e dynamic mutexe
3b7a0 73 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 69 6e s must not be in
3b7b0 20 0a 2a 2a 20 75 73 65 20 77 68 65 6e 20 74 68 .** use when th
3b7c0 65 79 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 ey are deallocat
3b7d0 65 64 2e 20 7b 55 31 37 30 32 32 7d 20 41 74 74 ed. {U17022} Att
3b7e0 65 6d 70 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c empting to deall
3b7f0 6f 63 61 74 65 20 61 20 73 74 61 74 69 63 0a 2a ocate a static.*
3b800 2a 20 6d 75 74 65 78 20 72 65 73 75 6c 74 73 20 * mutex results
3b810 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 in undefined beh
3b820 61 76 69 6f 72 2e 20 7b 46 31 37 30 32 33 7d 20 avior. {F17023}
3b830 53 51 4c 69 74 65 20 6e 65 76 65 72 20 64 65 61 SQLite never dea
3b840 6c 6c 6f 63 61 74 65 73 0a 2a 2a 20 61 20 73 74 llocates.** a st
3b850 61 74 69 63 20 6d 75 74 65 78 2e 20 7b 45 4e 44 atic mutex. {END
3b860 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 }.**.** The sqli
3b870 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 te3_mutex_enter(
3b880 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 ) and sqlite3_mu
3b890 74 65 78 5f 74 72 79 28 29 20 72 6f 75 74 69 6e tex_try() routin
3b8a0 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74 6f es attempt.** to
3b8b0 20 65 6e 74 65 72 20 61 20 6d 75 74 65 78 2e 20 enter a mutex.
3b8c0 7b 46 31 37 30 32 34 7d 20 49 66 20 61 6e 6f 74 {F17024} If anot
3b8d0 68 65 72 20 74 68 72 65 61 64 20 69 73 20 61 6c her thread is al
3b8e0 72 65 61 64 79 20 77 69 74 68 69 6e 20 74 68 65 ready within the
3b8f0 20 6d 75 74 65 78 2c 0a 2a 2a 20 73 71 6c 69 74 mutex,.** sqlit
3b900 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 e3_mutex_enter()
3b910 20 77 69 6c 6c 20 62 6c 6f 63 6b 20 61 6e 64 20 will block and
3b920 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 sqlite3_mutex_tr
3b930 79 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a y() will return.
3b940 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 ** SQLITE_BUSY.
3b950 7b 46 31 37 30 32 35 7d 20 20 54 68 65 20 73 71 {F17025} The sq
3b960 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 lite3_mutex_try(
3b970 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
3b980 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 0a 2a 2a rns SQLITE_OK.**
3b990 20 75 70 6f 6e 20 73 75 63 63 65 73 73 66 75 6c upon successful
3b9a0 20 65 6e 74 72 79 2e 20 20 7b 46 31 37 30 32 36 entry. {F17026
3b9b0 7d 20 4d 75 74 65 78 65 73 20 63 72 65 61 74 65 } Mutexes create
3b9c0 64 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 d using.** SQLIT
3b9d0 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 E_MUTEX_RECURSIV
3b9e0 45 20 63 61 6e 20 62 65 20 65 6e 74 65 72 65 64 E can be entered
3b9f0 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 multiple times
3ba00 62 79 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 by the same thre
3ba10 61 64 2e 0a 2a 2a 20 7b 46 31 37 30 32 37 7d 20 ad..** {F17027}
3ba20 49 6e 20 73 75 63 68 20 63 61 73 65 73 20 74 68 In such cases th
3ba30 65 2c 0a 2a 2a 20 6d 75 74 65 78 20 6d 75 73 74 e,.** mutex must
3ba40 20 62 65 20 65 78 69 74 65 64 20 61 6e 20 65 71 be exited an eq
3ba50 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 ual number of ti
3ba60 6d 65 73 20 62 65 66 6f 72 65 20 61 6e 6f 74 68 mes before anoth
3ba70 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 63 61 6e er thread.** can
3ba80 20 65 6e 74 65 72 2e 20 20 7b 55 31 37 30 32 38 enter. {U17028
3ba90 7d 20 49 66 20 74 68 65 20 73 61 6d 65 20 74 68 } If the same th
3baa0 72 65 61 64 20 74 72 69 65 73 20 74 6f 20 65 6e read tries to en
3bab0 74 65 72 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a ter any other.**
3bac0 20 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78 20 6d kind of mutex m
3bad0 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 74 ore than once, t
3bae0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 he behavior is u
3baf0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 7b 46 31 ndefined..** {F1
3bb00 37 30 32 39 7d 20 53 51 4c 69 74 65 20 77 69 6c 7029} SQLite wil
3bb10 6c 20 6e 65 76 65 72 20 65 78 68 69 62 69 74 0a l never exhibit.
3bb20 2a 2a 20 73 75 63 68 20 62 65 68 61 76 69 6f 72 ** such behavior
3bb30 20 69 6e 20 69 74 73 20 6f 77 6e 20 75 73 65 20 in its own use
3bb40 6f 66 20 6d 75 74 65 78 65 73 2e 20 7b 45 4e 44 of mutexes. {END
3bb50 7d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 73 79 73 }.**.** Some sys
3bb60 74 65 6d 73 20 28 65 78 3a 20 77 69 6e 64 6f 77 tems (ex: window
3bb70 73 39 35 29 20 64 6f 20 6e 6f 74 20 74 68 65 20 s95) do not the
3bb80 6f 70 65 72 61 74 69 6f 6e 20 69 6d 70 6c 65 6d operation implem
3bb90 65 6e 74 65 64 20 62 79 0a 2a 2a 20 73 71 6c 69 ented by.** sqli
3bba0 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2e te3_mutex_try().
3bbb0 20 20 4f 6e 20 74 68 6f 73 65 20 73 79 73 74 65 On those syste
3bbc0 6d 73 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 ms, sqlite3_mute
3bbd0 78 5f 74 72 79 28 29 20 77 69 6c 6c 0a 2a 2a 20 x_try() will.**
3bbe0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 53 51 always return SQ
3bbf0 4c 49 54 45 5f 42 55 53 59 2e 20 20 7b 46 31 37 LITE_BUSY. {F17
3bc00 30 33 30 7d 20 54 68 65 20 53 51 4c 69 74 65 20 030} The SQLite
3bc10 63 6f 72 65 20 6f 6e 6c 79 20 65 76 65 72 20 75 core only ever u
3bc20 73 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d ses.** sqlite3_m
3bc30 75 74 65 78 5f 74 72 79 28 29 20 61 73 20 61 6e utex_try() as an
3bc40 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 73 6f optimization so
3bc50 20 74 68 69 73 20 69 73 20 61 63 63 65 70 74 61 this is accepta
3bc60 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 20 7b 45 ble behavior. {E
3bc70 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 30 33 ND}.**.** {F1703
3bc80 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 1} The sqlite3_m
3bc90 75 74 65 78 5f 6c 65 61 76 65 28 29 20 72 6f 75 utex_leave() rou
3bca0 74 69 6e 65 20 65 78 69 74 73 20 61 20 6d 75 74 tine exits a mut
3bcb0 65 78 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 70 ex that was.** p
3bcc0 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 72 65 reviously entere
3bcd0 64 20 62 79 20 74 68 65 20 73 61 6d 65 20 74 68 d by the same th
3bce0 72 65 61 64 2e 20 20 7b 55 31 37 30 33 32 7d 20 read. {U17032}
3bcf0 54 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 The behavior.**
3bd00 69 73 20 75 6e 64 65 66 69 6e 65 64 20 69 66 20 is undefined if
3bd10 74 68 65 20 6d 75 74 65 78 20 69 73 20 6e 6f 74 the mutex is not
3bd20 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 currently enter
3bd30 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c ed by the.** cal
3bd40 6c 69 6e 67 20 74 68 72 65 61 64 20 6f 72 20 69 ling thread or i
3bd50 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 s not currently
3bd60 61 6c 6c 6f 63 61 74 65 64 2e 20 20 7b 46 31 37 allocated. {F17
3bd70 30 33 33 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 033} SQLite will
3bd80 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20 65 69 74 .** never do eit
3bd90 68 65 72 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a her. {END}.**.**
3bda0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
3bdb0 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 te3_mutex_held()
3bdc0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6d ] and [sqlite3_m
3bdd0 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e utex_notheld()].
3bde0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 .*/.sqlite3_mute
3bdf0 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 x *sqlite3_mutex
3be00 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 _alloc(int);.voi
3be10 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f d sqlite3_mutex_
3be20 66 72 65 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 free(sqlite3_mut
3be30 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 ex*);.void sqlit
3be40 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 73 e3_mutex_enter(s
3be50 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a qlite3_mutex*);.
3be60 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 int sqlite3_mute
3be70 78 5f 74 72 79 28 73 71 6c 69 74 65 33 5f 6d 75 x_try(sqlite3_mu
3be80 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 tex*);.void sqli
3be90 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 te3_mutex_leave(
3bea0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b sqlite3_mutex*);
3beb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
3bec0 3a 20 4d 75 74 65 78 20 56 65 72 69 66 63 61 74 : Mutex Verifcat
3bed0 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 46 31 ion Routines {F1
3bee0 37 30 38 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7080}.**.** The
3bef0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 sqlite3_mutex_he
3bf00 6c 64 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 ld() and sqlite3
3bf10 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 _mutex_notheld()
3bf20 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 routines.** are
3bf30 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 intended for us
3bf40 65 20 69 6e 73 69 64 65 20 61 73 73 65 72 74 28 e inside assert(
3bf50 29 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 7b 46 ) statements. {F
3bf60 31 37 30 38 31 7d 20 54 68 65 20 53 51 4c 69 74 17081} The SQLit
3bf70 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65 72 20 e core.** never
3bf80 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 69 uses these routi
3bf90 6e 65 73 20 65 78 63 65 70 74 20 69 6e 73 69 64 nes except insid
3bfa0 65 20 61 6e 20 61 73 73 65 72 74 28 29 20 61 6e e an assert() an
3bfb0 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a d applications.*
3bfc0 2a 20 61 72 65 20 61 64 76 69 73 65 64 20 74 6f * are advised to
3bfd0 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65 61 64 follow the lead
3bfe0 20 6f 66 20 74 68 65 20 63 6f 72 65 2e 20 20 7b of the core. {
3bff0 46 31 37 30 38 32 7d 20 54 68 65 20 63 6f 72 65 F17082} The core
3c000 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 64 65 only.** provide
3c010 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e s implementation
3c020 73 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 s for these rout
3c030 69 6e 65 73 20 77 68 65 6e 20 69 74 20 69 73 20 ines when it is
3c040 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 compiled.** with
3c050 20 74 68 65 20 53 51 4c 49 54 45 5f 44 45 42 55 the SQLITE_DEBU
3c060 47 20 66 6c 61 67 2e 20 20 7b 55 31 37 30 38 37 G flag. {U17087
3c070 7d 20 45 78 74 65 72 6e 61 6c 20 6d 75 74 65 78 } External mutex
3c080 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
3c090 0a 2a 2a 20 61 72 65 20 6f 6e 6c 79 20 72 65 71 .** are only req
3c0a0 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 uired to provide
3c0b0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
3c0c0 69 66 20 53 51 4c 49 54 45 5f 44 45 42 55 47 20 if SQLITE_DEBUG
3c0d0 69 73 0a 2a 2a 20 64 65 66 69 6e 65 64 20 61 6e is.** defined an
3c0e0 64 20 69 66 20 4e 44 45 42 55 47 20 69 73 20 6e d if NDEBUG is n
3c0f0 6f 74 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a ot defined..**.*
3c100 2a 20 7b 46 31 37 30 38 33 7d 20 54 68 65 73 65 * {F17083} These
3c110 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 routines should
3c120 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 return true if
3c130 74 68 65 20 6d 75 74 65 78 20 69 6e 20 74 68 65 the mutex in the
3c140 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 ir argument.** i
3c150 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20 68 65 s held or not he
3c160 6c 64 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 ld, respectively
3c170 2c 20 62 79 20 74 68 65 20 63 61 6c 6c 69 6e 67 , by the calling
3c180 20 74 68 72 65 61 64 2e 20 7b 45 4e 44 7d 0a 2a thread. {END}.*
3c190 2a 0a 2a 2a 20 7b 58 31 37 30 38 34 7d 20 54 68 *.** {X17084} Th
3c1a0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
3c1b0 20 69 73 20 6e 6f 74 20 72 65 71 75 69 72 65 64 is not required
3c1c0 20 74 6f 20 70 72 6f 76 69 64 65 64 20 76 65 72 to provided ver
3c1d0 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 0a 2a sions of these.*
3c1e0 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 * routines that
3c1f0 61 63 74 75 61 6c 6c 79 20 77 6f 72 6b 2e 0a 2a actually work..*
3c200 2a 20 49 66 20 74 68 65 20 69 6d 70 6c 65 6d 65 * If the impleme
3c210 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 ntation does not
3c220 20 70 72 6f 76 69 64 65 20 77 6f 72 6b 69 6e 67 provide working
3c230 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 .** versions of
3c240 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 these routines,
3c250 69 74 20 73 68 6f 75 6c 64 20 61 74 20 6c 65 61 it should at lea
3c260 73 74 20 70 72 6f 76 69 64 65 20 73 74 75 62 73 st provide stubs
3c270 0a 2a 2a 20 74 68 61 74 20 61 6c 77 61 79 73 20 .** that always
3c280 72 65 74 75 72 6e 20 74 72 75 65 20 73 6f 20 74 return true so t
3c290 68 61 74 20 6f 6e 65 20 64 6f 65 73 20 6e 6f 74 hat one does not
3c2a0 20 67 65 74 20 73 70 75 72 69 6f 75 73 0a 2a 2a get spurious.**
3c2b0 20 61 73 73 65 72 74 69 6f 6e 20 66 61 69 6c 75 assertion failu
3c2c0 72 65 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a res. {END}.**.**
3c2d0 20 7b 46 31 37 30 38 35 7d 20 49 66 20 74 68 65 {F17085} If the
3c2e0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
3c2f0 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 ite3_mutex_held(
3c300 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e ) is a NULL poin
3c310 74 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 ter then.** the
3c320 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 routine should r
3c330 65 74 75 72 6e 20 31 2e 20 20 7b 45 4e 44 7d 20 eturn 1. {END}
3c340 54 68 69 73 20 73 65 65 6d 73 20 63 6f 75 6e 74 This seems count
3c350 65 72 2d 69 6e 74 75 69 74 69 76 65 20 73 69 6e er-intuitive sin
3c360 63 65 0a 2a 2a 20 63 6c 65 61 72 6c 79 20 74 68 ce.** clearly th
3c370 65 20 6d 75 74 65 78 20 63 61 6e 6e 6f 74 20 62 e mutex cannot b
3c380 65 20 68 65 6c 64 20 69 66 20 69 74 20 64 6f 65 e held if it doe
3c390 73 20 6e 6f 74 20 65 78 69 73 74 2e 20 20 42 75 s not exist. Bu
3c3a0 74 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 65 61 t the.** the rea
3c3b0 73 6f 6e 20 74 68 65 20 6d 75 74 65 78 20 64 6f son the mutex do
3c3c0 65 73 20 6e 6f 74 20 65 78 69 73 74 20 69 73 20 es not exist is
3c3d0 62 65 63 61 75 73 65 20 74 68 65 20 62 75 69 6c because the buil
3c3e0 64 20 69 73 20 6e 6f 74 0a 2a 2a 20 75 73 69 6e d is not.** usin
3c3f0 67 20 6d 75 74 65 78 65 73 2e 20 20 41 6e 64 20 g mutexes. And
3c400 77 65 20 64 6f 20 6e 6f 74 20 77 61 6e 74 20 74 we do not want t
3c410 68 65 20 61 73 73 65 72 74 28 29 20 63 6f 6e 74 he assert() cont
3c420 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 61 aining the.** ca
3c430 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 ll to sqlite3_mu
3c440 74 65 78 5f 68 65 6c 64 28 29 20 74 6f 20 66 61 tex_held() to fa
3c450 69 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65 72 il, so a non-zer
3c460 6f 20 72 65 74 75 72 6e 20 69 73 0a 2a 2a 20 74 o return is.** t
3c470 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 74 he appropriate t
3c480 68 69 6e 67 20 74 6f 20 64 6f 2e 20 20 7b 46 31 hing to do. {F1
3c490 37 30 38 36 7d 20 54 68 65 20 73 71 6c 69 74 65 7086} The sqlite
3c4a0 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 3_mutex_notheld(
3c4b0 29 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 ) .** interface
3c4c0 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74 75 should also retu
3c4d0 72 6e 20 31 20 77 68 65 6e 20 67 69 76 65 6e 20 rn 1 when given
3c4e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a a NULL pointer..
3c4f0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d */.int sqlite3_m
3c500 75 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 74 65 utex_held(sqlite
3c510 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 3_mutex*);.int s
3c520 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 qlite3_mutex_not
3c530 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 held(sqlite3_mut
3c540 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ex*);../*.** CAP
3c550 49 33 52 45 46 3a 20 4d 75 74 65 78 20 54 79 70 I3REF: Mutex Typ
3c560 65 73 20 7b 46 31 37 30 30 31 7d 0a 2a 2a 0a 2a es {F17001}.**.*
3c570 2a 20 7b 46 31 37 30 30 32 7d 20 54 68 65 20 5b * {F17002} The [
3c580 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c sqlite3_mutex_al
3c590 6c 6f 63 28 29 5d 20 69 6e 74 65 72 66 61 63 65 loc()] interface
3c5a0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
3c5b0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 69 63 argument.** whic
3c5c0 68 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 h is one of thes
3c5d0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 e integer consta
3c5e0 6e 74 73 2e 20 7b 45 4e 44 7d 0a 2a 2f 0a 23 64 nts. {END}.*/.#d
3c5f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 efine SQLITE_MUT
3c600 45 58 5f 46 41 53 54 20 20 20 20 20 20 20 20 20 EX_FAST
3c610 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 0.#define SQ
3c620 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 LITE_MUTEX_RECUR
3c630 53 49 56 45 20 20 20 20 20 20 20 20 31 0a 23 64 SIVE 1.#d
3c640 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 efine SQLITE_MUT
3c650 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 EX_STATIC_MASTER
3c660 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 2.#define SQ
3c670 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
3c680 43 5f 4d 45 4d 20 20 20 20 20 20 20 33 20 20 2f C_MEM 3 /
3c690 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 * sqlite3_malloc
3c6a0 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
3c6b0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
3c6c0 43 5f 4d 45 4d 32 20 20 20 20 20 20 34 20 20 2f C_MEM2 4 /
3c6d0 2a 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 * sqlite3_releas
3c6e0 65 5f 6d 65 6d 6f 72 79 28 29 20 2a 2f 0a 23 64 e_memory() */.#d
3c6f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 efine SQLITE_MUT
3c700 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 20 20 EX_STATIC_PRNG
3c710 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 5 /* sqlite
3c720 33 5f 72 61 6e 64 6f 6d 28 29 20 2a 2f 0a 23 64 3_random() */.#d
3c730 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 efine SQLITE_MUT
3c740 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 20 20 20 EX_STATIC_LRU
3c750 20 20 20 20 36 20 20 2f 2a 20 6c 72 75 20 70 61 6 /* lru pa
3c760 67 65 20 6c 69 73 74 20 2a 2f 0a 23 64 65 66 69 ge list */.#defi
3c770 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f ne SQLITE_MUTEX_
3c780 53 54 41 54 49 43 5f 4c 52 55 32 20 20 20 20 20 STATIC_LRU2
3c790 20 37 20 20 2f 2a 20 6c 72 75 20 70 61 67 65 20 7 /* lru page
3c7a0 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 list */../*.** C
3c7b0 41 50 49 33 52 45 46 3a 20 4c 6f 77 2d 4c 65 76 API3REF: Low-Lev
3c7c0 65 6c 20 43 6f 6e 74 72 6f 6c 20 4f 66 20 44 61 el Control Of Da
3c7d0 74 61 62 61 73 65 20 46 69 6c 65 73 20 7b 46 31 tabase Files {F1
3c7e0 31 33 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 1300}.**.** {F11
3c7f0 33 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 301} The [sqlite
3c800 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
3c810 5d 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 ] interface make
3c820 73 20 61 20 64 69 72 65 63 74 20 63 61 6c 6c 20 s a direct call
3c830 74 6f 20 74 68 65 0a 2a 2a 20 78 46 69 6c 65 43 to the.** xFileC
3c840 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 66 6f ontrol method fo
3c850 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 r the [sqlite3_i
3c860 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 o_methods] objec
3c870 74 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 t associated.**
3c880 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 with a particula
3c890 72 20 64 61 74 61 62 61 73 65 20 69 64 65 6e 74 r database ident
3c8a0 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63 ified by the sec
3c8b0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 20 7b 46 ond argument. {F
3c8c0 31 31 33 30 32 7d 20 54 68 65 0a 2a 2a 20 6e 61 11302} The.** na
3c8d0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 me of the databa
3c8e0 73 65 20 69 73 20 74 68 65 20 6e 61 6d 65 20 61 se is the name a
3c8f0 73 73 69 67 6e 65 64 20 74 6f 20 74 68 65 20 64 ssigned to the d
3c900 61 74 61 62 61 73 65 20 62 79 20 74 68 65 0a 2a atabase by the.*
3c910 2a 20 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f * <a href="lang_
3c920 61 74 74 61 63 68 2e 68 74 6d 6c 22 3e 41 54 54 attach.html">ATT
3c930 41 43 48 3c 2f 61 3e 20 53 51 4c 20 63 6f 6d 6d ACH</a> SQL comm
3c940 61 6e 64 20 74 68 61 74 20 6f 70 65 6e 65 64 20 and that opened
3c950 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e the.** database.
3c960 20 7b 46 31 31 33 30 33 7d 20 54 6f 20 63 6f 6e {F11303} To con
3c970 74 72 6f 6c 20 74 68 65 20 6d 61 69 6e 20 64 61 trol the main da
3c980 74 61 62 61 73 65 20 66 69 6c 65 2c 20 75 73 65 tabase file, use
3c990 20 74 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 the name "main"
3c9a0 0a 2a 2a 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f .** or a NULL po
3c9b0 69 6e 74 65 72 2e 20 7b 46 31 31 33 30 34 7d 20 inter. {F11304}
3c9c0 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f The third and fo
3c9d0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 urth parameters
3c9e0 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a to this routine.
3c9f0 2a 2a 20 61 72 65 20 70 61 73 73 65 64 20 64 69 ** are passed di
3ca00 72 65 63 74 6c 79 20 74 68 72 6f 75 67 68 20 74 rectly through t
3ca10 6f 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 o the second and
3ca20 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
3ca30 73 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46 69 6c s of.** the xFil
3ca40 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e eControl method.
3ca50 20 20 7b 46 31 31 33 30 35 7d 20 54 68 65 20 72 {F11305} The r
3ca60 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 eturn value of t
3ca70 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 0a he xFileControl.
3ca80 2a 2a 20 6d 65 74 68 6f 64 20 62 65 63 6f 6d 65 ** method become
3ca90 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c s the return val
3caa0 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 ue of this routi
3cab0 6e 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 30 ne..**.** {F1130
3cac0 36 7d 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64 6} If the second
3cad0 20 70 61 72 61 6d 65 74 65 72 20 28 7a 44 62 4e parameter (zDbN
3cae0 61 6d 65 29 20 64 6f 65 73 20 6e 6f 74 20 6d 61 ame) does not ma
3caf0 74 63 68 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 tch the name of
3cb00 61 6e 79 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61 any.** open data
3cb10 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65 6e 20 base file, then
3cb20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 69 73 20 SQLITE_ERROR is
3cb30 72 65 74 75 72 6e 65 64 2e 20 7b 46 31 31 33 30 returned. {F1130
3cb40 37 7d 20 54 68 69 73 20 65 72 72 6f 72 0a 2a 2a 7} This error.**
3cb50 20 63 6f 64 65 20 69 73 20 6e 6f 74 20 72 65 6d code is not rem
3cb60 65 6d 62 65 72 65 64 20 61 6e 64 20 77 69 6c 6c embered and will
3cb70 20 6e 6f 74 20 62 65 20 72 65 63 61 6c 6c 65 64 not be recalled
3cb80 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 by [sqlite3_err
3cb90 63 6f 64 65 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 code()].** or [s
3cba0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d qlite3_errmsg()]
3cbb0 2e 20 7b 55 31 31 33 30 38 7d 20 54 68 65 20 75 . {U11308} The u
3cbc0 6e 64 65 72 6c 79 69 6e 67 20 78 46 69 6c 65 43 nderlying xFileC
3cbd0 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 6d 69 ontrol method mi
3cbe0 67 68 74 0a 2a 2a 20 61 6c 73 6f 20 72 65 74 75 ght.** also retu
3cbf0 72 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e rn SQLITE_ERROR.
3cc00 20 20 7b 55 31 31 33 30 39 7d 20 54 68 65 72 65 {U11309} There
3cc10 20 69 73 20 6e 6f 20 77 61 79 20 74 6f 20 64 69 is no way to di
3cc20 73 74 69 6e 67 75 69 73 68 20 62 65 74 77 65 65 stinguish betwee
3cc30 6e 0a 2a 2a 20 61 6e 20 69 6e 63 6f 72 72 65 63 n.** an incorrec
3cc40 74 20 7a 44 62 4e 61 6d 65 20 61 6e 64 20 61 6e t zDbName and an
3cc50 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 72 65 SQLITE_ERROR re
3cc60 74 75 72 6e 20 66 72 6f 6d 20 74 68 65 20 75 6e turn from the un
3cc70 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 78 46 69 6c derlying.** xFil
3cc80 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e eControl method.
3cc90 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53 65 65 {END}.**.** See
3cca0 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 46 also: [SQLITE_F
3ccb0 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 0a CNTL_LOCKSTATE].
3ccc0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 */.int sqlite3_f
3ccd0 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 73 71 6c 69 ile_control(sqli
3cce0 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 te3*, const char
3ccf0 20 2a 7a 44 62 4e 61 6d 65 2c 20 69 6e 74 20 6f *zDbName, int o
3cd00 70 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a p, void*);../*.*
3cd10 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 * CAPI3REF: Test
3cd20 69 6e 67 20 49 6e 74 65 72 66 61 63 65 20 7b 46 ing Interface {F
3cd30 31 31 34 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 11400}.**.** The
3cd40 20 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f sqlite3_test_co
3cd50 6e 74 72 6f 6c 28 29 20 69 6e 74 65 72 66 61 63 ntrol() interfac
3cd60 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 61 e is used to rea
3cd70 64 20 6f 75 74 20 69 6e 74 65 72 6e 61 6c 0a 2a d out internal.*
3cd80 2a 20 73 74 61 74 65 20 6f 66 20 53 51 4c 69 74 * state of SQLit
3cd90 65 20 61 6e 64 20 74 6f 20 69 6e 6a 65 63 74 20 e and to inject
3cda0 66 61 75 6c 74 73 20 69 6e 74 6f 20 53 51 4c 69 faults into SQLi
3cdb0 74 65 20 66 6f 72 20 74 65 73 74 69 6e 67 0a 2a te for testing.*
3cdc0 2a 20 70 75 72 70 6f 73 65 73 2e 20 20 54 68 65 * purposes. The
3cdd0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
3cde0 20 61 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 a operation cod
3cdf0 65 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 e that determine
3ce00 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 2c s.** the number,
3ce10 20 6d 65 61 6e 69 6e 67 2c 20 61 6e 64 20 6f 70 meaning, and op
3ce20 65 72 61 74 69 6f 6e 20 6f 66 20 61 6c 6c 20 73 eration of all s
3ce30 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 ubsequent parame
3ce40 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 ters..**.** This
3ce50 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f interface is no
3ce60 74 20 66 6f 72 20 75 73 65 20 62 79 20 61 70 70 t for use by app
3ce70 6c 69 63 61 74 69 6f 6e 73 2e 20 20 49 74 20 65 lications. It e
3ce80 78 69 73 74 73 20 73 6f 6c 65 6c 79 0a 2a 2a 20 xists solely.**
3ce90 66 6f 72 20 76 65 72 69 66 79 69 6e 67 20 74 68 for verifying th
3cea0 65 20 63 6f 72 72 65 63 74 20 6f 70 65 72 61 74 e correct operat
3ceb0 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 ion of the SQLit
3cec0 65 20 6c 69 62 72 61 72 79 2e 20 20 44 65 70 65 e library. Depe
3ced0 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 68 6f 77 20 nding.** on how
3cee0 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 the SQLite libra
3cef0 72 79 20 69 73 20 63 6f 6d 70 69 6c 65 64 2c 20 ry is compiled,
3cf00 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6d this interface m
3cf10 69 67 68 74 20 6e 6f 74 20 65 78 69 73 74 2e 0a ight not exist..
3cf20 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c **.** The detail
3cf30 73 20 6f 66 20 74 68 65 20 6f 70 65 72 61 74 69 s of the operati
3cf40 6f 6e 20 63 6f 64 65 73 2c 20 74 68 65 69 72 20 on codes, their
3cf50 6d 65 61 6e 69 6e 67 73 2c 20 74 68 65 20 70 61 meanings, the pa
3cf60 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 68 65 79 rameters.** they
3cf70 20 74 61 6b 65 2c 20 61 6e 64 20 77 68 61 74 20 take, and what
3cf80 74 68 65 79 20 64 6f 20 61 72 65 20 61 6c 6c 20 they do are all
3cf90 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 subject to chang
3cfa0 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 e without notice
3cfb0 2e 0a 2a 2a 20 55 6e 6c 69 6b 65 20 6d 6f 73 74 ..** Unlike most
3cfc0 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 41 of the SQLite A
3cfd0 50 49 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f PI, this functio
3cfe0 6e 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 n is not guarant
3cff0 65 65 64 20 74 6f 0a 2a 2a 20 6f 70 65 72 61 74 eed to.** operat
3d000 65 20 63 6f 6e 73 69 73 74 65 6e 74 6c 79 20 66 e consistently f
3d010 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 rom one release
3d020 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a to the next..*/.
3d030 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 65 73 74 int sqlite3_test
3d040 5f 63 6f 6e 74 72 6f 6c 28 69 6e 74 20 6f 70 2c _control(int op,
3d050 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ...);../*.** CA
3d060 50 49 33 52 45 46 3a 20 54 65 73 74 69 6e 67 20 PI3REF: Testing
3d070 49 6e 74 65 72 66 61 63 65 20 4f 70 65 72 61 74 Interface Operat
3d080 69 6f 6e 20 43 6f 64 65 73 20 7b 46 31 31 34 31 ion Codes {F1141
3d090 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 0}.**.** These c
3d0a0 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 onstants are the
3d0b0 20 76 61 6c 69 64 20 6f 70 65 72 61 74 69 6f 6e valid operation
3d0c0 20 63 6f 64 65 20 70 61 72 61 6d 65 74 65 72 73 code parameters
3d0d0 20 75 73 65 64 0a 2a 2a 20 61 73 20 74 68 65 20 used.** as the
3d0e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
3d0f0 6f 20 5b 73 71 6c 69 74 65 33 5f 74 65 73 74 5f o [sqlite3_test_
3d100 63 6f 6e 74 72 6f 6c 28 29 5d 2e 0a 2a 2a 0a 2a control()]..**.*
3d110 2a 20 54 68 65 73 65 20 70 61 72 61 6d 65 74 65 * These paramete
3d120 72 73 20 61 6e 64 20 74 68 65 69 72 20 6d 65 61 rs and their mea
3d130 6e 73 69 6e 67 20 61 72 65 20 73 75 62 6a 65 63 nsing are subjec
3d140 74 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 77 t to change.** w
3d150 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 2e 20 20 ithout notice.
3d160 54 68 65 73 65 20 76 61 6c 75 65 73 20 61 72 65 These values are
3d170 20 66 6f 72 20 74 65 73 74 69 6e 67 20 70 75 72 for testing pur
3d180 70 6f 73 65 73 20 6f 6e 6c 79 2e 0a 2a 2a 20 41 poses only..** A
3d190 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 pplications shou
3d1a0 6c 64 20 6e 6f 74 20 75 73 65 20 61 6e 79 20 6f ld not use any o
3d1b0 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 f these paramete
3d1c0 72 73 20 6f 72 20 74 68 65 0a 2a 2a 20 5b 73 71 rs or the.** [sq
3d1d0 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 lite3_test_contr
3d1e0 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e ol()] interface.
3d1f0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
3d200 54 45 5f 54 45 53 54 43 54 52 4c 5f 46 41 55 4c TE_TESTCTRL_FAUL
3d210 54 5f 43 4f 4e 46 49 47 20 20 20 20 20 20 20 20 T_CONFIG
3d220 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 1.#define S
3d230 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 46 QLITE_TESTCTRL_F
3d240 41 55 4c 54 5f 46 41 49 4c 55 52 45 53 20 20 20 AULT_FAILURES
3d250 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 2.#defin
3d260 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 e SQLITE_TESTCTR
3d270 4c 5f 46 41 55 4c 54 5f 42 45 4e 49 47 4e 5f 46 L_FAULT_BENIGN_F
3d280 41 49 4c 55 52 45 53 20 20 20 20 33 0a 23 64 65 AILURES 3.#de
3d290 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 fine SQLITE_TEST
3d2a0 43 54 52 4c 5f 46 41 55 4c 54 5f 50 45 4e 44 49 CTRL_FAULT_PENDI
3d2b0 4e 47 20 20 20 20 20 20 20 20 20 20 20 20 34 0a NG 4.
3d2c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
3d2d0 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f 53 41 56 ESTCTRL_PRNG_SAV
3d2e0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 E
3d2f0 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 5.#define SQLIT
3d300 45 5f 54 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f E_TESTCTRL_PRNG_
3d310 52 45 53 54 4f 52 45 20 20 20 20 20 20 20 20 20 RESTORE
3d320 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 6.#define SQ
3d330 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 52 LITE_TESTCTRL_PR
3d340 4e 47 5f 52 45 53 45 54 20 20 20 20 20 20 20 20 NG_RESET
3d350 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 7.#define
3d360 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c SQLITE_TESTCTRL
3d370 5f 42 49 54 56 45 43 5f 54 45 53 54 20 20 20 20 _BITVEC_TEST
3d380 20 20 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 8.../*
3d390 0a 2a 2a 20 55 6e 64 6f 20 74 68 65 20 68 61 63 .** Undo the hac
3d3a0 6b 20 74 68 61 74 20 63 6f 6e 76 65 72 74 73 20 k that converts
3d3b0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 74 floating point t
3d3c0 79 70 65 73 20 74 6f 20 69 6e 74 65 67 65 72 20 ypes to integer
3d3d0 66 6f 72 0a 2a 2a 20 62 75 69 6c 64 73 20 6f 6e for.** builds on
3d3e0 20 70 72 6f 63 65 73 73 6f 72 73 20 77 69 74 68 processors with
3d3f0 6f 75 74 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 out floating poi
3d400 6e 74 20 73 75 70 70 6f 72 74 2e 0a 2a 2f 0a 23 nt support..*/.#
3d410 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 ifdef SQLITE_OMI
3d420 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 T_FLOATING_POINT
3d430 0a 23 20 75 6e 64 65 66 20 64 6f 75 62 6c 65 0a .# undef double.
3d440 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 5f #endif..#ifdef _
3d450 5f 63 70 6c 75 73 70 6c 75 73 0a 7d 20 20 2f 2a _cplusplus.} /*
3d460 20 45 6e 64 20 6f 66 20 74 68 65 20 27 65 78 74 End of the 'ext
3d470 65 72 6e 20 22 43 22 27 20 62 6c 6f 63 6b 20 2a ern "C"' block *
3d480 2f 0a 23 65 6e 64 69 66 0a 23 65 6e 64 69 66 0a /.#endif.#endif.