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 33 2e 68 ) $Id: sqlite3.h
05e0: 2c 76 20 31 2e 33 33 20 32 30 30 37 2f 31 32 2f ,v 1.33 2007/12/
05f0: 30 34 20 31 36 3a 31 31 3a 31 33 20 72 6d 73 69 04 16:11:13 rmsi
0600: 6d 70 73 6f 6e 20 45 78 70 20 24 0a 2a 2f 0a 23 mpson Exp $.*/.#
0610: 69 66 6e 64 65 66 20 5f 53 51 4c 49 54 45 33 5f ifndef _SQLITE3_
0620: 48 5f 0a 23 64 65 66 69 6e 65 20 5f 53 51 4c 49 H_.#define _SQLI
0630: 54 45 33 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20 TE3_H_.#include
0640: 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20 2f <stdarg.h> /
0650: 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68 65 * Needed for the
0660: 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 definition of v
0670: 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a a_list */../*.**
0680: 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63 61 Make sure we ca
0690: 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75 66 n call this stuf
06a0: 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 f from C++..*/.#
06b0: 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 ifdef __cplusplu
06c0: 73 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 s.extern "C" {.#
06d0: 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 endif.../*.** Ad
06e0: 64 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f d the ability to
06f0: 20 6f 76 65 72 72 69 64 65 20 27 65 78 74 65 72 override 'exter
0700: 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 n'.*/.#ifndef SQ
0710: 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 LITE_EXTERN.# de
0720: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 fine SQLITE_EXTE
0730: 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 RN extern.#endif
0740: 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 ../*.** Make sur
0750: 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c 73 20 e these symbols
0760: 77 68 65 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 where not define
0770: 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69 6f d by some previo
0780: 75 73 20 68 65 61 64 65 72 0a 2a 2a 20 66 69 6c us header.** fil
0790: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c e..*/.#ifdef SQL
07a0: 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e ITE_VERSION.# un
07b0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 def SQLITE_VERSI
07c0: 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 ON.#endif.#ifdef
07d0: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f SQLITE_VERSION_
07e0: 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 NUMBER.# undef S
07f0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 QLITE_VERSION_NU
0800: 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a MBER.#endif../*.
0810: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d ** CAPI3REF: Com
0820: 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 pile-Time Librar
0830: 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 y Version Number
0840: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 65 72 73 s.**.** The vers
0850: 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 ion of the SQLit
0860: 65 20 6c 69 62 72 61 72 79 20 69 73 20 63 6f 6e e library is con
0870: 74 61 69 6e 65 64 20 69 6e 20 74 68 65 20 73 71 tained in the sq
0880: 6c 69 74 65 33 2e 68 0a 2a 2a 20 68 65 61 64 65 lite3.h.** heade
0890: 72 20 66 69 6c 65 20 69 6e 20 61 20 23 64 65 66 r file in a #def
08a0: 69 6e 65 20 6e 61 6d 65 64 20 53 51 4c 49 54 45 ine named SQLITE
08b0: 5f 56 45 52 53 49 4f 4e 2e 20 20 54 68 65 20 53 _VERSION. The S
08c0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 2a 2a QLITE_VERSION.**
08d0: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 macro resolves
08e0: 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 to a string cons
08f0: 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 tant..**.** The
0900: 66 6f 72 6d 61 74 20 6f 66 20 74 68 65 20 76 65 format of the ve
0910: 72 73 69 6f 6e 20 73 74 72 69 6e 67 20 69 73 20 rsion string is
0920: 22 58 2e 59 2e 5a 22 2c 20 77 68 65 72 65 0a 2a "X.Y.Z", where.*
0930: 2a 20 58 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 * X is the major
0940: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 2c version number,
0950: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 Y is the minor
0960: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 version number a
0970: 6e 64 20 5a 0a 2a 2a 20 69 73 20 74 68 65 20 72 nd Z.** is the r
0980: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 20 20 elease number.
0990: 54 68 65 20 58 2e 59 2e 5a 20 6d 69 67 68 74 20 The X.Y.Z might
09a0: 62 65 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 22 be followed by "
09b0: 61 6c 70 68 61 22 20 6f 72 20 22 62 65 74 61 22 alpha" or "beta"
09c0: 2e 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 ..** For example
09d0: 20 22 33 2e 31 2e 31 62 65 74 61 22 2e 0a 2a 2a "3.1.1beta"..**
09e0: 0a 2a 2a 20 54 68 65 20 58 20 76 61 6c 75 65 20 .** The X value
09f0: 69 73 20 61 6c 77 61 79 73 20 33 20 69 6e 20 53 is always 3 in S
0a00: 51 4c 69 74 65 2e 20 20 54 68 65 20 58 20 76 61 QLite. The X va
0a10: 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 lue only changes
0a20: 20 77 68 65 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 when.** backwar
0a30: 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ds compatibility
0a40: 20 69 73 20 62 72 6f 6b 65 6e 20 61 6e 64 20 77 is broken and w
0a50: 65 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65 76 65 e intend to neve
0a60: 72 20 62 72 65 61 6b 0a 2a 2a 20 62 61 63 6b 77 r break.** backw
0a70: 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 ards compatibili
0a80: 74 79 2e 20 20 54 68 65 20 59 20 76 61 6c 75 65 ty. The Y value
0a90: 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77 68 only changes wh
0aa0: 65 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72 65 20 en.** there are
0ab0: 6d 61 6a 6f 72 20 66 65 61 74 75 72 65 20 65 6e major feature en
0ac0: 68 61 6e 63 65 6d 65 6e 74 73 20 74 68 61 74 20 hancements that
0ad0: 61 72 65 20 66 6f 72 77 61 72 64 73 20 63 6f 6d are forwards com
0ae0: 70 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20 6e patible.** but n
0af0: 6f 74 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d ot backwards com
0b00: 70 61 74 69 62 6c 65 2e 20 20 54 68 65 20 5a 20 patible. The Z
0b10: 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 6d 65 value is increme
0b20: 6e 74 65 64 20 77 69 74 68 0a 2a 2a 20 65 61 63 nted with.** eac
0b30: 68 20 72 65 6c 65 61 73 65 20 62 75 74 20 72 65 h release but re
0b40: 73 65 74 73 20 62 61 63 6b 20 74 6f 20 30 20 77 sets back to 0 w
0b50: 68 65 6e 20 59 20 69 73 20 69 6e 63 72 65 6d 65 hen Y is increme
0b60: 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 nted..**.** The
0b70: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e SQLITE_VERSION_N
0b80: 55 4d 42 45 52 20 69 73 20 61 6e 20 69 6e 74 65 UMBER is an inte
0b90: 67 65 72 20 77 69 74 68 20 74 68 65 20 76 61 6c ger with the val
0ba0: 75 65 20 0a 2a 2a 20 28 58 2a 31 30 30 30 30 30 ue .** (X*100000
0bb0: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 2e 0 + Y*1000 + Z).
0bc0: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 66 6f For example, fo
0bd0: 72 20 76 65 72 73 69 6f 6e 20 22 33 2e 31 2e 31 r version "3.1.1
0be0: 62 65 74 61 22 2c 20 0a 2a 2a 20 53 51 4c 49 54 beta", .** SQLIT
0bf0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 E_VERSION_NUMBER
0c00: 20 69 73 20 73 65 74 20 74 6f 20 33 30 30 31 30 is set to 30010
0c10: 30 31 2e 20 54 6f 20 64 65 74 65 63 74 20 69 66 01. To detect if
0c20: 20 74 68 65 79 20 61 72 65 20 75 73 69 6e 67 20 they are using
0c30: 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 31 2e .** version 3.1.
0c40: 31 20 6f 72 20 67 72 65 61 74 65 72 20 61 74 20 1 or greater at
0c50: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2c 20 70 72 compile time, pr
0c60: 6f 67 72 61 6d 73 20 6d 61 79 20 75 73 65 20 74 ograms may use t
0c70: 68 65 20 74 65 73 74 20 0a 2a 2a 20 28 53 51 4c he test .** (SQL
0c80: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 ITE_VERSION_NUMB
0c90: 45 52 3e 3d 33 30 30 31 30 30 31 29 2e 0a 2a 2a ER>=3001001)..**
0ca0: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
0cb0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
0cc0: 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 n()] and [sqlite
0cd0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 3_libversion_num
0ce0: 62 65 72 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 ber()]..*/.#defi
0cf0: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f ne SQLITE_VERSIO
0d00: 4e 20 20 20 20 20 20 20 20 20 22 33 2e 35 2e 33 N "3.5.3
0d10: 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ".#define SQLITE
0d20: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 _VERSION_NUMBER
0d30: 33 30 30 35 30 30 33 0a 0a 2f 2a 0a 2a 2a 20 43 3005003../*.** C
0d40: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d API3REF: Run-Tim
0d50: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f e Library Versio
0d60: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 n Numbers.**.**
0d70: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
0d80: 65 74 75 72 6e 20 76 61 6c 75 65 73 20 65 71 75 eturn values equ
0d90: 69 76 61 6c 65 6e 74 20 74 6f 20 74 68 65 20 68 ivalent to the h
0da0: 65 61 64 65 72 20 63 6f 6e 73 74 61 6e 74 73 0a eader constants.
0db0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 ** [SQLITE_VERSI
0dc0: 4f 4e 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f ON] and [SQLITE_
0dd0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e VERSION_NUMBER].
0de0: 20 20 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 The values ret
0df0: 75 72 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69 73 urned.** by this
0e00: 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 routines should
0e10: 20 6f 6e 6c 79 20 62 65 20 64 69 66 66 65 72 65 only be differe
0e20: 6e 74 20 66 72 6f 6d 20 74 68 65 20 68 65 61 64 nt from the head
0e30: 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 69 66 20 er values.** if
0e40: 79 6f 75 20 63 6f 6d 70 69 6c 65 20 79 6f 75 72 you compile your
0e50: 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 61 program using a
0e60: 6e 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 n sqlite3.h head
0e70: 65 72 20 66 72 6f 6d 20 61 0a 2a 2a 20 64 69 66 er from a.** dif
0e80: 66 65 72 65 6e 74 20 76 65 72 73 69 6f 6e 20 6f ferent version o
0e90: 66 20 53 51 4c 69 74 65 20 74 68 61 74 20 74 68 f SQLite that th
0ea0: 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 e version of the
0eb0: 20 6c 69 62 72 61 72 79 20 79 6f 75 0a 2a 2a 20 library you.**
0ec0: 6c 69 6e 6b 20 61 67 61 69 6e 73 74 2e 0a 2a 2a link against..**
0ed0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
0ee0: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 version[] string
0ef0: 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 constant contai
0f00: 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 74 ns the text of t
0f10: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 he.** [SQLITE_VE
0f20: 52 53 49 4f 4e 5d 20 73 74 72 69 6e 67 2e 20 20 RSION] string.
0f30: 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 The sqlite3_libv
0f40: 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f ersion() functio
0f50: 6e 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 n returns.** a p
0f60: 6f 69 6e 65 72 20 74 6f 20 74 68 65 20 73 71 6c oiner to the sql
0f70: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 ite3_version[] s
0f80: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 tring constant.
0f90: 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a The function.**
0fa0: 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 is provided for
0fb0: 20 44 4c 4c 20 75 73 65 72 73 20 77 68 6f 20 63 DLL users who c
0fc0: 61 6e 20 6f 6e 6c 79 20 61 63 63 65 73 73 20 66 an only access f
0fd0: 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 6e 6f 74 unctions and not
0fe0: 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 .** constants wi
0ff0: 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 0a 2a 2f thin the DLL..*/
1000: 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 .SQLITE_EXTERN c
1010: 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74 65 onst char sqlite
1020: 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 3_version[];.con
1030: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
1040: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 _libversion(void
1050: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c );.int sqlite3_l
1060: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 ibversion_number
1070: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 (void);../*.** C
1080: 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f API3REF: Test To
1090: 20 53 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 See If The Libr
10a0: 61 72 79 20 49 73 20 54 68 72 65 61 64 73 61 66 ary Is Threadsaf
10b0: 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 e.**.** This rou
10c0: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 54 52 55 tine returns TRU
10d0: 45 20 28 6e 6f 6e 7a 65 72 6f 29 20 69 66 20 53 E (nonzero) if S
10e0: 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69 6c QLite was compil
10f0: 65 64 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 6f ed with.** all o
1100: 66 20 69 74 73 20 6d 75 74 65 78 65 73 20 65 6e f its mutexes en
1110: 61 62 6c 65 64 20 61 6e 64 20 69 73 20 74 68 75 abled and is thu
1120: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 49 s threadsafe. I
1130: 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20 7a 65 72 t returns.** zer
1140: 6f 20 69 66 20 74 68 65 20 70 61 72 74 69 63 75 o if the particu
1150: 6c 61 72 20 62 75 69 6c 64 20 69 73 20 66 6f 72 lar build is for
1160: 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 single-threaded
1170: 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 6f 6e operation.** on
1180: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 52 65 61 6c 6c 79 ly..**.** Really
1190: 20 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e all this routin
11a0: 65 20 64 6f 65 73 20 69 73 20 72 65 74 75 72 6e e does is return
11b0: 20 74 72 75 65 20 69 66 20 53 51 4c 69 74 65 20 true if SQLite
11c0: 77 61 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 was compiled.**
11d0: 77 69 74 68 20 74 68 65 20 2d 44 53 51 4c 49 54 with the -DSQLIT
11e0: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f E_THREADSAFE=1 o
11f0: 70 74 69 6f 6e 20 61 6e 64 20 66 61 6c 73 65 20 ption and false
1200: 69 66 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 if.** compiled w
1210: 69 74 68 20 2d 44 53 51 4c 49 54 45 5f 54 48 52 ith -DSQLITE_THR
1220: 45 41 44 53 41 46 45 3d 30 2e 20 20 49 66 20 53 EADSAFE=0. If S
1230: 51 4c 69 74 65 20 75 73 65 73 20 61 6e 0a 2a 2a QLite uses an.**
1240: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
1250: 69 6e 65 64 20 6d 75 74 65 78 20 73 75 62 73 79 ined mutex subsy
1260: 73 74 65 6d 2c 20 6d 61 6c 6c 6f 63 20 73 75 62 stem, malloc sub
1270: 73 79 73 74 65 6d 2c 20 63 6f 6c 6c 61 74 69 6e system, collatin
1280: 67 0a 2a 2a 20 73 65 71 75 65 6e 63 65 2c 20 56 g.** sequence, V
1290: 46 53 2c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e FS, SQL function
12a0: 2c 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 , progress callb
12b0: 61 63 6b 2c 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b ack, commit hook
12c0: 2c 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 2c 20 ,.** extension,
12d0: 6f 72 20 6f 74 68 65 72 20 61 63 63 65 73 73 6f or other accesso
12e0: 72 69 65 73 20 61 6e 64 20 74 68 65 73 65 20 61 ries and these a
12f0: 64 64 2d 6f 6e 73 20 61 72 65 20 6e 6f 74 0a 2a dd-ons are not.*
1300: 2a 20 74 68 72 65 61 64 73 61 66 65 2c 20 74 68 * threadsafe, th
1310: 65 6e 20 63 6c 65 61 72 6c 79 20 74 68 65 20 63 en clearly the c
1320: 6f 6d 62 69 6e 61 74 69 6f 6e 20 77 69 6c 6c 20 ombination will
1330: 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66 not be threadsaf
1340: 65 0a 2a 2a 20 65 69 74 68 65 72 2e 20 20 48 65 e.** either. He
1350: 6e 63 65 2c 20 74 68 69 73 20 72 6f 75 74 69 6e nce, this routin
1360: 65 20 6e 65 76 65 72 20 72 65 70 6f 72 74 73 20 e never reports
1370: 74 68 61 74 20 74 68 65 20 6c 69 62 72 61 72 79 that the library
1380: 0a 2a 2a 20 69 73 20 67 75 61 72 61 6e 74 65 65 .** is guarantee
1390: 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 d to be threadsa
13a0: 66 65 2c 20 6f 6e 6c 79 20 77 68 65 6e 20 69 74 fe, only when it
13b0: 20 69 73 20 67 75 61 72 61 6e 74 65 65 64 20 6e is guaranteed n
13c0: 6f 74 0a 2a 2a 20 74 6f 20 62 65 2e 0a 2a 2a 0a ot.** to be..**.
13d0: 2a 2a 20 54 68 69 73 20 69 73 20 61 6e 20 65 78 ** This is an ex
13e0: 70 65 72 69 6d 65 6e 74 61 6c 20 41 50 49 20 61 perimental API a
13f0: 6e 64 20 6d 61 79 20 67 6f 20 61 77 61 79 20 6f nd may go away o
1400: 72 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 r change in futu
1410: 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 73 2e 0a re.** releases..
1420: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 */.int sqlite3_t
1430: 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b hreadsafe(void);
1440: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1450: 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 : Database Conne
1460: 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 0a ction Handle.**.
1470: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c ** Each open SQL
1480: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20 ite database is
1490: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 70 represented by p
14a0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 ointer to an ins
14b0: 74 61 6e 63 65 20 6f 66 20 74 68 65 0a 2a 2a 20 tance of the.**
14c0: 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65 opaque structure
14d0: 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 named "sqlite3"
14e0: 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 . It is useful
14f0: 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 to think of an s
1500: 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 qlite3.** pointe
1510: 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 r as an object.
1520: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 The [sqlite3_op
1530: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f en()], [sqlite3_
1540: 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a open16()], and.*
1550: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f * [sqlite3_open_
1560: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 v2()] interfaces
1570: 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 are its constru
1580: 63 74 6f 72 73 0a 2a 2a 20 61 6e 64 20 5b 73 71 ctors.** and [sq
1590: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 lite3_close()] i
15a0: 73 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 s its destructor
15b0: 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e . There are man
15c0: 79 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63 y other interfac
15d0: 65 73 0a 2a 2a 20 28 73 75 63 68 20 61 73 20 5b es.** (such as [
15e0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
15f0: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f v2()], [sqlite3_
1600: 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
1610: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 )], and.** [sqli
1620: 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 te3_busy_timeout
1630: 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 ()] to name but
1640: 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20 three) that are
1650: 6d 65 74 68 6f 64 73 20 6f 6e 20 74 68 69 73 0a methods on this.
1660: 2a 2a 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 ** object..*/.ty
1670: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
1680: 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 0a ite3 sqlite3;...
1690: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
16a0: 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 64-Bit Integer T
16b0: 79 70 65 73 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 ypes.**.** Some
16c0: 63 6f 6d 70 69 6c 65 72 73 20 64 6f 20 6e 6f 74 compilers do not
16d0: 20 73 75 70 70 6f 72 74 20 74 68 65 20 22 6c 6f support the "lo
16e0: 6e 67 20 6c 6f 6e 67 22 20 64 61 74 61 74 79 70 ng long" datatyp
16f0: 65 2e 20 20 53 6f 20 77 65 20 68 61 76 65 0a 2a e. So we have.*
1700: 2a 20 74 6f 20 64 6f 20 63 6f 6d 70 69 6c 65 72 * to do compiler
1710: 2d 73 70 65 63 69 66 69 63 20 74 79 70 65 64 65 -specific typede
1720: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 fs for 64-bit si
1730: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 gned and unsigne
1740: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a d integers..**.*
1750: 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 69 6e * Many SQLite in
1760: 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e terface function
1770: 73 20 72 65 71 75 69 72 65 20 61 20 36 34 2d 62 s require a 64-b
1780: 69 74 20 69 6e 74 65 67 65 72 20 61 72 67 75 6d it integer argum
1790: 65 6e 74 73 2e 0a 2a 2a 20 54 68 6f 73 65 20 69 ents..** Those i
17a0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 64 65 nterfaces are de
17b0: 63 6c 61 72 65 64 20 75 73 69 6e 67 20 74 68 69 clared using thi
17c0: 73 20 74 79 70 65 64 65 66 2e 0a 2a 2f 0a 23 69 s typedef..*/.#i
17d0: 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 fdef SQLITE_INT6
17e0: 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 4_TYPE. typedef
17f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 SQLITE_INT64_TY
1800: 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b PE sqlite_int64;
1810: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 . typedef unsig
1820: 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 ned SQLITE_INT64
1830: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e _TYPE sqlite_uin
1840: 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e t64;.#elif defin
1850: 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 ed(_MSC_VER) ||
1860: 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e defined(__BORLAN
1870: 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 DC__). typedef
1880: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 __int64 sqlite_i
1890: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 nt64;. typedef
18a0: 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 unsigned __int64
18b0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a sqlite_uint64;.
18c0: 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 #else. typedef
18d0: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 long long int sq
18e0: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 lite_int64;. ty
18f0: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c pedef unsigned l
1900: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c ong long int sql
1910: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 ite_uint64;.#end
1920: 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 if.typedef sqlit
1930: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f e_int64 sqlite3_
1940: 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 int64;.typedef s
1950: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c qlite_uint64 sql
1960: 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a ite3_uint64;../*
1970: 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 .** If compiling
1980: 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 for a processor
1990: 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 that lacks floa
19a0: 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f ting point suppo
19b0: 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 rt,.** substitut
19c0: 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c e integer for fl
19d0: 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 0a 2a 2f 0a oating-point.*/.
19e0: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d #ifdef SQLITE_OM
19f0: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e IT_FLOATING_POIN
1a00: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c T.# define doubl
1a10: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a e sqlite3_int64.
1a20: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 #endif../*.** CA
1a30: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 PI3REF: Closing
1a40: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 A Database Conne
1a50: 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c ction.**.** Call
1a60: 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 77 this function w
1a70: 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f ith a pointer to
1a80: 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61 a structure tha
1a90: 74 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79 t was previously
1aa0: 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f .** returned fro
1ab0: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 m [sqlite3_open(
1ac0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
1ad0: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 n16()], or.** [s
1ae0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
1af0: 5d 20 61 6e 64 20 74 68 65 20 63 6f 72 72 65 73 ] and the corres
1b00: 70 6f 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 ponding database
1b10: 20 77 69 6c 6c 20 62 79 0a 2a 2a 20 63 6c 6f 73 will by.** clos
1b20: 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6c 6c 20 53 51 ed..**.** All SQ
1b30: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 72 65 L statements pre
1b40: 70 61 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c pared using [sql
1b50: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
1b60: 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
1b70: 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
1b80: 5d 20 6d 75 73 74 20 62 65 20 64 65 73 74 72 6f ] must be destro
1b90: 79 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 yed using [sqlit
1ba0: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a e3_finalize()].*
1bb0: 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20 72 6f * before this ro
1bc0: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2e utine is called.
1bd0: 20 4f 74 68 65 72 77 69 73 65 2c 20 53 51 4c 49 Otherwise, SQLI
1be0: 54 45 5f 42 55 53 59 20 69 73 20 72 65 74 75 72 TE_BUSY is retur
1bf0: 6e 65 64 20 61 6e 64 20 74 68 65 0a 2a 2a 20 64 ned and the.** d
1c00: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1c10: 6f 6e 20 72 65 6d 61 69 6e 73 20 6f 70 65 6e 2e on remains open.
1c20: 0a 2a 2a 0a 2a 2a 20 50 61 73 73 69 6e 67 20 74 .**.** Passing t
1c30: 68 69 73 20 72 6f 75 74 69 6e 65 20 61 20 64 61 his routine a da
1c40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1c50: 6e 20 74 68 61 74 20 68 61 73 20 61 6c 72 65 61 n that has alrea
1c60: 64 79 20 62 65 65 6e 0a 2a 2a 20 63 6c 6f 73 65 dy been.** close
1c70: 64 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 d results in und
1c80: 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e efined behavior.
1c90: 20 20 49 66 20 6f 74 68 65 72 20 69 6e 74 65 72 If other inter
1ca0: 66 61 63 65 73 20 74 68 61 74 0a 2a 2a 20 72 65 faces that.** re
1cb0: 66 65 72 65 6e 63 65 20 74 68 65 20 73 61 6d 65 ference the same
1cc0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1cd0: 74 69 6f 6e 20 61 72 65 20 70 65 6e 64 69 6e 67 tion are pending
1ce0: 20 28 65 69 74 68 65 72 20 69 6e 20 74 68 65 0a (either in the.
1cf0: 2a 2a 20 73 61 6d 65 20 74 68 72 65 61 64 20 6f ** same thread o
1d00: 72 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 r in different t
1d10: 68 72 65 61 64 73 29 20 77 68 65 6e 20 74 68 69 hreads) when thi
1d20: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c s routine is cal
1d30: 6c 65 64 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 led,.** then the
1d40: 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 behavior is und
1d50: 65 66 69 6e 65 64 20 61 6e 64 20 69 73 20 61 6c efined and is al
1d60: 6d 6f 73 74 20 63 65 72 74 61 69 6e 6c 79 20 75 most certainly u
1d70: 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 69 ndesirable..*/.i
1d80: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 nt sqlite3_close
1d90: 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a (sqlite3 *);../*
1da0: 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 .** The type for
1db0: 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 a callback func
1dc0: 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 tion..** This is
1dd0: 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 legacy and depr
1de0: 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 ecated. It is i
1df0: 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 ncluded for hist
1e00: 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 orical.** compat
1e10: 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e ibility and is n
1e20: 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a ot documented..*
1e30: 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a /.typedef int (*
1e40: 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b sqlite3_callback
1e50: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 )(void*,int,char
1e60: 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a **, char**);../*
1e70: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e .** CAPI3REF: On
1e80: 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 e-Step Query Exe
1e90: 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 cution Interface
1ea0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 .**.** This inte
1eb0: 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f rface is used to
1ec0: 20 64 6f 20 61 20 6f 6e 65 2d 74 69 6d 65 20 65 do a one-time e
1ed0: 76 61 6c 75 61 74 61 74 69 6f 6e 20 6f 66 20 7a valuatation of z
1ee0: 65 72 6f 0a 2a 2a 20 6f 72 20 6d 6f 72 65 20 53 ero.** or more S
1ef0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 QL statements.
1f00: 55 54 46 2d 38 20 74 65 78 74 20 6f 66 20 74 68 UTF-8 text of th
1f10: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 e SQL statements
1f20: 20 74 6f 0a 2a 2a 20 62 65 20 65 76 61 6c 75 74 to.** be evalut
1f30: 65 64 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 ed is passed in
1f40: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 as the second pa
1f50: 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 73 74 rameter. The st
1f60: 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 72 65 20 atements.** are
1f70: 70 72 65 70 61 72 65 64 20 6f 6e 65 20 62 79 20 prepared one by
1f80: 6f 6e 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 one using [sqlit
1f90: 65 33 5f 70 72 65 70 61 72 65 28 29 5d 2c 20 65 e3_prepare()], e
1fa0: 76 61 6c 75 61 74 65 64 0a 2a 2a 20 75 73 69 6e valuated.** usin
1fb0: 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 g [sqlite3_step(
1fc0: 29 5d 2c 20 74 68 65 6e 20 64 65 73 74 72 6f 79 )], then destroy
1fd0: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ed using [sqlite
1fe0: 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 3_finalize()]..*
1ff0: 2a 0a 2a 2a 20 49 66 20 6f 6e 65 20 6f 72 20 6d *.** If one or m
2000: 6f 72 65 20 6f 66 20 74 68 65 20 53 51 4c 20 73 ore of the SQL s
2010: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 71 75 tatements are qu
2020: 65 72 69 65 73 2c 20 74 68 65 6e 0a 2a 2a 20 74 eries, then.** t
2030: 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 he callback func
2040: 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 tion specified b
2050: 79 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 y the 3rd parame
2060: 74 65 72 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 ter is.** invoke
2070: 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 d once for each
2080: 72 6f 77 20 6f 66 20 74 68 65 20 71 75 65 72 79 row of the query
2090: 20 72 65 73 75 6c 74 2e 20 20 54 68 69 73 20 63 result. This c
20a0: 61 6c 6c 62 61 63 6b 0a 2a 2a 20 73 68 6f 75 6c allback.** shoul
20b0: 64 20 6e 6f 72 6d 61 6c 6c 79 20 72 65 74 75 72 d normally retur
20c0: 6e 20 30 2e 20 20 49 66 20 74 68 65 20 63 61 6c n 0. If the cal
20d0: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 lback returns a
20e0: 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 76 61 6c 75 non-zero.** valu
20f0: 65 20 74 68 65 6e 20 74 68 65 20 71 75 65 72 79 e then the query
2100: 20 69 73 20 61 62 6f 72 74 65 64 2c 20 61 6c 6c is aborted, all
2110: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 subsequent SQL
2120: 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 72 statements.** ar
2130: 65 20 73 6b 69 70 70 65 64 20 61 6e 64 20 74 68 e skipped and th
2140: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 e sqlite3_exec()
2150: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e function return
2160: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 42 s the [SQLITE_AB
2170: 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ORT]..**.** The
2180: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 4th parameter to
2190: 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 this interface
21a0: 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 is an arbitrary
21b0: 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 0a pointer that is.
21c0: 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 ** passed throug
21d0: 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 h to the callbac
21e0: 6b 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 69 74 k function as it
21f0: 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 s first paramete
2200: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 32 6e 64 r..**.** The 2nd
2210: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
2220: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
2230: 69 6f 6e 20 69 73 20 74 68 65 20 6e 75 6d 62 65 ion is the numbe
2240: 72 20 6f 66 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 r of.** columns
2250: 69 6e 20 74 68 65 20 71 75 65 72 79 20 72 65 73 in the query res
2260: 75 6c 74 2e 20 20 54 68 65 20 33 72 64 20 70 61 ult. The 3rd pa
2270: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 rameter to the c
2280: 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 61 6e allback.** is an
2290: 20 61 72 72 61 79 20 6f 66 20 73 74 72 69 6e 67 array of string
22a0: 73 20 68 6f 6c 64 69 6e 67 20 74 68 65 20 76 61 s holding the va
22b0: 6c 75 65 73 20 66 6f 72 20 65 61 63 68 20 63 6f lues for each co
22c0: 6c 75 6d 6e 0a 2a 2a 20 61 73 20 65 78 74 72 61 lumn.** as extra
22d0: 63 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 cted using [sqli
22e0: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
22f0: 29 5d 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 )]..** The 4th p
2300: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
2310: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 callback is an a
2320: 72 72 61 79 20 6f 66 20 73 74 72 69 6e 67 73 0a rray of strings.
2330: 2a 2a 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e ** obtained usin
2340: 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d g [sqlite3_colum
2350: 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 68 6f n_name()] and ho
2360: 6c 64 69 6e 67 0a 2a 2a 20 74 68 65 20 6e 61 6d lding.** the nam
2370: 65 73 20 6f 66 20 65 61 63 68 20 63 6f 6c 75 6d es of each colum
2380: 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c n..**.** The cal
2390: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d lback function m
23a0: 61 79 20 62 65 20 4e 55 4c 4c 2c 20 65 76 65 6e ay be NULL, even
23b0: 20 66 6f 72 20 71 75 65 72 69 65 73 2e 20 20 41 for queries. A
23c0: 20 4e 55 4c 4c 0a 2a 2a 20 63 61 6c 6c 62 61 63 NULL.** callbac
23d0: 6b 20 69 73 20 6e 6f 74 20 61 6e 20 65 72 72 6f k is not an erro
23e0: 72 2e 20 20 49 74 20 6a 75 73 74 20 6d 65 61 6e r. It just mean
23f0: 73 20 74 68 61 74 20 6e 6f 20 63 61 6c 6c 62 61 s that no callba
2400: 63 6b 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 69 6e ck.** will be in
2410: 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 voked..**.** If
2420: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 an error occurs
2430: 77 68 69 6c 65 20 70 61 72 73 69 6e 67 20 6f 72 while parsing or
2440: 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 evaluating the
2450: 53 51 4c 20 28 62 75 74 0a 2a 2a 20 6e 6f 74 20 SQL (but.** not
2460: 77 68 69 6c 65 20 65 78 65 63 75 74 69 6e 67 20 while executing
2470: 74 68 65 20 63 61 6c 6c 62 61 63 6b 29 20 74 68 the callback) th
2480: 65 6e 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 en an appropriat
2490: 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 e error.** messa
24a0: 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e ge is written in
24b0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e to memory obtain
24c0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
24d0: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 0a 2a _malloc()] and.*
24e0: 2a 20 2a 65 72 72 6d 73 67 20 69 73 20 6d 61 64 * *errmsg is mad
24f0: 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 e to point to th
2500: 61 74 20 6d 65 73 73 61 67 65 2e 20 20 54 68 65 at message. The
2510: 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f calling functio
2520: 6e 0a 2a 2a 20 69 73 20 72 65 73 70 6f 6e 73 69 n.** is responsi
2530: 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 ble for freeing
2540: 74 68 65 20 6d 65 6d 6f 72 79 20 75 73 69 6e 67 the memory using
2550: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
2560: 5d 2e 0a 2a 2a 20 49 66 20 65 72 72 6d 73 67 3d ]..** If errmsg=
2570: 3d 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 65 =NULL, then no e
2580: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 rror message is
2590: 65 76 65 72 20 77 72 69 74 74 65 6e 2e 0a 2a 2a ever written..**
25a0: 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 20 76 .** The return v
25b0: 61 6c 75 65 20 69 73 20 69 73 20 53 51 4c 49 54 alue is is SQLIT
25c0: 45 5f 4f 4b 20 69 66 20 74 68 65 72 65 20 61 72 E_OK if there ar
25d0: 65 20 6e 6f 20 65 72 72 6f 72 73 20 61 6e 64 0a e no errors and.
25e0: 2a 2a 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 53 ** some other [S
25f0: 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 74 75 72 QLITE_OK | retur
2600: 6e 20 63 6f 64 65 5d 20 69 66 20 74 68 65 72 65 n code] if there
2610: 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 20 0a is an error. .
2620: 2a 2a 20 54 68 65 20 70 61 72 74 69 63 75 6c 61 ** The particula
2630: 72 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 64 r return value d
2640: 65 70 65 6e 64 73 20 6f 6e 20 74 68 65 20 74 79 epends on the ty
2650: 70 65 20 6f 66 20 65 72 72 6f 72 2e 20 0a 2a 2a pe of error. .**
2660: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
2670: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a exec(. sqlite3*
2680: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
2690: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
26a0: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 /* An open da
26b0: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 tabase */. cons
26c0: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 t char *sql,
26d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
26e0: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f /* SQL to
26f0: 20 62 65 20 65 76 61 6c 75 74 65 64 20 2a 2f 0a be evaluted */.
2700: 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b int (*callback
2710: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 )(void*,int,char
2720: 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 **,char**), /*
2730: 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f Callback functio
2740: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 n */. void *,
2750: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2760: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2770: 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e /* 1st argumen
2780: 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f t to callback */
2790: 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 . char **errmsg
27a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
27b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
27c0: 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 Error msg writt
27d0: 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f en here */.);../
27e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
27f0: 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b esult Codes.** K
2800: 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f EYWORDS: SQLITE_
2810: 4f 4b 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 OK.**.** Many SQ
2820: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 Lite functions r
2830: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 eturn an integer
2840: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f result code fro
2850: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a m the set shown.
2860: 2a 2a 20 61 62 6f 76 65 20 69 6e 20 6f 72 64 65 ** above in orde
2870: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 r to indicates s
2880: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 uccess or failur
2890: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 73 e..**.** The res
28a0: 75 6c 74 20 63 6f 64 65 73 20 61 62 6f 76 65 20 ult codes above
28b0: 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6f 6e 65 are the only one
28c0: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 s returned by SQ
28d0: 4c 69 74 65 20 69 6e 20 69 74 73 0a 2a 2a 20 64 Lite in its.** d
28e0: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 efault configura
28f0: 74 69 6f 6e 2e 20 20 48 6f 77 65 76 65 72 2c 20 tion. However,
2900: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 the [sqlite3_ext
2910: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 ended_result_cod
2920: 65 73 28 29 5d 0a 2a 2a 20 41 50 49 20 63 61 6e es()].** API can
2930: 20 62 65 20 75 73 65 64 20 74 6f 20 73 65 74 20 be used to set
2940: 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 a database conne
2950: 63 74 6f 69 6e 20 74 6f 20 72 65 74 75 72 6e 20 ctoin to return
2960: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a more detailed.**
2970: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 2e 0a 2a result codes..*
2980: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
2990: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 SQLITE_IOERR_REA
29a0: 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 D | extended res
29b0: 75 6c 74 20 63 6f 64 65 73 5d 0a 2a 2a 0a 2a 2f ult codes].**.*/
29c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
29d0: 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20 OK 0
29e0: 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 /* Successful r
29f0: 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 esult */./* begi
2a00: 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 nning-of-error-c
2a10: 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 odes */.#define
2a20: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 SQLITE_ERROR
2a30: 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 1 /* SQL e
2a40: 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 rror or missing
2a50: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 database */.#def
2a60: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 ine SQLITE_INTER
2a70: 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 4e NAL 2 /* N
2a80: 4f 54 20 55 53 45 44 2e 20 49 6e 74 65 72 6e 61 OT USED. Interna
2a90: 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e l logic error in
2aa0: 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 SQLite */.#defi
2ab0: 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 ne SQLITE_PERM
2ac0: 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 3 /* Ac
2ad0: 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 cess permission
2ae0: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e denied */.#defin
2af0: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 e SQLITE_ABORT
2b00: 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 4 /* Cal
2b10: 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 lback routine re
2b20: 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 quested an abort
2b30: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
2b40: 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 TE_BUSY
2b50: 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 5 /* The datab
2b60: 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b ase file is lock
2b70: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
2b80: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 LITE_LOCKED
2b90: 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 6 /* A table
2ba0: 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 in the database
2bb0: 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 is locked */.#d
2bc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d efine SQLITE_NOM
2bd0: 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a EM 7 /*
2be0: 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c A malloc() fail
2bf0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
2c00: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 LITE_READONLY
2c10: 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 8 /* Attempt
2c20: 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 to write a read
2c30: 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f only database */
2c40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2c50: 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 INTERRUPT 9
2c60: 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 /* Operation te
2c70: 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 rminated by sqli
2c80: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a te3_interrupt()*
2c90: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
2ca0: 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 _IOERR 10
2cb0: 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f /* Some kind o
2cc0: 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 f disk I/O error
2cd0: 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 occurred */.#de
2ce0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 fine SQLITE_CORR
2cf0: 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 UPT 11 /*
2d00: 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 The database dis
2d10: 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f k image is malfo
2d20: 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rmed */.#define
2d30: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 SQLITE_NOTFOUND
2d40: 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55 12 /* NOT U
2d50: 53 45 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 65 SED. Table or re
2d60: 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a cord not found *
2d70: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
2d80: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 _FULL 13
2d90: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 /* Insertion f
2da0: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 ailed because da
2db0: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a tabase is full *
2dc0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
2dd0: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 _CANTOPEN 14
2de0: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f /* Unable to o
2df0: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 pen the database
2e00: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 file */.#define
2e10: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c SQLITE_PROTOCOL
2e20: 20 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20 15 /* NOT
2e30: 55 53 45 44 2e 20 44 61 74 61 62 61 73 65 20 6c USED. Database l
2e40: 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 ock protocol err
2e50: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 or */.#define SQ
2e60: 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 LITE_EMPTY
2e70: 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 16 /* Databas
2e80: 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 e is empty */.#d
2e90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 efine SQLITE_SCH
2ea0: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a EMA 17 /*
2eb0: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63 The database sc
2ec0: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a hema changed */.
2ed0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
2ee0: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20 OOBIG 18
2ef0: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f /* String or BLO
2f00: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c B exceeds size l
2f10: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 imit */.#define
2f20: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
2f30: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 T 19 /* Abort
2f40: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 due to constrai
2f50: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a nt violation */.
2f60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d #define SQLITE_M
2f70: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 ISMATCH 20
2f80: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 /* Data type mis
2f90: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 match */.#define
2fa0: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 SQLITE_MISUSE
2fb0: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 21 /* Libr
2fc0: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 ary used incorre
2fd0: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ctly */.#define
2fe0: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 SQLITE_NOLFS
2ff0: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 22 /* Uses
3000: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 OS features not
3010: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 supported on hos
3020: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
3030: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 ITE_AUTH
3040: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 23 /* Authoriz
3050: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a ation denied */.
3060: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
3070: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 ORMAT 24
3080: 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 /* Auxiliary dat
3090: 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 abase format err
30a0: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 or */.#define SQ
30b0: 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 LITE_RANGE
30c0: 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 25 /* 2nd par
30d0: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
30e0: 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 3_bind out of ra
30f0: 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nge */.#define S
3100: 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 QLITE_NOTADB
3110: 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 26 /* File o
3120: 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f pened that is no
3130: 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c t a database fil
3140: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
3150: 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 ITE_ROW
3160: 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 100 /* sqlite3_
3170: 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 step() has anoth
3180: 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a er row ready */.
3190: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
31a0: 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20 ONE 101
31b0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 /* sqlite3_step(
31c0: 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 ) has finished e
31d0: 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 xecuting */./* e
31e0: 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 nd-of-error-code
31f0: 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 s */../*.** CAPI
3200: 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 3REF: Extended R
3210: 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a esult Codes.**.*
3220: 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 * In its default
3230: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 configuration,
3240: 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 SQLite API routi
3250: 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f nes return one o
3260: 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 f 26 integer.**
3270: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 64 65 73 result codes des
3280: 63 72 69 62 65 64 20 61 74 20 72 65 73 75 6c 74 cribed at result
3290: 2d 63 6f 64 65 73 2e 20 20 48 6f 77 65 76 65 72 -codes. However
32a0: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 , experience has
32b0: 20 73 68 6f 77 6e 20 74 68 61 74 0a 2a 2a 20 6d shown that.** m
32c0: 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 65 73 any of these res
32d0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f ult codes are to
32e0: 6f 20 63 6f 75 72 73 65 2d 67 72 61 69 6e 65 64 o course-grained
32f0: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 . They do not p
3300: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 rovide as.** muc
3310: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 h information ab
3320: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 out problems as
3330: 75 73 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 users might like
3340: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 . In an effort
3350: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68 to.** address th
3360: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f is, newer versio
3370: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65 ns of SQLite (ve
3380: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 rsion 3.3.8 and
3390: 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a later) include.*
33a0: 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 * support for ad
33b0: 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 ditional result
33c0: 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 codes that provi
33d0: 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 de more detailed
33e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 information.**
33f0: 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 20 54 about errors. T
3400: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 he extended resu
3410: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61 lt codes are ena
3420: 62 6c 65 64 20 28 6f 72 20 64 69 73 61 62 6c 65 bled (or disable
3430: 64 29 20 66 6f 72 20 0a 2a 2a 20 65 61 63 68 20 d) for .** each
3440: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
3450: 65 63 74 69 6f 6e 20 75 73 69 6e 67 20 74 68 65 ection using the
3460: 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 [sqlite3_extend
3470: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 ed_result_codes(
3480: 29 5d 20 41 50 49 2e 0a 2a 2a 20 0a 2a 2a 20 53 )] API..** .** S
3490: 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c ome of the avail
34a0: 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 able extended re
34b0: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c sult codes are l
34c0: 69 73 74 65 64 20 61 62 6f 76 65 2e 0a 2a 2a 20 isted above..**
34d0: 57 65 20 65 78 70 65 63 74 20 74 68 65 20 6e 75 We expect the nu
34e0: 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65 64 mber of extended
34f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77 69 result codes wi
3500: 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20 ll be expand.**
3510: 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 74 over time. Soft
3520: 77 61 72 65 20 74 68 61 74 20 75 73 65 73 20 65 ware that uses e
3530: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
3540: 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65 odes should expe
3550: 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 ct.** to see new
3560: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e result codes in
3570: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
3580: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 0a of SQLite..** .
3590: 2a 2a 20 54 68 65 20 73 79 6d 62 6f 6c 69 63 20 ** The symbolic
35a0: 6e 61 6d 65 20 66 6f 72 20 61 6e 20 65 78 74 65 name for an exte
35b0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
35c0: 20 61 6c 77 61 79 73 20 63 6f 6e 74 61 69 6e 73 always contains
35d0: 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 70 72 a related.** pr
35e0: 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64 imary result cod
35f0: 65 20 61 73 20 61 20 70 72 65 66 69 78 2e 20 20 e as a prefix.
3600: 50 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63 Primary result c
3610: 6f 64 65 73 20 63 6f 6e 74 61 69 6e 20 61 20 73 odes contain a s
3620: 69 6e 67 6c 65 0a 2a 2a 20 22 5f 22 20 63 68 61 ingle.** "_" cha
3630: 72 61 63 74 65 72 2e 20 20 45 78 74 65 6e 64 65 racter. Extende
3640: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 63 d result codes c
3650: 6f 6e 74 61 69 6e 20 74 77 6f 20 6f 72 20 6d 6f ontain two or mo
3660: 72 65 20 22 5f 22 20 63 68 61 72 61 63 74 65 72 re "_" character
3670: 73 2e 0a 2a 2a 20 54 68 65 20 6e 75 6d 65 72 69 s..** The numeri
3680: 63 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 65 78 c value of an ex
3690: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
36a0: 64 65 20 63 61 6e 20 62 65 20 63 6f 6e 76 65 72 de can be conver
36b0: 74 65 64 20 74 6f 20 69 74 73 0a 2a 2a 20 63 6f ted to its.** co
36c0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 70 72 69 6d rresponding prim
36d0: 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 ary result code
36e0: 62 79 20 6d 61 73 6b 69 6e 67 20 6f 66 66 20 74 by masking off t
36f0: 68 65 20 6c 6f 77 65 72 20 38 20 62 79 74 65 73 he lower 8 bytes
3700: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 ..**.** The SQLI
3710: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64 TE_OK result cod
3720: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20 e will never be
3730: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69 extended. It wi
3740: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 ll always.** be
3750: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f exactly zero..*/
3760: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3770: 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 IOERR_READ
3780: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
3790: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 R | (1<<8)).#def
37a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
37b0: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 28 _SHORT_READ (
37c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
37d0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 2<<8)).#define S
37e0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 QLITE_IOERR_WRIT
37f0: 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 E (SQLIT
3800: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 E_IOERR | (3<<8)
3810: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
3820: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 _IOERR_FSYNC
3830: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
3840: 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 RR | (4<<8)).#de
3850: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
3860: 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 R_DIR_FSYNC
3870: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
3880: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (5<<8)).#define
3890: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 SQLITE_IOERR_TRU
38a0: 4e 43 41 54 45 20 20 20 20 20 20 28 53 51 4c 49 NCATE (SQLI
38b0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 TE_IOERR | (6<<8
38c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
38d0: 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 E_IOERR_FSTAT
38e0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
38f0: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 ERR | (7<<8)).#d
3900: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
3910: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 RR_UNLOCK
3920: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
3930: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (8<<8)).#define
3940: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 SQLITE_IOERR_RD
3950: 4c 4f 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c LOCK (SQL
3960: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c ITE_IOERR | (9<<
3970: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
3980: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 TE_IOERR_DELETE
3990: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
39a0: 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a OERR | (10<<8)).
39b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
39c0: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 OERR_BLOCKED
39d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
39e0: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 | (11<<8)).#def
39f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
3a00: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 28 _NOMEM (
3a10: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
3a20: 31 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 12<<8))../*.** C
3a30: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 API3REF: Flags F
3a40: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 or File Open Ope
3a50: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 43 6f rations.**.** Co
3a60: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 74 68 65 mbination of the
3a70: 20 66 6f 6c 6c 6f 77 69 6e 67 20 62 69 74 20 76 following bit v
3a80: 61 6c 75 65 73 20 61 72 65 20 75 73 65 64 20 61 alues are used a
3a90: 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 s the.** third a
3aa0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b rgument to the [
3ab0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
3ac0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 )] interface and
3ad0: 0a 2a 2a 20 61 73 20 66 6f 75 72 74 68 20 61 72 .** as fourth ar
3ae0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 78 4f gument to the xO
3af0: 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 pen method of th
3b00: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 e.** [sqlite3_vf
3b10: 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2f s] object..**.*/
3b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3b30: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 OPEN_READONLY
3b40: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0x00000001
3b50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3b60: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 OPEN_READWRITE
3b70: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0x00000002
3b80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3b90: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 OPEN_CREATE
3ba0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0x00000004
3bb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3bc0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f OPEN_DELETEONCLO
3bd0: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 SE 0x00000008
3be0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3bf0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 OPEN_EXCLUSIVE
3c00: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0x00000010
3c10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3c20: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 OPEN_MAIN_DB
3c30: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0x00000100
3c40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3c50: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 OPEN_TEMP_DB
3c60: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0x00000200
3c70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3c80: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 OPEN_TRANSIENT_D
3c90: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 B 0x00000400
3ca0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3cb0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 OPEN_MAIN_JOURNA
3cc0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 L 0x00000800
3cd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3ce0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 OPEN_TEMP_JOURNA
3cf0: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 L 0x00001000
3d00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3d10: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 OPEN_SUBJOURNAL
3d20: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0x00002000
3d30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3d40: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 OPEN_MASTER_JOUR
3d50: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 NAL 0x00004000
3d60: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
3d70: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74 : Device Charact
3d80: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 eristics.**.** T
3d90: 68 65 20 78 44 65 76 69 63 65 43 61 70 61 62 69 he xDeviceCapabi
3da0: 6c 69 74 69 65 73 20 6d 65 74 68 6f 64 20 6f 66 lities method of
3db0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f the [sqlite3_io
3dc0: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a _methods].** obj
3dd0: 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 ect returns an i
3de0: 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 nteger which is
3df0: 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20 a vector of the
3e00: 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 62 69 74 following.** bit
3e10: 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 values expressi
3e20: 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 ng I/O character
3e30: 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 istics of the ma
3e40: 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 ss storage.** de
3e50: 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 vice that holds
3e60: 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 the file that th
3e70: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 e [sqlite3_io_me
3e80: 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 thods].** refers
3e90: 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 to..**.** The S
3ea0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
3eb0: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e IC property mean
3ec0: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 s that all write
3ed0: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 s of.** any size
3ee0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 are atomic. Th
3ef0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
3f00: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a TOMICnnn values.
3f10: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 ** mean that wri
3f20: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 tes of blocks th
3f30: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 at are nnn bytes
3f40: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 in size and.**
3f50: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 are aligned to a
3f60: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 n address which
3f70: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 is an integer mu
3f80: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e ltiple of.** nnn
3f90: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 are atomic. Th
3fa0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 e SQLITE_IOCAP_S
3fb0: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 AFE_APPEND value
3fc0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 means.** that w
3fd0: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 hen data is appe
3fe0: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 nded to a file,
3ff0: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 the data is appe
4000: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 nded.** first th
4010: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 en the size of t
4020: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e he file is exten
4030: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f ded, never the o
4040: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 ther.** way arou
4050: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f nd. The SQLITE_
4060: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c IOCAP_SEQUENTIAL
4070: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 property means
4080: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 that.** informat
4090: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 ion is written t
40a0: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 o disk in the sa
40b0: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c me order as call
40c0: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 s.** to xWrite()
40d0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
40e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
40f0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
4100: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 0001.#define SQL
4110: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
4120: 35 31 32 20 20 20 20 20 20 20 30 78 30 30 30 30 512 0x0000
4130: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 0002.#define SQL
4140: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
4150: 31 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 1K 0x0000
4160: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 0004.#define SQL
4170: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
4180: 32 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 2K 0x0000
4190: 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 0008.#define SQL
41a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
41b0: 34 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 4K 0x0000
41c0: 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0010.#define SQL
41d0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
41e0: 38 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 8K 0x0000
41f0: 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0020.#define SQL
4200: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
4210: 31 36 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 16K 0x0000
4220: 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0040.#define SQL
4230: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
4240: 33 32 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 32K 0x0000
4250: 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0080.#define SQL
4260: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
4270: 36 34 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 64K 0x0000
4280: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0100.#define SQL
4290: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 ITE_IOCAP_SAFE_A
42a0: 50 50 45 4e 44 20 20 20 20 20 30 78 30 30 30 30 PPEND 0x0000
42b0: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0200.#define SQL
42c0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e ITE_IOCAP_SEQUEN
42d0: 54 49 41 4c 20 20 20 20 20 20 30 78 30 30 30 30 TIAL 0x0000
42e0: 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 0400../*.** CAPI
42f0: 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 3REF: File Locki
4300: 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 ng Levels.**.**
4310: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 SQLite uses one
4320: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 of the following
4330: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 integer values
4340: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a as the second.**
4350: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c argument to cal
4360: 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 ls it makes to t
4370: 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 he xLock() and x
4380: 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 Unlock() methods
4390: 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 .** of an [sqlit
43a0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f e3_io_methods] o
43b0: 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e bject..*/.#defin
43c0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f e SQLITE_LOCK_NO
43d0: 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 NE 0.#d
43e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 efine SQLITE_LOC
43f0: 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20 K_SHARED
4400: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
4410: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 _LOCK_RESERVED
4420: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 2.#define SQ
4430: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e LITE_LOCK_PENDIN
4440: 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e G 3.#defin
4450: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 e SQLITE_LOCK_EX
4460: 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f CLUSIVE 4../
4470: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
4480: 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 ynchronization T
4490: 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 ype Flags.**.**
44a0: 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f When SQLite invo
44b0: 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 kes the xSync()
44c0: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 method of an [sq
44d0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
44e0: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 74 20 75 ].** object it u
44f0: 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f ses a combinatio
4500: 6e 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 n of the followi
4510: 6e 67 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 ng integer value
4520: 73 20 61 73 0a 2a 2a 20 74 68 65 20 73 65 63 6f s as.** the seco
4530: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a nd argument..**.
4540: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 ** When the SQLI
4550: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 TE_SYNC_DATAONLY
4560: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 flag is used, i
4570: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 t means that the
4580: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 .** sync operati
4590: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f on only needs to
45a0: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d flush data to m
45b0: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e ass storage. In
45c0: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 ode.** informati
45d0: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 on need not be f
45e0: 6c 75 73 68 65 64 2e 20 20 54 68 65 20 53 51 4c lushed. The SQL
45f0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 ITE_SYNC_NORMAL
4600: 6d 65 61 6e 73 20 0a 2a 2a 20 74 6f 20 75 73 65 means .** to use
4610: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 normal fsync()
4620: 73 65 6d 61 6e 74 69 63 73 2e 20 20 54 68 65 20 semantics. The
4630: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c SQLITE_SYNC_FULL
4640: 20 66 6c 61 67 20 6d 65 61 6e 73 20 0a 2a 2a 20 flag means .**
4650: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 2d 58 20 to use Mac OS-X
4660: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 style fullsync i
4670: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 nstead of fsync(
4680: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 )..*/.#define SQ
4690: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c LITE_SYNC_NORMAL
46a0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 0x00002.
46b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
46c0: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 YNC_FULL
46d0: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 0x00003.#defin
46e0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 e SQLITE_SYNC_DA
46f0: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 TAONLY 0x00
4700: 30 31 30 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 010.../*.** CAPI
4710: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 3REF: OS Interfa
4720: 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e ce Open File Han
4730: 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 dle.**.** An [sq
4740: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 lite3_file] obje
4750: 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e ct represents an
4760: 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 open file in th
4770: 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66 61 63 e OS.** interfac
4780: 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 69 76 69 e layer. Indivi
4790: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 dual OS interfac
47a0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
47b0: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 s will.** want t
47c0: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 o subclass this
47d0: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 object by append
47e0: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 ing additional f
47f0: 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 ields.** for the
4800: 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 ir own use. The
4810: 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 pMethods entry
4820: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
4830: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 an.** [sqlite3_i
4840: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 o_methods] objec
4850: 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d t that defines m
4860: 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f ethods for perfo
4870: 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 rming.** I/O ope
4880: 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f rations on the o
4890: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 pen file..*/.typ
48a0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
48b0: 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 te3_file sqlite3
48c0: 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 _file;.struct sq
48d0: 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 lite3_file {. c
48e0: 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 onst struct sqli
48f0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a te3_io_methods *
4900: 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 pMethods; /* Me
4910: 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 thods for an ope
4920: 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a n file */.};../*
4930: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 .** CAPI3REF: OS
4940: 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 Interface File
4950: 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 Virtual Methods
4960: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 Object.**.** Eve
4970: 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 ry file opened b
4980: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 y the [sqlite3_v
4990: 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 fs] xOpen method
49a0: 20 63 6f 6e 74 61 69 6e 73 20 61 20 70 6f 69 6e contains a poin
49b0: 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 69 6e 73 ter to.** an ins
49c0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 74 68 69 tance of the thi
49d0: 73 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 s object. This
49e0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 object defines t
49f0: 68 65 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 75 73 he.** methods us
4a00: 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 ed to perform va
4a10: 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 rious operations
4a20: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 against the ope
4a30: 6e 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 n file..**.** Th
4a40: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 e flags argument
4a50: 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 to xSync may be
4a60: 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f one of [SQLITE_
4a70: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a SYNC_NORMAL] or.
4a80: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f ** [SQLITE_SYNC_
4a90: 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 FULL]. The firs
4aa0: 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 t choice is the
4ab0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a normal fsync()..
4ac0: 2a 20 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 * The second ch
4ad0: 6f 69 63 65 20 69 73 20 61 6e 0a 2a 2a 20 4f 53 oice is an.** OS
4ae0: 2d 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e -X style fullsyn
4af0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 53 c. The SQLITE_S
4b00: 59 4e 43 5f 44 41 54 41 20 66 6c 61 67 20 6d 61 YNC_DATA flag ma
4b10: 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 0a y be ORed in to.
4b20: 2a 2a 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 ** indicate that
4b30: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f only the data o
4b40: 66 20 74 68 65 20 66 69 6c 65 20 61 6e 64 20 6e f the file and n
4b50: 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 ot its inode nee
4b60: 64 73 20 74 6f 20 62 65 0a 2a 2a 20 73 79 6e 63 ds to be.** sync
4b70: 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 69 ed..** .** The i
4b80: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f nteger values to
4b90: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e xLock() and xUn
4ba0: 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f lock() are one o
4bb0: 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 f.** <ul>.** <li
4bc0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e > [SQLITE_LOCK_N
4bd0: 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 ONE],.** <li> [S
4be0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 QLITE_LOCK_SHARE
4bf0: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c D],.** <li> [SQL
4c00: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 ITE_LOCK_RESERVE
4c10: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c D],.** <li> [SQL
4c20: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 ITE_LOCK_PENDING
4c30: 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 ], or.** <li> [S
4c40: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 QLITE_LOCK_EXCLU
4c50: 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a SIVE]..** </ul>.
4c60: 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 ** xLock() incre
4c70: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 ases the lock. x
4c80: 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 Unlock() decreas
4c90: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 20 0a 2a es the lock. .*
4ca0: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 * The xCheckRese
4cb0: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f rvedLock() metho
4cc0: 64 20 6c 6f 6f 6b 73 0a 2a 2a 20 74 6f 20 73 65 d looks.** to se
4cd0: 65 20 69 66 20 61 6e 79 20 64 61 74 61 62 61 73 e if any databas
4ce0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 65 69 e connection, ei
4cf0: 74 68 65 72 20 69 6e 20 74 68 69 73 0a 2a 2a 20 ther in this.**
4d00: 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f process or in so
4d10: 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 me other process
4d20: 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 6e 20 , is holding an
4d30: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e RESERVED,.** PEN
4d40: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 DING, or EXCLUSI
4d50: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 VE lock on the f
4d60: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 ile. It returns
4d70: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 true.** if such
4d80: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 a lock exists a
4d90: 6e 64 20 66 61 6c 73 65 20 69 66 20 6e 6f 74 2e nd false if not.
4da0: 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 78 46 69 6c .** .** The xFil
4db0: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f eControl() metho
4dc0: 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 d is a generic i
4dd0: 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c nterface that al
4de0: 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 lows custom.** V
4df0: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f FS implementatio
4e00: 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 ns to directly c
4e10: 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 ontrol an open f
4e20: 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a ile using the.**
4e30: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 [sqlite3_file_c
4e40: 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 ontrol()] interf
4e50: 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 ace. The second
4e60: 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 0a 2a "op" argument.*
4e70: 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 * is an integer
4e80: 6f 70 63 6f 64 65 2e 20 20 20 54 68 65 20 74 68 opcode. The th
4e90: 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 ird.** argument
4ea0: 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 is a generic poi
4eb0: 6e 74 65 72 20 77 68 69 63 68 20 69 73 20 69 6e nter which is in
4ec0: 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 70 tended to be a p
4ed0: 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 20 73 ointer.** to a s
4ee0: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 tructure that ma
4ef0: 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 y contain argume
4f00: 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 nts or space in
4f10: 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 which to.** writ
4f20: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e e return values.
4f30: 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 Potential uses
4f40: 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f for xFileContro
4f50: 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 l() might be.**
4f60: 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 functions to ena
4f70: 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 ble blocking loc
4f80: 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 ks with timeouts
4f90: 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a , to change the.
4fa0: 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 ** locking strat
4fb0: 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 egy (for example
4fc0: 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 to use dot-file
4fd0: 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 locks), to inqu
4fe0: 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 ire.** about the
4ff0: 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 status of a loc
5000: 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 k, or to break s
5010: 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 tale locks. The
5020: 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 SQLite.** core
5030: 72 65 73 65 72 76 65 73 20 6f 70 63 6f 64 65 73 reserves opcodes
5040: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 less than 100 f
5050: 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 20 or its own use.
5060: 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 .** A [SQLITE_FC
5070: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 NTL_LOCKSTATE |
5080: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d list of opcodes]
5090: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 less than 100 i
50a0: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 s available..**
50b0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 Applications tha
50c0: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f t define a custo
50d0: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d m xFileControl m
50e0: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 ethod should use
50f0: 20 6f 70 63 6f 64 65 73 20 0a 2a 2a 20 67 72 65 opcodes .** gre
5100: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f ater than 100 to
5110: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 avoid conflicts
5120: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 ..**.** The xSec
5130: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 torSize() method
5140: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 returns the sec
5150: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a tor size of the.
5160: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 ** device that u
5170: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c nderlies the fil
5180: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 e. The sector s
5190: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 ize is the.** mi
51a0: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 nimum write that
51b0: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 can be performe
51c0: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 d without distur
51d0: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 bing.** other by
51e0: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e tes in the file.
51f0: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 The xDeviceCha
5200: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a racteristics().*
5210: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 * method returns
5220: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 a bit vector de
5230: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f scribing behavio
5240: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 rs of the.** und
5250: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a erlying device:.
5260: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
5270: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
5280: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e _ATOMIC].** <li>
5290: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
52a0: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 TOMIC512].** <li
52b0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
52c0: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 ATOMIC1K].** <li
52d0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
52e0: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 ATOMIC2K].** <li
52f0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
5300: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 ATOMIC4K].** <li
5310: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
5320: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 ATOMIC8K].** <li
5330: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
5340: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c ATOMIC16K].** <l
5350: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
5360: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c _ATOMIC32K].** <
5370: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
5380: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 P_ATOMIC64K].**
5390: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
53a0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a AP_SAFE_APPEND].
53b0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
53c0: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c IOCAP_SEQUENTIAL
53d0: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a ].** </ul>.**.**
53e0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
53f0: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 P_ATOMIC propert
5400: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c y means that all
5410: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e writes of.** an
5420: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 y size are atomi
5430: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 c. The SQLITE_I
5440: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 OCAP_ATOMICnnn v
5450: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 alues.** mean th
5460: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f at writes of blo
5470: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e cks that are nnn
5480: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 bytes in size a
5490: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 nd.** are aligne
54a0: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 d to an address
54b0: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 which is an inte
54c0: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a ger multiple of.
54d0: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 ** nnn are atomi
54e0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 c. The SQLITE_I
54f0: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 OCAP_SAFE_APPEND
5500: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 value means.**
5510: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 that when data i
5520: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 s appended to a
5530: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 file, the data i
5540: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 s appended.** fi
5550: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a rst then the siz
5560: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 e of the file is
5570: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 extended, never
5580: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 the other.** wa
5590: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 y around. The S
55a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 QLITE_IOCAP_SEQU
55b0: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 ENTIAL property
55c0: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e means that.** in
55d0: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 formation is wri
55e0: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 tten to disk in
55f0: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 the same order a
5600: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 s calls.** to xW
5610: 72 69 74 65 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 rite()..*/.typed
5620: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
5630: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 3_io_methods sql
5640: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b ite3_io_methods;
5650: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
5660: 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 io_methods {. i
5670: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 nt iVersion;. i
5680: 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c nt (*xClose)(sql
5690: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 ite3_file*);. i
56a0: 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 nt (*xRead)(sqli
56b0: 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a te3_file*, void*
56c0: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 , int iAmt, sqli
56d0: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 te3_int64 iOfst)
56e0: 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 ;. int (*xWrite
56f0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
5700: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
5710: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f t iAmt, sqlite3_
5720: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 int64 iOfst);.
5730: 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 int (*xTruncate)
5740: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
5750: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 sqlite3_int64 si
5760: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 ze);. int (*xSy
5770: 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 nc)(sqlite3_file
5780: 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 *, int flags);.
5790: 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 int (*xFileSize
57a0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
57b0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a sqlite3_int64 *
57c0: 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a pSize);. int (*
57d0: 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 xLock)(sqlite3_f
57e0: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e ile*, int);. in
57f0: 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c t (*xUnlock)(sql
5800: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 ite3_file*, int)
5810: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b ;. int (*xCheck
5820: 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 ReservedLock)(sq
5830: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 lite3_file*);.
5840: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 int (*xFileContr
5850: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ol)(sqlite3_file
5860: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 *, int op, void
5870: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a *pArg);. int (*
5880: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c xSectorSize)(sql
5890: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 ite3_file*);. i
58a0: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 nt (*xDeviceChar
58b0: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c acteristics)(sql
58c0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f ite3_file*);. /
58d0: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 * Additional met
58e0: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 hods may be adde
58f0: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
5900: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a ases */.};../*.*
5910: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e * CAPI3REF: Stan
5920: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f dard File Contro
5930: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 l Opcodes.**.**
5940: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f These integer co
5950: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f nstants are opco
5960: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c des for the xFil
5970: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a eControl method.
5980: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ** of the [sqlit
5990: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f e3_io_methods] o
59a0: 62 6a 65 63 74 20 61 6e 64 20 74 6f 20 74 68 65 bject and to the
59b0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 [sqlite3_file_c
59c0: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 ontrol()].** int
59d0: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 erface..**.** Th
59e0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
59f0: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 LOCKSTATE] opcod
5a00: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 e is used for de
5a10: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a bugging. This.*
5a20: 2a 20 6f 70 63 6f 64 65 20 63 61 73 65 73 20 74 * opcode cases t
5a30: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 he xFileControl
5a40: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 method to write
5a50: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 the current stat
5a60: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b e of.** the lock
5a70: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 (one of [SQLITE
5a80: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 _LOCK_NONE], [SQ
5a90: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 LITE_LOCK_SHARED
5aa0: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f ],.** [SQLITE_LO
5ab0: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 CK_RESERVED], [S
5ac0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 QLITE_LOCK_PENDI
5ad0: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f NG], or [SQLITE_
5ae0: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 LOCK_EXCLUSIVE])
5af0: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 .** into an inte
5b00: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72 ger that the pAr
5b10: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 g argument point
5b20: 73 20 74 6f 2e 20 20 54 68 69 73 20 63 61 70 61 s to. This capa
5b30: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 bility.** is use
5b40: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 d during testing
5b50: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 and only needs
5b60: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 to be supported
5b70: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 when SQLITE_TEST
5b80: 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a .** is defined..
5b90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5ba0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 E_FCNTL_LOCKSTAT
5bb0: 45 20 20 20 20 20 20 20 20 31 0a 0a 2f 2a 0a 2a E 1../*.*
5bc0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 * CAPI3REF: Mute
5bd0: 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 x Handle.**.** T
5be0: 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 he mutex module
5bf0: 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 within SQLite de
5c00: 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d fines [sqlite3_m
5c10: 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a utex] to be an.*
5c20: 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 * abstract type
5c30: 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 for a mutex obje
5c40: 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 ct. The SQLite
5c50: 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 core never looks
5c60: 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 .** at the inter
5c70: 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 nal representati
5c80: 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 on of an [sqlite
5c90: 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 3_mutex]. It on
5ca0: 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 ly.** deals with
5cb0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 pointers to the
5cc0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d [sqlite3_mutex]
5cd0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d object..**.** M
5ce0: 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 utexes are creat
5cf0: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ed using [sqlite
5d00: 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 3_mutex_alloc()]
5d10: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
5d20: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 uct sqlite3_mute
5d30: 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b x sqlite3_mutex;
5d40: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
5d50: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f : OS Interface O
5d60: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 bject.**.** An i
5d70: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
5d80: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 object defines t
5d90: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 he interface bet
5da0: 77 65 65 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 ween the.** SQLi
5db0: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 te core and the
5dc0: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 underlying opera
5dd0: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 ting system. Th
5de0: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 e "vfs".** in th
5df0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 e name of the ob
5e00: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 ject stands for
5e10: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 "virtual file sy
5e20: 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 stem"..**.** The
5e30: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 iVersion field
5e40: 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 is initially 1 b
5e50: 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 ut may be larger
5e60: 20 66 6f 72 20 66 75 74 75 72 65 0a 2a 2a 20 76 for future.** v
5e70: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
5e80: 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 e. Additional f
5e90: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 ields may be app
5ea0: 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a ended to this.**
5eb0: 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 object when the
5ec0: 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 iVersion value
5ed0: 69 73 20 69 6e 63 72 65 61 73 65 64 2e 0a 2a 2a is increased..**
5ee0: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 .** The szOsFile
5ef0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 field is the si
5f00: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 ze of the subcla
5f10: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 ssed [sqlite3_fi
5f20: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 le].** structure
5f30: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 used by this VF
5f40: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 S. mxPathname i
5f50: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 s the maximum le
5f60: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 ngth of.** a pat
5f70: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 hname in this VF
5f80: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 S..**.** Registe
5f90: 72 65 64 20 76 66 73 20 6d 6f 64 75 6c 65 73 20 red vfs modules
5fa0: 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 are kept on a li
5fb0: 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 nked list formed
5fc0: 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 by.** the pNext
5fd0: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b pointer. The [
5fe0: 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 sqlite3_vfs_regi
5ff0: 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b ster()].** and [
6000: 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 sqlite3_vfs_unre
6010: 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 gister()] interf
6020: 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 aces manage this
6030: 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 list.** in a th
6040: 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 read-safe way.
6050: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 The [sqlite3_vfs
6060: 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 _find()] interfa
6070: 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 ce.** searches t
6080: 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 54 he list..**.** T
6090: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 he pNext field i
60a0: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 s the only field
60b0: 73 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 s in the sqlite3
60c0: 5f 76 66 73 20 0a 2a 2a 20 73 74 72 75 63 74 75 _vfs .** structu
60d0: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 re that SQLite w
60e0: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e ill ever modify.
60f0: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e SQLite will on
6100: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 ly access.** or
6110: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c modify this fiel
6120: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 d while holding
6130: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 a particular sta
6140: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 tic mutex..** Th
6150: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 e application sh
6160: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 ould never modif
6170: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 y anything withi
6180: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 n the sqlite3_vf
6190: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 s.** object once
61a0: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 the object has
61b0: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e been registered.
61c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 .**.** The zName
61d0: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 field holds the
61e0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 name of the VFS
61f0: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 module. The na
6200: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e me must.** be un
6210: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 ique across all
6220: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a VFS modules..**.
6230: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67 ** SQLite will g
6240: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 uarantee that th
6250: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 73 74 72 69 e zFilename stri
6260: 6e 67 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 ng passed to.**
6270: 78 4f 70 65 6e 28 29 20 69 73 20 61 20 66 75 6c xOpen() is a ful
6280: 6c 20 70 61 74 68 6e 61 6d 65 20 61 73 20 67 65 l pathname as ge
6290: 6e 65 72 61 74 65 64 20 62 79 20 78 46 75 6c 6c nerated by xFull
62a0: 50 61 74 68 6e 61 6d 65 28 29 20 61 6e 64 0a 2a Pathname() and.*
62b0: 2a 20 74 68 61 74 20 74 68 65 20 73 74 72 69 6e * that the strin
62c0: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 g will be valid
62d0: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e and unchanged un
62e0: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a til xClose() is.
62f0: 2a 2a 20 63 61 6c 6c 65 64 2e 20 20 53 6f 20 74 ** called. So t
6300: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 he [sqlite3_file
6310: 5d 20 63 61 6e 20 73 74 6f 72 65 20 61 20 70 6f ] can store a po
6320: 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 inter to the.**
6330: 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e filename if it n
6340: 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 eeds to remember
6350: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f the filename fo
6360: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a r some reason..*
6370: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 *.** The flags a
6380: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e rgument to xOpen
6390: 28 29 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 () is a copy of
63a0: 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 the flags argume
63b0: 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 nt.** to [sqlite
63c0: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 49 3_open_v2()]. I
63d0: 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 f [sqlite3_open(
63e0: 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f )] or [sqlite3_o
63f0: 70 65 6e 31 36 28 29 5d 0a 2a 2a 20 69 73 20 75 pen16()].** is u
6400: 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 sed, then flags
6410: 69 73 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f is [SQLITE_OPEN_
6420: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 READWRITE] | [SQ
6430: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
6440: 5d 2e 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 ]..** If xOpen()
6450: 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 opens a file re
6460: 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 ad-only then it
6470: 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 sets *pOutFlags
6480: 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 to.** include [S
6490: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
64a0: 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 NLY]. Other bit
64b0: 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 s in *pOutFlags
64c0: 6d 61 79 20 62 65 0a 2a 2a 20 73 65 74 2e 0a 2a may be.** set..*
64d0: 2a 20 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c * .** SQLite wil
64e0: 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f l also add one o
64f0: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 f the following
6500: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 flags to the xOp
6510: 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 en().** call, de
6520: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f pending on the o
6530: 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e bject being open
6540: 65 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a ed:.** .** <ul>.
6550: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
6560: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a _OPEN_MAIN_DB].*
6570: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
6580: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 OPEN_MAIN_JOURNA
6590: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c L].** <li> [SQL
65a0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 ITE_OPEN_TEMP_DB
65b0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 ].** <li> [SQLI
65c0: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 TE_OPEN_TEMP_JOU
65d0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b RNAL].** <li> [
65e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e SQLITE_OPEN_TRAN
65f0: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 SIENT_DB].** <li
6600: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
6610: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c SUBJOURNAL].** <
6620: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
6630: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c N_MASTER_JOURNAL
6640: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a ].** </ul>.**.**
6650: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d The file I/O im
6660: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e plementation can
6670: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 use the object
6680: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a type flags to.**
6690: 20 63 68 61 6e 67 65 73 20 74 68 65 20 77 61 79 changes the way
66a0: 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 it deals with f
66b0: 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 iles. For examp
66c0: 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 le, an applicati
66d0: 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 on.** that does
66e0: 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 not care about c
66f0: 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 rash recovery or
6700: 20 72 6f 6c 6c 62 61 63 6b 2c 20 6d 69 67 68 74 rollback, might
6710: 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 make.** the ope
6720: 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 n of a journal f
6730: 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 ile a no-op. Wr
6740: 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 ites to this jou
6750: 72 6e 61 6c 20 61 72 65 0a 2a 2a 20 61 6c 73 6f rnal are.** also
6760: 20 61 20 6e 6f 2d 6f 70 2e 20 20 41 6e 79 20 61 a no-op. Any a
6770: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 ttempt to read t
6780: 68 65 20 6a 6f 75 72 6e 61 6c 20 72 65 74 75 72 he journal retur
6790: 6e 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 0a n SQLITE_IOERR..
67a0: 2a 2a 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d ** Or the implem
67b0: 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 entation might r
67c0: 65 63 6f 67 6e 69 7a 65 20 74 68 65 20 61 20 64 ecognize the a d
67d0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c atabase file wil
67e0: 6c 0a 2a 2a 20 62 65 20 64 6f 69 6e 67 20 70 61 l.** be doing pa
67f0: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f ge-aligned secto
6800: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 r reads and writ
6810: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 20 6f es in a random o
6820: 72 64 65 72 0a 2a 2a 20 61 6e 64 20 73 65 74 20 rder.** and set
6830: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 up its I/O subsy
6840: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 stem accordingly
6850: 2e 0a 2a 2a 20 0a 2a 2a 20 53 51 4c 69 74 65 20 ..** .** SQLite
6860: 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f might also add o
6870: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 ne of the follow
6880: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 ing flags to the
6890: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 65 74 68 6f 64 xOpen.** method
68a0: 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a :.** .** <ul>.**
68b0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
68c0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 EN_DELETEONCLOSE
68d0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
68e0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 E_OPEN_EXCLUSIVE
68f0: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a ].** </ul>.** .*
6900: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 * The [SQLITE_OP
6910: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 EN_DELETEONCLOSE
6920: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 ] flag means the
6930: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a file should be.
6940: 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 ** deleted when
6950: 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 54 it is closed. T
6960: 68 69 73 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 his will always
6970: 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 be set for TEMP
6980: 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 20 61 6e .** databases an
6990: 64 20 6a 6f 75 72 6e 61 6c 73 20 61 6e 64 20 66 d journals and f
69a0: 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 20 or subjournals.
69b0: 20 54 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 The .** [SQLITE
69c0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d _OPEN_EXCLUSIVE]
69d0: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 flag means the
69e0: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f file should be o
69f0: 70 65 6e 65 64 0a 2a 2a 20 66 6f 72 20 65 78 63 pened.** for exc
6a00: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 20 20 lusive access.
6a10: 54 68 69 73 20 66 6c 61 67 20 69 73 20 73 65 74 This flag is set
6a20: 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65 73 20 65 for all files e
6a30: 78 63 65 70 74 0a 2a 2a 20 66 6f 72 20 74 68 65 xcept.** for the
6a40: 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 main database f
6a50: 69 6c 65 2e 0a 2a 2a 20 0a 2a 2a 20 53 70 61 63 ile..** .** Spac
6a60: 65 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b e to hold the [
6a70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 sqlite3_file] st
6a80: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61 ructure passed a
6a90: 73 20 74 68 65 20 74 68 69 72 64 20 0a 2a 2a 20 s the third .**
6aa0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 argument to xOpe
6ab0: 6e 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 62 n is allocated b
6ac0: 79 20 63 61 6c 6c 65 72 20 28 74 68 65 20 53 51 y caller (the SQ
6ad0: 4c 69 74 65 20 63 6f 72 65 29 2e 20 0a 2a 2a 20 Lite core). .**
6ae0: 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 61 szOsFile bytes a
6af0: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 66 6f 72 re allocated for
6b00: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 20 20 54 this object. T
6b10: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 0a he xOpen method.
6b20: 2a 2a 20 66 69 6c 6c 73 20 69 6e 20 74 68 65 20 ** fills in the
6b30: 61 6c 6c 6f 63 61 74 65 64 20 73 70 61 63 65 2e allocated space.
6b40: 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 66 6c 61 67 .** .** The flag
6b50: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 s argument to xA
6b60: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b ccess() may be [
6b70: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 SQLITE_ACCESS_EX
6b80: 49 53 54 53 5d 20 0a 2a 2a 20 74 6f 20 74 65 73 ISTS] .** to tes
6b90: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 61 t for the exista
6ba0: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 0a 2a nce of a file,.*
6bb0: 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 * or [SQLITE_ACC
6bc0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 ESS_READWRITE] t
6bd0: 6f 20 74 65 73 74 20 74 6f 20 73 65 65 0a 2a 2a o test to see.**
6be0: 20 69 66 20 61 20 66 69 6c 65 20 69 73 20 72 65 if a file is re
6bf0: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 adable and writa
6c00: 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f ble, or [SQLITE_
6c10: 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 ACCESS_READ].**
6c20: 74 6f 20 74 65 73 74 20 74 6f 20 73 65 65 20 69 to test to see i
6c30: 66 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c f a file is at l
6c40: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 east readable.
6c50: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 The file can be
6c60: 61 20 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e a .** directory.
6c70: 0a 2a 2a 20 0a 2a 2a 20 53 51 4c 69 74 65 20 77 .** .** SQLite w
6c80: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 ill always alloc
6c90: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 ate at least mxP
6ca0: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 20 66 athname+1 byte f
6cb0: 6f 72 0a 2a 2a 20 74 68 65 20 6f 75 74 70 75 74 or.** the output
6cc0: 20 62 75 66 66 65 72 73 20 66 6f 72 20 78 47 65 buffers for xGe
6cd0: 74 54 65 6d 70 6e 61 6d 65 20 61 6e 64 20 78 46 tTempname and xF
6ce0: 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 54 68 65 ullPathname. The
6cf0: 20 65 78 61 63 74 0a 2a 2a 20 73 69 7a 65 20 6f exact.** size o
6d00: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 f the output buf
6d10: 66 65 72 20 69 73 20 61 6c 73 6f 20 70 61 73 73 fer is also pass
6d20: 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 ed as a paramete
6d30: 72 20 74 6f 20 62 6f 74 68 20 0a 2a 2a 20 6d 65 r to both .** me
6d40: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 thods. If the ou
6d50: 74 70 75 74 20 62 75 66 66 65 72 20 69 73 20 6e tput buffer is n
6d60: 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c ot large enough,
6d70: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e SQLITE_CANTOPEN
6d80: 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 .** should be re
6d90: 74 75 72 6e 65 64 2e 20 41 73 20 74 68 69 73 20 turned. As this
6da0: 69 73 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 is handled as a
6db0: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 fatal error by S
6dc0: 51 4c 69 74 65 2c 0a 2a 2a 20 76 66 73 20 69 6d QLite,.** vfs im
6dd0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 plementations sh
6de0: 6f 75 6c 64 20 65 6e 64 65 76 6f 75 72 20 74 6f ould endevour to
6df0: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 prevent this by
6e00: 20 73 65 74 74 69 6e 67 20 0a 2a 2a 20 6d 78 50 setting .** mxP
6e10: 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 athname to a suf
6e20: 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 ficiently large
6e30: 76 61 6c 75 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 value..** .** Th
6e40: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c e xRandomness(),
6e50: 20 78 53 6c 65 65 70 28 29 2c 20 61 6e 64 20 78 xSleep(), and x
6e60: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 6e CurrentTime() in
6e70: 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 terfaces.** are
6e80: 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 not strictly a p
6e90: 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 art of the files
6ea0: 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 ystem, but they
6eb0: 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 are.** included
6ec0: 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 in the VFS struc
6ed0: 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 ture for complet
6ee0: 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 eness..** The xR
6ef0: 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 andomness() func
6f00: 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f tion attempts to
6f10: 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 return nBytes b
6f20: 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d ytes.** of good-
6f30: 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 quality randomne
6f40: 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 ss into zOut. T
6f50: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
6f60: 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c is.** the actual
6f70: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
6f80: 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f of randomness o
6f90: 62 74 61 69 6e 65 64 2e 20 20 54 68 65 0a 2a 2a btained. The.**
6fa0: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 xSleep() method
6fb0: 20 63 61 75 73 65 20 74 68 65 20 63 61 6c 6c 69 cause the calli
6fc0: 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 ng thread to sle
6fd0: 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 ep for at.** lea
6fe0: 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 st the number of
6ff0: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 microseconds gi
7000: 76 65 6e 2e 20 20 54 68 65 20 78 43 75 72 72 65 ven. The xCurre
7010: 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 ntTime().** meth
7020: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c od returns a Jul
7030: 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 ian Day Number f
7040: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 or the current d
7050: 61 74 65 20 61 6e 64 0a 2a 2a 20 74 69 6d 65 2e ate and.** time.
7060: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
7070: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 ct sqlite3_vfs s
7080: 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 qlite3_vfs;.stru
7090: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b ct sqlite3_vfs {
70a0: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b . int iVersion;
70b0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 /* S
70c0: 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e tructure version
70d0: 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 69 6e 74 number */. int
70e0: 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 szOsFile;
70f0: 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 /* Size of
7100: 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 subclassed sqli
7110: 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e te3_file */. in
7120: 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 t mxPathname;
7130: 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 /* Maximu
7140: 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 m file pathname
7150: 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 length */. sqli
7160: 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 te3_vfs *pNext;
7170: 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 /* Next reg
7180: 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 istered VFS */.
7190: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
71a0: 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d me; /* Nam
71b0: 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 e of this virtua
71c0: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f l file system */
71d0: 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 . void *pAppDat
71e0: 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 a; /* P
71f0: 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 ointer to applic
7200: 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 ation-specific d
7210: 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 ata */. int (*x
7220: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 Open)(sqlite3_vf
7230: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a s*, const char *
7240: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 zName, sqlite3_f
7250: 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 ile*,.
7260: 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 int flags,
7270: 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b int *pOutFlags);
7280: 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 . int (*xDelete
7290: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
72a0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
72b0: 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b e, int syncDir);
72c0: 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 . int (*xAccess
72d0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
72e0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
72f0: 65 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 e, int flags);.
7300: 20 69 6e 74 20 28 2a 78 47 65 74 54 65 6d 70 6e int (*xGetTempn
7310: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ame)(sqlite3_vfs
7320: 2a 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 *, int nOut, cha
7330: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 r *zOut);. int
7340: 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 (*xFullPathname)
7350: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
7360: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
7370: 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 , int nOut, char
7380: 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 *zOut);. void
7390: 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 *(*xDlOpen)(sqli
73a0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
73b0: 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 char *zFilename)
73c0: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 ;. void (*xDlEr
73d0: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ror)(sqlite3_vfs
73e0: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 *, int nByte, ch
73f0: 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 ar *zErrMsg);.
7400: 76 6f 69 64 20 2a 28 2a 78 44 6c 53 79 6d 29 28 void *(*xDlSym)(
7410: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 sqlite3_vfs*,voi
7420: 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a d*, const char *
7430: 7a 53 79 6d 62 6f 6c 29 3b 0a 20 20 76 6f 69 64 zSymbol);. void
7440: 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c (*xDlClose)(sql
7450: 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a ite3_vfs*, void*
7460: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 );. int (*xRand
7470: 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f omness)(sqlite3_
7480: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c vfs*, int nByte,
7490: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 char *zOut);.
74a0: 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 int (*xSleep)(sq
74b0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 lite3_vfs*, int
74c0: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 microseconds);.
74d0: 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 int (*xCurrentT
74e0: 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ime)(sqlite3_vfs
74f0: 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 2f *, double*);. /
7500: 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 * New fields may
7510: 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 be appended in
7520: 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e figure versions.
7530: 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 The iVersion.
7540: 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 ** value will i
7550: 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 ncrement wheneve
7560: 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 r this happens.
7570: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.};../*.** CAP
7580: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 I3REF: Flags for
7590: 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53 the xAccess VFS
75a0: 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 method.**.** Th
75b0: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 ese integer cons
75c0: 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 tants can be use
75d0: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70 d as the third p
75e0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 arameter to.** t
75f0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f he xAccess metho
7600: 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 d of an [sqlite3
7610: 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 _vfs] object. T
7620: 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a hey determine.**
7630: 20 74 68 65 20 6b 69 6e 64 20 6f 66 20 77 68 61 the kind of wha
7640: 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 t kind of permis
7650: 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 sions the xAcces
7660: 73 20 6d 65 74 68 6f 64 20 69 73 0a 2a 2a 20 6c s method is.** l
7670: 6f 6f 6b 69 6e 67 20 66 6f 72 2e 20 20 57 69 74 ooking for. Wit
7680: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f h SQLITE_ACCESS_
7690: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 EXISTS, the xAcc
76a0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 ess method.** si
76b0: 6d 70 6c 79 20 63 68 65 63 6b 73 20 74 6f 20 73 mply checks to s
76c0: 65 65 20 69 66 20 74 68 65 20 66 69 6c 65 20 65 ee if the file e
76d0: 78 69 73 74 73 2e 20 20 57 69 74 68 20 53 51 4c xists. With SQL
76e0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 ITE_ACCESS_READW
76f0: 52 49 54 45 2c 0a 2a 2a 20 74 68 65 20 78 41 63 RITE,.** the xAc
7700: 63 65 73 73 20 6d 65 74 68 6f 64 20 63 68 65 63 cess method chec
7710: 6b 73 20 74 6f 20 73 65 65 20 69 66 20 74 68 65 ks to see if the
7720: 20 66 69 6c 65 20 69 73 20 62 6f 74 68 20 72 65 file is both re
7730: 61 64 61 62 6c 65 0a 2a 2a 20 61 6e 64 20 77 72 adable.** and wr
7740: 69 74 61 62 6c 65 2e 20 20 57 69 74 68 20 53 51 itable. With SQ
7750: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
7760: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 the xAccess met
7770: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 74 6f hod.** checks to
7780: 20 73 65 65 20 69 66 20 74 68 65 20 66 69 6c 65 see if the file
7790: 20 69 73 20 72 65 61 64 61 62 6c 65 2e 0a 2a 2f is readable..*/
77a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
77b0: 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 ACCESS_EXISTS
77c0: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 0.#define SQLIT
77d0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 E_ACCESS_READWRI
77e0: 54 45 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c TE 1.#define SQL
77f0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 ITE_ACCESS_READ
7800: 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 2../*.** CA
7810: 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f PI3REF: Enable O
7820: 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 r Disable Extend
7830: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a ed Result Codes.
7840: 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
7850: 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 ne enables or di
7860: 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 53 sables the.** [S
7870: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 QLITE_IOERR_READ
7880: 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 | extended resu
7890: 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 lt codes] featur
78a0: 65 2e 0a 2a 2a 20 42 79 20 64 65 66 61 75 6c 74 e..** By default
78b0: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 , SQLite API rou
78c0: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 tines return one
78d0: 20 6f 66 20 6f 6e 6c 79 20 32 36 20 69 6e 74 65 of only 26 inte
78e0: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f ger.** [SQLITE_O
78f0: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 K | result codes
7900: 5d 2e 20 20 57 68 65 6e 20 65 78 74 65 6e 64 65 ]. When extende
7910: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 0a 2a d result codes.*
7920: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 * are enabled by
7930: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 this routine, t
7940: 68 65 20 72 65 70 65 74 6f 69 72 65 20 6f 66 20 he repetoire of
7950: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 63 61 6e result codes can
7960: 20 62 65 0a 2a 2a 20 6d 75 63 68 20 6c 61 72 67 be.** much larg
7970: 65 72 20 61 6e 64 20 63 61 6e 20 28 68 6f 70 65 er and can (hope
7980: 66 75 6c 6c 79 29 20 70 72 6f 76 69 64 65 20 6d fully) provide m
7990: 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 ore detailed inf
79a0: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 ormation.** abou
79b0: 74 20 74 68 65 20 63 61 75 73 65 20 6f 66 20 61 t the cause of a
79c0: 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 n error..**.** T
79d0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
79e0: 6e 74 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 nt is a boolean
79f0: 76 61 6c 75 65 20 74 68 61 74 20 74 75 72 6e 73 value that turns
7a00: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 extended result
7a10: 0a 2a 2a 20 63 6f 64 65 73 20 6f 6e 20 61 6e 64 .** codes on and
7a20: 20 6f 66 66 2e 20 20 45 78 74 65 6e 64 65 64 20 off. Extended
7a30: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 result codes are
7a40: 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 20 off by default
7a50: 66 6f 72 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 for.** backwards
7a60: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 compatibility w
7a70: 69 74 68 20 6f 6c 64 65 72 20 76 65 72 73 69 6f ith older versio
7a80: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f ns of SQLite..*/
7a90: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 .int sqlite3_ext
7aa0: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 ended_result_cod
7ab0: 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 es(sqlite3*, int
7ac0: 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 onoff);../*.**
7ad0: 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 CAPI3REF: Last I
7ae0: 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a nsert Rowid.**.*
7af0: 2a 20 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 * Each entry in
7b00: 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 an SQLite table
7b10: 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d has a unique 64-
7b20: 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 bit signed integ
7b30: 65 72 20 6b 65 79 0a 2a 2a 20 63 61 6c 6c 65 64 er key.** called
7b40: 20 74 68 65 20 22 72 6f 77 69 64 22 2e 20 54 68 the "rowid". Th
7b50: 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 e rowid is alway
7b60: 73 20 61 76 61 69 6c 61 62 6c 65 20 61 73 20 61 s available as a
7b70: 6e 20 75 6e 64 65 63 6c 61 72 65 64 0a 2a 2a 20 n undeclared.**
7b80: 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 column named ROW
7b90: 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 ID, OID, or _ROW
7ba0: 49 44 5f 2e 20 20 49 66 20 74 68 65 20 74 61 62 ID_. If the tab
7bb0: 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 le has a column
7bc0: 6f 66 0a 2a 2a 20 74 79 70 65 20 49 4e 54 45 47 of.** type INTEG
7bd0: 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20 74 ER PRIMARY KEY t
7be0: 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 hen that column
7bf0: 69 73 20 61 6e 6f 74 68 65 72 20 61 6e 20 61 6c is another an al
7c00: 69 61 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 72 ias for the.** r
7c10: 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 owid..**.** This
7c20: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
7c30: 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 the rowid of th
7c40: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 e most recent su
7c50: 63 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54 20 ccessful INSERT
7c60: 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 64 61 74 61 into.** the data
7c70: 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 64 61 base from the da
7c80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
7c90: 6e 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 66 n given in the f
7ca0: 69 72 73 74 20 0a 2a 2a 20 61 72 67 75 6d 65 6e irst .** argumen
7cb0: 74 2e 20 20 49 66 20 6e 6f 20 73 75 63 63 65 73 t. If no succes
7cc0: 73 66 75 6c 20 69 6e 73 65 72 74 73 20 68 61 76 sful inserts hav
7cd0: 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 e ever occurred
7ce0: 6f 6e 20 74 68 69 73 20 64 61 74 61 62 61 73 65 on this database
7cf0: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 .** connection,
7d00: 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 zero is returned
7d10: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 49 4e ..**.** If an IN
7d20: 53 45 52 54 20 6f 63 63 75 72 73 20 77 69 74 68 SERT occurs with
7d30: 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 in a trigger, th
7d40: 65 6e 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 en the rowid of
7d50: 74 68 65 0a 2a 2a 20 69 6e 73 65 72 74 65 64 20 the.** inserted
7d60: 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 row is returned
7d70: 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 by this routine
7d80: 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 as long as the t
7d90: 72 69 67 67 65 72 0a 2a 2a 20 69 73 20 72 75 6e rigger.** is run
7da0: 6e 69 6e 67 2e 20 20 42 75 74 20 6f 6e 63 65 20 ning. But once
7db0: 74 68 65 20 74 72 69 67 67 65 72 20 74 65 72 6d the trigger term
7dc0: 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75 inates, the valu
7dd0: 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 e returned.** by
7de0: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 this routine re
7df0: 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73 verts to the las
7e00: 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64 t value inserted
7e10: 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 74 before the.** t
7e20: 72 69 67 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a rigger fired..**
7e30: 0a 2a 2a 20 41 6e 20 49 4e 53 45 52 54 20 74 68 .** An INSERT th
7e40: 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 at fails due to
7e50: 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f a constraint vio
7e60: 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a lation is not a.
7e70: 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e ** successful in
7e80: 73 65 72 74 20 61 6e 64 20 64 6f 65 73 20 6e 6f sert and does no
7e90: 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c t change the val
7ea0: 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 ue returned by t
7eb0: 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 his.** routine.
7ec0: 20 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 Thus INSERT OR
7ed0: 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 FAIL, INSERT OR
7ee0: 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f IGNORE, INSERT O
7ef0: 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 R ROLLBACK,.** a
7f00: 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f nd INSERT OR ABO
7f10: 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 RT make no chang
7f20: 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e es to the return
7f30: 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a value of this.*
7f40: 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 * routine when t
7f50: 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 heir insertion f
7f60: 61 69 6c 73 2e 20 20 57 68 65 6e 20 49 4e 53 45 ails. When INSE
7f70: 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 0a 2a RT OR REPLACE .*
7f80: 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 * encounters a c
7f90: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 onstraint violat
7fa0: 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 ion, it does not
7fb0: 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 fail. The.** I
7fc0: 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 NSERT continues
7fd0: 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 to completion af
7fe0: 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 ter deleting row
7ff0: 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a s that caused.**
8000: 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 the constraint
8010: 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 problem so INSER
8020: 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c T OR REPLACE wil
8030: 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a l always change.
8040: 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 ** the return va
8050: 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 lue of this inte
8060: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 rface..**.** If
8070: 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 64 another thread d
8080: 6f 65 73 20 61 20 6e 65 77 20 69 6e 73 65 72 74 oes a new insert
8090: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 on the same dat
80a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
80b0: 0a 2a 2a 20 77 68 69 6c 65 20 74 68 69 73 20 72 .** while this r
80c0: 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e outine is runnin
80d0: 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 g and thus chang
80e0: 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 es the last inse
80f0: 72 74 20 72 6f 77 69 64 2c 0a 2a 2a 20 74 68 65 rt rowid,.** the
8100: 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c n the return val
8110: 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 ue of this routi
8120: 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e ne is undefined.
8130: 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 .*/.sqlite3_int6
8140: 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 4 sqlite3_last_i
8150: 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 nsert_rowid(sqli
8160: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
8170: 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 PI3REF: Count Th
8180: 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 e Number Of Rows
8190: 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 Modified.**.**
81a0: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 This function re
81b0: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
81c0: 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 of database row
81d0: 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e s that were chan
81e0: 67 65 64 0a 2a 2a 20 28 6f 72 20 69 6e 73 65 72 ged.** (or inser
81f0: 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 29 20 ted or deleted)
8200: 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 by the most rece
8210: 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 nt SQL statement
8220: 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 63 68 61 6e 67 . Only.** chang
8230: 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65 es that are dire
8240: 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 ctly specified b
8250: 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50 y the INSERT, UP
8260: 44 41 54 45 2c 20 6f 72 0a 2a 2a 20 44 45 4c 45 DATE, or.** DELE
8270: 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 TE statement are
8280: 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c counted. Auxil
8290: 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 iary changes cau
82a0: 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 sed by.** trigge
82b0: 72 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 rs are not count
82c0: 65 64 2e 20 20 55 73 65 20 74 68 65 20 5b 73 71 ed. Use the [sq
82d0: 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e lite3_total_chan
82e0: 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a ges()] function.
82f0: 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 ** to find the t
8300: 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 otal number of c
8310: 68 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 hanges including
8320: 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 changes caused
8330: 62 79 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a by triggers..**.
8340: 2a 2a 20 57 69 74 68 69 6e 20 74 68 65 20 62 6f ** Within the bo
8350: 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c dy of a trigger,
8360: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 the sqlite3_cha
8370: 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 nges() interface
8380: 20 63 61 6e 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 can be.** calle
8390: 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 d to find the nu
83a0: 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 mber of.** chang
83b0: 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 es in the most r
83c0: 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 ecently complete
83d0: 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 d INSERT, UPDATE
83e0: 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 , or DELETE.** s
83f0: 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 tatement within
8400: 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 the body of the
8410: 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 trigger..**.** A
8420: 6c 6c 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 ll changes are c
8430: 6f 75 6e 74 65 64 2c 20 65 76 65 6e 20 69 66 20 ounted, even if
8440: 74 68 65 79 20 77 65 72 65 20 6c 61 74 65 72 20 they were later
8450: 75 6e 64 6f 6e 65 20 62 79 20 61 0a 2a 2a 20 52 undone by a.** R
8460: 4f 4c 4c 42 41 43 4b 20 6f 72 20 41 42 4f 52 54 OLLBACK or ABORT
8470: 2e 20 20 45 78 63 65 70 74 2c 20 63 68 61 6e 67 . Except, chang
8480: 65 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 es associated wi
8490: 74 68 20 63 72 65 61 74 69 6e 67 20 61 6e 64 0a th creating and.
84a0: 2a 2a 20 64 72 6f 70 70 69 6e 67 20 74 61 62 6c ** dropping tabl
84b0: 65 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 es are not count
84c0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 ed..**.** If a c
84d0: 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 6b 65 73 20 allback invokes
84e0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
84f0: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 or [sqlite3_ste
8500: 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79 p()] recursively
8510: 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 68 ,.** then the ch
8520: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 69 6e 6e anges in the inn
8530: 65 72 2c 20 72 65 63 75 72 73 69 76 65 20 63 61 er, recursive ca
8540: 6c 6c 20 61 72 65 20 63 6f 75 6e 74 65 64 20 74 ll are counted t
8550: 6f 67 65 74 68 65 72 0a 2a 2a 20 77 69 74 68 20 ogether.** with
8560: 74 68 65 20 63 68 61 6e 67 65 73 20 69 6e 20 74 the changes in t
8570: 68 65 20 6f 75 74 65 72 20 63 61 6c 6c 2e 0a 2a he outer call..*
8580: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c *.** SQLite impl
8590: 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 ements the comma
85a0: 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 nd "DELETE FROM
85b0: 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61 table" without a
85c0: 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a WHERE clause.**
85d0: 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 by dropping and
85e0: 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 recreating the
85f0: 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73 table. (This is
8600: 20 6d 75 63 68 20 66 61 73 74 65 72 20 74 68 61 much faster tha
8610: 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 n going.** throu
8620: 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 gh and deleting
8630: 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 individual eleme
8640: 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61 62 nts from the tab
8650: 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66 le.) Because of
8660: 0a 2a 2a 20 74 68 69 73 20 6f 70 74 69 6d 69 7a .** this optimiz
8670: 61 74 69 6f 6e 2c 20 74 68 65 20 63 68 61 6e 67 ation, the chang
8680: 65 20 63 6f 75 6e 74 20 66 6f 72 20 22 44 45 4c e count for "DEL
8690: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 ETE FROM table"
86a0: 77 69 6c 6c 20 62 65 0a 2a 2a 20 7a 65 72 6f 20 will be.** zero
86b0: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 regardless of th
86c0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d e number of elem
86d0: 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 20 6f ents that were o
86e0: 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65 riginally in the
86f0: 0a 2a 2a 20 74 61 62 6c 65 2e 20 54 6f 20 67 65 .** table. To ge
8700: 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f t an accurate co
8710: 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 unt of the numbe
8720: 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65 r of rows delete
8730: 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 d, use.** "DELET
8740: 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 E FROM table WHE
8750: 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a RE 1" instead..*
8760: 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 *.** If another
8770: 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 thread makes cha
8780: 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 nges on the same
8790: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
87a0: 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 74 68 tion.** while th
87b0: 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 is routine is ru
87c0: 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 72 nning then the r
87d0: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 eturn value of t
87e0: 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 69 his routine.** i
87f0: 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a s undefined..*/.
8800: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e int sqlite3_chan
8810: 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a ges(sqlite3*);..
8820: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
8830: 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 Total Number Of
8840: 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a Rows Modified.**
8850: 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 *.** This functi
8860: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e on returns the n
8870: 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 umber of databas
8880: 65 20 72 6f 77 73 20 74 68 61 74 20 68 61 76 65 e rows that have
8890: 20 62 65 65 6e 0a 2a 2a 20 6d 6f 64 69 66 69 65 been.** modifie
88a0: 64 20 62 79 20 49 4e 53 45 52 54 2c 20 55 50 44 d by INSERT, UPD
88b0: 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 ATE or DELETE st
88c0: 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 atements since t
88d0: 68 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 he database hand
88e0: 6c 65 0a 2a 2a 20 77 61 73 20 6f 70 65 6e 65 64 le.** was opened
88f0: 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 . This includes
8900: 55 50 44 41 54 45 2c 20 49 4e 53 45 52 54 20 61 UPDATE, INSERT a
8910: 6e 64 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d nd DELETE statem
8920: 65 6e 74 73 20 65 78 65 63 75 74 65 64 0a 2a 2a ents executed.**
8930: 20 61 73 20 70 61 72 74 20 6f 66 20 74 72 69 67 as part of trig
8940: 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 41 6c ger programs. Al
8950: 6c 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f l changes are co
8960: 75 6e 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 unted as soon as
8970: 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e the.** statemen
8980: 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 t that makes the
8990: 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 m is completed (
89a0: 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 when the stateme
89b0: 6e 74 20 68 61 6e 64 6c 65 20 69 73 0a 2a 2a 20 nt handle is.**
89c0: 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 passed to [sqlit
89d0: 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b e3_reset()] or [
89e0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
89f0: 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 ()])..**.** See
8a00: 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 also the [sqlite
8a10: 33 5f 63 68 61 6e 67 65 28 29 5d 20 69 6e 74 65 3_change()] inte
8a20: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c rface..**.** SQL
8a30: 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 ite implements t
8a40: 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 he command "DELE
8a50: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 TE FROM table" w
8a60: 69 74 68 6f 75 74 20 61 20 57 48 45 52 45 20 63 ithout a WHERE c
8a70: 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70 lause.** by drop
8a80: 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74 ping and recreat
8a90: 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20 ing the table.
8aa0: 28 54 68 69 73 20 69 73 20 6d 75 63 68 20 66 61 (This is much fa
8ab0: 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a ster than going.
8ac0: 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64 ** through and d
8ad0: 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75 eleting individu
8ae0: 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 6f 72 6d al elements form
8af0: 20 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42 65 the table.) Be
8b00: 63 61 75 73 65 20 6f 66 0a 2a 2a 20 74 68 69 73 cause of.** this
8b10: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 optimization, t
8b20: 68 65 20 63 68 61 6e 67 65 20 63 6f 75 6e 74 20 he change count
8b30: 66 6f 72 20 22 44 45 4c 45 54 45 20 46 52 4f 4d for "DELETE FROM
8b40: 20 74 61 62 6c 65 22 20 77 69 6c 6c 20 62 65 0a table" will be.
8b50: 2a 2a 20 7a 65 72 6f 20 72 65 67 61 72 64 6c 65 ** zero regardle
8b60: 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 ss of the number
8b70: 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 of elements tha
8b80: 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c t were originall
8b90: 79 20 69 6e 20 74 68 65 0a 2a 2a 20 74 61 62 6c y in the.** tabl
8ba0: 65 2e 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63 e. To get an acc
8bb0: 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 urate count of t
8bc0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 he number of row
8bd0: 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a s deleted, use.*
8be0: 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 * "DELETE FROM t
8bf0: 61 62 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e able WHERE 1" in
8c00: 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 stead..**.** If
8c10: 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 6d another thread m
8c20: 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 akes changes on
8c30: 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
8c40: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
8c50: 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 while this routi
8c60: 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 ne is running th
8c70: 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 en the return va
8c80: 6c 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 lue of this rout
8c90: 69 6e 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 ine.** is undefi
8ca0: 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ned..*/.int sqli
8cb0: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
8cc0: 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a s(sqlite3*);../*
8cd0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e .** CAPI3REF: In
8ce0: 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 terrupt A Long-R
8cf0: 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a unning Query.**.
8d00: 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e ** This function
8d10: 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 causes any pend
8d20: 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 ing database ope
8d30: 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 ration to abort
8d40: 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 and.** return at
8d50: 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 its earliest op
8d60: 70 6f 72 74 75 6e 69 74 79 2e 20 20 54 68 69 73 portunity. This
8d70: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 routine is typi
8d80: 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 cally.** called
8d90: 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 in response to a
8da0: 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 user action suc
8db0: 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 h as pressing "C
8dc0: 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 ancel".** or Ctr
8dd0: 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 l-C where the us
8de0: 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 er wants a long
8df0: 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 query operation
8e00: 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 to halt.** immed
8e10: 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 iately..**.** It
8e20: 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c is safe to call
8e30: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 this routine fr
8e40: 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 om a thread diff
8e50: 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a erent from the.*
8e60: 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 * thread that is
8e70: 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 currently runni
8e80: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ng the database
8e90: 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 operation. But
8ea0: 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 it.** is not saf
8eb0: 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 e to call this r
8ec0: 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 64 61 outine with a da
8ed0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
8ee0: 6e 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f n that.** is clo
8ef0: 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f sed or might clo
8f00: 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 se before sqlite
8f10: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 3_interrupt() re
8f20: 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 turns..**.** The
8f30: 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 SQL operation t
8f40: 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 hat is interrupt
8f50: 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b ed will return [
8f60: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 SQLITE_INTERRUPT
8f70: 5d 2e 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 ]..** If an inte
8f80: 72 72 75 70 74 65 64 20 6f 70 65 72 61 74 69 6f rrupted operatio
8f90: 6e 20 77 61 73 20 61 6e 20 75 70 64 61 74 65 20 n was an update
8fa0: 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 that is inside a
8fb0: 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 n.** explicit tr
8fc0: 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 ansaction, then
8fd0: 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 the entire trans
8fe0: 61 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 72 action will be r
8ff0: 6f 6c 6c 65 64 0a 2a 2a 20 62 61 63 6b 20 61 75 olled.** back au
9000: 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2f 0a tomatically..*/.
9010: 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 void sqlite3_int
9020: 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 errupt(sqlite3*)
9030: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
9040: 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 F: Determine If
9050: 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 An SQL Statement
9060: 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a Is Complete.**.
9070: 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f ** These functio
9080: 6e 73 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 ns return true i
9090: 66 20 74 68 65 20 67 69 76 65 6e 20 69 6e 70 75 f the given inpu
90a0: 74 20 73 74 72 69 6e 67 20 63 6f 6d 70 72 69 73 t string compris
90b0: 65 73 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 es.** one or mor
90c0: 65 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 e complete SQL s
90d0: 74 61 74 65 6d 65 6e 74 73 2e 20 46 6f 72 20 74 tatements. For t
90e0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c he sqlite3_compl
90f0: 65 74 65 28 29 20 63 61 6c 6c 2c 0a 2a 2a 20 74 ete() call,.** t
9100: 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 he parameter mus
9110: 74 20 62 65 20 61 20 6e 75 6c 2d 74 65 72 6d 69 t be a nul-termi
9120: 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 nated UTF-8 stri
9130: 6e 67 2e 20 46 6f 72 0a 2a 2a 20 73 71 6c 69 74 ng. For.** sqlit
9140: 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2c e3_complete16(),
9150: 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 a nul-terminate
9160: 64 20 6d 61 63 68 69 6e 65 20 62 79 74 65 20 6f d machine byte o
9170: 72 64 65 72 20 55 54 46 2d 31 36 20 73 74 72 69 rder UTF-16 stri
9180: 6e 67 0a 2a 2a 20 69 73 20 72 65 71 75 69 72 65 ng.** is require
9190: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 d..**.** These r
91a0: 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 outines are usef
91b0: 75 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d 6c ul for command-l
91c0: 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 ine input to det
91d0: 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a ermine if the.**
91e0: 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 currently enter
91f0: 65 64 20 74 65 78 74 20 66 6f 72 6d 73 20 6f 6e ed text forms on
9200: 65 20 6f 72 20 6d 6f 72 65 20 63 6f 6d 70 6c 65 e or more comple
9210: 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 te SQL statement
9220: 73 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 s or.** if addit
9230: 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e ional input is n
9240: 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e eeded before sen
9250: 64 69 6e 67 20 74 68 65 20 73 74 61 74 65 6d 65 ding the stateme
9260: 6e 74 73 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 nts into.** SQLi
9270: 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 te for parsing.
9280: 54 68 65 20 61 6c 67 6f 72 69 74 68 6d 20 69 73 The algorithm is
9290: 20 73 69 6d 70 6c 65 2e 20 20 49 66 20 74 68 65 simple. If the
92a0: 20 0a 2a 2a 20 6c 61 73 74 20 74 6f 6b 65 6e 20 .** last token
92b0: 6f 74 68 65 72 20 74 68 61 6e 20 73 70 61 63 65 other than space
92c0: 73 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 69 s and comments i
92d0: 73 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 2c 20 74 s a semicolon, t
92e0: 68 65 6e 20 72 65 74 75 72 6e 20 0a 2a 2a 20 74 hen return .** t
92f0: 72 75 65 2e 20 20 41 63 74 75 61 6c 6c 79 2c 20 rue. Actually,
9300: 74 68 65 20 61 6c 67 6f 72 69 74 68 6d 20 69 73 the algorithm is
9310: 20 61 20 6c 69 74 74 6c 65 20 6d 6f 72 65 20 63 a little more c
9320: 6f 6d 70 6c 69 63 61 74 65 64 20 74 68 61 6e 20 omplicated than
9330: 74 68 61 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 that.** in order
9340: 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 74 72 to deal with tr
9350: 69 67 67 65 72 73 2c 20 62 75 74 20 74 68 65 20 iggers, but the
9360: 62 61 73 69 63 20 69 64 65 61 20 69 73 20 74 68 basic idea is th
9370: 65 20 73 61 6d 65 3a 20 20 74 68 65 0a 2a 2a 20 e same: the.**
9380: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 statement is not
9390: 20 63 6f 6d 70 6c 65 74 65 20 75 6e 6c 65 73 73 complete unless
93a0: 20 69 74 20 65 6e 64 73 20 69 6e 20 61 20 73 65 it ends in a se
93b0: 6d 69 63 6f 6c 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 micolon..*/.int
93c0: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 sqlite3_complete
93d0: 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c (const char *sql
93e0: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 );.int sqlite3_c
93f0: 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 omplete16(const
9400: 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a void *sql);../*.
9410: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 ** CAPI3REF: Reg
9420: 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b ister A Callback
9430: 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 To Handle SQLIT
9440: 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a E_BUSY Errors.**
9450: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
9460: 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 63 61 identifies a ca
9470: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
9480: 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e that might be in
9490: 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 65 76 65 voked.** wheneve
94a0: 72 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 r an attempt is
94b0: 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 made to open a d
94c0: 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 0a 2a atabase table .*
94d0: 2a 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 * that another t
94e0: 68 72 65 61 64 20 6f 72 20 70 72 6f 63 65 73 73 hread or process
94f0: 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 has locked..**
9500: 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c If the busy call
9510: 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 back is NULL, th
9520: 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d en [SQLITE_BUSY]
9530: 0a 2a 2a 20 28 6f 72 20 73 6f 6d 65 74 69 6d 65 .** (or sometime
9540: 73 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f s [SQLITE_IOERR_
9550: 42 4c 4f 43 4b 45 44 5d 29 0a 2a 2a 20 69 73 20 BLOCKED]).** is
9560: 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 returned immedia
9570: 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e tely upon encoun
9580: 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e tering the lock.
9590: 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79 20 .** If the busy
95a0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 callback is not
95b0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 0a 2a NULL, then the.*
95c0: 2a 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 * callback will
95d0: 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 be invoked with
95e0: 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 two arguments.
95f0: 54 68 65 0a 2a 2a 20 66 69 72 73 74 20 61 72 67 The.** first arg
9600: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 61 6e ument to the han
9610: 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f dler is a copy o
9620: 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e f the void* poin
9630: 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 ter which.** is
9640: 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 the third argume
9650: 6e 74 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 nt to this routi
9660: 6e 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 ne. The second
9670: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 argument to.** t
9680: 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20 74 68 he handler is th
9690: 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 e number of time
96a0: 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 s that the busy
96b0: 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 handler has.** b
96c0: 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 een invoked for
96d0: 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 this locking eve
96e0: 6e 74 2e 20 49 66 20 74 68 65 0a 2a 2a 20 62 75 nt. If the.** bu
96f0: 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 sy callback retu
9700: 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 rns 0, then no a
9710: 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 dditional attemp
9720: 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a ts are made to.*
9730: 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 * access the dat
9740: 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 abase and [SQLIT
9750: 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 E_BUSY] or [SQLI
9760: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 TE_IOERR_BLOCKED
9770: 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a ] is returned..*
9780: 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 * If the callbac
9790: 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 k returns non-ze
97a0: 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 ro, then another
97b0: 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 attempt is made
97c0: 20 74 6f 20 6f 70 65 6e 20 74 68 65 0a 2a 2a 20 to open the.**
97d0: 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 database for rea
97e0: 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 ding and the cyc
97f0: 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a le repeats..**.*
9800: 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f * The presence o
9810: 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 f a busy handler
9820: 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e does not guaran
9830: 74 65 65 20 74 68 61 74 0a 2a 2a 20 69 74 20 77 tee that.** it w
9840: 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 ill be invoked w
9850: 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 hen there is loc
9860: 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 0a 2a 2a k contention..**
9870: 20 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 If SQLite deter
9880: 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b mines that invok
9890: 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e ing the busy han
98a0: 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c dler could resul
98b0: 74 20 69 6e 0a 2a 2a 20 61 20 64 65 61 64 6c 6f t in.** a deadlo
98c0: 63 6b 2c 20 69 74 20 77 69 6c 6c 20 72 65 74 75 ck, it will retu
98d0: 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d rn [SQLITE_BUSY]
98e0: 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 20 43 6f 6e instead..** Con
98f0: 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f sider a scenario
9900: 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 where one proce
9910: 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 ss is holding a
9920: 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a read lock that.*
9930: 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 * it is trying t
9940: 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 o promote to a r
9950: 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 eserved lock and
9960: 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f .** a second pro
9970: 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 cess is holding
9980: 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 a reserved lock
9990: 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e that it is tryin
99a0: 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 g.** to promote
99b0: 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 to an exclusive
99c0: 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 lock. The first
99d0: 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 process cannot
99e0: 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 proceed.** becau
99f0: 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 se it is blocked
9a00: 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 by the second a
9a10: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 nd the second pr
9a20: 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 ocess cannot.**
9a30: 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 proceed because
9a40: 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 it is blocked by
9a50: 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 the first. If
9a60: 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a both processes.*
9a70: 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 * invoke the bus
9a80: 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 y handlers, neit
9a90: 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e her will make an
9aa0: 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 y progress. The
9ab0: 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 refore,.** SQLit
9ac0: 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 e returns [SQLIT
9ad0: 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 E_BUSY] for the
9ae0: 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 first process, h
9af0: 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a oping that this.
9b00: 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 ** will induce t
9b10: 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 he first process
9b20: 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 to release its
9b30: 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c read lock and al
9b40: 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e low.** the secon
9b50: 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f d process to pro
9b60: 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ceed..**.** The
9b70: 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c default busy cal
9b80: 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a lback is NULL..*
9b90: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 *.** The [SQLITE
9ba0: 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 _BUSY] error is
9bb0: 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 converted to [SQ
9bc0: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b LITE_IOERR_BLOCK
9bd0: 45 44 5d 20 77 68 65 6e 0a 2a 2a 20 53 51 4c 69 ED] when.** SQLi
9be0: 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 te is in the mid
9bf0: 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 dle of a large t
9c00: 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 ransaction where
9c10: 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e all the.** chan
9c20: 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 ges will not fit
9c30: 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d into the in-mem
9c40: 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 ory cache. SQLi
9c50: 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 te will.** alrea
9c60: 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 dy hold a RESERV
9c70: 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 ED lock on the d
9c80: 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 atabase file, bu
9c90: 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f t it needs.** to
9ca0: 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f promote this lo
9cb0: 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 ck to EXCLUSIVE
9cc0: 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 so that it can s
9cd0: 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 pill cache.** pa
9ce0: 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 ges into the dat
9cf0: 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f abase file witho
9d00: 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 ut harm to concu
9d10: 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 rrent.** readers
9d20: 2e 20 20 49 66 20 69 74 20 69 73 20 75 6e 61 62 . If it is unab
9d30: 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 le to promote th
9d40: 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 e lock, then the
9d50: 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 in-memory.** ca
9d60: 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 che will be left
9d70: 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 in an inconsist
9d80: 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f ent state and so
9d90: 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f the error.** co
9da0: 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 de is promoted f
9db0: 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 rom the relative
9dc0: 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 ly benign [SQLIT
9dd0: 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 E_BUSY] to.** th
9de0: 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 e more severe [S
9df0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 QLITE_IOERR_BLOC
9e00: 4b 45 44 5d 2e 20 20 54 68 69 73 20 65 72 72 6f KED]. This erro
9e10: 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e r code promotion
9e20: 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 .** forces an au
9e30: 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b tomatic rollback
9e40: 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e of the changes.
9e50: 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 See the.** <a h
9e60: 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e ref="http://www.
9e70: 73 71 6c 69 74 65 2e 6f 72 67 2f 63 76 73 74 72 sqlite.org/cvstr
9e80: 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 ac/wiki?p=Corrup
9e90: 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 tionFollowingBus
9ea0: 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 yError">.** Corr
9eb0: 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 uptionFollowingB
9ec0: 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b usyError</a> wik
9ed0: 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 i page for a dis
9ee0: 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a cussion of why.*
9ef0: 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 * this is import
9f00: 61 6e 74 2e 0a 2a 2a 09 0a 2a 2a 20 53 71 6c 69 ant..**..** Sqli
9f10: 74 65 20 69 73 20 72 65 2d 65 6e 74 72 61 6e 74 te is re-entrant
9f20: 2c 20 73 6f 20 74 68 65 20 62 75 73 79 20 68 61 , so the busy ha
9f30: 6e 64 6c 65 72 20 6d 61 79 20 73 74 61 72 74 20 ndler may start
9f40: 61 20 6e 65 77 20 71 75 65 72 79 2e 20 0a 2a 2a a new query. .**
9f50: 20 28 49 74 20 69 73 20 6e 6f 74 20 63 6c 65 61 (It is not clea
9f60: 72 20 77 68 79 20 61 6e 79 6f 6e 65 20 77 6f 75 r why anyone wou
9f70: 6c 64 20 65 76 65 72 79 20 77 61 6e 74 20 74 6f ld every want to
9f80: 20 64 6f 20 74 68 69 73 2c 20 62 75 74 20 69 74 do this, but it
9f90: 0a 2a 2a 20 69 73 20 61 6c 6c 6f 77 65 64 2c 20 .** is allowed,
9fa0: 69 6e 20 74 68 65 6f 72 79 2e 29 20 20 42 75 74 in theory.) But
9fb0: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
9fc0: 72 20 6d 61 79 20 6e 6f 74 20 63 6c 6f 73 65 20 r may not close
9fd0: 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e the.** database.
9fe0: 20 20 43 6c 6f 73 69 6e 67 20 74 68 65 20 64 61 Closing the da
9ff0: 74 61 62 61 73 65 20 66 72 6f 6d 20 61 20 62 75 tabase from a bu
a000: 73 79 20 68 61 6e 64 6c 65 72 20 77 69 6c 6c 20 sy handler will
a010: 64 65 6c 65 74 65 20 0a 2a 2a 20 64 61 74 61 20 delete .** data
a020: 73 74 72 75 63 74 75 72 65 73 20 6f 75 74 20 66 structures out f
a030: 72 6f 6d 20 75 6e 64 65 72 20 74 68 65 20 65 78 rom under the ex
a040: 65 63 75 74 69 6e 67 20 71 75 65 72 79 20 61 6e ecuting query an
a050: 64 20 77 69 6c 6c 20 0a 2a 2a 20 70 72 6f 62 61 d will .** proba
a060: 62 6c 79 20 72 65 73 75 6c 74 20 69 6e 20 61 20 bly result in a
a070: 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 segmentation fau
a080: 6c 74 20 6f 72 20 6f 74 68 65 72 20 72 75 6e 74 lt or other runt
a090: 69 6d 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a ime error..**.**
a0a0: 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 There can only
a0b0: 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 be a single busy
a0c0: 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 handler defined
a0d0: 20 66 6f 72 20 65 61 63 68 20 64 61 74 61 62 61 for each databa
a0e0: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e se.** connection
a0f0: 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 . Setting a new
a100: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c busy handler cl
a110: 65 61 72 73 20 61 6e 79 20 70 72 65 76 69 6f 75 ears any previou
a120: 73 20 6f 6e 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 s one..** Note t
a130: 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c hat calling [sql
a140: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 ite3_busy_timeou
a150: 74 28 29 5d 20 77 69 6c 6c 20 61 6c 73 6f 20 73 t()] will also s
a160: 65 74 20 6f 72 20 63 6c 65 61 72 0a 2a 2a 20 74 et or clear.** t
a170: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e he busy handler.
a180: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 6f 70 65 72 .**.** When oper
a190: 61 74 69 6e 67 20 69 6e 20 5b 73 71 6c 69 74 65 ating in [sqlite
a1a0: 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 3_enable_shared_
a1b0: 63 61 63 68 65 20 7c 20 73 68 61 72 65 64 20 63 cache | shared c
a1c0: 61 63 68 65 20 6d 6f 64 65 5d 2c 0a 2a 2a 20 6f ache mode],.** o
a1d0: 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 62 75 73 nly a single bus
a1e0: 79 20 68 61 6e 64 6c 65 72 20 63 61 6e 20 62 65 y handler can be
a1f0: 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 defined for eac
a200: 68 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e h database file.
a210: 0a 2a 2a 20 53 6f 20 69 66 20 74 77 6f 20 64 61 .** So if two da
a220: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
a230: 6e 73 20 73 68 61 72 65 20 61 20 73 69 6e 67 6c ns share a singl
a240: 65 20 63 61 63 68 65 2c 20 74 68 65 6e 20 63 68 e cache, then ch
a250: 61 6e 67 69 6e 67 0a 2a 2a 20 74 68 65 20 62 75 anging.** the bu
a260: 73 79 20 68 61 6e 64 6c 65 72 20 6f 6e 20 6f 6e sy handler on on
a270: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 69 6c e connection wil
a280: 6c 20 61 6c 73 6f 20 63 68 61 6e 67 65 20 74 68 l also change th
a290: 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 e busy.** handle
a2a0: 72 20 69 6e 20 74 68 65 20 6f 74 68 65 72 20 63 r in the other c
a2b0: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 onnection. The
a2c0: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 busy handler is
a2d0: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 69 6e 20 74 68 invoked.** in th
a2e0: 65 20 74 68 72 65 61 64 20 74 68 61 74 20 77 61 e thread that wa
a2f0: 73 20 72 75 6e 6e 69 6e 67 20 77 68 65 6e 20 74 s running when t
a300: 68 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 77 he SQLITE_BUSY w
a310: 61 73 20 68 69 74 2e 0a 2a 2f 0a 69 6e 74 20 73 as hit..*/.int s
a320: 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
a330: 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e ler(sqlite3*, in
a340: 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c t(*)(void*,int),
a350: 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 void*);../*.**
a360: 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 CAPI3REF: Set A
a370: 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a Busy Timeout.**.
a380: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
a390: 73 65 74 73 20 61 20 62 75 73 79 20 68 61 6e 64 sets a busy hand
a3a0: 6c 65 72 20 74 68 61 74 20 73 6c 65 65 70 73 20 ler that sleeps
a3b0: 66 6f 72 20 61 20 77 68 69 6c 65 20 77 68 65 6e for a while when
a3c0: 20 61 0a 2a 2a 20 74 61 62 6c 65 20 69 73 20 6c a.** table is l
a3d0: 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 61 6e 64 ocked. The hand
a3e0: 6c 65 72 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d ler will sleep m
a3f0: 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e ultiple times un
a400: 74 69 6c 20 0a 2a 2a 20 61 74 20 6c 65 61 73 74 til .** at least
a410: 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e "ms" millisecon
a420: 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 20 68 ds of sleeping h
a430: 61 76 65 20 62 65 65 6e 20 64 6f 6e 65 2e 20 20 ave been done.
a440: 41 66 74 65 72 0a 2a 2a 20 22 6d 73 22 20 6d 69 After.** "ms" mi
a450: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c lliseconds of sl
a460: 65 65 70 69 6e 67 2c 20 74 68 65 20 68 61 6e 64 eeping, the hand
a470: 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 ler returns 0 wh
a480: 69 63 68 0a 2a 2a 20 63 61 75 73 65 73 20 5b 73 ich.** causes [s
a490: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 qlite3_step()] t
a4a0: 6f 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 o return [SQLITE
a4b0: 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 _BUSY] or [SQLIT
a4c0: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d E_IOERR_BLOCKED]
a4d0: 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 ..**.** Calling
a4e0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 this routine wit
a4f0: 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 h an argument le
a500: 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c ss than or equal
a510: 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e to zero.** turn
a520: 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 s off all busy h
a530: 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 andlers..**.** T
a540: 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 here can only be
a550: 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 a single busy h
a560: 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 andler for a par
a570: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 ticular database
a580: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 .** connection.
a590: 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 If another busy
a5a0: 20 68 61 6e 64 6c 65 72 20 77 61 73 20 64 65 66 handler was def
a5b0: 69 6e 65 64 20 20 0a 2a 2a 20 28 75 73 69 6e 67 ined .** (using
a5c0: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 [sqlite3_busy_h
a5d0: 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 andler()]) prior
a5e0: 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 to calling.** t
a5f0: 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 his routine, tha
a600: 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e t other busy han
a610: 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e dler is cleared.
a620: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
a630: 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c busy_timeout(sql
a640: 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a ite3*, int ms);.
a650: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
a660: 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 Convenience Rou
a670: 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e tines For Runnin
a680: 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 g Queries.**.**
a690: 54 68 69 73 20 6e 65 78 74 20 72 6f 75 74 69 6e This next routin
a6a0: 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e e is a convenien
a6b0: 63 65 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e ce wrapper aroun
a6c0: 64 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 d [sqlite3_exec(
a6d0: 29 5d 2e 0a 2a 2a 20 49 6e 73 74 65 61 64 20 6f )]..** Instead o
a6e0: 66 20 69 6e 76 6f 6b 69 6e 67 20 61 20 75 73 65 f invoking a use
a6f0: 72 2d 73 75 70 70 6c 69 65 64 20 63 61 6c 6c 62 r-supplied callb
a700: 61 63 6b 20 66 6f 72 20 65 61 63 68 20 72 6f 77 ack for each row
a710: 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c of the.** resul
a720: 74 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 t, this routine
a730: 72 65 6d 65 6d 62 65 72 73 20 65 61 63 68 20 72 remembers each r
a740: 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 ow of the result
a750: 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 6f 62 in memory.** ob
a760: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c tained from [sql
a770: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 ite3_malloc()],
a780: 74 68 65 6e 20 72 65 74 75 72 6e 73 20 61 6c 6c then returns all
a790: 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 61 of the result a
a7a0: 66 74 65 72 20 74 68 65 0a 2a 2a 20 71 75 65 72 fter the.** quer
a7b0: 79 20 68 61 73 20 66 69 6e 69 73 68 65 64 2e 20 y has finished.
a7c0: 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61 .**.** As an exa
a7d0: 6d 70 6c 65 2c 20 73 75 70 70 6f 73 65 20 74 68 mple, suppose th
a7e0: 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 77 e query result w
a7f0: 68 65 72 65 20 74 68 69 73 20 74 61 62 6c 65 3a here this table:
a800: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
a810: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 te><pre>.**
a820: 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c Name |
a830: 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d Age.** -
a840: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
a850: 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 ------.**
a860: 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 Alice | 4
a870: 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 3.** Bob
a880: 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 | 28.**
a890: 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 Cindy
a8a0: 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 | 21.** </pre
a8b0: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
a8c0: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 *.** If the 3rd
a8d0: 61 72 67 75 6d 65 6e 74 20 77 65 72 65 20 26 61 argument were &a
a8e0: 7a 52 65 73 75 6c 74 20 74 68 65 6e 20 61 66 74 zResult then aft
a8f0: 65 72 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 er the function
a900: 72 65 74 75 72 6e 73 0a 2a 2a 20 61 7a 52 65 73 returns.** azRes
a910: 75 6c 74 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e ult will contain
a920: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 64 the following d
a930: 61 74 61 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 ata:.**.** <bloc
a940: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 kquote><pre>.**
a950: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
a960: 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b #91;0] = "Name";
a970: 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
a980: 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 ult[1] = "Ag
a990: 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a e";.** az
a9a0: 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 Result[2] =
a9b0: 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 "Alice";.**
a9c0: 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
a9d0: 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 3] = "43";.**
a9e0: 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
a9f0: 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 1;4] = "Bob";.**
aa00: 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
aa10: 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a [5] = "28";.
aa20: 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
aa30: 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e lt[6] = "Cin
aa40: 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 dy";.** a
aa50: 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d zResult[7] =
aa60: 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e "21";.** </pre>
aa70: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
aa80: 0a 2a 2a 20 4e 6f 74 69 63 65 20 74 68 61 74 20 .** Notice that
aa90: 74 68 65 72 65 20 69 73 20 61 6e 20 65 78 74 72 there is an extr
aaa0: 61 20 72 6f 77 20 6f 66 20 64 61 74 61 20 63 6f a row of data co
aab0: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 63 6f 6c ntaining the col
aac0: 75 6d 6e 0a 2a 2a 20 68 65 61 64 65 72 73 2e 20 umn.** headers.
aad0: 20 42 75 74 20 74 68 65 20 2a 6e 72 6f 77 20 72 But the *nrow r
aae0: 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 20 73 eturn value is s
aaf0: 74 69 6c 6c 20 33 2e 20 20 2a 6e 63 6f 6c 75 6d till 3. *ncolum
ab00: 6e 20 69 73 0a 2a 2a 20 73 65 74 20 74 6f 20 32 n is.** set to 2
ab10: 2e 20 20 49 6e 20 67 65 6e 65 72 61 6c 2c 20 74 . In general, t
ab20: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c he number of val
ab30: 75 65 73 20 69 6e 73 65 72 74 65 64 20 69 6e 74 ues inserted int
ab40: 6f 20 61 7a 52 65 73 75 6c 74 0a 2a 2a 20 77 69 o azResult.** wi
ab50: 6c 6c 20 62 65 20 28 28 2a 6e 72 6f 77 29 20 2b ll be ((*nrow) +
ab60: 20 31 29 2a 28 2a 6e 63 6f 6c 75 6d 6e 29 2e 0a 1)*(*ncolumn)..
ab70: 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 **.** After the
ab80: 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e calling function
ab90: 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 has finished us
aba0: 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2c 20 ing the result,
abb0: 69 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 61 it should .** pa
abc0: 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 64 61 ss the result da
abd0: 74 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 ta pointer to sq
abe0: 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 lite3_free_table
abf0: 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 0a () in order to .
ac00: 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d ** release the m
ac10: 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d emory that was m
ac20: 61 6c 6c 6f 63 2d 65 64 2e 20 20 42 65 63 61 75 alloc-ed. Becau
ac30: 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 se of the way th
ac40: 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d e .** [sqlite3_m
ac50: 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 alloc()] happens
ac60: 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 , the calling fu
ac70: 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 nction must not
ac80: 74 72 79 20 74 6f 20 63 61 6c 6c 20 0a 2a 2a 20 try to call .**
ac90: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
aca0: 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 directly. Only
acb0: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 [sqlite3_free_t
acc0: 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 able()] is able
acd0: 74 6f 20 72 65 6c 65 61 73 65 20 0a 2a 2a 20 74 to release .** t
ace0: 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 he memory proper
acf0: 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a ly and safely..*
ad00: 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 20 *.** The return
ad10: 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 72 6f value of this ro
ad20: 75 74 69 6e 65 20 69 73 20 74 68 65 20 73 61 6d utine is the sam
ad30: 65 20 61 73 20 66 72 6f 6d 20 5b 73 71 6c 69 74 e as from [sqlit
ad40: 65 33 5f 65 78 65 63 28 29 5d 2e 0a 2a 2f 0a 69 e3_exec()]..*/.i
ad50: 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 nt sqlite3_get_t
ad60: 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 2a able(. sqlite3*
ad70: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
ad80: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 * An open databa
ad90: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 se */. const ch
ada0: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 2f ar *sql, /
adb0: 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 78 65 63 * SQL to be exec
adc0: 75 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a uted */. char *
add0: 2a 2a 72 65 73 75 6c 74 70 2c 20 20 20 20 20 20 **resultp,
ade0: 20 2f 2a 20 52 65 73 75 6c 74 20 77 72 69 74 74 /* Result writt
adf0: 65 6e 20 74 6f 20 61 20 63 68 61 72 20 2a 5b 5d en to a char *[]
ae00: 20 20 74 68 61 74 20 74 68 69 73 20 70 6f 69 6e that this poin
ae10: 74 73 20 74 6f 20 2a 2f 0a 20 20 69 6e 74 20 2a ts to */. int *
ae20: 6e 72 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 nrow,
ae30: 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 /* Number of r
ae40: 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 esult rows writt
ae50: 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 en here */. int
ae60: 20 2a 6e 63 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 *ncolumn,
ae70: 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 /* Number of
ae80: 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 result columns
ae90: 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a written here */.
aea0: 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 char **errmsg
aeb0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f /* Erro
aec0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 r msg written he
aed0: 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 re */.);.void sq
aee0: 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 lite3_free_table
aef0: 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b (char **result);
af00: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
af10: 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 : Formatted Stri
af20: 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 ng Printing Func
af30: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 tions.**.** Thes
af40: 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 e routines are w
af50: 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 orkalikes of the
af60: 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 "printf()" fami
af70: 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a ly of functions.
af80: 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e ** from the stan
af90: 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a dard C library..
afa0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
afb0: 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 3_mprintf() and
afc0: 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 sqlite3_vmprintf
afd0: 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 () routines writ
afe0: 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c e their.** resul
aff0: 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f ts into memory o
b000: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
b010: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e lite3_malloc()].
b020: 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 .** The strings
b030: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 returned by thes
b040: 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 e two routines s
b050: 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 hould be.** rele
b060: 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 ased by [sqlite3
b070: 5f 66 72 65 65 28 29 5d 2e 20 20 42 6f 74 68 20 _free()]. Both
b080: 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
b090: 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 a.** NULL pointe
b0a0: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 r if [sqlite3_ma
b0b0: 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c lloc()] is unabl
b0c0: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e e to allocate en
b0d0: 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 ough.** memory t
b0e0: 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c o hold the resul
b0f0: 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a ting string..**.
b100: 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e ** In sqlite3_sn
b110: 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 printf() routine
b120: 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 is similar to "
b130: 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d snprintf()" from
b140: 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 .** the standard
b150: 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 C library. The
b160: 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 result is writt
b170: 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 en into the.** b
b180: 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 uffer supplied a
b190: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 s the second par
b1a0: 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a ameter whose siz
b1b0: 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a e is given by.**
b1c0: 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
b1d0: 65 74 65 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 eter. Note that
b1e0: 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 the order of th
b1f0: 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 e.** first two p
b200: 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 arameters is rev
b210: 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 ersed from snpri
b220: 6e 74 66 28 29 2e 20 20 54 68 69 73 20 69 73 20 ntf(). This is
b230: 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c an.** historical
b240: 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 accident that c
b250: 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 annot be fixed w
b260: 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a ithout breaking.
b270: 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d ** backwards com
b280: 70 61 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 patibility. Not
b290: 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 e also that sqli
b2a0: 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a te3_snprintf().*
b2b0: 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e * returns a poin
b2c0: 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 ter to its buffe
b2d0: 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 r instead of the
b2e0: 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 number of.** ch
b2f0: 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c aracters actuall
b300: 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 y written into t
b310: 68 65 20 62 75 66 66 65 72 2e 20 20 57 65 20 61 he buffer. We a
b320: 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 dmit that.** the
b330: 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 number of chara
b340: 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f cters written wo
b350: 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 uld be a more us
b360: 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 eful return.** v
b370: 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e alue but we cann
b380: 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d ot change the im
b390: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
b3a0: 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
b3b0: 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 ().** now withou
b3c0: 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 t breaking compa
b3d0: 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 tibility..**.**
b3e0: 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 As long as the b
b3f0: 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 uffer size is gr
b400: 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c eater than zero,
b410: 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
b420: 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 f().** guarantee
b430: 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 s that the buffe
b440: 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f r is always zero
b450: 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 -terminated. Th
b460: 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d e first.** param
b470: 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 eter "n" is the
b480: 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 total size of th
b490: 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 e buffer, includ
b4a0: 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a ing space for.**
b4b0: 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e the zero termin
b4c0: 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f ator. So the lo
b4d0: 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 ngest string tha
b4e0: 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 t can be complet
b4f0: 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 ely.** written w
b500: 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 ill be n-1 chara
b510: 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 cters..**.** The
b520: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 se routines all
b530: 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 implement some a
b540: 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 dditional format
b550: 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 ting.** options
b560: 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 that are useful
b570: 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 for constructing
b580: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e SQL statements.
b590: 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 .** All of the u
b5a0: 73 75 61 6c 20 70 72 69 6e 74 66 20 66 6f 72 6d sual printf form
b5b0: 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 atting options a
b5c0: 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 pply. In additi
b5d0: 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 on, there.** is
b5e0: 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 are "%q", "%Q",
b5f0: 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 and "%z" options
b600: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f ..**.** The %q o
b610: 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 ption works like
b620: 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 %s in that it s
b630: 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c ubstitutes a nul
b640: 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 l-terminated.**
b650: 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 string from the
b660: 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 argument list.
b670: 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 But %q also doub
b680: 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 les every '\'' c
b690: 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 haracter..** %q
b6a0: 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 is designed for
b6b0: 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 use inside a str
b6c0: 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 ing literal. By
b6d0: 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 doubling each '
b6e0: 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 \''.** character
b6f0: 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 it escapes that
b700: 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 character and a
b710: 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 llows it to be i
b720: 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 nserted into.**
b730: 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a the string..**.*
b740: 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 73 * For example, s
b750: 6f 20 73 6f 6d 65 20 73 74 72 69 6e 67 20 76 61 o some string va
b760: 72 69 61 62 6c 65 20 63 6f 6e 74 61 69 6e 73 20 riable contains
b770: 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a text as follows:
b780: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
b790: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 te><pre>.** cha
b7a0: 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 r *zText = "It's
b7b0: 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a a happy day!";.
b7c0: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
b7d0: 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 quote>.**.** One
b7e0: 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 can use this te
b7f0: 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 xt in an SQL sta
b800: 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 tement as follow
b810: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s:.**.** <blockq
b820: 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 uote><pre>.** c
b830: 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 har *zSQL = sqli
b840: 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 te3_mprintf("INS
b850: 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 ERT INTO table V
b860: 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 ALUES('%q')", zT
b870: 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 ext);.** sqlite
b880: 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 3_exec(db, zSQL,
b890: 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 0, 0, 0);.** s
b8a0: 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c qlite3_free(zSQL
b8b0: 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c );.** </pre></bl
b8c0: 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
b8d0: 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 Because the %q f
b8e0: 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 ormat string is
b8f0: 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 used, the '\'' c
b900: 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 haracter in zTex
b910: 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 t.** is escaped
b920: 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 and the SQL gene
b930: 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c rated is as foll
b940: 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 ows:.**.** <bloc
b950: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 kquote><pre>.**
b960: 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 INSERT INTO tab
b970: 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 le1 VALUES('It''
b980: 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 s a happy day!')
b990: 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
b9a0: 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 kquote>.**.** Th
b9b0: 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 is is correct.
b9c0: 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 Had we used %s i
b9d0: 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 nstead of %q, th
b9e0: 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a e generated SQL.
b9f0: 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f ** would have lo
ba00: 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a oked like this:.
ba10: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
ba20: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 e><pre>.** INSE
ba30: 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 RT INTO table1 V
ba40: 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 ALUES('It's a ha
ba50: 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c ppy day!');.** <
ba60: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
ba70: 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 e>.**.** This se
ba80: 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 cond example is
ba90: 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 an SQL syntax er
baa0: 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 ror. As a gener
bab0: 61 6c 20 72 75 6c 65 20 79 6f 75 0a 2a 2a 20 73 al rule you.** s
bac0: 68 6f 75 6c 64 20 61 6c 77 61 79 73 20 75 73 65 hould always use
bad0: 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 %q instead of %
bae0: 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 s when inserting
baf0: 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 text into a str
bb00: 69 6e 67 20 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e ing .** literal.
bb10: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f 70 .**.** The %Q op
bb20: 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 tion works like
bb30: 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 %q except it als
bb40: 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 o adds single qu
bb50: 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 otes around.** t
bb60: 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 he outside of th
bb70: 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 e total string.
bb80: 20 4f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d Or if the param
bb90: 65 74 65 72 20 69 6e 20 74 68 65 20 61 72 67 75 eter in the argu
bba0: 6d 65 6e 74 0a 2a 2a 20 6c 69 73 74 20 69 73 20 ment.** list is
bbb0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 a NULL pointer,
bbc0: 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 %Q substitutes t
bbd0: 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 he text "NULL" (
bbe0: 77 69 74 68 6f 75 74 20 73 69 6e 67 6c 65 0a 2a without single.*
bbf0: 2a 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c 61 * quotes) in pla
bc00: 63 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70 74 ce of the %Q opt
bc10: 69 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 78 ion. So, for ex
bc20: 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 ample, one could
bc30: 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f say:.**.** <blo
bc40: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
bc50: 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 char *zSQL = s
bc60: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 qlite3_mprintf("
bc70: 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c INSERT INTO tabl
bc80: 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a e VALUES(%Q)", z
bc90: 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 Text);.** sqlit
bca0: 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c e3_exec(db, zSQL
bcb0: 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 , 0, 0, 0);.**
bcc0: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 sqlite3_free(zSQ
bcd0: 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 L);.** </pre></b
bce0: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
bcf0: 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 The code above
bd00: 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f will render a co
bd10: 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d rrect SQL statem
bd20: 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a ent in the zSQL.
bd30: 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e ** variable even
bd40: 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 if the zText va
bd50: 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c riable is a NULL
bd60: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 pointer..**.**
bd70: 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 The "%z" formatt
bd80: 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 ing option works
bd90: 20 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 exactly like "%
bda0: 73 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 s" with the.** a
bdb0: 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 ddition that aft
bdc0: 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 er the string ha
bdd0: 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 s been read and
bde0: 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 copied into.** t
bdf0: 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 he result, [sqli
be00: 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 te3_free()] is c
be10: 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 alled on the inp
be20: 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2f 0a 63 68 ut string..*/.ch
be30: 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 ar *sqlite3_mpri
be40: 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c ntf(const char*,
be50: 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 ...);.char *sqli
be60: 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e te3_vmprintf(con
be70: 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 st char*, va_lis
be80: 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 t);.char *sqlite
be90: 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 3_snprintf(int,c
bea0: 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a har*,const char*
beb0: 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 , ...);../*.** C
bec0: 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 API3REF: Memory
bed0: 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 Allocation Subsy
bee0: 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 stem.**.** The S
bef0: 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 QLite core uses
bf00: 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 these three rout
bf10: 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 ines for all of
bf20: 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 its own.** inter
bf30: 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 nal memory alloc
bf40: 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 28 53 65 ation needs. (Se
bf50: 65 20 74 68 65 20 65 78 63 65 70 74 69 6f 6e 20 e the exception
bf60: 62 65 6c 6f 77 2e 29 0a 2a 2a 0a 2a 2a 20 54 68 below.).**.** Th
bf70: 65 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d e default implem
bf80: 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 entation.** of t
bf90: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
bfa0: 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 75 tion subsystem u
bfb0: 73 65 73 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29 ses the malloc()
bfc0: 2c 20 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 61 , realloc().** a
bfd0: 6e 64 20 66 72 65 65 28 29 20 70 72 6f 76 69 64 nd free() provid
bfe0: 65 64 20 62 79 20 74 68 65 20 73 74 61 6e 64 61 ed by the standa
bff0: 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 48 rd C library. H
c000: 6f 77 65 76 65 72 2c 20 69 66 20 0a 2a 2a 20 53 owever, if .** S
c010: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
c020: 64 20 77 69 74 68 20 74 68 65 20 66 6f 6c 6c 6f d with the follo
c030: 77 69 6e 67 20 43 20 70 72 65 70 72 6f 63 65 73 wing C preproces
c040: 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 0a 2a 2a 20 sor macro.**.**
c050: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 20 53 51 4c <blockquote> SQL
c060: 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45 3d ITE_MEMORY_SIZE=
c070: 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 3c 2f 62 6c 6f <i>NNN</i> </blo
c080: 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 77 ckquote>.**.** w
c090: 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 here <i>NNN</i>
c0a0: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 is an integer, t
c0b0: 68 65 6e 20 53 51 4c 69 74 65 20 63 72 65 61 74 hen SQLite creat
c0c0: 65 20 61 20 73 74 61 74 69 63 0a 2a 2a 20 61 72 e a static.** ar
c0d0: 72 61 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20 ray of at least
c0e0: 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74 65 73 <i>NNN</i> bytes
c0f0: 20 69 6e 20 73 69 7a 65 20 61 6e 64 20 75 73 65 in size and use
c100: 20 74 68 61 74 20 61 72 72 61 79 0a 2a 2a 20 66 that array.** f
c110: 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 or all of its dy
c120: 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c namic memory all
c130: 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a ocation needs..*
c140: 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 *.** In SQLite v
c150: 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 ersion 3.5.0 and
c160: 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 3.5.1, it was p
c170: 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e ossible to defin
c180: 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f e.** the SQLITE_
c190: 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f OMIT_MEMORY_ALLO
c1a0: 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 CATION which wou
c1b0: 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 ld cause the bui
c1c0: 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 lt-in.** impleme
c1d0: 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 ntation of these
c1e0: 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 routines to be
c1f0: 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 omitted. That c
c200: 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 apability.** is
c210: 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 no longer provid
c220: 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d ed. Only built-
c230: 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 in memory alloca
c240: 74 6f 72 73 20 63 61 6e 20 62 65 0a 2a 2a 20 75 tors can be.** u
c250: 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 45 78 sed..**.** <b>Ex
c260: 63 65 70 74 69 6f 6e 3a 3c 2f 62 3e 20 54 68 65 ception:</b> The
c270: 20 77 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 windows OS inte
c280: 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c rface layer call
c290: 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 s.** the system
c2a0: 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 malloc() and fre
c2b0: 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 e() directly whe
c2c0: 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 n converting.**
c2d0: 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 filenames betwee
c2e0: 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f n the UTF-8 enco
c2f0: 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c ding used by SQL
c300: 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 ite.** and whate
c310: 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 ver filename enc
c320: 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 oding is used by
c330: 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 the particular
c340: 77 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 windows.** insta
c350: 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 llation. Memory
c360: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f allocation erro
c370: 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64 2c rs are detected,
c380: 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 but.** they are
c390: 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 reported back a
c3a0: 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 s [SQLITE_CANTOP
c3b0: 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 EN] or.** [SQLIT
c3c0: 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 E_IOERR] rather
c3d0: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d than [SQLITE_NOM
c3e0: 45 4d 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 EM]..*/.void *sq
c3f0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 lite3_malloc(int
c400: 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 );.void *sqlite3
c410: 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 _realloc(void*,
c420: 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 int);.void sqlit
c430: 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a e3_free(void*);.
c440: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
c450: 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f Memory Allocato
c460: 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a r Statistics.**.
c470: 2a 2a 20 49 6e 20 61 64 64 69 74 69 6f 6e 20 74 ** In addition t
c480: 6f 20 74 68 65 20 62 61 73 69 63 20 74 68 72 65 o the basic thre
c490: 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 e allocation rou
c4a0: 74 69 6e 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 tines .** [sqlit
c4b0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 e3_malloc()], [s
c4c0: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 qlite3_free()],
c4d0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 and [sqlite3_rea
c4e0: 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 74 68 65 20 lloc()],.** the
c4f0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
c500: 6e 20 73 75 62 73 79 73 74 65 6d 20 69 6e 63 6c n subsystem incl
c510: 75 64 65 64 20 77 69 74 68 20 74 68 65 20 53 51 uded with the SQ
c520: 4c 69 74 65 0a 2a 2a 20 73 6f 75 72 63 65 73 20 Lite.** sources
c530: 70 72 6f 76 69 64 65 73 20 74 68 65 20 69 6e 74 provides the int
c540: 65 72 66 61 63 65 73 20 73 68 6f 77 6e 20 62 65 erfaces shown be
c550: 6c 6f 77 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 low..**.** The f
c560: 69 72 73 74 20 6f 66 20 74 68 65 73 65 20 74 77 irst of these tw
c570: 6f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 o routines retur
c580: 6e 73 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 ns the amount of
c590: 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 63 75 72 72 memory .** curr
c5a0: 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e ently outstandin
c5b0: 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 g (malloced but
c5c0: 6e 6f 74 20 66 72 65 65 64 29 2e 20 20 54 68 65 not freed). The
c5d0: 20 73 65 63 6f 6e 64 0a 2a 2a 20 72 65 74 75 72 second.** retur
c5e0: 6e 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 69 ns the largest i
c5f0: 6e 73 74 61 6e 74 61 6e 65 6f 75 73 20 61 6d 6f nstantaneous amo
c600: 75 6e 74 20 6f 66 20 6f 75 74 73 74 61 6e 64 69 unt of outstandi
c610: 6e 67 0a 2a 2a 20 6d 65 6d 6f 72 79 2e 20 20 54 ng.** memory. T
c620: 68 65 20 68 69 67 68 77 61 74 65 72 20 6d 61 72 he highwater mar
c630: 6b 20 69 73 20 72 65 73 65 74 20 69 66 20 74 68 k is reset if th
c640: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a e argument is.**
c650: 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 true..**.** The
c660: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
c670: 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 69 may or may not i
c680: 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f nclude allocatio
c690: 6e 0a 2a 2a 20 6f 76 65 72 68 65 61 64 2c 20 64 n.** overhead, d
c6a0: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 epending on whic
c6b0: 68 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 h built-in memor
c6c0: 79 20 61 6c 6c 6f 63 61 74 6f 72 0a 2a 2a 20 69 y allocator.** i
c6d0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 mplementation is
c6e0: 20 75 73 65 64 2e 0a 2a 2f 0a 73 71 6c 69 74 65 used..*/.sqlite
c6f0: 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 3_int64 sqlite3_
c700: 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 memory_used(void
c710: 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 );.sqlite3_int64
c720: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f sqlite3_memory_
c730: 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 highwater(int re
c740: 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a setFlag);../*.**
c750: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 CAPI3REF: Compi
c760: 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a le-Time Authoriz
c770: 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a ation Callbacks.
c780: 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 ***.** This rout
c790: 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 20 ine registers a
c7a0: 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
c7b0: 61 63 6b 20 77 69 74 68 20 74 68 65 20 53 51 4c ack with the SQL
c7c0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 0a 2a ite library. .*
c7d0: 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 * The authorizer
c7e0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
c7f0: 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 oked as SQL stat
c800: 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 ements are being
c810: 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 compiled.** by
c820: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
c830: 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 ()] or its varia
c840: 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 nts [sqlite3_pre
c850: 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b pare_v2()],.** [
c860: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
c870: 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 6()] and [sqlite
c880: 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
c890: 5d 2e 20 20 41 74 20 76 61 72 69 6f 75 73 0a 2a ]. At various.*
c8a0: 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 * points during
c8b0: 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 the compilation
c8c0: 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 process, as logi
c8d0: 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 c is being creat
c8e0: 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d ed.** to perform
c8f0: 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 various actions
c900: 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 , the authorizer
c910: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
c920: 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 oked to.** see i
c930: 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 f those actions
c940: 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68 are allowed. Th
c950: 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
c960: 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 lback should.**
c970: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b return SQLITE_OK
c980: 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 to allow the ac
c990: 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 tion, [SQLITE_IG
c9a0: 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f NORE] to disallo
c9b0: 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 w the.** specifi
c9c0: 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c c action but all
c9d0: 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 ow the SQL state
c9e0: 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 ment to continue
c9f0: 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c to be.** compil
ca00: 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 ed, or [SQLITE_D
ca10: 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 ENY] to cause th
ca20: 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 e entire SQL sta
ca30: 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 tement to be.**
ca40: 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e rejected with an
ca50: 20 65 72 72 6f 72 2e 20 20 0a 2a 2a 0a 2a 2a 20 error. .**.**
ca60: 44 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 Depending on the
ca70: 20 61 63 74 69 6f 6e 2c 20 74 68 65 20 5b 53 51 action, the [SQ
ca80: 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 61 6e 64 LITE_IGNORE] and
ca90: 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 72 [SQLITE_DENY] r
caa0: 65 74 75 72 6e 0a 2a 2a 20 63 6f 64 65 73 20 6d eturn.** codes m
cab0: 69 67 68 74 20 6d 65 61 6e 20 73 6f 6d 65 74 68 ight mean someth
cac0: 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 6f 72 ing different or
cad0: 20 74 68 65 79 20 6d 69 67 68 74 20 6d 65 61 6e they might mean
cae0: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 68 69 the same.** thi
caf0: 6e 67 2e 20 20 49 66 20 74 68 65 20 61 63 74 69 ng. If the acti
cb00: 6f 6e 20 69 73 2c 20 66 6f 72 20 65 78 61 6d 70 on is, for examp
cb10: 6c 65 2c 20 74 6f 20 70 65 72 66 6f 72 6d 20 61 le, to perform a
cb20: 20 64 65 6c 65 74 65 20 6f 70 65 72 74 69 6f 6e delete opertion
cb30: 2c 0a 2a 2a 20 74 68 65 6e 20 5b 53 51 4c 49 54 ,.** then [SQLIT
cb40: 45 5f 49 47 4e 4f 52 45 5d 20 61 6e 64 20 5b 53 E_IGNORE] and [S
cb50: 51 4c 49 54 45 5f 44 45 4e 59 5d 20 62 6f 74 68 QLITE_DENY] both
cb60: 20 63 61 75 73 65 20 74 68 65 20 73 74 61 74 65 cause the state
cb70: 6d 65 6e 74 20 63 6f 6d 70 69 6c 61 74 69 6f 6e ment compilation
cb80: 0a 2a 2a 20 74 6f 20 66 61 69 6c 20 77 69 74 68 .** to fail with
cb90: 20 61 6e 20 65 72 72 6f 72 2e 20 20 42 75 74 20 an error. But
cba0: 69 66 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 if the action is
cbb0: 20 74 6f 20 72 65 61 64 20 61 20 73 70 65 63 69 to read a speci
cbc0: 66 69 63 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 66 72 fic column.** fr
cbd0: 6f 6d 20 61 20 73 70 65 63 69 66 69 63 20 74 61 om a specific ta
cbe0: 62 6c 65 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 ble, then [SQLIT
cbf0: 45 5f 44 45 4e 59 5d 20 77 69 6c 6c 20 63 61 75 E_DENY] will cau
cc00: 73 65 20 74 68 65 20 65 6e 74 69 72 65 0a 2a 2a se the entire.**
cc10: 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 66 61 statement to fa
cc20: 69 6c 20 62 75 74 20 5b 53 51 4c 49 54 45 5f 49 il but [SQLITE_I
cc30: 47 4e 4f 52 45 5d 20 77 69 6c 6c 20 63 61 75 73 GNORE] will caus
cc40: 65 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 74 e a NULL value t
cc50: 6f 20 62 65 0a 2a 2a 20 72 65 61 64 20 69 6e 73 o be.** read ins
cc60: 74 65 61 64 20 6f 66 20 74 68 65 20 61 63 74 75 tead of the actu
cc70: 61 6c 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2e al column value.
cc80: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
cc90: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
cca0: 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
ccb0: 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 lback is a copy
ccc0: 6f 66 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20 of.** the third
ccd0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
cce0: 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 sqlite3_set_aut
ccf0: 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 horizer() interf
cd00: 61 63 65 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f ace..** The seco
cd10: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 nd parameter to
cd20: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 the callback is
cd30: 61 6e 20 69 6e 74 65 67 65 72 20 0a 2a 2a 20 5b an integer .** [
cd40: 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 SQLITE_COPY | ac
cd50: 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 tion code] that
cd60: 73 70 65 63 69 66 69 65 73 20 74 68 65 20 70 61 specifies the pa
cd70: 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a rticular action.
cd80: 2a 2a 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 ** to be authori
cd90: 7a 65 64 2e 20 20 54 68 65 20 61 76 61 69 6c 61 zed. The availa
cda0: 62 6c 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 ble action codes
cdb0: 20 61 72 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f are.** [SQLITE_
cdc0: 43 4f 50 59 20 7c 20 64 6f 63 75 6d 65 6e 74 65 COPY | documente
cdd0: 64 20 73 65 70 61 72 61 74 65 6c 79 5d 2e 20 20 d separately].
cde0: 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 The third throug
cdf0: 68 20 73 69 78 74 68 0a 2a 2a 20 70 61 72 61 6d h sixth.** param
ce00: 65 74 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c eters to the cal
ce10: 6c 62 61 63 6b 20 61 72 65 20 73 74 72 69 6e 67 lback are string
ce20: 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 s that contain a
ce30: 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 dditional.** det
ce40: 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 ails about the a
ce50: 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 ction to be auth
ce60: 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e orized..**.** An
ce70: 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 authorizer is u
ce80: 73 65 64 20 77 68 65 6e 20 70 72 65 70 61 72 69 sed when prepari
ce90: 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ng SQL statement
cea0: 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 s from an untrus
ceb0: 74 65 64 0a 2a 2a 20 73 6f 75 72 63 65 2c 20 74 ted.** source, t
cec0: 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 o ensure that th
ced0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 e SQL statements
cee0: 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 do not try to a
cef0: 63 63 65 73 73 20 64 61 74 61 0a 2a 2a 20 74 68 ccess data.** th
cf00: 61 74 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 at they are not
cf10: 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 allowed to see,
cf20: 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 or that they do
cf30: 6e 6f 74 20 74 72 79 20 74 6f 0a 2a 2a 20 65 78 not try to.** ex
cf40: 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 ecute malicious
cf50: 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 statements that
cf60: 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 damage the datab
cf70: 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 ase. For.** exa
cf80: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 mple, an applica
cf90: 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 tion may allow a
cfa0: 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 user to enter a
cfb0: 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 rbitrary.** SQL
cfc0: 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c queries for eval
cfd0: 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 uation by a data
cfe0: 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 base. But the a
cff0: 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a pplication does.
d000: 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 ** not want the
d010: 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 user to be able
d020: 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 to make arbitrar
d030: 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 y changes to the
d040: 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 .** database. A
d050: 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 n authorizer cou
d060: 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 ld then be put i
d070: 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 n place while th
d080: 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 e.** user-entere
d090: 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 70 d SQL is being p
d0a0: 72 65 70 61 72 65 64 20 74 68 61 74 20 64 69 73 repared that dis
d0b0: 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e allows everythin
d0c0: 67 0a 2a 2a 20 65 78 63 65 70 74 20 53 45 4c 45 g.** except SELE
d0d0: 43 54 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 CT statements.
d0e0: 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 .**.** Only a si
d0f0: 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 ngle authorizer
d100: 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 can be in place
d110: 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f on a database co
d120: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 nnection.** at a
d130: 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c time. Each cal
d140: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 l to sqlite3_set
d150: 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 _authorizer over
d160: 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 rides the.** pre
d170: 76 69 6f 75 73 20 63 61 6c 6c 2e 20 20 41 20 4e vious call. A N
d180: 55 4c 4c 20 61 75 74 68 6f 72 69 7a 65 72 20 6d ULL authorizer m
d190: 65 61 6e 73 20 74 68 61 74 20 6e 6f 20 61 75 74 eans that no aut
d1a0: 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 horization.** ca
d1b0: 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
d1c0: 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 d. The default
d1d0: 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 4e 55 authorizer is NU
d1e0: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 LL..**.** Note t
d1f0: 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a hat the authoriz
d200: 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 er callback is i
d210: 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 nvoked only duri
d220: 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ng .** [sqlite3_
d230: 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 prepare()] or it
d240: 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 s variants. Aut
d250: 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f horization is no
d260: 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 t.** performed d
d270: 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 uring statement
d280: 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 evaluation in [s
d290: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a qlite3_step()]..
d2a0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 */.int sqlite3_s
d2b0: 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 et_authorizer(.
d2c0: 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 sqlite3*,. int
d2d0: 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c (*xAuth)(void*,
d2e0: 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c int,const char*,
d2f0: 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 const char*,cons
d300: 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 t char*,const ch
d310: 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 ar*),. void *pU
d320: 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a serData.);../*.*
d330: 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 * CAPI3REF: Auth
d340: 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f orizer Return Co
d350: 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 des.**.** The [s
d360: 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
d370: 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a rizer | authoriz
d380: 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 er callback func
d390: 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 tion] must.** re
d3a0: 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c turn either [SQL
d3b0: 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f ITE_OK] or one o
d3c0: 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 f these two cons
d3d0: 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a tants in order.*
d3e0: 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 * to signal SQLi
d3f0: 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f te whether or no
d400: 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 t the action is
d410: 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 permitted. See
d420: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
d430: 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c set_authorizer |
d440: 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 authorizer docu
d450: 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 mentation] for a
d460: 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 dditional.** inf
d470: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 ormation..*/.#de
d480: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 fine SQLITE_DENY
d490: 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 1 /* Abort
d4a0: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
d4b0: 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 t with an error
d4c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
d4d0: 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 E_IGNORE 2 /*
d4e0: 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 Don't allow acce
d4f0: 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 ss, but don't ge
d500: 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 nerate an error
d510: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
d520: 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 EF: Authorizer A
d530: 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a ction Codes.**.*
d540: 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 * The [sqlite3_s
d550: 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d et_authorizer()]
d560: 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 interface regis
d570: 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 ters a callback
d580: 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 function.** that
d590: 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 is invoked to a
d5a0: 75 74 68 6f 72 69 7a 65 72 20 63 65 72 74 61 69 uthorizer certai
d5b0: 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 n SQL statement
d5c0: 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a actions. The.**
d5d0: 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
d5e0: 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 r to the callbac
d5f0: 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 k is an integer
d600: 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 code that specif
d610: 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 ies.** what acti
d620: 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 on is being auth
d630: 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 orized. These a
d640: 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 re the integer a
d650: 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 ction codes that
d660: 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a .** the authoriz
d670: 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 er callback may
d680: 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a be passed..**.**
d690: 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f These action co
d6a0: 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 de values signif
d6b0: 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f y what kind of o
d6c0: 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 peration is to b
d6d0: 65 20 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 e .** authorized
d6e0: 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 . The 3rd and 4
d6f0: 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f th parameters to
d700: 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 the authorizati
d710: 6f 6e 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 on callback.** f
d720: 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 unction will be
d730: 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 parameters or NU
d740: 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 LL depending on
d750: 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a which of these.*
d760: 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 * codes is used
d770: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 as the second pa
d780: 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 35 74 rameter. The 5t
d790: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
d7a0: 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 he.** authorizer
d7b0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 callback is the
d7c0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 name of the dat
d7d0: 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 abase ("main", "
d7e0: 74 65 6d 70 22 2c 20 0a 2a 2a 20 65 74 63 2e 29 temp", .** etc.)
d7f0: 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 20 if applicable.
d800: 20 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 The 6th paramet
d810: 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 er to the author
d820: 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a izer callback.**
d830: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 is the name of
d840: 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 the inner-most t
d850: 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 rigger or view t
d860: 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 hat is responsib
d870: 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 le for.** the ac
d880: 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 cess attempt or
d890: 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 NULL if this acc
d8a0: 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 ess attempt is d
d8b0: 69 72 65 63 74 6c 79 20 66 72 6f 6d 20 0a 2a 2a irectly from .**
d8c0: 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 top-level SQL c
d8d0: 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a ode..*/./*******
d8e0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
d8f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
d900: 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a **** 3rd *******
d910: 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a ***** 4th ******
d920: 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 *****/.#define S
d930: 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 QLITE_CREATE_IND
d940: 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 EX 1
d950: 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 /* Index Name
d960: 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
d970: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
d980: 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c LITE_CREATE_TABL
d990: 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f E 2 /
d9a0: 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
d9b0: 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
d9c0: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
d9d0: 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f ITE_CREATE_TEMP_
d9e0: 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a INDEX 3 /*
d9f0: 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 Index Name
da00: 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
da10: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
da20: 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 TE_CREATE_TEMP_T
da30: 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 ABLE 4 /*
da40: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
da50: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
da60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
da70: 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 E_CREATE_TEMP_TR
da80: 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 IGGER 5 /* T
da90: 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 rigger Name T
daa0: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
dab0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
dac0: 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 _CREATE_TEMP_VIE
dad0: 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 W 6 /* Vi
dae0: 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 ew Name NU
daf0: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
db00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
db10: 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 CREATE_TRIGGER
db20: 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 7 /* Tri
db30: 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 gger Name Tab
db40: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
db50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
db60: 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 REATE_VIEW
db70: 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 8 /* View
db80: 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c Name NULL
db90: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
dba0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 define SQLITE_DE
dbb0: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 LETE
dbc0: 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 9 /* Table
dbd0: 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
dbe0: 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
dbf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
dc00: 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 P_INDEX
dc10: 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 10 /* Index
dc20: 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 Name Table
dc30: 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
dc40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
dc50: 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 _TABLE
dc60: 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 11 /* Table N
dc70: 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
dc80: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
dc90: 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
dca0: 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 TEMP_INDEX
dcb0: 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 12 /* Index Na
dcc0: 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 me Table Na
dcd0: 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
dce0: 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
dcf0: 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 EMP_TABLE 1
dd00: 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 3 /* Table Nam
dd10: 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
dd20: 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
dd30: 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 e SQLITE_DROP_TE
dd40: 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 MP_TRIGGER 14
dd50: 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 /* Trigger Na
dd60: 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 me Table Name
dd70: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
dd80: 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d SQLITE_DROP_TEM
dd90: 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 P_VIEW 15
dda0: 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 /* View Name
ddb0: 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
ddc0: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
ddd0: 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 SQLITE_DROP_TRIG
dde0: 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 GER 16
ddf0: 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 /* Trigger Name
de00: 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
de10: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
de20: 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 QLITE_DROP_VIEW
de30: 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 17
de40: 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 /* View Name
de50: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
de60: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
de70: 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 LITE_INSERT
de80: 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 18 /
de90: 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
dea0: 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
deb0: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
dec0: 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 ITE_PRAGMA
ded0: 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 19 /*
dee0: 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 Pragma Name
def0: 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 1st arg or NULL
df00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
df10: 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 TE_READ
df20: 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 20 /*
df30: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
df40: 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 Column Name
df50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
df60: 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 E_SELECT
df70: 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 21 /* N
df80: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e ULL N
df90: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
dfa0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
dfb0: 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 _TRANSACTION
dfc0: 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4e 55 22 /* NU
dfd0: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 LL NU
dfe0: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
dff0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
e000: 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 UPDATE
e010: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 23 /* Tab
e020: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c le Name Col
e030: 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a umn Name */.
e040: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
e050: 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 TTACH
e060: 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 24 /* File
e070: 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c name NULL
e080: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
e090: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 define SQLITE_DE
e0a0: 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 TACH
e0b0: 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 25 /* Datab
e0c0: 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 ase Name NULL
e0d0: 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
e0e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 efine SQLITE_ALT
e0f0: 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 ER_TABLE
e100: 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 26 /* Databa
e110: 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 se Name Table
e120: 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
e130: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e fine SQLITE_REIN
e140: 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 DEX
e150: 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 27 /* Index N
e160: 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
e170: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
e180: 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 ine SQLITE_ANALY
e190: 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ZE
e1a0: 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 28 /* Table Na
e1b0: 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
e1c0: 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
e1d0: 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
e1e0: 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 _VTABLE 2
e1f0: 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 9 /* Table Nam
e200: 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 e Module Na
e210: 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e me */.#defin
e220: 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 e SQLITE_DROP_VT
e230: 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 ABLE 30
e240: 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
e250: 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d Module Nam
e260: 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 e */.#define
e270: 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e SQLITE_FUNCTION
e280: 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 31
e290: 20 20 2f 2a 20 46 75 6e 63 74 69 6f 6e 20 4e 61 /* Function Na
e2a0: 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 me NULL
e2b0: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
e2c0: 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 SQLITE_COPY
e2d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 0
e2e0: 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 /* No longer us
e2f0: 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ed */../*.** CAP
e300: 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 I3REF: Tracing A
e310: 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e nd Profiling Fun
e320: 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 ctions.**.** The
e330: 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 se routines regi
e340: 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 ster callback fu
e350: 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e nctions that can
e360: 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 be used for.**
e370: 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 tracing and prof
e380: 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 iling the execut
e390: 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 ion of SQL state
e3a0: 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 63 61 ments..** The ca
e3b0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
e3c0: 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 registered by sq
e3d0: 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 lite3_trace() is
e3e0: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 74 20 74 invoked.** at t
e3f0: 68 65 20 66 69 72 73 74 20 5b 73 71 6c 69 74 65 he first [sqlite
e400: 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 74 68 3_step()] for th
e410: 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 e evaluation of
e420: 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 an SQL statement
e430: 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 ..** The callbac
e440: 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 k function regis
e450: 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 tered by sqlite3
e460: 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e _profile() is in
e470: 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 voked.** as each
e480: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 SQL statement f
e490: 69 6e 69 73 68 65 73 20 61 6e 64 20 69 6e 63 6c inishes and incl
e4a0: 75 64 65 73 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 udes.** informat
e4b0: 69 6f 6e 20 6f 6e 20 68 6f 77 20 6c 6f 6e 67 20 ion on how long
e4c0: 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 72 that statement r
e4d0: 61 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 an..**.** The sq
e4e0: 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 lite3_profile()
e4f0: 41 50 49 20 69 73 20 63 75 72 72 65 6e 74 6c 79 API is currently
e500: 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 considered expe
e510: 72 69 6d 65 6e 74 61 6c 20 61 6e 64 0a 2a 2a 20 rimental and.**
e520: 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 is subject to ch
e530: 61 6e 67 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 ange..*/.void *s
e540: 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c qlite3_trace(sql
e550: 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 ite3*, void(*xTr
e560: 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 ace)(void*,const
e570: 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b char*), void*);
e580: 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 .void *sqlite3_p
e590: 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c rofile(sqlite3*,
e5a0: 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 . void(*xProfi
e5b0: 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 le)(void*,const
e5c0: 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 char*,sqlite3_ui
e5d0: 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a nt64), void*);..
e5e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
e5f0: 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 Query Progress C
e600: 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54 allbacks.**.** T
e610: 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 his routine conf
e620: 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63 igures a callbac
e630: 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 k function - the
e640: 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 progress callba
e650: 63 6b 20 2d 20 74 68 61 74 0a 2a 2a 20 69 73 20 ck - that.** is
e660: 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 invoked periodic
e670: 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 ally during long
e680: 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 running calls t
e690: 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 o [sqlite3_exec(
e6a0: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
e6b0: 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c step()] and [sql
e6c0: 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
e6d0: 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 ]. An example u
e6e0: 73 65 20 66 6f 72 20 74 68 69 73 20 0a 2a 2a 20 se for this .**
e6f0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 interface is to
e700: 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 keep a GUI updat
e710: 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 ed during a larg
e720: 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 e query..**.** T
e730: 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c he progress call
e740: 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
e750: 6f 6e 63 65 20 66 6f 72 20 65 76 65 72 79 20 4e once for every N
e760: 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 virtual machine
e770: 20 6f 70 63 6f 64 65 73 2c 0a 2a 2a 20 77 68 65 opcodes,.** whe
e780: 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f re N is the seco
e790: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 nd argument to t
e7a0: 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 his function. Th
e7b0: 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 e progress callb
e7c0: 61 63 6b 0a 2a 2a 20 69 74 73 65 6c 66 20 69 73 ack.** itself is
e7d0: 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 identified by t
e7e0: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
e7f0: 74 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 t to this functi
e800: 6f 6e 2e 20 54 68 65 20 66 6f 75 72 74 68 0a 2a on. The fourth.*
e810: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 * argument to th
e820: 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 is function is a
e830: 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 70 61 void pointer pa
e840: 73 73 65 64 20 74 6f 20 74 68 65 20 70 72 6f 67 ssed to the prog
e850: 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a ress callback.**
e860: 20 66 75 6e 63 74 69 6f 6e 20 65 61 63 68 20 74 function each t
e870: 69 6d 65 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 ime it is invoke
e880: 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 61 d..**.** If a ca
e890: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 ll to [sqlite3_e
e8a0: 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 xec()], [sqlite3
e8b0: 5f 73 74 65 70 28 29 5d 2c 20 6f 72 20 5b 73 71 _step()], or [sq
e8c0: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
e8d0: 29 5d 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e )].** results in
e8e0: 20 66 65 77 65 72 20 74 68 61 6e 20 4e 20 6f 70 fewer than N op
e8f0: 63 6f 64 65 73 20 62 65 69 6e 67 20 65 78 65 63 codes being exec
e900: 75 74 65 64 2c 20 74 68 65 6e 20 74 68 65 20 70 uted, then the p
e910: 72 6f 67 72 65 73 73 20 0a 2a 2a 20 63 61 6c 6c rogress .** call
e920: 62 61 63 6b 20 69 73 20 6e 65 76 65 72 20 69 6e back is never in
e930: 76 6f 6b 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 4f 6e voked..** .** On
e940: 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 ly a single prog
e950: 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 66 75 ress callback fu
e960: 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 nction may be re
e970: 67 69 73 74 65 72 65 64 20 66 6f 72 20 65 61 63 gistered for eac
e980: 68 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62 61 h.** open databa
e990: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 se connection.
e9a0: 45 76 65 72 79 20 63 61 6c 6c 20 74 6f 20 73 71 Every call to sq
e9b0: 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 lite3_progress_h
e9c0: 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 6f 76 65 72 andler().** over
e9d0: 77 72 69 74 65 73 20 74 68 65 20 72 65 73 75 6c writes the resul
e9e0: 74 73 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f ts of the previo
e9f0: 75 73 20 63 61 6c 6c 2e 0a 2a 2a 20 54 6f 20 72 us call..** To r
ea00: 65 6d 6f 76 65 20 74 68 65 20 70 72 6f 67 72 65 emove the progre
ea10: 73 73 20 63 61 6c 6c 62 61 63 6b 20 61 6c 74 6f ss callback alto
ea20: 67 65 74 68 65 72 2c 20 70 61 73 73 20 4e 55 4c gether, pass NUL
ea30: 4c 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a L as the third.*
ea40: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 * argument to th
ea50: 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a is function..**.
ea60: 2a 2a 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 ** If the progre
ea70: 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 ss callback retu
ea80: 72 6e 73 20 61 20 72 65 73 75 6c 74 20 6f 74 68 rns a result oth
ea90: 65 72 20 74 68 61 6e 20 30 2c 20 74 68 65 6e 20 er than 0, then
eaa0: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 the current .**
eab0: 71 75 65 72 79 20 69 73 20 69 6d 6d 65 64 69 61 query is immedia
eac0: 74 65 6c 79 20 74 65 72 6d 69 6e 61 74 65 64 20 tely terminated
ead0: 61 6e 64 20 61 6e 79 20 64 61 74 61 62 61 73 65 and any database
eae0: 20 63 68 61 6e 67 65 73 20 72 6f 6c 6c 65 64 20 changes rolled
eaf0: 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 63 6f 6e back..** The con
eb00: 74 61 69 6e 69 6e 67 20 5b 73 71 6c 69 74 65 33 taining [sqlite3
eb10: 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 _exec()], [sqlit
eb20: 65 33 5f 73 74 65 70 28 29 5d 2c 20 6f 72 0a 2a e3_step()], or.*
eb30: 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 * [sqlite3_get_t
eb40: 61 62 6c 65 28 29 5d 20 63 61 6c 6c 20 72 65 74 able()] call ret
eb50: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4e 54 45 urns SQLITE_INTE
eb60: 52 52 55 50 54 2e 20 20 20 54 68 69 73 20 66 65 RRUPT. This fe
eb70: 61 74 75 72 65 0a 2a 2a 20 63 61 6e 20 62 65 20 ature.** can be
eb80: 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c used, for exampl
eb90: 65 2c 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 e, to implement
eba0: 74 68 65 20 22 43 61 6e 63 65 6c 22 20 62 75 74 the "Cancel" but
ebb0: 74 6f 6e 20 6f 6e 20 61 0a 2a 2a 20 70 72 6f 67 ton on a.** prog
ebc0: 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 20 ress dialog box
ebd0: 69 6e 20 61 20 47 55 49 2e 0a 2a 2f 0a 76 6f 69 in a GUI..*/.voi
ebe0: 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 d sqlite3_progre
ebf0: 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 ss_handler(sqlit
ec00: 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 e3*, int, int(*)
ec10: 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b (void*), void*);
ec20: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
ec30: 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 : Opening A New
ec40: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 Database Connect
ec50: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 4f 70 65 6e 20 74 ion.**.** Open t
ec60: 68 65 20 73 71 6c 69 74 65 20 64 61 74 61 62 61 he sqlite databa
ec70: 73 65 20 66 69 6c 65 20 22 66 69 6c 65 6e 61 6d se file "filenam
ec80: 65 22 2e 20 20 54 68 65 20 22 66 69 6c 65 6e 61 e". The "filena
ec90: 6d 65 22 20 69 73 20 55 54 46 2d 38 0a 2a 2a 20 me" is UTF-8.**
eca0: 65 6e 63 6f 64 65 64 20 66 6f 72 20 5b 73 71 6c encoded for [sql
ecb0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 ite3_open()] and
ecc0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
ecd0: 32 28 29 5d 20 61 6e 64 20 55 54 46 2d 31 36 20 2()] and UTF-16
ece0: 65 6e 63 6f 64 65 64 0a 2a 2a 20 69 6e 20 74 68 encoded.** in th
ecf0: 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 e native byte or
ed00: 64 65 72 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 der for [sqlite3
ed10: 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 41 _open16()]..** A
ed20: 6e 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e n [sqlite3*] han
ed30: 64 6c 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 dle is returned
ed40: 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 0a 2a in *ppDb, even.*
ed50: 2a 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 * if an error oc
ed60: 63 75 72 73 2e 20 49 66 20 74 68 65 20 64 61 74 curs. If the dat
ed70: 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 abase is opened
ed80: 28 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63 (or created) suc
ed90: 63 65 73 73 66 75 6c 6c 79 2c 0a 2a 2a 20 74 68 cessfully,.** th
eda0: 65 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 en [SQLITE_OK] i
edb0: 73 20 72 65 74 75 72 6e 65 64 2e 20 4f 74 68 65 s returned. Othe
edc0: 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 63 rwise an error c
edd0: 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e ode is returned.
ede0: 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 The.** [sqlite3
edf0: 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 _errmsg()] or [s
ee00: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 qlite3_errmsg16(
ee10: 29 5d 20 20 72 6f 75 74 69 6e 65 73 20 63 61 6e )] routines can
ee20: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 be used to obta
ee30: 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 in.** an English
ee40: 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 language descri
ee50: 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 ption of the err
ee60: 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 or..**.** The de
ee70: 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 fault encoding f
ee80: 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 or the database
ee90: 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 will be UTF-8 if
eea0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 .** [sqlite3_ope
eeb0: 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 n()] or [sqlite3
eec0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73 20 63 _open_v2()] is c
eed0: 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 alled and.** UTF
eee0: 2d 31 36 20 69 66 20 5b 73 71 6c 69 74 65 33 5f -16 if [sqlite3_
eef0: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 open16()] is use
ef00: 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 d..**.** Whether
ef10: 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 or not an error
ef20: 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 occurs when it
ef30: 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 is opened, resou
ef40: 72 63 65 73 20 61 73 73 6f 63 69 61 74 65 64 0a rces associated.
ef50: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c ** with the [sql
ef60: 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20 73 68 ite3*] handle sh
ef70: 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 ould be released
ef80: 20 62 79 20 70 61 73 73 69 6e 67 20 69 74 20 74 by passing it t
ef90: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6c o.** [sqlite3_cl
efa0: 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 ose()] when it i
efb0: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 s no longer requ
efc0: 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ired..**.** The
efd0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
efe0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 6f ()] interface wo
eff0: 72 6b 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 rks like [sqlite
f000: 33 5f 6f 70 65 6e 28 29 5d 20 65 78 63 65 70 74 3_open()] except
f010: 20 74 68 61 74 0a 2a 2a 20 70 72 6f 76 69 64 65 that.** provide
f020: 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c s two additional
f030: 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 parameters for
f040: 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 additional contr
f050: 6f 6c 20 6f 76 65 72 20 74 68 65 0a 2a 2a 20 6e ol over the.** n
f060: 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ew database conn
f070: 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61 ection. The fla
f080: 67 73 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e gs parameter can
f090: 20 62 65 20 6f 6e 65 20 6f 66 3a 0a 2a 2a 0a 2a be one of:.**.*
f0a0: 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 * <ol>.** <li>
f0b0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 [SQLITE_OPEN_REA
f0c0: 44 4f 4e 4c 59 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 DONLY].** <li>
f0d0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 [SQLITE_OPEN_REA
f0e0: 44 57 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 DWRITE].** <li>
f0f0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 [SQLITE_OPEN_RE
f100: 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 ADWRITE] | [SQLI
f110: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 0a TE_OPEN_CREATE].
f120: 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 54 ** </ol>.**.** T
f130: 68 65 20 66 69 72 73 74 20 76 61 6c 75 65 20 6f he first value o
f140: 70 65 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 pens the databas
f150: 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 49 66 e read-only. If
f160: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f the database do
f170: 65 73 0a 2a 2a 20 6e 6f 74 20 70 72 65 76 69 6f es.** not previo
f180: 75 73 6c 79 20 65 78 69 73 74 2c 20 61 6e 20 65 usly exist, an e
f190: 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 rror is returned
f1a0: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 6f 70 . The second op
f1b0: 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 74 68 tion opens.** th
f1c0: 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 e database for r
f1d0: 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 eading and writi
f1e0: 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 ng if possible,
f1f0: 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 20 or reading only
f200: 69 66 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 6c if.** if the fil
f210: 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 e is write prote
f220: 63 74 65 64 2e 20 20 49 6e 20 65 69 74 68 65 72 cted. In either
f230: 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61 case the databa
f240: 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 0a se must already.
f250: 2a 2a 20 65 78 69 73 74 20 6f 72 20 61 6e 20 65 ** exist or an e
f260: 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 rror is returned
f270: 2e 20 20 54 68 65 20 74 68 69 72 64 20 6f 70 74 . The third opt
f280: 69 6f 6e 20 6f 70 65 6e 73 20 74 68 65 20 64 61 ion opens the da
f290: 74 61 62 61 73 65 0a 2a 2a 20 66 6f 72 20 72 65 tabase.** for re
f2a0: 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e ading and writin
f2b0: 67 20 61 6e 64 20 63 72 65 61 74 65 73 20 69 74 g and creates it
f2c0: 20 69 66 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 if it does not
f2d0: 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 0a 2a already exist..*
f2e0: 2a 20 54 68 65 20 74 68 69 72 64 20 6f 70 74 69 * The third opti
f2f0: 6f 6e 73 20 69 73 20 62 65 68 61 76 69 6f 72 20 ons is behavior
f300: 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 that is always u
f310: 73 65 64 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 sed for [sqlite3
f320: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 _open()].** and
f330: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 [sqlite3_open16(
f340: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 )]..**.** If the
f350: 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d filename is ":m
f360: 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e emory:", then an
f370: 20 70 72 69 76 61 74 65 0a 2a 2a 20 69 6e 2d 6d private.** in-m
f380: 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 69 emory database i
f390: 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 s created for th
f3a0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 e connection. T
f3b0: 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a his in-memory.**
f3c0: 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 database will v
f3d0: 61 6e 69 73 68 20 77 68 65 6e 20 74 68 65 20 64 anish when the d
f3e0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
f3f0: 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 on is closed. F
f400: 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e uture.** version
f410: 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 of SQLite might
f420: 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 make use of add
f430: 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 itional special
f440: 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 74 68 61 filenames.** tha
f450: 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 t begin with the
f460: 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 20 ":" character.
f470: 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 It is recommend
f480: 65 64 20 74 68 61 74 20 0a 2a 2a 20 77 68 65 6e ed that .** when
f490: 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 a database file
f4a0: 6e 61 6d 65 20 72 65 61 6c 6c 79 20 64 6f 65 73 name really does
f4b0: 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 22 begin with.** "
f4c0: 3a 22 20 74 68 61 74 20 79 6f 75 20 70 72 65 66 :" that you pref
f4d0: 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 ix the filename
f4e0: 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 with a pathname
f4f0: 6c 69 6b 65 20 22 2e 2f 22 20 74 6f 0a 2a 2a 20 like "./" to.**
f500: 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e avoid ambiguity.
f510: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 .**.** If the fi
f520: 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 lename is an emp
f530: 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 ty string, then
f540: 61 20 70 72 69 76 61 74 65 20 74 65 6d 70 6f 72 a private tempor
f550: 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 ary.** on-disk d
f560: 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 atabase will be
f570: 63 72 65 61 74 65 64 2e 20 20 54 68 69 73 20 70 created. This p
f580: 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20 rivate database
f590: 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d will be.** autom
f5a0: 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 atically deleted
f5b0: 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 as soon as the
f5c0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
f5d0: 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a ion is closed..*
f5e0: 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 *.** The fourth
f5f0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
f600: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 ite3_open_v2() i
f610: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
f620: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 e.** [sqlite3_vf
f630: 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 s] object that d
f640: 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 efines the opera
f650: 74 69 6e 67 20 73 79 73 74 65 6d 20 0a 2a 2a 20 ting system .**
f660: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74 interface that t
f670: 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 he new database
f680: 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c connection shoul
f690: 64 20 75 73 65 2e 20 20 49 66 20 74 68 65 0a 2a d use. If the.*
f6a0: 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 * fourth paramet
f6b0: 65 72 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 er is a NULL poi
f6c0: 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 nter then the de
f6d0: 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 fault [sqlite3_v
f6e0: 66 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 73 fs].** object is
f6f0: 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e used..**.** <b>
f700: 4e 6f 74 65 20 74 6f 20 77 69 6e 64 6f 77 73 20 Note to windows
f710: 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 users:</b> The
f720: 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f encoding used fo
f730: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 r the filename a
f740: 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 5b 73 rgument.** of [s
f750: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 qlite3_open()] a
f760: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e nd [sqlite3_open
f770: 5f 76 32 28 29 5d 20 6d 75 73 74 20 62 65 20 55 _v2()] must be U
f780: 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 TF-8, not whatev
f790: 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 er.** codepage i
f7a0: 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 s currently defi
f7b0: 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 ned. Filenames
f7c0: 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 containing inter
f7d0: 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 national.** char
f7e0: 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 acters must be c
f7f0: 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d onverted to UTF-
f800: 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 8 prior to passi
f810: 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 ng them into.**
f820: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
f830: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 or [sqlite3_ope
f840: 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 n_v2()]..*/.int
f850: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 sqlite3_open(.
f860: 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 const char *file
f870: 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 name, /* Datab
f880: 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 ase filename (UT
f890: 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 F-8) */. sqlite
f8a0: 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 3 **ppDb
f8b0: 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 /* OUT: SQLite
f8c0: 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b db handle */.);
f8d0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 .int sqlite3_ope
f8e0: 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 n16(. const voi
f8f0: 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f d *filename, /
f900: 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e * Database filen
f910: 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a ame (UTF-16) */.
f920: 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 sqlite3 **ppDb
f930: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 /* OUT
f940: 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 : SQLite db hand
f950: 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c le */.);.int sql
f960: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 ite3_open_v2(.
f970: 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 const char *file
f980: 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 name, /* Datab
f990: 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 ase filename (UT
f9a0: 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 F-8) */. sqlite
f9b0: 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 3 **ppDb,
f9c0: 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 /* OUT: SQLite
f9d0: 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 db handle */.
f9e0: 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 int flags,
f9f0: 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 /* Flags
fa00: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
fa10: 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a *zVfs /*
fa20: 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 Name of VFS mod
fa30: 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b ule to use */.);
fa40: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
fa50: 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e : Error Codes An
fa60: 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a d Messages.**.**
fa70: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 The sqlite3_err
fa80: 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 code() interface
fa90: 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
faa0: 65 72 69 63 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f eric.** [SQLITE_
fab0: 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 OK | result code
fac0: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 ] or [SQLITE_IOE
fad0: 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 RR_READ | extend
fae0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a ed result code].
faf0: 2a 2a 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 ** for the most
fb00: 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 recent failed sq
fb10: 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c lite3_* API call
fb20: 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 associated.** w
fb30: 69 74 68 20 5b 73 71 6c 69 74 65 33 5d 20 68 61 ith [sqlite3] ha
fb40: 6e 64 6c 65 20 27 64 62 27 2e 20 20 49 66 20 61 ndle 'db'. If a
fb50: 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 prior API call
fb60: 66 61 69 6c 65 64 20 62 75 74 20 74 68 65 0a 2a failed but the.*
fb70: 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 * most recent AP
fb80: 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 I call succeeded
fb90: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c , the return val
fba0: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ue from sqlite3_
fbb0: 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 73 20 errcode().** is
fbc0: 75 6e 64 65 66 69 6e 65 64 2e 20 0a 2a 2a 0a 2a undefined. .**.*
fbd0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 * The sqlite3_er
fbe0: 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 rmsg() and sqlit
fbf0: 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 e3_errmsg16() re
fc00: 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e turn English-lan
fc10: 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 guage.** text th
fc20: 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 at describes the
fc30: 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 error, as eithe
fc40: 72 20 55 54 46 38 20 6f 72 20 55 54 46 31 36 20 r UTF8 or UTF16
fc50: 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a respectively..**
fc60: 20 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 Memory to hold
fc70: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 the error messag
fc80: 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 e string is mana
fc90: 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 20 ged internally.
fca0: 20 54 68 65 20 0a 2a 2a 20 73 74 72 69 6e 67 20 The .** string
fcb0: 6d 61 79 20 62 65 20 6f 76 65 72 77 72 69 74 74 may be overwritt
fcc0: 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 en or deallocate
fcd0: 64 20 62 79 20 73 75 62 73 65 71 75 65 6e 74 20 d by subsequent
fce0: 63 61 6c 6c 73 20 74 6f 20 53 51 4c 69 74 65 0a calls to SQLite.
fcf0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e ** interface fun
fd00: 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 43 61 ctions..**.** Ca
fd10: 6c 6c 73 20 74 6f 20 6d 61 6e 79 20 73 71 6c 69 lls to many sqli
fd20: 74 65 33 5f 2a 20 66 75 6e 63 74 69 6f 6e 73 20 te3_* functions
fd30: 73 65 74 20 74 68 65 20 65 72 72 6f 72 20 63 6f set the error co
fd40: 64 65 20 61 6e 64 20 73 74 72 69 6e 67 20 72 65 de and string re
fd50: 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 turned.** by [sq
fd60: 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d lite3_errcode()]
fd70: 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 , [sqlite3_errms
fd80: 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 g()], and [sqlit
fd90: 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a e3_errmsg16()].*
fda0: 2a 20 28 6f 76 65 72 77 72 69 74 69 6e 67 20 74 * (overwriting t
fdb0: 68 65 20 70 72 65 76 69 6f 75 73 20 76 61 6c 75 he previous valu
fdc0: 65 73 29 2e 20 4e 6f 74 65 20 74 68 61 74 20 63 es). Note that c
fdd0: 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
fde0: 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 _errcode()],.**
fdf0: 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 [sqlite3_errmsg(
fe00: 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 )], and [sqlite3
fe10: 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 74 68 65 _errmsg16()] the
fe20: 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 mselves do not a
fe30: 66 66 65 63 74 20 74 68 65 0a 2a 2a 20 72 65 73 ffect the.** res
fe40: 75 6c 74 73 20 6f 66 20 66 75 74 75 72 65 20 69 ults of future i
fe50: 6e 76 6f 63 61 74 69 6f 6e 73 2e 20 20 43 61 6c nvocations. Cal
fe60: 6c 73 20 74 6f 20 41 50 49 20 72 6f 75 74 69 6e ls to API routin
fe70: 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 72 es that do not r
fe80: 65 74 75 72 6e 0a 2a 2a 20 61 6e 20 65 72 72 6f eturn.** an erro
fe90: 72 20 63 6f 64 65 20 28 65 78 61 6d 70 6c 65 3a r code (example:
fea0: 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 [sqlite3_data_c
feb0: 6f 75 6e 74 28 29 5d 29 20 64 6f 20 6e 6f 74 0a ount()]) do not.
fec0: 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 65 72 ** change the er
fed0: 72 6f 72 20 63 6f 64 65 20 72 65 74 75 72 6e 65 ror code returne
fee0: 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e d by this routin
fef0: 65 2e 20 20 49 6e 74 65 72 66 61 63 65 73 20 74 e. Interfaces t
ff00: 68 61 74 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 61 hat are.** not a
ff10: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 ssociated with a
ff20: 20 73 70 65 63 69 66 69 63 20 64 61 74 61 62 61 specific databa
ff30: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 28 65 se connection (e
ff40: 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20 5b 73 71 6c xamples:.** [sql
ff50: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 ite3_mprintf()]
ff60: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 or [sqlite3_enab
ff70: 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 le_shared_cache(
ff80: 29 5d 20 64 6f 20 6e 6f 74 20 63 68 61 6e 67 65 )] do not change
ff90: 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 63 .** the return c
ffa0: 6f 64 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 41 73 73 ode. .**.** Ass
ffb0: 75 6d 69 6e 67 20 6e 6f 20 6f 74 68 65 72 20 69 uming no other i
ffc0: 6e 74 65 72 76 65 6e 69 6e 67 20 73 71 6c 69 74 ntervening sqlit
ffd0: 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 73 20 61 e3_* API calls a
ffe0: 72 65 20 6d 61 64 65 2c 20 74 68 65 20 65 72 72 re made, the err
fff0: 6f 72 0a 2a 2a 20 63 6f 64 65 20 72 65 74 75 72 or.** code retur
10000 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 ned by this func
10010 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74 tion is associat
10020 65 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 ed with the same
10030 20 65 72 72 6f 72 20 61 73 0a 2a 2a 20 74 68 65 error as.** the
10040 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 strings returne
10050 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 d by [sqlite3_er
10060 72 6d 73 67 28 29 5d 20 61 6e 64 20 5b 73 71 6c rmsg()] and [sql
10070 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d ite3_errmsg16()]
10080 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
10090 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 _errcode(sqlite3
100a0 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 *db);.const cha
100b0 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 r *sqlite3_errms
100c0 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e g(sqlite3*);.con
100d0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
100e0 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 _errmsg16(sqlite
100f0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 3*);../*.** CAPI
10100 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 3REF: SQL Statem
10110 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a ent Object.**.**
10120 20 49 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 Instance of thi
10130 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 s object represe
10140 6e 74 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 nt single SQL st
10150 61 74 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 0a atements. This.
10160 2a 2a 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 ** is variously
10170 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 known as a "prep
10180 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 ared statement"
10190 6f 72 20 61 20 0a 2a 2a 20 22 63 6f 6d 70 69 6c or a .** "compil
101a0 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ed SQL statement
101b0 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 " or simply as a
101c0 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a "statement"..**
101d0 20 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 .** The life of
101e0 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a a statement obj
101f0 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 ect goes somethi
10200 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a ng like this:.**
10210 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ol>.** <li>
10220 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 Create the obje
10230 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ct using [sqlite
10240 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
10250 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 or a related.**
10260 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a function..*
10270 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 * <li> Bind valu
10280 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d es to host param
10290 65 74 65 72 73 20 75 73 69 6e 67 0a 2a 2a 20 20 eters using.**
102a0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e [sqlite3_bin
102b0 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 d_blob | sqlite3
102c0 5f 62 69 6e 64 5f 2a 20 69 6e 74 65 72 66 61 63 _bind_* interfac
102d0 65 73 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e es]..** <li> Run
102e0 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c the SQL by call
102f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 ing [sqlite3_ste
10300 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 p()] one or more
10310 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 times..** <li>
10320 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d Reset the statem
10330 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ent using [sqlit
10340 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e e3_reset()] then
10350 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 go back.**
10360 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 to step 2. Do
10370 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 this zero or mor
10380 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e e times..** <li>
10390 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a Destroy the obj
103a0 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ect using [sqlit
103b0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a e3_finalize()]..
103c0 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 ** </ol>.**.** R
103d0 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 efer to document
103e0 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 ation on individ
103f0 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 ual methods abov
10400 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c e for additional
10410 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e .** information.
10420 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
10430 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 ct sqlite3_stmt
10440 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f sqlite3_stmt;../
10450 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
10460 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 ompiling An SQL
10470 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 Statement.**.**
10480 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 To execute an SQ
10490 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 L query, it must
104a0 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c first be compil
104b0 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 ed into a byte-c
104c0 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 ode.** program u
104d0 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 sing one of thes
104e0 65 20 72 6f 75 74 69 6e 65 73 2e 20 0a 2a 2a 0a e routines. .**.
104f0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 ** The first arg
10500 75 6d 65 6e 74 20 22 64 62 22 20 69 73 20 61 6e ument "db" is an
10510 20 5b 73 71 6c 69 74 65 33 20 7c 20 53 51 4c 69 [sqlite3 | SQLi
10520 74 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 te database hand
10530 6c 65 5d 20 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 le] .** obtained
10540 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 20 63 61 from a prior ca
10550 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f ll to [sqlite3_o
10560 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 pen()], [sqlite3
10570 5f 6f 70 65 6e 5f 76 32 28 29 5d 0a 2a 2a 20 6f _open_v2()].** o
10580 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 r [sqlite3_open1
10590 36 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6()]..** The sec
105a0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 22 7a 53 ond argument "zS
105b0 71 6c 22 20 69 73 20 74 68 65 20 73 74 61 74 65 ql" is the state
105c0 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 ment to be compi
105d0 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 led, encoded.**
105e0 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 as either UTF-8
105f0 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 or UTF-16. The
10600 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
10610 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 ) and sqlite3_pr
10620 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e epare_v2().** in
10630 74 65 72 66 61 63 65 73 20 75 73 65 73 20 55 54 terfaces uses UT
10640 46 2d 38 20 61 6e 64 20 73 71 6c 69 74 65 33 5f F-8 and sqlite3_
10650 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 prepare16() and
10660 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
10670 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 6_v2().** use UT
10680 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 F-16..**.** If t
10690 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e he nByte argumen
106a0 74 20 69 73 20 6c 65 73 73 0a 2a 2a 20 74 68 61 t is less.** tha
106b0 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 n zero, then zSq
106c0 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 l is read up to
106d0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 the first zero t
106e0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 49 66 0a 2a erminator. If.*
106f0 2a 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e * nByte is non-n
10700 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 egative, then it
10710 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 is the maximum
10720 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 62 79 number of .** by
10730 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 tes read from zS
10740 71 6c 2e 20 20 57 68 65 6e 20 6e 42 79 74 65 20 ql. When nByte
10750 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c is non-negative,
10760 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 the.** zSql str
10770 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 ing ends at eith
10780 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 er the first '\0
10790 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 00' character or
107a0 20 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20 6e .** until the n
107b0 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 Byte-th byte, wh
107c0 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 ichever comes fi
107d0 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61 rst..**.** *pzTa
107e0 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f il is made to po
107f0 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 int to the first
10800 20 62 79 74 65 20 70 61 73 74 20 74 68 65 20 65 byte past the e
10810 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 0a nd of the first.
10820 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
10830 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 69 73 20 in zSql. This
10840 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6d routine only com
10850 70 69 6c 65 73 20 74 68 65 20 66 69 72 73 74 20 piles the first
10860 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 69 6e 20 statement.** in
10870 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c zSql, so *pzTail
10880 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e is left pointin
10890 67 20 74 6f 20 77 68 61 74 20 72 65 6d 61 69 6e g to what remain
108a0 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a s uncompiled..**
108b0 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69 73 20 6c .** *ppStmt is l
108c0 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 eft pointing to
108d0 61 20 63 6f 6d 70 69 6c 65 64 20 0a 2a 2a 20 5b a compiled .** [
108e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 53 sqlite3_stmt | S
108f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 73 74 72 QL statement str
10900 75 63 74 75 72 65 5d 20 74 68 61 74 20 63 61 6e ucture] that can
10910 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 be.** executed
10920 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 using [sqlite3_s
10930 74 65 70 28 29 5d 2e 20 20 4f 72 20 69 66 20 74 tep()]. Or if t
10940 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 here is an error
10950 2c 20 2a 70 70 53 74 6d 74 20 6d 61 79 20 62 65 , *ppStmt may be
10960 0a 2a 2a 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e .** set to NULL.
10970 20 20 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 If the input t
10980 65 78 74 20 63 6f 6e 74 61 69 6e 65 64 20 6e 6f ext contained no
10990 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 SQL (if the inp
109a0 75 74 20 69 73 20 61 6e 64 0a 2a 2a 20 65 6d 70 ut is and.** emp
109b0 74 79 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 ty string or a c
109c0 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 omment) then *pp
109d0 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e Stmt is set to N
109e0 55 4c 4c 2e 20 20 54 68 65 20 63 61 6c 6c 69 6e ULL. The callin
109f0 67 0a 2a 2a 20 70 72 6f 63 65 64 75 72 65 20 69 g.** procedure i
10a00 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f s responsible fo
10a10 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 r deleting the c
10a20 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 ompiled SQL stat
10a30 65 6d 65 6e 74 0a 2a 2a 20 75 73 69 6e 67 20 5b ement.** using [
10a40 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
10a50 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 ()] after it has
10a60 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 finished with i
10a70 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 t..**.** On succ
10a80 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d ess, [SQLITE_OK]
10a90 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f is returned. O
10aa0 74 68 65 72 77 69 73 65 20 61 6e 20 0a 2a 2a 20 therwise an .**
10ab0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 [SQLITE_ERROR |
10ac0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 error code] is r
10ad0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 eturned..**.** T
10ae0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 he sqlite3_prepa
10af0 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 re_v2() and sqli
10b00 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
10b10 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 () interfaces ar
10b20 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 e.** recommended
10b30 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f for all new pro
10b40 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f grams. The two o
10b50 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 lder interfaces
10b60 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 are retained.**
10b70 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f for backwards co
10b80 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 mpatibility, but
10b90 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 their use is di
10ba0 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 49 6e scouraged..** In
10bb0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 the "v2" interf
10bc0 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 aces, the prepar
10bd0 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 ed statement.**
10be0 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 that is returned
10bf0 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 (the [sqlite3_s
10c00 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e tmt] object) con
10c10 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 tains a copy of
10c20 74 68 65 20 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c the .** original
10c30 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 SQL text. This
10c40 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 causes the [sqli
10c50 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 te3_step()] inte
10c60 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 rface to.** beha
10c70 76 65 20 61 20 64 69 66 66 65 72 65 6e 74 6c 79 ve a differently
10c80 20 69 6e 20 74 77 6f 20 77 61 79 73 3a 0a 2a 2a in two ways:.**
10c90 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ol>.** <li>
10ca0 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 .** If the datab
10cb0 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 ase schema chang
10cc0 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 es, instead of r
10cd0 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 eturning [SQLITE
10ce0 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a _SCHEMA] as it.*
10cf0 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f * always used to
10d00 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 do, [sqlite3_st
10d10 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d ep()] will autom
10d20 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 atically recompi
10d30 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 le the SQL.** st
10d40 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 atement and try
10d50 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e to run it again.
10d60 20 20 49 66 20 74 68 65 20 73 63 68 65 6d 61 20 If the schema
10d70 68 61 73 20 63 68 61 6e 67 65 64 20 69 6e 20 61 has changed in a
10d80 20 77 61 79 0a 2a 2a 20 74 68 61 74 20 6d 61 6b way.** that mak
10d90 65 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 es the statement
10da0 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 no longer valid
10db0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 , [sqlite3_step(
10dc0 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a )] will still.**
10dd0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
10de0 53 43 48 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e SCHEMA]. But un
10df0 6c 69 6b 65 20 74 68 65 20 6c 65 67 61 63 79 20 like the legacy
10e00 62 65 68 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54 behavior, [SQLIT
10e10 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 E_SCHEMA] is.**
10e20 6e 6f 77 20 61 20 66 61 74 61 6c 20 65 72 72 6f now a fatal erro
10e30 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c r. Calling [sql
10e40 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
10e50 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f )] again will no
10e60 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 t make the.** er
10e70 72 6f 72 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f ror go away. No
10e80 74 65 3a 20 75 73 65 20 5b 73 71 6c 69 74 65 33 te: use [sqlite3
10e90 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 _errmsg()] to fi
10ea0 6e 64 20 74 68 65 20 74 65 78 74 20 6f 66 20 74 nd the text of t
10eb0 68 65 20 70 61 72 73 69 6e 67 0a 2a 2a 20 65 72 he parsing.** er
10ec0 72 6f 72 20 74 68 61 74 20 72 65 73 75 6c 74 73 ror that results
10ed0 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 in an [SQLITE_S
10ee0 43 48 45 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a CHEMA] return..*
10ef0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c * </li>.**.** <l
10f00 69 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e 20 65 72 i>.** When an er
10f10 72 6f 72 20 6f 63 63 75 72 73 2c 20 0a 2a 2a 20 ror occurs, .**
10f20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
10f30 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 will return one
10f40 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 of the detailed
10f50 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 .** [SQLITE_ERR
10f60 4f 52 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 OR | result code
10f70 73 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 s] or.** [SQLITE
10f80 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 _IOERR_READ | ex
10f90 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
10fa0 64 65 73 5d 20 73 75 63 68 20 61 73 20 64 69 72 des] such as dir
10fb0 65 63 74 6c 79 2e 0a 2a 2a 20 54 68 65 20 6c 65 ectly..** The le
10fc0 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 gacy behavior wa
10fd0 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f s that [sqlite3_
10fe0 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e step()] would on
10ff0 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 ly return a gene
11000 72 69 63 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 ric.** [SQLITE_E
11010 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 RROR] result cod
11020 65 20 61 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20 e and you would
11030 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 have to make a s
11040 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 0a 2a 2a econd call to.**
11050 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
11060 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 )] in order to f
11070 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 ind the underlyi
11080 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 ng cause of the
11090 70 72 6f 62 6c 65 6d 2e 0a 2a 2a 20 57 69 74 68 problem..** With
110a0 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 the "v2" prepar
110b0 65 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 e interfaces, th
110c0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 e underlying rea
110d0 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f son for the erro
110e0 72 20 69 73 0a 2a 2a 20 72 65 74 75 72 6e 65 64 r is.** returned
110f0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a immediately..**
11100 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a </li>.** </ol>.
11110 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 */.int sqlite3_p
11120 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 repare(. sqlite
11130 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
11140 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 /* Database ha
11150 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
11160 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 char *zSql,
11170 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 /* SQL stateme
11180 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 nt, UTF-8 encode
11190 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 d */. int nByte
111a0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
111b0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 * Maximum length
111c0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 of zSql in byte
111d0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f s. */. sqlite3_
111e0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 stmt **ppStmt,
111f0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e /* OUT: Statemen
11200 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f t handle */. co
11210 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 nst char **pzTai
11220 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f l /* OUT: Po
11230 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 inter to unused
11240 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 portion of zSql
11250 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 */.);.int sqlite
11260 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 3_prepare_v2(.
11270 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
11280 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 /* Datab
11290 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ase handle */.
112a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c const char *zSql
112b0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 , /* SQL s
112c0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 tatement, UTF-8
112d0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 encoded */. int
112e0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 nByte,
112f0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 /* Maximum
11300 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 length of zSql i
11310 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 n bytes. */. sq
11320 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 lite3_stmt **ppS
11330 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 tmt, /* OUT: St
11340 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a atement handle *
11350 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
11360 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f *pzTail /* O
11370 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 UT: Pointer to u
11380 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 nused portion of
11390 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 zSql */.);.int
113a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
113b0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 6(. sqlite3 *db
113c0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 , /*
113d0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 Database handle
113e0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
113f0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 *zSql, /*
11400 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 SQL statement, U
11410 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f TF-16 encoded */
11420 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 . int nByte,
11430 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 /* Ma
11440 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
11450 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a zSql in bytes. *
11460 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
11470 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
11480 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
11490 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
114a0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 void **pzTail
114b0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
114c0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
114d0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
114e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 ;.int sqlite3_pr
114f0 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 epare16_v2(. sq
11500 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
11510 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 /* Databas
11520 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f e handle */. co
11530 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 nst void *zSql,
11540 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 /* SQL sta
11550 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 tement, UTF-16 e
11560 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 ncoded */. int
11570 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 nByte,
11580 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c /* Maximum l
11590 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e ength of zSql in
115a0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c bytes. */. sql
115b0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 ite3_stmt **ppSt
115c0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 mt, /* OUT: Sta
115d0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f tement handle */
115e0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a . const void **
115f0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 pzTail /* OU
11600 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e T: Pointer to un
11610 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 used portion of
11620 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a zSql */.);../*.*
11630 2a 20 52 65 74 72 69 65 76 65 20 74 68 65 20 6f * Retrieve the o
11640 72 69 67 69 6e 61 6c 20 53 51 4c 20 73 74 61 74 riginal SQL stat
11650 65 6d 65 6e 74 20 61 73 73 6f 63 69 61 74 65 64 ement associated
11660 20 77 69 74 68 20 61 20 63 6f 6d 70 69 6c 65 64 with a compiled
11670 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 69 6e statement.** in
11680 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2e UTF-8 encoding.
11690 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 63 6f .**.** If the co
116a0 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 mpiled SQL state
116b0 6d 65 6e 74 20 70 61 73 73 65 64 20 61 73 20 61 ment passed as a
116c0 6e 20 61 72 67 75 6d 65 6e 74 20 77 61 73 20 63 n argument was c
116d0 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 0a 2a 2a ompiled using.**
116e0 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f either sqlite3_
116f0 70 72 65 70 61 72 65 5f 76 32 20 6f 72 20 73 71 prepare_v2 or sq
11700 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
11710 76 32 2c 20 74 68 65 6e 20 74 68 69 73 20 66 75 v2, then this fu
11720 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65 74 75 72 6e nction.** return
11730 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
11740 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 20 nul-terminated
11750 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e string containin
11760 67 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 g a copy of.** t
11770 68 65 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 he original SQL
11780 73 74 61 74 65 6d 65 6e 74 2e 20 54 68 65 20 70 statement. The p
11790 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 ointer is valid
117a0 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d until the statem
117b0 65 6e 74 0a 2a 2a 20 69 73 20 64 65 6c 65 74 65 ent.** is delete
117c0 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f d using sqlite3_
117d0 66 69 6e 61 6c 69 7a 65 28 29 2e 0a 2a 2a 0a 2a finalize()..**.*
117e0 2a 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 * If the stateme
117f0 6e 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 nt was compiled
11800 75 73 69 6e 67 20 65 69 74 68 65 72 20 6f 66 20 using either of
11810 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 the legacy inter
11820 66 61 63 65 73 20 0a 2a 2a 20 73 71 6c 69 74 65 faces .** sqlite
11830 33 5f 70 72 65 70 61 72 65 28 29 20 6f 72 20 73 3_prepare() or s
11840 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
11850 28 29 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f (), this functio
11860 6e 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a n returns NULL..
11870 2a 2a 20 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 ** .****** EXPER
11880 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 IMENTAL - subjec
11890 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 t to change with
118a0 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a out notice *****
118b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 63 6f 6e *********.*/.con
118c0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
118d0 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d _sql(sqlite3_stm
118e0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
118f0 2a 20 43 41 50 49 33 52 45 46 3a 20 20 44 79 6e * CAPI3REF: Dyn
11900 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 amically Typed V
11910 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a alue Object.**.*
11920 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 * SQLite uses dy
11930 6e 61 6d 69 63 20 74 79 70 69 6e 67 20 66 6f 72 namic typing for
11940 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 the values it s
11950 74 6f 72 65 73 2e 20 20 56 61 6c 75 65 73 20 63 tores. Values c
11960 61 6e 20 0a 2a 2a 20 62 65 20 69 6e 74 65 67 65 an .** be intege
11970 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 rs, floating poi
11980 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e nt values, strin
11990 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 gs, BLOBs, or NU
119a0 4c 4c 2e 20 20 57 68 65 6e 0a 2a 2a 20 70 61 73 LL. When.** pas
119b0 73 69 6e 67 20 61 72 6f 75 6e 64 20 76 61 6c 75 sing around valu
119c0 65 73 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 65 es internally, e
119d0 61 63 68 20 76 61 6c 75 65 20 69 73 20 72 65 70 ach value is rep
119e0 72 65 73 65 6e 74 65 64 20 61 73 0a 2a 2a 20 61 resented as.** a
119f0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
11a00 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 e sqlite3_value
11a10 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 object..*/.typed
11a20 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 ef struct Mem sq
11a30 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a lite3_value;../*
11a40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 53 .** CAPI3REF: S
11a50 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 QL Function Cont
11a60 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a ext Object.**.**
11a70 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 The context in
11a80 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e which an SQL fun
11a90 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 ction executes i
11aa0 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a s stored in an.*
11ab0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 * sqlite3_contex
11ac0 74 20 6f 62 6a 65 63 74 2e 20 20 41 20 70 6f 69 t object. A poi
11ad0 6e 74 65 72 20 74 6f 20 73 75 63 68 20 61 6e 20 nter to such an
11ae0 6f 62 6a 65 63 74 20 69 73 20 74 68 65 0a 2a 2a object is the.**
11af0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
11b00 20 74 6f 20 75 73 65 72 2d 64 65 66 69 6e 65 64 to user-defined
11b10 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 0a SQL functions..
11b20 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
11b30 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t sqlite3_contex
11b40 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t sqlite3_contex
11b50 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 t;../*.** CAPI3R
11b60 45 46 3a 20 20 42 69 6e 64 69 6e 67 20 56 61 6c EF: Binding Val
11b70 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 ues To Prepared
11b80 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 0a 2a 2a Statements.**.**
11b90 20 49 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69 In the SQL stri
11ba0 6e 67 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 ngs input to [sq
11bb0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
11bc0 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 ()] and its vari
11bd0 61 6e 74 73 2c 0a 2a 2a 20 6f 6e 65 20 6f 72 20 ants,.** one or
11be0 6d 6f 72 65 20 6c 69 74 65 72 61 6c 73 20 63 61 more literals ca
11bf0 6e 20 62 65 20 72 65 70 6c 61 63 65 20 62 79 20 n be replace by
11c00 61 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 6f a parameter in o
11c10 6e 65 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 66 ne of these.** f
11c20 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e orms:.**.** <ul>
11c30 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c .** <li> ?.** <
11c40 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 li> ?NNN.** <li
11c50 3e 20 20 3a 41 41 41 0a 2a 2a 20 3c 6c 69 3e 20 > :AAA.** <li>
11c60 20 40 41 41 41 0a 2a 2a 20 3c 6c 69 3e 20 20 24 @AAA.** <li> $
11c70 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a VVV.** </ul>.**.
11c80 2a 2a 20 49 6e 20 74 68 65 20 70 61 72 61 6d 65 ** In the parame
11c90 74 65 72 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20 ter forms shown
11ca0 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20 above NNN is an
11cb0 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c integer literal,
11cc0 0a 2a 2a 20 41 41 41 20 69 73 20 61 6e 20 61 6c .** AAA is an al
11cd0 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 phanumeric ident
11ce0 69 66 69 65 72 20 61 6e 64 20 56 56 56 20 69 73 ifier and VVV is
11cf0 20 61 20 76 61 72 69 61 62 6c 65 20 6e 61 6d 65 a variable name
11d00 20 61 63 63 6f 72 64 69 6e 67 0a 2a 2a 20 74 6f according.** to
11d10 20 74 68 65 20 73 79 6e 74 61 78 20 72 75 6c 65 the syntax rule
11d20 73 20 6f 66 20 74 68 65 20 54 43 4c 20 70 72 6f s of the TCL pro
11d30 67 72 61 6d 6d 69 6e 67 20 6c 61 6e 67 75 61 67 gramming languag
11d40 65 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 73 e..** The values
11d50 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 of these parame
11d60 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 ters (also calle
11d70 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 d "host paramete
11d80 72 20 6e 61 6d 65 73 22 29 0a 2a 2a 20 63 61 6e r names").** can
11d90 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 be set using th
11da0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
11db0 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 () routines defi
11dc0 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 ned here..**.**
11dd0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
11de0 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 nt to the sqlite
11df0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 3_bind_*() routi
11e00 6e 65 73 20 61 6c 77 61 79 73 20 69 73 20 61 20 nes always is a
11e10 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 pointer.** to th
11e20 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d e [sqlite3_stmt]
11e30 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 object returned
11e40 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 from [sqlite3_p
11e50 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a repare_v2()] or.
11e60 2a 2a 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e ** its variants.
11e70 20 20 54 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 The second.**
11e80 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 argument is the
11e90 69 6e 64 65 78 20 6f 66 20 74 68 65 20 70 61 72 index of the par
11ea0 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 ameter to be set
11eb0 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 . The first par
11ec0 61 6d 65 74 65 72 20 68 61 73 0a 2a 2a 20 61 6e ameter has.** an
11ed0 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 57 68 65 index of 1. Whe
11ee0 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 n the same named
11ef0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 parameter is us
11f00 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 ed more than onc
11f10 65 2c 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 6e 64 e, second.** and
11f20 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f subsequent.** o
11f30 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 ccurrences have
11f40 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 the same index a
11f50 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 s the first occu
11f60 72 72 65 6e 63 65 2e 20 20 54 68 65 20 69 6e 64 rrence. The ind
11f70 65 78 20 66 6f 72 0a 2a 2a 20 6e 61 6d 65 64 20 ex for.** named
11f80 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 parameters can b
11f90 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e e looked up usin
11fa0 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 g the.** [sqlite
11fb0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
11fc0 5f 6e 61 6d 65 28 29 5d 20 41 50 49 20 69 66 20 _name()] API if
11fd0 64 65 73 69 72 65 64 2e 20 20 54 68 65 20 69 6e desired. The in
11fe0 64 65 78 20 66 6f 72 20 22 3f 4e 4e 4e 22 0a 2a dex for "?NNN".*
11ff0 2a 20 70 61 72 61 6d 65 74 65 73 20 69 73 20 74 * parametes is t
12000 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e he value of NNN.
12010 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75 .** The NNN valu
12020 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 e must be betwee
12030 6e 20 31 20 61 6e 64 20 74 68 65 20 63 6f 6d 70 n 1 and the comp
12040 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 70 61 72 61 ile-time.** para
12050 6d 65 74 65 72 20 53 51 4c 49 54 45 5f 4d 41 58 meter SQLITE_MAX
12060 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 _VARIABLE_NUMBER
12070 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a (default value:
12080 20 39 39 39 29 2e 0a 2a 2a 20 53 65 65 20 3c 61 999)..** See <a
12090 20 68 72 65 66 3d 22 6c 69 6d 69 74 73 2e 68 74 href="limits.ht
120a0 6d 6c 22 3e 6c 69 6d 69 74 73 2e 68 74 6d 6c 3c ml">limits.html<
120b0 2f 61 3e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e /a> for addition
120c0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a al information..
120d0 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 **.** The third
120e0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 argument is the
120f0 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f value to bind to
12100 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a the parameter..
12110 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 0a 2a **.** In those.*
12120 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 * routines that
12130 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 have a fourth ar
12140 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 gument, its valu
12150 65 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 e is the number
12160 6f 66 20 62 79 74 65 73 0a 2a 2a 20 69 6e 20 74 of bytes.** in t
12170 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 he parameter. T
12180 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 o be clear: the
12190 76 61 6c 75 65 20 69 73 20 74 68 65 20 6e 75 6d value is the num
121a0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 ber of bytes in
121b0 74 68 65 0a 2a 2a 20 73 74 72 69 6e 67 2c 20 6e the.** string, n
121c0 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ot the number of
121d0 20 63 68 61 72 61 63 74 65 72 73 2e 20 20 54 68 characters. Th
121e0 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 e number.** of b
121f0 79 74 65 73 20 64 6f 65 73 20 6e 6f 74 20 69 6e ytes does not in
12200 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 2d 74 clude the zero-t
12210 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 erminator at the
12220 20 65 6e 64 20 6f 66 20 73 74 72 69 6e 67 73 2e end of strings.
12230 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 .** If the fourt
12240 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e h parameter is n
12250 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e egative, the len
12260 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e gth of the strin
12270 67 20 69 73 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f g is.** number o
12280 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 f bytes up to th
12290 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 e first zero ter
122a0 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 minator..**.** T
122b0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e he fifth argumen
122c0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e t to sqlite3_bin
122d0 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 d_blob(), sqlite
122e0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 3_bind_text(), a
122f0 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 nd.** sqlite3_bi
12300 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 nd_text16() is a
12310 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 destructor used
12320 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 to dispose of t
12330 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 74 65 he BLOB or.** te
12340 78 74 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 xt after SQLite
12350 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 has finished wit
12360 68 20 69 74 2e 20 20 49 66 20 74 68 65 20 66 69 h it. If the fi
12370 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 20 fth argument is
12380 74 68 65 0a 2a 2a 20 73 70 65 63 69 61 6c 20 76 the.** special v
12390 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 alue [SQLITE_STA
123a0 54 49 43 5d 2c 20 74 68 65 6e 20 74 68 65 20 6c TIC], then the l
123b0 69 62 72 61 72 79 20 61 73 73 75 6d 65 73 20 74 ibrary assumes t
123c0 68 61 74 20 74 68 65 20 69 6e 66 6f 72 6d 61 74 hat the informat
123d0 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 20 73 74 61 ion.** is in sta
123e0 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 tic, unmanaged s
123f0 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f pace and does no
12400 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 t need to be fre
12410 65 64 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 66 ed. If the.** f
12420 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 ifth argument ha
12430 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c s the value [SQL
12440 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 ITE_TRANSIENT],
12450 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 then SQLite make
12460 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 70 72 69 s its.** own pri
12470 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 vate copy of the
12480 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c data immediatel
12490 79 2c 20 62 65 66 6f 72 65 20 74 68 65 20 73 71 y, before the sq
124a0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a lite3_bind_*().*
124b0 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e * routine return
124c0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c s..**.** The sql
124d0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c ite3_bind_zerobl
124e0 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e ob() routine bin
124f0 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e ds a BLOB of len
12500 67 74 68 20 6e 20 74 68 61 74 0a 2a 2a 20 69 73 gth n that.** is
12510 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 filled with zer
12520 6f 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f 62 20 os. A zeroblob
12530 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f uses a fixed amo
12540 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a unt of memory.**
12550 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 (just an intege
12560 72 20 74 6f 20 68 6f 6c 64 20 69 74 20 73 69 7a r to hold it siz
12570 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 e) while it is b
12580 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a eing processed..
12590 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 ** Zeroblobs are
125a0 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 intended to ser
125b0 76 65 20 61 73 20 70 6c 61 63 65 2d 68 6f 6c 64 ve as place-hold
125c0 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 ers for BLOBs wh
125d0 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 ose.** content i
125e0 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 s later written
125f0 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 using .** [sqlit
12600 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 e3_blob_open | i
12610 6e 63 72 65 6d 65 6e 74 20 42 4c 4f 42 20 49 2f ncrement BLOB I/
12620 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 20 20 41 20 O] routines. A
12630 6e 65 67 61 74 69 76 65 0a 2a 2a 20 76 61 6c 75 negative.** valu
12640 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c e for the zerobl
12650 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 ob results in a
12660 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 zero-length BLOB
12670 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
12680 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
12690 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 tines must be ca
126a0 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73 lled after.** [s
126b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
126c0 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20 76 61 2()] (and its va
126d0 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69 riants) or [sqli
126e0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 6e 64 te3_reset()] and
126f0 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 .** before [sqli
12700 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 te3_step()]..**
12710 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 Bindings are not
12720 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 cleared by the
12730 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
12740 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e ] routine..** Un
12750 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 bound parameters
12760 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 are interpreted
12770 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 as NULL..**.**
12780 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
12790 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b eturn [SQLITE_OK
127a0 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 ] on success or
127b0 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66 an error code if
127c0 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 .** anything goe
127d0 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54 s wrong. [SQLIT
127e0 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 E_RANGE] is retu
127f0 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 rned if the para
12800 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 meter.** index i
12810 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 s out of range.
12820 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 [SQLITE_NOMEM]
12830 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d is returned if m
12840 61 6c 6c 6f 63 20 66 61 69 6c 73 2e 0a 2a 2a 20 alloc fails..**
12850 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 [SQLITE_MISUSE]
12860 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 is returned if t
12870 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
12880 65 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 76 69 e called on a vi
12890 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 rtual.** machine
128a0 20 74 68 61 74 20 69 73 20 74 68 65 20 77 72 6f that is the wro
128b0 6e 67 20 73 74 61 74 65 20 6f 72 20 77 68 69 63 ng state or whic
128c0 68 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65 h has already be
128d0 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2f en finalized..*/
128e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
128f0 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 d_blob(sqlite3_s
12900 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
12910 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 void*, int n, v
12920 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
12930 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
12940 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f _double(sqlite3_
12950 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 stmt*, int, doub
12960 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 le);.int sqlite3
12970 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 _bind_int(sqlite
12980 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 3_stmt*, int, in
12990 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f t);.int sqlite3_
129a0 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 bind_int64(sqlit
129b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 e3_stmt*, int, s
129c0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 qlite3_int64);.i
129d0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
129e0 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d null(sqlite3_stm
129f0 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 t*, int);.int sq
12a00 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 lite3_bind_text(
12a10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
12a20 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c nt, const char*,
12a30 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 int n, void(*)(
12a40 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c void*));.int sql
12a50 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 ite3_bind_text16
12a60 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
12a70 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a int, const void*
12a80 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 , int, void(*)(v
12a90 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 oid*));.int sqli
12aa0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 te3_bind_value(s
12ab0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
12ac0 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 t, const sqlite3
12ad0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 _value*);.int sq
12ae0 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 lite3_bind_zerob
12af0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lob(sqlite3_stmt
12b00 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a *, int, int n);.
12b10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
12b20 20 4e 75 6d 62 65 72 20 4f 66 20 48 6f 73 74 20 Number Of Host
12b30 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a Parameters.**.**
12b40 20 52 65 74 75 72 6e 20 74 68 65 20 6c 61 72 67 Return the larg
12b50 65 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 est host paramet
12b60 65 72 20 69 6e 64 65 78 20 69 6e 20 74 68 65 20 er index in the
12b70 70 72 65 63 6f 6d 70 69 6c 65 64 20 73 74 61 74 precompiled stat
12b80 65 6d 65 6e 74 20 67 69 76 65 6e 0a 2a 2a 20 61 ement given.** a
12b90 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 2e 20 s the argument.
12ba0 20 57 68 65 6e 20 74 68 65 20 68 6f 73 74 20 70 When the host p
12bb0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 6f 66 arameters are of
12bc0 20 74 68 65 20 66 6f 72 6d 73 20 6c 69 6b 65 20 the forms like
12bd0 22 3a 41 41 41 22 0a 2a 2a 20 6f 72 20 22 3f 22 ":AAA".** or "?"
12be0 2c 20 74 68 65 6e 20 74 68 65 79 20 61 72 65 20 , then they are
12bf0 61 73 73 69 67 6e 65 64 20 73 65 71 75 65 6e 74 assigned sequent
12c00 69 61 6c 20 69 6e 63 72 65 61 73 69 6e 67 20 6e ial increasing n
12c10 75 6d 62 65 72 73 20 62 65 67 69 6e 6e 69 6e 67 umbers beginning
12c20 0a 2a 2a 20 77 69 74 68 20 6f 6e 65 2c 20 73 6f .** with one, so
12c30 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
12c40 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 ned is the numbe
12c50 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 2e r of parameters.
12c60 20 20 48 6f 77 65 76 65 72 0a 2a 2a 20 69 66 20 However.** if
12c70 74 68 65 20 73 61 6d 65 20 68 6f 73 74 20 70 61 the same host pa
12c80 72 61 6d 65 74 65 72 20 6e 61 6d 65 20 69 73 20 rameter name is
12c90 75 73 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 used multiple ti
12ca0 6d 65 73 2c 20 65 61 63 68 20 6f 63 63 75 72 72 mes, each occurr
12cb0 61 6e 63 65 0a 2a 2a 20 69 73 20 67 69 76 65 6e ance.** is given
12cc0 20 74 68 65 20 73 61 6d 65 20 6e 75 6d 62 65 72 the same number
12cd0 2c 20 73 6f 20 74 68 65 20 76 61 6c 75 65 20 72 , so the value r
12ce0 65 74 75 72 6e 65 64 20 69 6e 20 74 68 61 74 20 eturned in that
12cf0 63 61 73 65 20 69 73 20 74 68 65 20 6e 75 6d 62 case is the numb
12d00 65 72 0a 2a 2a 20 6f 66 20 75 6e 69 71 75 65 20 er.** of unique
12d10 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e host parameter n
12d20 61 6d 65 73 2e 20 20 49 66 20 68 6f 73 74 20 70 ames. If host p
12d30 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 arameters of the
12d40 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 0a 2a 2a 20 form "?NNN".**
12d50 61 72 65 20 75 73 65 64 20 28 77 68 65 72 65 20 are used (where
12d60 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65 NNN is an intege
12d70 72 29 20 74 68 65 6e 20 74 68 65 72 65 20 6d 69 r) then there mi
12d80 67 68 74 20 62 65 20 67 61 70 73 20 69 6e 20 74 ght be gaps in t
12d90 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 69 6e 67 20 he.** numbering
12da0 61 6e 64 20 74 68 65 20 76 61 6c 75 65 20 72 65 and the value re
12db0 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 69 turned by this i
12dc0 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 nterface is the
12dd0 69 6e 64 65 78 20 6f 66 20 74 68 65 0a 2a 2a 20 index of the.**
12de0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 77 host parameter w
12df0 69 74 68 20 74 68 65 20 6c 61 72 67 65 73 74 20 ith the largest
12e00 69 6e 64 65 78 20 76 61 6c 75 65 2e 0a 2a 2a 0a index value..**.
12e10 2a 2a 20 54 68 65 20 70 72 65 70 61 72 65 64 20 ** The prepared
12e20 73 74 61 74 65 6d 65 6e 74 20 6d 75 73 74 20 6e statement must n
12e30 6f 74 20 62 65 20 5b 73 71 6c 69 74 65 33 5f 66 ot be [sqlite3_f
12e40 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 inalize | finali
12e50 7a 65 64 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f zed].** prior to
12e60 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 this routine re
12e70 74 75 72 6e 6e 69 6e 67 2e 20 20 4f 74 68 65 72 turnning. Other
12e80 77 69 73 65 20 74 68 65 20 72 65 73 75 6c 74 73 wise the results
12e90 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 0a 2a are undefined.*
12ea0 2a 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 * and probably u
12eb0 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 69 ndesirable..*/.i
12ec0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
12ed0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 parameter_count(
12ee0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a sqlite3_stmt*);.
12ef0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
12f00 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 Name Of A Host
12f10 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 Parameter.**.**
12f20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 This routine ret
12f30 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
12f40 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 o the name of th
12f50 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 e n-th parameter
12f60 20 69 6e 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 in a .** [sqlit
12f70 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 e3_stmt | prepar
12f80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a ed statement]..*
12f90 2a 20 48 6f 73 74 20 70 61 72 61 6d 65 74 65 72 * Host parameter
12fa0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3a s of the form ":
12fb0 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f AAA" or "@AAA" o
12fc0 72 20 22 24 56 56 56 22 20 68 61 76 65 20 61 20 r "$VVV" have a
12fd0 6e 61 6d 65 0a 2a 2a 20 77 68 69 63 68 20 69 73 name.** which is
12fe0 20 74 68 65 20 73 74 72 69 6e 67 20 22 3a 41 41 the string ":AA
12ff0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 A" or "@AAA" or
13000 22 24 56 56 56 22 2e 20 20 0a 2a 2a 20 49 6e 20 "$VVV". .** In
13010 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 other words, the
13020 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 initial ":" or
13030 22 24 22 20 6f 72 20 22 40 22 0a 2a 2a 20 69 73 "$" or "@".** is
13040 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 included as par
13050 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a t of the name..*
13060 2a 20 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 * Parameters of
13070 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 6f 72 20 the form "?" or
13080 22 3f 4e 4e 4e 22 20 68 61 76 65 20 6e 6f 20 6e "?NNN" have no n
13090 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 ame..**.** The f
130a0 69 72 73 74 20 62 6f 75 6e 64 20 70 61 72 61 6d irst bound param
130b0 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 eter has an inde
130c0 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a x of 1, not 0..*
130d0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76 61 6c 75 *.** If the valu
130e0 65 20 6e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 e n is out of ra
130f0 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 6e 2d nge or if the n-
13100 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 th parameter is
13110 6e 61 6d 65 6c 65 73 73 2c 0a 2a 2a 20 74 68 65 nameless,.** the
13120 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e n NULL is return
13130 65 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 ed. The returne
13140 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 d string is alwa
13150 79 73 20 69 6e 20 74 68 65 0a 2a 2a 20 55 54 46 ys in the.** UTF
13160 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e -8 encoding even
13170 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 if the named pa
13180 72 61 6d 65 74 65 72 20 77 61 73 20 6f 72 69 67 rameter was orig
13190 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 inally specified
131a0 0a 2a 2a 20 61 73 20 55 54 46 2d 31 36 20 69 6e .** as UTF-16 in
131b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
131c0 65 31 36 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 e16()] or [sqlit
131d0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
131e0 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 )]..*/.const cha
131f0 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f r *sqlite3_bind_
13200 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 parameter_name(s
13210 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
13220 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
13230 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 REF: Index Of A
13240 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 Parameter With A
13250 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a Given Name.**.*
13260 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 * This routine r
13270 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 eturns the index
13280 20 6f 66 20 61 20 68 6f 73 74 20 70 61 72 61 6d of a host param
13290 65 74 65 72 20 77 69 74 68 20 74 68 65 20 67 69 eter with the gi
132a0 76 65 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 ven name..** The
132b0 20 6e 61 6d 65 20 6d 75 73 74 20 6d 61 74 63 68 name must match
132c0 20 65 78 61 63 74 6c 79 2e 20 20 49 66 20 6e 6f exactly. If no
132d0 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 parameter with
132e0 74 68 65 20 67 69 76 65 6e 20 6e 61 6d 65 20 69 the given name i
132f0 73 20 0a 2a 2a 20 66 6f 75 6e 64 2c 20 72 65 74 s .** found, ret
13300 75 72 6e 20 30 2e 20 20 50 61 72 61 6d 65 74 65 urn 0. Paramete
13310 72 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20 r names must be
13320 55 54 46 38 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c UTF8..*/.int sql
13330 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
13340 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 ter_index(sqlite
13350 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 3_stmt*, const c
13360 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a har *zName);../*
13370 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
13380 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 set All Bindings
13390 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 On A Prepared S
133a0 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 43 tatement.**.** C
133b0 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 ontrary to the i
133c0 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 ntuition of many
133d0 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 , [sqlite3_reset
133e0 28 29 5d 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 ()] does not.**
133f0 72 65 73 65 74 20 74 68 65 20 5b 73 71 6c 69 74 reset the [sqlit
13400 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 e3_bind_blob | b
13410 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 0a 2a indings] on a .*
13420 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 * [sqlite3_stmt
13430 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 | prepared state
13440 6d 65 6e 74 5d 2e 20 20 55 73 65 20 74 68 69 73 ment]. Use this
13450 20 72 6f 75 74 69 6e 65 20 74 6f 0a 2a 2a 20 72 routine to.** r
13460 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 eset all host pa
13470 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c rameters to NULL
13480 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
13490 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 _clear_bindings(
134a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a sqlite3_stmt*);.
134b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
134c0 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d Number Of Colum
134d0 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 ns In A Result S
134e0 65 74 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 et.**.** Return
134f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f the number of co
13500 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 lumns in the res
13510 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 ult set returned
13520 20 62 79 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c by the .** [sql
13530 69 74 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 ite3_stmt | comp
13540 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 iled SQL stateme
13550 6e 74 5d 2e 20 54 68 69 73 20 72 6f 75 74 69 6e nt]. This routin
13560 65 20 72 65 74 75 72 6e 73 20 30 0a 2a 2a 20 69 e returns 0.** i
13570 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 f pStmt is an SQ
13580 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 L statement that
13590 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e does not return
135a0 20 64 61 74 61 20 28 66 6f 72 20 0a 2a 2a 20 65 data (for .** e
135b0 78 61 6d 70 6c 65 20 61 6e 20 55 50 44 41 54 45 xample an UPDATE
135c0 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 )..*/.int sqlite
135d0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 3_column_count(s
135e0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
135f0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
13600 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 3REF: Column Nam
13610 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 es In A Result S
13620 65 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 et.**.** These r
13630 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 outines return t
13640 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 he name assigned
13650 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 to a particular
13660 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 column.** in th
13670 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 e result set of
13680 61 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 a SELECT stateme
13690 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 nt. The sqlite3
136a0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a _column_name().*
136b0 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 * interface retu
136c0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
136d0 20 61 20 55 54 46 38 20 73 74 72 69 6e 67 20 61 a UTF8 string a
136e0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
136f0 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a 2a 20 72 65 n_name16().** re
13700 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
13710 74 6f 20 61 20 55 54 46 31 36 20 73 74 72 69 6e to a UTF16 strin
13720 67 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 g. The first pa
13730 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a rameter is the.*
13740 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 * [sqlite3_stmt
13750 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 | prepared state
13760 6d 65 6e 74 5d 20 74 68 61 74 20 69 6d 70 6c 65 ment] that imple
13770 6d 65 6e 74 73 20 74 68 65 20 53 45 4c 45 43 54 ments the SELECT
13780 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 statement..** T
13790 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
137a0 74 65 72 20 69 73 20 74 68 65 20 63 6f 6c 75 6d ter is the colum
137b0 6e 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 6c n number. The l
137c0 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 eft-most column
137d0 69 73 0a 2a 2a 20 6e 75 6d 62 65 72 20 30 2e 0a is.** number 0..
137e0 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e **.** The return
137f0 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 ed string pointe
13800 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c r is valid until
13810 20 65 69 74 68 65 72 20 74 68 65 20 0a 2a 2a 20 either the .**
13820 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 [sqlite3_stmt |
13830 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
13840 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 nt] is destroyed
13850 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e by [sqlite3_fin
13860 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 6f 72 20 75 alize()].** or u
13870 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 ntil the next ca
13880 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ll sqlite3_colum
13890 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 n_name() or sqli
138a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 te3_column_name1
138b0 36 28 29 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6().** on the sa
138c0 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a me column..**.**
138d0 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c If sqlite3_mall
138e0 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e oc() fails durin
138f0 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 g the processing
13900 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 of either routi
13910 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 ne.** (for examp
13920 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 le during a conv
13930 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d ersion from UTF-
13940 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 8 to UTF-16) the
13950 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e n a.** NULL poin
13960 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e ter is returned.
13970 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a .*/.const char *
13980 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e sqlite3_column_n
13990 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ame(sqlite3_stmt
139a0 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 *, int N);.const
139b0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 void *sqlite3_c
139c0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c olumn_name16(sql
139d0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
139e0 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 N);../*.** CAPI3
139f0 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 REF: Source Of D
13a00 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 ata In A Query R
13a10 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 esult.**.** Thes
13a20 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 e routines provi
13a30 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 de a means to de
13a40 74 65 72 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c termine what col
13a50 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74 umn of what.** t
13a60 61 62 6c 65 20 69 6e 20 77 68 69 63 68 20 64 61 able in which da
13a70 74 61 62 61 73 65 20 61 20 72 65 73 75 6c 74 20 tabase a result
13a80 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74 61 74 of a SELECT stat
13a90 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d ement comes from
13aa0 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 ..** The name of
13ab0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 the database or
13ac0 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e table or column
13ad0 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 can be returned
13ae0 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 as.** either a
13af0 55 54 46 38 20 6f 72 20 55 54 46 31 36 20 73 74 UTF8 or UTF16 st
13b00 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 74 61 ring. The _data
13b10 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 base_ routines r
13b20 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 eturn.** the dat
13b30 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 abase name, the
13b40 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 _table_ routines
13b50 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c return the tabl
13b60 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 e name, and.** t
13b70 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 he origin_ routi
13b80 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 nes return the c
13b90 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 olumn name..** T
13ba0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 he returned stri
13bb0 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 ng is valid unti
13bc0 6c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 l.** the [sqlite
13bd0 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 3_stmt | prepare
13be0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 d statement] is
13bf0 64 65 73 74 72 6f 79 65 64 20 75 73 69 6e 67 0a destroyed using.
13c00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ** [sqlite3_fina
13c10 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c lize()] or until
13c20 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d the same inform
13c30 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 ation is request
13c40 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 ed.** again in a
13c50 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 different encod
13c60 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e ing..**.** The n
13c70 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 ames returned ar
13c80 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 e the original u
13c90 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 n-aliased names
13ca0 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 of the.** databa
13cb0 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 se, table, and c
13cc0 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 olumn..**.** The
13cd0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
13ce0 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 to the following
13cf0 20 63 61 6c 6c 73 20 69 73 20 61 20 0a 2a 2a 20 calls is a .**
13d00 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 [sqlite3_stmt |
13d10 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 compiled SQL sta
13d20 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 tement]..** Thes
13d30 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 e functions retu
13d40 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 rn information a
13d50 62 6f 75 74 20 74 68 65 20 4e 74 68 20 63 6f 6c bout the Nth col
13d60 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 umn returned by
13d70 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e .** the statemen
13d80 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 t, where N is th
13d90 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f e second functio
13da0 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a n argument..**.*
13db0 2a 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c * If the Nth col
13dc0 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 umn returned by
13dd0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 the statement is
13de0 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a an expression.*
13df0 2a 20 6f 72 20 73 75 62 71 75 65 72 79 20 61 6e * or subquery an
13e00 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d d is not a colum
13e10 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c n value, then al
13e20 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 l of these funct
13e30 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20 4e ions.** return N
13e40 55 4c 4c 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 ULL. Otherwise,
13e50 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 they return the
13e60 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 .** name of the
13e70 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 attached databas
13e80 65 2c 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c e, table and col
13e90 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 umn that query r
13ea0 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 esult.** column
13eb0 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 was extracted fr
13ec0 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 om..**.** As wit
13ed0 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 h all other SQLi
13ee0 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 70 te APIs, those p
13ef0 6f 73 74 66 69 78 65 64 20 77 69 74 68 20 22 31 ostfixed with "1
13f00 36 22 20 72 65 74 75 72 6e 20 55 54 46 2d 31 36 6" return UTF-16
13f10 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 73 74 72 69 .** encoded stri
13f20 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72 20 66 ngs, the other f
13f30 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 unctions return
13f40 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 UTF-8..**.** The
13f50 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 se APIs are only
13f60 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 available if th
13f70 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f e library was co
13f80 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 mpiled with the
13f90 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c .** SQLITE_ENABL
13fa0 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 E_COLUMN_METADAT
13fb0 41 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 A preprocessor s
13fc0 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a ymbol defined..*
13fd0 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d *.** If two or m
13fe0 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c ore threads call
13ff0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 one or more of
14000 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 these routines a
14010 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a gainst the same.
14020 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 ** prepared stat
14030 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e ement and column
14040 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d at the same tim
14050 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c e then the resul
14060 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 ts are.** undefi
14070 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 ned..*/.const ch
14080 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ar *sqlite3_colu
14090 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 mn_database_name
140a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
140b0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 nt);.const void
140c0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
140d0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 database_name16(
140e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
140f0 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a t);.const char *
14100 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
14110 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 able_name(sqlite
14120 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 3_stmt*,int);.co
14130 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
14140 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 3_column_table_n
14150 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ame16(sqlite3_st
14160 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 mt*,int);.const
14170 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
14180 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 lumn_origin_name
14190 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
141a0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 nt);.const void
141b0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
141c0 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 origin_name16(sq
141d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
141e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
141f0 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 F: Declared Data
14200 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 type Of A Query
14210 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 54 68 65 Result.**.** The
14220 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
14230 20 69 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 is a [sqlite3_s
14240 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 tmt | compiled S
14250 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 0a QL statement]. .
14260 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 ** If this state
14270 6d 65 6e 74 20 69 73 20 61 20 53 45 4c 45 43 54 ment is a SELECT
14280 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 statement and t
14290 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 he Nth column of
142a0 20 74 68 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 the .** returne
142b0 64 20 72 65 73 75 6c 74 20 73 65 74 20 20 6f 66 d result set of
142c0 20 74 68 61 74 20 53 45 4c 45 43 54 20 69 73 20 that SELECT is
142d0 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 a table column (
142e0 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 not an.** expres
142f0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 sion or subquery
14300 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 ) then the decla
14310 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 red type of the
14320 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 table.** column
14330 69 73 20 72 65 74 75 72 6e 65 64 2e 20 49 66 20 is returned. If
14340 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f the Nth column o
14350 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 f the result set
14360 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 is an.** expres
14370 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 sion or subquery
14380 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f , then a NULL po
14390 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 inter is returne
143a0 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e d..** The return
143b0 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 ed string is alw
143c0 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 ays UTF-8 encode
143d0 64 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 d. For example,
143e0 69 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 in.** the databa
143f0 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a se schema:.**.**
14400 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 CREATE TABLE t1
14410 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a (c1 VARIANT);.**
14420 0a 2a 2a 20 41 6e 64 20 74 68 65 20 66 6f 6c 6c .** And the foll
14430 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 owing statement
14440 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 compiled:.**.**
14450 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 SELECT c1 + 1, c
14460 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 1 FROM t1;.**.**
14470 20 54 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 Then this routi
14480 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 ne would return
14490 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 the string "VARI
144a0 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 ANT" for the sec
144b0 6f 6e 64 0a 2a 2a 20 72 65 73 75 6c 74 20 63 6f ond.** result co
144c0 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 lumn (i==1), and
144d0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
144e0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 for the first re
144f0 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 28 sult column.** (
14500 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c i==0)..**.** SQL
14510 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 ite uses dynamic
14520 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 run-time typing
14530 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75 . So just becau
14540 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 se a column.** i
14550 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f s declared to co
14560 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c ntain a particul
14570 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 ar type does not
14580 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a mean that the.*
14590 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e * data stored in
145a0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 that column is
145b0 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 of the declared
145c0 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 type. SQLite is
145d0 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 .** strongly typ
145e0 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 ed, but the typi
145f0 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f ng is dynamic no
14600 74 20 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a t static. Type.
14610 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 ** is associated
14620 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c with individual
14630 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 values, not wit
14640 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 h the containers
14650 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 .** used to hold
14660 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a those values..*
14670 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 /.const char *sq
14680 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 lite3_column_dec
14690 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 ltype(sqlite3_st
146a0 6d 74 20 2a 2c 20 69 6e 74 20 69 29 3b 0a 63 6f mt *, int i);.co
146b0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
146c0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 3_column_decltyp
146d0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 e16(sqlite3_stmt
146e0 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 20 0a 2a 2a 20 *,int);../* .**
146f0 43 41 50 49 33 52 45 46 3a 20 20 45 76 61 6c 75 CAPI3REF: Evalu
14700 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 ate An SQL State
14710 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 ment.**.** After
14720 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d an [sqlite3_stm
14730 74 20 7c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e t | SQL statemen
14740 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 t] has been prep
14750 61 72 65 64 20 77 69 74 68 20 61 20 63 61 6c 6c ared with a call
14760 0a 2a 2a 20 74 6f 20 65 69 74 68 65 72 20 5b 73 .** to either [s
14770 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
14780 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 2()] or [sqlite3
14790 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
147a0 20 6f 72 20 74 6f 20 6f 6e 65 20 6f 66 0a 2a 2a or to one of.**
147b0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 the legacy inte
147c0 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f rfaces [sqlite3_
147d0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 prepare()] or [s
147e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
147f0 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 ()],.** then thi
14800 73 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 s function must
14810 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 be called one or
14820 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 more times to e
14830 76 61 6c 75 61 74 65 20 74 68 65 20 0a 2a 2a 20 valuate the .**
14840 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a statement..**.**
14850 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 The details of
14860 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 the behavior of
14870 74 68 69 73 20 73 71 6c 69 74 65 33 5f 73 74 65 this sqlite3_ste
14880 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 p() interface de
14890 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 pend.** on wheth
148a0 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 er the statement
148b0 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 was prepared us
148c0 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 ing the newer "v
148d0 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 2" interface.**
148e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
148f0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 _v2()] and [sqli
14900 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
14910 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 ()] or the older
14920 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 legacy.** inter
14930 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 face [sqlite3_pr
14940 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 epare()] and [sq
14950 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
14960 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 )]. The use of
14970 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 the.** new "v2"
14980 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 interface is rec
14990 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 ommended for new
149a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 applications bu
149b0 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 t the legacy.**
149c0 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 interface will c
149d0 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 ontinue to be su
149e0 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 pported..**.** I
149f0 6e 20 74 68 65 20 6c 61 67 61 63 79 20 69 6e 74 n the lagacy int
14a00 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 erface, the retu
14a10 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 rn value will be
14a20 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f either [SQLITE_
14a30 42 55 53 59 5d 2c 20 0a 2a 2a 20 5b 53 51 4c 49 BUSY], .** [SQLI
14a40 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 TE_DONE], [SQLIT
14a50 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f E_ROW], [SQLITE_
14a60 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 ERROR], or [SQLI
14a70 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 TE_MISUSE]..** W
14a80 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 ith the "v2" int
14a90 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 erface, any of t
14aa0 68 65 20 6f 74 68 65 72 20 5b 53 51 4c 49 54 45 he other [SQLITE
14ab0 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 _OK | result cod
14ac0 65 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 e].** or [SQLITE
14ad0 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 _IOERR_READ | ex
14ae0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
14af0 64 65 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 de] might be ret
14b00 75 72 6e 65 64 20 61 73 0a 2a 2a 20 77 65 6c 6c urned as.** well
14b10 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ..**.** [SQLITE_
14b20 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 BUSY] means that
14b30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e the database en
14b40 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 gine was unable
14b50 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a to acquire the.*
14b60 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 * database locks
14b70 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 it needs to do
14b80 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68 65 its job. If the
14b90 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 statement is a
14ba0 43 4f 4d 4d 49 54 0a 2a 2a 20 6f 72 20 6f 63 63 COMMIT.** or occ
14bb0 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 urs outside of a
14bc0 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 n explicit trans
14bd0 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 action, then you
14be0 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a can retry the.*
14bf0 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 * statement. If
14c00 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
14c10 73 20 6e 6f 74 20 61 20 43 4f 4d 4d 49 54 20 61 s not a COMMIT a
14c20 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e nd occurs within
14c30 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 a.** explicit t
14c40 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 ransaction then
14c50 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 you should rollb
14c60 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 ack the transact
14c70 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f ion before.** co
14c80 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 ntinuing..**.**
14c90 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 [SQLITE_DONE] me
14ca0 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 ans that the sta
14cb0 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 tement has finis
14cc0 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a hed executing.**
14cd0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 successfully.
14ce0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 sqlite3_step() s
14cf0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c hould not be cal
14d00 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 led again on thi
14d10 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 s virtual.** mac
14d20 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 hine without fir
14d30 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 st calling [sqli
14d40 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 te3_reset()] to
14d50 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 reset the virtua
14d60 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 l.** machine bac
14d70 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c k to its initial
14d80 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 state..**.** If
14d90 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
14da0 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 nt being execute
14db0 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 d returns any da
14dc0 74 61 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 53 51 ta, then .** [SQ
14dd0 4c 49 54 45 5f 52 4f 57 5d 20 69 73 20 72 65 74 LITE_ROW] is ret
14de0 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 urned each time
14df0 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 a new row of dat
14e00 61 20 69 73 20 72 65 61 64 79 0a 2a 2a 20 66 6f a is ready.** fo
14e10 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 r processing by
14e20 74 68 65 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 the caller. The
14e30 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 values may be ac
14e40 63 65 73 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 cessed using.**
14e50 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c the [sqlite3_col
14e60 75 6d 6e 5f 69 6e 74 20 7c 20 63 6f 6c 75 6d 6e umn_int | column
14e70 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e access function
14e80 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 s]..** sqlite3_s
14e90 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 tep() is called
14ea0 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 again to retriev
14eb0 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f e the next row o
14ec0 66 20 64 61 74 61 2e 0a 2a 2a 20 0a 2a 2a 20 5b f data..** .** [
14ed0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 SQLITE_ERROR] me
14ee0 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 ans that a run-t
14ef0 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 ime error (such
14f00 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a as a constraint.
14f10 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 ** violation) ha
14f20 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c s occurred. sql
14f30 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 ite3_step() shou
14f40 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 ld not be called
14f50 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 again on.** the
14f60 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d VM. More inform
14f70 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 ation may be fou
14f80 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 nd by calling [s
14f90 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d qlite3_errmsg()]
14fa0 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 6c 65 ..** With the le
14fb0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 gacy interface,
14fc0 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 a more specific
14fd0 65 72 72 6f 72 20 63 6f 64 65 20 28 65 78 61 6d error code (exam
14fe0 70 6c 65 3a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ple:.** [SQLITE_
14ff0 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c INTERRUPT], [SQL
15000 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 ITE_SCHEMA], [SQ
15010 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 LITE_CORRUPT], a
15020 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 nd so forth).**
15030 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 can be obtained
15040 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 by calling [sqli
15050 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 te3_reset()] on
15060 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
15070 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20 stmt | prepared
15080 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 statement]. In
15090 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
150a0 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 ce,.** the more
150b0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 specific error c
150c0 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 ode is returned
150d0 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 directly by sqli
150e0 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a te3_step()..**.*
150f0 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 * [SQLITE_MISUSE
15100 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 ] means that the
15110 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 this routine wa
15120 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f s called inappro
15130 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 priately..** Per
15140 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c haps it was call
15150 65 64 20 6f 6e 20 61 20 5b 73 71 6c 69 74 65 33 ed on a [sqlite3
15160 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 _stmt | prepared
15170 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 statement] that
15180 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 has.** already
15190 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 been [sqlite3_fi
151a0 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a nalize | finaliz
151b0 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 ed] or on one th
151c0 61 74 20 68 61 64 20 0a 2a 2a 20 70 72 65 76 69 at had .** previ
151d0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b ously returned [
151e0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 SQLITE_ERROR] or
151f0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 [SQLITE_DONE].
15200 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 Or it could.**
15210 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 be the case that
15220 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
15230 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
15240 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 being used by t
15250 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 wo or.** more th
15260 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d reads at the sam
15270 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 e moment in time
15280 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 ..**.** <b>Goofy
15290 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 Interface Alert
152a0 3a 3c 2f 62 3e 0a 2a 2a 20 49 6e 20 74 68 65 20 :</b>.** In the
152b0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 legacy interface
152c0 2c 20 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 , .** the sqlite
152d0 33 5f 73 74 65 70 28 29 20 41 50 49 20 61 6c 77 3_step() API alw
152e0 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 ays returns a ge
152f0 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 neric error code
15300 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 ,.** [SQLITE_ERR
15310 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 OR], following a
15320 6e 79 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 ny error other t
15330 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 han [SQLITE_BUSY
15340 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45 ].** and [SQLITE
15350 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d _MISUSE]. You m
15360 75 73 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 ust call [sqlite
15370 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 3_reset()] or.**
15380 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
15390 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 ze()] in order t
153a0 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 o find one of th
153b0 65 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 5b 53 e specific.** [S
153c0 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72 65 QLITE_ERROR | re
153d0 73 75 6c 74 20 63 6f 64 65 73 5d 20 74 68 61 74 sult codes] that
153e0 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 better describe
153f0 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 s the error..**
15400 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 We admit that th
15410 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 is is a goofy de
15420 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c sign. The probl
15430 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 em has been fixe
15440 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 d.** with the "v
15450 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 2" interface. I
15460 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c f you prepare al
15470 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 l of your SQL st
15480 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e atements.** usin
15490 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 g either [sqlite
154a0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
154b0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 or [sqlite3_prep
154c0 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 are16_v2()] inst
154d0 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 ead.** of the le
154e0 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 gacy [sqlite3_pr
154f0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 epare()] and [sq
15500 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
15510 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 0a 2a 2a )], then the .**
15520 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b more specific [
15530 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72 SQLITE_ERROR | r
15540 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 esult codes] are
15550 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 returned direct
15560 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 ly.** by sqlite3
15570 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 _step(). The us
15580 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e e of the "v2" in
15590 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d terface is recom
155a0 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 mended..*/.int s
155b0 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 qlite3_step(sqli
155c0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a te3_stmt*);../*.
155d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 0a 2a 2a 0a ** CAPI3REF:.**.
155e0 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75 ** Return the nu
155f0 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73 20 69 mber of values i
15600 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f n the current ro
15610 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 w of the result
15620 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 set..**.** After
15630 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 a call to [sqli
15640 74 65 33 5f 73 74 65 70 28 29 5d 20 74 68 61 74 te3_step()] that
15650 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
15660 5f 52 4f 57 5d 2c 20 74 68 69 73 20 72 6f 75 74 _ROW], this rout
15670 69 6e 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 ine.** will retu
15680 72 6e 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 rn the same valu
15690 65 20 61 73 20 74 68 65 20 5b 73 71 6c 69 74 65 e as the [sqlite
156a0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 3_column_count()
156b0 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 41 ] function..** A
156c0 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 fter [sqlite3_st
156d0 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e ep()] has return
156e0 65 64 20 61 6e 20 5b 53 51 4c 49 54 45 5f 44 4f ed an [SQLITE_DO
156f0 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 NE], [SQLITE_BUS
15700 59 5d 2c 20 6f 72 0a 2a 2a 20 61 20 5b 53 51 4c Y], or.** a [SQL
15710 49 54 45 5f 45 52 52 4f 52 20 7c 20 65 72 72 6f ITE_ERROR | erro
15720 72 20 63 6f 64 65 5d 2c 20 6f 72 20 62 65 66 6f r code], or befo
15730 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 re [sqlite3_step
15740 28 29 5d 20 68 61 73 20 62 65 65 6e 20 0a 2a 2a ()] has been .**
15750 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 5b called on the [
15760 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 sqlite3_stmt | p
15770 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
15780 74 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 t] for the first
15790 20 74 69 6d 65 2c 0a 2a 2a 20 74 68 69 73 20 72 time,.** this r
157a0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a outine returns z
157b0 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ero..*/.int sqli
157c0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 te3_data_count(s
157d0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
157e0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
157f0 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 3REF: Fundamenta
15800 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 0a 2a l Datatypes.**.*
15810 2a 20 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e * Every value in
15820 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 SQLite has one
15830 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e of five fundamen
15840 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a tal datatypes:.*
15850 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
15860 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 > 64-bit signed
15870 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 integer.** <li>
15880 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 64-bit IEEE floa
15890 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 ting point numbe
158a0 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 r.** <li> string
158b0 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a .** <li> BLOB.**
158c0 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f <li> NULL.** </
158d0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ul>.**.** These
158e0 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f constants are co
158f0 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 des for each of
15900 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a those types..**.
15910 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 ** Note that the
15920 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e SQLITE_TEXT con
15930 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 stant was also u
15940 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 sed in SQLite ve
15950 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 rsion 2.** for a
15960 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 completely diff
15970 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 erent meaning.
15980 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 Software that li
15990 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 nks against both
159a0 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 .** SQLite versi
159b0 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 on 2 and SQLite
159c0 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 version 3 should
159d0 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 use SQLITE3_TEX
159e0 54 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f T not.** SQLITE_
159f0 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 TEXT..*/.#define
15a00 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 SQLITE_INTEGER
15a10 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 1.#define SQLIT
15a20 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 E_FLOAT 2.#de
15a30 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 fine SQLITE_BLOB
15a40 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 4.#define S
15a50 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 QLITE_NULL 5
15a60 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 .#ifdef SQLITE_T
15a70 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 EXT.# undef SQLI
15a80 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 TE_TEXT.#else.#
15a90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 define SQLITE_TE
15aa0 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a XT 3.#endif.
15ab0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f #define SQLITE3_
15ac0 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a TEXT 3../*.*
15ad0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 * CAPI3REF: Resu
15ae0 6c 74 73 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 lts Values From
15af0 41 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 54 68 A Query.**.** Th
15b00 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 ese routines ret
15b10 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 urn information
15b20 61 62 6f 75 74 0a 2a 2a 20 61 20 73 69 6e 67 6c about.** a singl
15b30 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 e column of the
15b40 63 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20 72 current result r
15b50 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 ow of a query.
15b60 49 6e 20 65 76 65 72 79 0a 2a 2a 20 63 61 73 65 In every.** case
15b70 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
15b80 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ent is a pointer
15b90 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c to the .** [sql
15ba0 69 74 65 33 5f 73 74 6d 74 20 7c 20 53 51 4c 20 ite3_stmt | SQL
15bb0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 statement] that
15bc0 69 73 20 62 65 69 6e 67 0a 2a 2a 20 65 76 61 6c is being.** eval
15bd0 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 uated (the [sqli
15be0 74 65 33 5f 73 74 6d 74 2a 5d 20 74 68 61 74 20 te3_stmt*] that
15bf0 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f was returned fro
15c00 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 m .** [sqlite3_p
15c10 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
15c20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 one of its varia
15c30 6e 74 73 29 20 61 6e 64 0a 2a 2a 20 74 68 65 20 nts) and.** the
15c40 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
15c50 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 is the index of
15c60 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 the column for w
15c70 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e hich information
15c80 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 .** should be r
15c90 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 6c 65 eturned. The le
15ca0 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f ft-most column o
15cb0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 f the result set
15cc0 0a 2a 2a 20 68 61 73 20 61 6e 20 69 6e 64 65 78 .** has an index
15cd0 20 6f 66 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 of 0..**.** If
15ce0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
15cf0 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 t is not current
15d00 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 ly point to a va
15d10 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 lid row, or if t
15d20 68 65 0a 2a 2a 20 74 68 65 20 63 6f 6c 75 6d 6e he.** the column
15d30 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 index is out of
15d40 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 range, the resu
15d50 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e lt is undefined.
15d60 20 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 .** These routi
15d70 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 nes may only be
15d80 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 called when the
15d90 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c most recent call
15da0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
15db0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 step()] has retu
15dc0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 rned [SQLITE_ROW
15dd0 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a ] and neither.**
15de0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
15df0 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f )] nor [sqlite3_
15e00 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 73 20 finalize()] has
15e10 62 65 65 6e 20 63 61 6c 6c 20 73 75 62 73 65 71 been call subseq
15e20 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e uently..** If an
15e30 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 y of these routi
15e40 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 nes are called a
15e50 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 fter [sqlite3_re
15e60 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 set()] or.** [sq
15e70 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
15e80 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 ] or after [sqli
15e90 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 te3_step()] has
15ea0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 returned.** some
15eb0 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e thing other than
15ec0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 [SQLITE_ROW], t
15ed0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 he results are u
15ee0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 ndefined..** If
15ef0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
15f00 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 or [sqlite3_res
15f10 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 et()] or [sqlite
15f20 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 3_finalize()].**
15f30 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d are called from
15f40 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 a different thr
15f50 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 ead while any of
15f60 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a these routines.
15f70 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 ** are pending,
15f80 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 then the results
15f90 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 20 are undefined.
15fa0 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 .**.** The sqli
15fb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
15fc0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ) routine return
15fd0 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e s .** [SQLITE_IN
15fe0 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 TEGER | datatype
15ff0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 code] for the i
16000 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 nitial data type
16010 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c .** of the resul
16020 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72 t column. The r
16030 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 eturned value is
16040 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f one of [SQLITE_
16050 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 INTEGER],.** [SQ
16060 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 LITE_FLOAT], [SQ
16070 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c LITE_TEXT], [SQL
16080 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 ITE_BLOB], or [S
16090 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 QLITE_NULL]. Th
160a0 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 e value.** retur
160b0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 ned by sqlite3_c
160c0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 olumn_type() is
160d0 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 only meaningful
160e0 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f if no type.** co
160f0 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f nversions have o
16100 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72 ccurred as descr
16110 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 ibed below. Aft
16120 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 er a type conver
16130 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c sion,.** the val
16140 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ue returned by s
16150 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 qlite3_column_ty
16160 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 pe() is undefine
16170 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 d. Future.** ve
16180 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
16190 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 may change the
161a0 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 behavior of sqli
161b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
161c0 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 ).** following a
161d0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e type conversion
161e0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 ..**.** If the r
161f0 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 esult is a BLOB
16200 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 or UTF-8 string
16210 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 then the sqlite3
16220 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 _column_bytes()
16230 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 .** routine retu
16240 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
16250 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 f bytes in that
16260 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a BLOB or string..
16270 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 ** If the result
16280 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 is a UTF-16 str
16290 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 ing, then sqlite
162a0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
162b0 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 converts.** the
162c0 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 string to UTF-8
162d0 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e and then return
162e0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
162f0 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 bytes..** If the
16300 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d result is a num
16310 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 eric value then
16320 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
16330 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b ytes() uses.** [
16340 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
16350 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 ()] to convert t
16360 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 hat value to a U
16370 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 TF-8 string and
16380 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e returns.** the n
16390 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 umber of bytes i
163a0 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a n that string..*
163b0 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 * The value retu
163c0 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e rned does not in
163d0 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 clude the zero t
163e0 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 erminator at the
163f0 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 end.** of the s
16400 74 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72 tring. For clar
16410 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72 ity: the value r
16420 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e eturned is the n
16430 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 umber of.** byte
16440 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c s in the string,
16450 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 not the number
16460 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a of characters..*
16470 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 74 *.** Strings ret
16480 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
16490 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 _column_text() a
164a0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
164b0 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 n_text16(),.** e
164c0 76 65 6e 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 ven zero-length
164d0 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 strings, are alw
164e0 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 ays zero termina
164f0 74 65 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e ted. The return
16500 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 .** value from s
16510 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
16520 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d ob() for a zero-
16530 6c 65 6e 67 74 68 20 62 6c 6f 62 20 69 73 20 61 length blob is a
16540 6e 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 70 n arbitrary.** p
16550 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c 79 ointer, possibly
16560 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 even a NULL poi
16570 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 nter..**.** The
16580 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
16590 79 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e 65 ytes16() routine
165a0 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 is similar to s
165b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
165c0 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 tes().** but lea
165d0 76 65 73 20 74 68 65 20 72 65 73 75 6c 74 20 69 ves the result i
165e0 6e 20 55 54 46 2d 31 36 20 69 6e 73 74 65 61 64 n UTF-16 instead
165f0 20 6f 66 20 55 54 46 2d 38 2e 20 20 0a 2a 2a 20 of UTF-8. .**
16600 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 The zero termina
16610 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 tor is not inclu
16620 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e ded in this coun
16630 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 t..**.** These r
16640 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 outines attempt
16650 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 to convert the v
16660 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f alue where appro
16670 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20 priate. For.**
16680 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 example, if the
16690 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 internal represe
166a0 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 ntation is FLOAT
166b0 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 and a text resu
166c0 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 lt.** is request
166d0 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 ed, [sqlite3_snp
166e0 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 rintf()] is used
166f0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 64 internally to d
16700 6f 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e o the conversion
16710 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c .** automaticall
16720 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e y. The followin
16730 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 g table details
16740 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 the conversions
16750 74 68 61 74 0a 2a 2a 20 61 72 65 20 61 70 70 6c that.** are appl
16760 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 ied:.**.** <bloc
16770 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c kquote>.** <tabl
16780 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a e border="1">.**
16790 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e <tr><th> Intern
167a0 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 al<br>Type <th>
167b0 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 Requested<br>Typ
167c0 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 e <th> Conversi
167d0 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 on.**.** <tr><td
167e0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 > NULL <td>
167f0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 INTEGER <td> R
16800 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 esult is 0.** <t
16810 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 r><td> NULL
16820 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c <td> FLOAT <
16830 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e td> Result is 0.
16840 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 0.** <tr><td> N
16850 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 ULL <td> TE
16860 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c XT <td> Resul
16870 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 t is NULL pointe
16880 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e r.** <tr><td> N
16890 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c ULL <td> BL
168a0 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c OB <td> Resul
168b0 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 t is NULL pointe
168c0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e r.** <tr><td> IN
168d0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f TEGER <td> FLO
168e0 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 AT <td> Conve
168f0 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 rt from integer
16900 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e to float.** <tr>
16910 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 <td> INTEGER <t
16920 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 d> TEXT <td
16930 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e > ASCII renderin
16940 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 g of the integer
16950 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 .** <tr><td> INT
16960 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f EGER <td> BLO
16970 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 B <td> Same a
16980 73 20 66 6f 72 20 49 4e 54 45 47 45 52 2d 3e 54 s for INTEGER->T
16990 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 EXT.** <tr><td>
169a0 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e FLOAT <td> IN
169b0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e TEGER <td> Con
169c0 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 vert from float
169d0 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 to integer.** <t
169e0 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 r><td> FLOAT
169f0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c <td> TEXT <
16a00 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 td> ASCII render
16a10 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 ing of the float
16a20 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c .** <tr><td> FL
16a30 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f OAT <td> BLO
16a40 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 B <td> Same a
16a50 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a s FLOAT->TEXT.**
16a60 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 <tr><td> TEXT
16a70 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 <td> INTEGER
16a80 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 <td> Use atoi(
16a90 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 ).** <tr><td> T
16aa0 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f EXT <td> FLO
16ab0 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 AT <td> Use a
16ac0 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 tof().** <tr><td
16ad0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 > TEXT <td>
16ae0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e BLOB <td> N
16af0 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e o change.** <tr>
16b00 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 <td> BLOB <t
16b10 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 d> INTEGER <td
16b20 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 > Convert to TEX
16b30 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 T then use atoi(
16b40 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 ).** <tr><td> B
16b50 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f LOB <td> FLO
16b60 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 AT <td> Conve
16b70 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 rt to TEXT then
16b80 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 use atof().** <t
16b90 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 r><td> BLOB
16ba0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c <td> TEXT <
16bb0 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 td> Add a zero t
16bc0 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 erminator if nee
16bd0 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a ded.** </table>.
16be0 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e ** </blockquote>
16bf0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 .**.** The table
16c00 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 above makes ref
16c10 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 erence to standa
16c20 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e rd C library fun
16c30 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a ctions atoi().**
16c40 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 and atof(). SQ
16c50 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 Lite does not re
16c60 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 ally use these f
16c70 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 unctions. It ha
16c80 73 20 69 74 73 0a 2a 2a 20 6f 6e 20 65 71 75 61 s its.** on equa
16c90 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 valent internal
16ca0 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 routines. The a
16cb0 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 toi() and atof()
16cc0 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 names are.** us
16cd0 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 ed in the table
16ce0 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 for brevity and
16cf0 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65 because they are
16d00 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 familiar to mos
16d10 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 t.** C programme
16d20 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 rs..**.** Note t
16d30 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f hat when type co
16d40 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c nversions occur,
16d50 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e pointers return
16d60 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 ed by prior.** c
16d70 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
16d80 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 column_blob(), s
16d90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
16da0 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 xt(), and/or.**
16db0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
16dc0 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 ext16() may be i
16dd0 6e 76 61 6c 69 64 61 74 65 64 2e 20 0a 2a 2a 20 nvalidated. .**
16de0 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 Type conversions
16df0 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 and pointer inv
16e00 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 alidations might
16e10 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 occur.** in the
16e20 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 following cases
16e30 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
16e40 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69 <li><p> The ini
16e50 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 tial content is
16e60 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 a BLOB and sqlit
16e70 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
16e80 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 .** or
16e90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
16ea0 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c text16() is call
16eb0 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d ed. A zero-term
16ec0 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 inator might.**
16ed0 20 20 20 20 20 20 20 20 20 6e 65 65 64 20 74 6f need to
16ee0 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 be added to the
16ef0 20 73 74 72 69 6e 67 2e 3c 2f 70 3e 3c 2f 6c 69 string.</p></li
16f00 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 >.**.** <li><p>
16f10 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e The initial con
16f20 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 tent is UTF-8 te
16f30 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 xt and sqlite3_c
16f40 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 olumn_bytes16()
16f50 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 or.** s
16f60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
16f70 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 xt16() is called
16f80 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d . The content m
16f90 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 ust be converted
16fa0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 .** to
16fb0 55 54 46 2d 31 36 2e 3c 2f 70 3e 3c 2f 6c 69 3e UTF-16.</p></li>
16fc0 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 .**.** <li><p>
16fd0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 The initial cont
16fe0 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 ent is UTF-16 te
16ff0 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 xt and sqlite3_c
17000 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 olumn_bytes() or
17010 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 71 6c .** sql
17020 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
17030 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 () is called. T
17040 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 he content must
17050 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 be converted.**
17060 20 20 20 20 20 20 20 20 20 74 6f 20 55 54 46 2d to UTF-
17070 38 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 8.</p></li>.** <
17080 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 /ul>.**.** Conve
17090 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 rsions between U
170a0 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d TF-16be and UTF-
170b0 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 16le are always
170c0 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e done in place an
170d0 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 d do.** not inva
170e0 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 lidate a prior p
170f0 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f ointer, though o
17100 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e f course the con
17110 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 tent of the buff
17120 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 er.** that the p
17130 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 rior pointer poi
17140 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 nts to will have
17150 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 been modified.
17160 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 Other kinds.**
17170 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 of conversion ar
17180 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 e done in place
17190 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 when it is possi
171a0 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d ble, but sometim
171b0 65 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 e it is.** not p
171c0 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 ossible and in t
171d0 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 hose cases prior
171e0 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e pointers are in
171f0 76 61 6c 69 64 61 74 65 64 2e 20 20 0a 2a 2a 0a validated. .**.
17200 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e ** The safest an
17210 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d d easiest to rem
17220 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 ember policy is
17230 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 to invoke these
17240 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f routines.** in o
17250 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 ne of the follow
17260 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 ing ways:.**.**
17270 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 <ul>.** <li>sq
17280 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
17290 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 t() followed by
172a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
172b0 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 ytes()</li>.**
172c0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 <li>sqlite3_colu
172d0 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 mn_blob() follow
172e0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f ed by sqlite3_co
172f0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 lumn_bytes()</li
17300 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 >.** <li>sqlite
17310 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
17320 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 ) followed by sq
17330 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
17340 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 es16()</li>.**
17350 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f </ul>.**.** In o
17360 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 ther words, you
17370 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 should call sqli
17380 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
17390 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ), sqlite3_colum
173a0 6e 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 6f 72 20 n_blob(),.** or
173b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
173c0 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f ext16() first to
173d0 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c force the resul
173e0 74 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 t into the desir
173f0 65 64 0a 2a 2a 20 66 6f 72 6d 61 74 2c 20 74 68 ed.** format, th
17400 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 en invoke sqlite
17410 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
17420 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 or sqlite3_colu
17430 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 0a mn_bytes16() to.
17440 2a 2a 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 ** find the size
17450 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 of the result.
17460 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c Do not mix call
17470 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to sqlite3_colu
17480 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 mn_text() or.**
17490 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
174a0 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 lob() with calls
174b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to sqlite3_colu
174c0 6d 6e 5f 62 79 74 65 73 31 36 28 29 2e 20 20 41 mn_bytes16(). A
174d0 6e 64 20 64 6f 20 6e 6f 74 0a 2a 2a 20 6d 69 78 nd do not.** mix
174e0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 calls to sqlite
174f0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
17500 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 ) with calls to
17510 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
17520 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 ytes()..**.** Th
17530 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 e pointers retur
17540 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e ned are valid un
17550 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 til a type conve
17560 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a rsion occurs as.
17570 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f ** described abo
17580 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 ve, or until [sq
17590 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 lite3_step()] or
175a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
175b0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
175c0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 3_finalize()] is
175d0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65 called. The me
175e0 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 mory space used
175f0 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a to hold strings.
17600 2a 2a 20 61 6e 64 20 62 6c 6f 62 73 20 69 73 20 ** and blobs is
17610 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 freed automatica
17620 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c lly. Do <b>not<
17630 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 /b> pass the poi
17640 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a nters returned.*
17650 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
17660 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 n_blob()], [sqli
17670 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
17680 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 20 0a 2a )], etc. into .*
17690 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 * [sqlite3_free(
176a0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d )]..**.** If a m
176b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
176c0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 error occurs du
176d0 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 ring the evaluat
176e0 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 ion of any.** of
176f0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c these routines,
17700 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 a default value
17710 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 is returned. T
17720 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 he default value
17730 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 .** is either th
17740 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 e integer 0, the
17750 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
17760 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 number 0.0, or a
17770 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 NULL.** pointer
17780 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 . Subsequent ca
17790 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
177a0 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 errcode()] will
177b0 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 return.** [SQLIT
177c0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2f 0a 63 6f 6e E_NOMEM]..*/.con
177d0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
177e0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c _column_blob(sql
177f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
17800 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 iCol);.int sqlit
17810 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
17820 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
17830 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 nt iCol);.int sq
17840 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
17850 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d es16(sqlite3_stm
17860 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 t*, int iCol);.d
17870 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f ouble sqlite3_co
17880 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 lumn_double(sqli
17890 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
178a0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 Col);.int sqlite
178b0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 3_column_int(sql
178c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
178d0 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 iCol);.sqlite3_i
178e0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c nt64 sqlite3_col
178f0 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 umn_int64(sqlite
17900 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
17910 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e l);.const unsign
17920 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 ed char *sqlite3
17930 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c _column_text(sql
17940 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
17950 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 iCol);.const voi
17960 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
17970 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 n_text16(sqlite3
17980 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
17990 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 );.int sqlite3_c
179a0 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 olumn_type(sqlit
179b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
179c0 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c ol);.sqlite3_val
179d0 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ue *sqlite3_colu
179e0 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 mn_value(sqlite3
179f0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
17a00 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
17a10 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 EF: Destroy A Pr
17a20 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
17a30 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 Object.**.** Th
17a40 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 e sqlite3_finali
17a50 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 ze() function is
17a60 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 called to delet
17a70 65 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 e a .** [sqlite3
17a80 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 _stmt | compiled
17a90 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e SQL statement].
17aa0 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e If the statemen
17ab0 74 20 77 61 73 0a 2a 2a 20 65 78 65 63 75 74 65 t was.** execute
17ac0 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 d successfully,
17ad0 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20 or not executed
17ae0 61 74 20 61 6c 6c 2c 20 74 68 65 6e 20 53 51 4c at all, then SQL
17af0 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e ITE_OK is return
17b00 65 64 2e 0a 2a 2a 20 49 66 20 65 78 65 63 75 74 ed..** If execut
17b10 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 ion of the state
17b20 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65 6e ment failed then
17b30 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f an .** [SQLITE_
17b40 45 52 52 4f 52 20 7c 20 65 72 72 6f 72 20 63 6f ERROR | error co
17b50 64 65 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 de] or [SQLITE_I
17b60 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 OERR_READ | exte
17b70 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d nded error code]
17b80 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e .** is returned.
17b90 20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 .**.** This rou
17ba0 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c tine can be call
17bb0 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 ed at any point
17bc0 64 75 72 69 6e 67 20 74 68 65 20 65 78 65 63 75 during the execu
17bd0 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b tion of the.** [
17be0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 76 sqlite3_stmt | v
17bf0 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 5d 2e irtual machine].
17c00 20 20 49 66 20 74 68 65 20 76 69 72 74 75 61 6c If the virtual
17c10 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e 6f 74 machine has not
17c20 20 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 .** completed e
17c30 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 xecution when th
17c40 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 is routine is ca
17c50 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20 6c 69 lled, that is li
17c60 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 ke.** encounteri
17c70 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 ng an error or a
17c80 6e 20 69 6e 74 65 72 72 75 70 74 2e 20 20 28 53 n interrupt. (S
17c90 65 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 ee [sqlite3_inte
17ca0 72 72 75 70 74 28 29 5d 2e 29 20 0a 2a 2a 20 49 rrupt()].) .** I
17cb0 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 65 ncomplete update
17cc0 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 s may be rolled
17cd0 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 back and transac
17ce0 74 69 6f 6e 73 20 63 61 6e 63 65 6c 6c 65 64 2c tions cancelled,
17cf0 20 20 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 .** depending
17d00 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73 74 61 on the circumsta
17d10 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 20 0a 2a nces, and the .*
17d20 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 * [SQLITE_ERROR
17d30 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 72 | result code] r
17d40 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62 65 20 eturned will be
17d50 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a [SQLITE_ABORT]..
17d60 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 */.int sqlite3_f
17d70 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f inalize(sqlite3_
17d80 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f stmt *pStmt);../
17d90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
17da0 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 eset A Prepared
17db0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 Statement Object
17dc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
17dd0 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 e3_reset() funct
17de0 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f ion is called to
17df0 20 72 65 73 65 74 20 61 20 0a 2a 2a 20 5b 73 71 reset a .** [sq
17e00 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d lite3_stmt | com
17e10 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d piled SQL statem
17e20 65 6e 74 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 ent] object..**
17e30 62 61 63 6b 20 74 6f 20 69 74 27 73 20 69 6e 69 back to it's ini
17e40 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 tial state, read
17e50 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 y to be re-execu
17e60 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c 20 ted..** Any SQL
17e70 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 statement variab
17e80 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c les that had val
17e90 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 ues bound to the
17ea0 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b m using.** the [
17eb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
17ec0 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 b | sqlite3_bind
17ed0 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e _*() API] retain
17ee0 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a their values..*
17ef0 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 * Use [sqlite3_c
17f00 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d lear_bindings()]
17f10 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 to reset the bi
17f20 6e 64 69 6e 67 73 2e 0a 2a 2f 0a 69 6e 74 20 73 ndings..*/.int s
17f30 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c qlite3_reset(sql
17f40 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
17f50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
17f60 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 EF: Create Or Re
17f70 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 define SQL Funct
17f80 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 ions.**.** The f
17f90 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e ollowing two fun
17fa0 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20 ctions are used
17fb0 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 to add SQL funct
17fc0 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 ions or aggregat
17fd0 65 73 0a 2a 2a 20 6f 72 20 74 6f 20 72 65 64 65 es.** or to rede
17fe0 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f fine the behavio
17ff0 72 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 r of existing SQ
18000 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 L functions or a
18010 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 0a ggregates. The.
18020 2a 2a 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e ** difference on
18030 6c 79 20 62 65 74 77 65 65 6e 20 74 68 65 20 74 ly between the t
18040 77 6f 20 69 73 20 74 68 61 74 20 74 68 65 20 73 wo is that the s
18050 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c econd parameter,
18060 20 74 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 the.** name of
18070 74 68 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e the (scalar) fun
18080 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 ction or aggrega
18090 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69 te, is encoded i
180a0 6e 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 n UTF-8 for.** s
180b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
180c0 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 nction() and UTF
180d0 2d 31 36 20 66 6f 72 20 73 71 6c 69 74 65 33 5f -16 for sqlite3_
180e0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
180f0 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6()..**.** The f
18100 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 irst argument is
18110 20 74 68 65 20 5b 73 71 6c 69 74 65 33 20 7c 20 the [sqlite3 |
18120 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 5d database handle]
18130 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 0a that holds the.
18140 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 ** SQL function
18150 6f 72 20 61 67 67 72 65 67 61 74 65 20 69 73 20 or aggregate is
18160 74 6f 20 62 65 20 61 64 64 65 64 20 6f 72 20 72 to be added or r
18170 65 64 65 66 69 6e 65 64 2e 20 49 66 20 61 20 73 edefined. If a s
18180 69 6e 67 6c 65 0a 2a 2a 20 70 72 6f 67 72 61 6d ingle.** program
18190 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 uses more than
181a0 6f 6e 65 20 64 61 74 61 62 61 73 65 20 68 61 6e one database han
181b0 64 6c 65 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 dle internally,
181c0 74 68 65 6e 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 then SQL.** func
181d0 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 tions or aggrega
181e0 74 65 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 tes must be adde
181f0 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 74 d individually t
18200 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 0a o each database.
18210 2a 2a 20 68 61 6e 64 6c 65 20 77 69 74 68 20 77 ** handle with w
18220 68 69 63 68 20 74 68 65 79 20 77 69 6c 6c 20 62 hich they will b
18230 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 e used..**.** Th
18240 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
18250 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f er is the name o
18260 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 f the SQL functi
18270 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 on to be created
18280 0a 2a 2a 20 6f 72 20 72 65 64 65 66 69 6e 65 64 .** or redefined
18290 2e 0a 2a 2a 20 54 68 65 20 6c 65 6e 67 74 68 20 ..** The length
182a0 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c of the name is l
182b0 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 imited to 255 by
182c0 74 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f tes, exclusive o
182d0 66 20 74 68 65 20 0a 2a 2a 20 7a 65 72 6f 2d 74 f the .** zero-t
182e0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 erminator. Note
182f0 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c that the name l
18300 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 ength limit is i
18310 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 n bytes, not.**
18320 63 68 61 72 61 63 74 65 72 73 2e 20 20 41 6e 79 characters. Any
18330 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 attempt to crea
18340 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 te a function wi
18350 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 th a longer name
18360 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 .** will result
18370 69 6e 20 61 6e 20 53 51 4c 49 54 45 5f 45 52 52 in an SQLITE_ERR
18380 4f 52 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 OR error..**.**
18390 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 The third parame
183a0 74 65 72 20 69 73 20 74 68 65 20 6e 75 6d 62 65 ter is the numbe
183b0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 r of arguments t
183c0 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 hat the SQL func
183d0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 tion or.** aggre
183e0 67 61 74 65 20 74 61 6b 65 73 2e 20 49 66 20 74 gate takes. If t
183f0 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 his parameter is
18400 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 negative, then
18410 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
18420 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 or.** aggregate
18430 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 may take any nu
18440 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 mber of argument
18450 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 s..**.** The fou
18460 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 rth parameter, e
18470 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 TextRep, specifi
18480 65 73 20 77 68 61 74 20 0a 2a 2a 20 5b 53 51 4c es what .** [SQL
18490 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 ITE_UTF8 | text
184a0 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 encoding] this S
184b0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 QL function pref
184c0 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 ers for.** its p
184d0 61 72 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 arameters. Any
184e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 SQL function imp
184f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 lementation shou
18500 6c 64 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f ld be able to wo
18510 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 rk.** work with
18520 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c UTF-8, UTF-16le,
18530 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 or UTF-16be. B
18540 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e ut some implemen
18550 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a tations may be.*
18560 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 * more efficient
18570 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 with one encodi
18580 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e ng than another.
18590 20 20 49 74 20 69 73 20 61 6c 6c 6f 77 65 64 20 It is allowed
185a0 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c to.** invoke sql
185b0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
185c0 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 tion() or sqlite
185d0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
185e0 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a n16() multiple.*
185f0 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 * times with the
18600 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 same function b
18610 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e ut with differen
18620 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78 t values of eTex
18630 74 52 65 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 tRep..** When mu
18640 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 ltiple implement
18650 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 ations of the sa
18660 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 me function are
18670 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 available, SQLit
18680 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 e.** will pick t
18690 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f he one that invo
186a0 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 lves the least a
186b0 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f mount of data co
186c0 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 nversion..** If
186d0 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 there is only a
186e0 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 single implement
186f0 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 ation which does
18700 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 0a 2a not care what.*
18710 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 * text encoding
18720 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 is used, then th
18730 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e e fourth argumen
18740 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 5b t should be.** [
18750 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a SQLITE_ANY]..**.
18760 2a 2a 20 54 68 65 20 66 69 66 74 68 20 70 61 72 ** The fifth par
18770 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 ameter is an arb
18780 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 itrary pointer.
18790 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 The implementat
187a0 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 66 75 ion.** of the fu
187b0 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 nction can gain
187c0 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 access to this p
187d0 6f 69 6e 74 65 72 20 75 73 69 6e 67 0a 2a 2a 20 ointer using.**
187e0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 [sqlite3_user_da
187f0 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ta()]..**.** The
18800 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68 seventh, eighth
18810 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d and ninth param
18820 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 eters, xFunc, xS
18830 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 tep and xFinal,
18840 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 are.** pointers
18850 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 to C-language fu
18860 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 nctions that imp
18870 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 0a 2a lement the SQL.*
18880 2a 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 * function or ag
18890 67 72 65 67 61 74 65 2e 20 41 20 73 63 61 6c 61 gregate. A scala
188a0 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 r SQL function r
188b0 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 equires an imple
188c0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 mentation of.**
188d0 74 68 65 20 78 46 75 6e 63 20 63 61 6c 6c 62 61 the xFunc callba
188e0 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f ck only, NULL po
188f0 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 inters should be
18900 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78 passed as the x
18910 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e Step.** and xFin
18920 61 6c 20 70 61 72 61 6d 65 74 65 72 73 2e 20 41 al parameters. A
18930 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 n aggregate SQL
18940 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 function require
18950 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 s an implementat
18960 69 6f 6e 0a 2a 2a 20 6f 66 20 78 53 74 65 70 20 ion.** of xStep
18970 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e and xFinal and N
18980 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61 ULL should be pa
18990 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 ssed for xFunc.
189a0 54 6f 20 64 65 6c 65 74 65 20 61 6e 0a 2a 2a 20 To delete an.**
189b0 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e existing SQL fun
189c0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 ction or aggrega
189d0 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f te, pass NULL fo
189e0 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 r all three func
189f0 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b tion.** callback
18a00 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65 ..**.** It is pe
18a10 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 rmitted to regis
18a20 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 ter multiple imp
18a30 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 lementations of
18a40 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 the same.** func
18a50 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 tions with the s
18a60 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 ame name but wit
18a70 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 h either differi
18a80 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a ng numbers of.**
18a90 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 arguments or di
18aa0 66 66 65 72 69 6e 67 20 70 65 72 66 65 72 72 65 ffering perferre
18ab0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 d text encodings
18ac0 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 . SQLite will u
18ad0 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d se.** the implem
18ae0 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c entation most cl
18af0 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 osely matches th
18b00 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 e way in which t
18b10 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 he.** SQL functi
18b20 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2f 0a 69 on is used..*/.i
18b30 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 nt sqlite3_creat
18b40 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 e_function(. sq
18b50 6c 69 74 65 33 20 2a 2c 0a 20 20 63 6f 6e 73 74 lite3 *,. const
18b60 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e char *zFunction
18b70 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 Name,. int nArg
18b80 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 ,. int eTextRep
18b90 2c 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 ,. void*,. voi
18ba0 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 d (*xFunc)(sqlit
18bb0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c e3_context*,int,
18bc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 sqlite3_value**)
18bd0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 ,. void (*xStep
18be0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 )(sqlite3_contex
18bf0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 t*,int,sqlite3_v
18c00 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 alue**),. void
18c10 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 (*xFinal)(sqlite
18c20 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 3_context*).);.i
18c30 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 nt sqlite3_creat
18c40 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 e_function16(.
18c50 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 sqlite3*,. cons
18c60 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f t void *zFunctio
18c70 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 nName,. int nAr
18c80 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 g,. int eTextRe
18c90 70 2c 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f p,. void*,. vo
18ca0 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 id (*xFunc)(sqli
18cb0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
18cc0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
18cd0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 ),. void (*xSte
18ce0 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 p)(sqlite3_conte
18cf0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f xt*,int,sqlite3_
18d00 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 value**),. void
18d10 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 (*xFinal)(sqlit
18d20 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a e3_context*).);.
18d30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
18d40 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a Text Encodings.
18d50 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
18d60 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 tant define inte
18d70 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 ger codes that r
18d80 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 epresent the var
18d90 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 ious.** text enc
18da0 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 odings supported
18db0 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 by SQLite..*/.#
18dc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 define SQLITE_UT
18dd0 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 F8 1.#
18de0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 define SQLITE_UT
18df0 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 F16LE 2.#
18e00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 define SQLITE_UT
18e10 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 F16BE 3.#
18e20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 define SQLITE_UT
18e30 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20 F16 4
18e40 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 /* Use native
18e50 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 byte order */.#d
18e60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 efine SQLITE_ANY
18e70 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 5
18e80 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 /* sqlite3_crea
18e90 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 te_function only
18ea0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
18eb0 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 TE_UTF16_ALIGNED
18ec0 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 8 /* sqlite
18ed0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
18ee0 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a on only */../*.*
18ef0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 73 6f * CAPI3REF: Obso
18f00 6c 65 74 65 20 46 75 6e 63 74 69 6f 6e 73 0a 2a lete Functions.*
18f10 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 *.** These funct
18f20 69 6f 6e 73 20 61 72 65 20 61 6c 6c 20 6e 6f 77 ions are all now
18f30 20 6f 62 73 6f 6c 65 74 65 2e 20 20 49 6e 20 6f obsolete. In o
18f40 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e rder to maintain
18f50 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f .** backwards co
18f60 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 mpatibility with
18f70 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 77 65 20 older code, we
18f80 63 6f 6e 74 69 6e 75 65 20 74 6f 20 73 75 70 70 continue to supp
18f90 6f 72 74 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e ort.** these fun
18fa0 63 74 69 6f 6e 73 2e 20 20 48 6f 77 65 76 65 72 ctions. However
18fb0 2c 20 6e 65 77 20 64 65 76 65 6c 6f 70 6d 65 6e , new developmen
18fc0 74 20 70 72 6f 6a 65 63 74 73 20 73 68 6f 75 6c t projects shoul
18fd0 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 d avoid.** the u
18fe0 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 se of these func
18ff0 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 tions. To help
19000 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 encourage people
19010 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 to avoid.** usi
19020 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f ng these functio
19030 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 ns, we are not g
19040 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 oing to tell you
19050 20 77 61 6e 74 20 74 68 65 79 20 64 6f 2e 0a 2a want they do..*
19060 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 /.int sqlite3_ag
19070 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 gregate_count(sq
19080 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b lite3_context*);
19090 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 .int sqlite3_exp
190a0 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d ired(sqlite3_stm
190b0 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 t*);.int sqlite3
190c0 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e _transfer_bindin
190d0 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a gs(sqlite3_stmt*
190e0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 , sqlite3_stmt*)
190f0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c ;.int sqlite3_gl
19100 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 obal_recover(voi
19110 64 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 d);.void sqlite3
19120 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 _thread_cleanup(
19130 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 void);.int sqlit
19140 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 e3_memory_alarm(
19150 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 void(*)(void*,sq
19160 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 lite3_int64,int)
19170 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 ,void*,sqlite3_i
19180 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 nt64);../*.** CA
19190 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e PI3REF: Obtainin
191a0 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 g SQL Function P
191b0 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a arameter Values.
191c0 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 **.** The C-lang
191d0 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 uage implementat
191e0 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 ion of SQL funct
191f0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 ions and aggrega
19200 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 tes uses.** this
19210 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 set of interfac
19220 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 e routines to ac
19230 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 cess the paramet
19240 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 er values on.**
19250 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 the function or
19260 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a aggregate..**.**
19270 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 The xFunc (for
19280 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 scalar functions
19290 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 ) or xStep (for
192a0 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61 aggregates) para
192b0 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 meters.** to [sq
192c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
192d0 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 ction()] and [sq
192e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
192f0 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 ction16()].** de
19300 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 fine callbacks t
19310 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 hat implement th
19320 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 e SQL functions
19330 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a and aggregates..
19340 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d ** The 4th param
19350 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 eter to these ca
19360 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 llbacks is an ar
19370 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 ray of pointers
19380 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 to.** [sqlite3_v
19390 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 alue] objects.
193a0 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 There is one [sq
193b0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
193c0 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 ect for.** each
193d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
193e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 SQL function.
193f0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
19400 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 re used to.** ex
19410 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f tract values fro
19420 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 m the [sqlite3_v
19430 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a alue] objects..*
19440 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
19450 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 nes work just li
19460 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e ke the correspon
19470 64 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 ding .** [sqlite
19480 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 20 7c 20 3_column_blob |
19490 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a sqlite3_column_*
194a0 20 72 6f 75 74 69 6e 65 73 5d 20 65 78 63 65 70 routines] excep
194b0 74 20 74 68 61 74 20 0a 2a 2a 20 74 68 65 73 65 t that .** these
194c0 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 routines take a
194d0 20 73 69 6e 67 6c 65 20 5b 73 71 6c 69 74 65 33 single [sqlite3
194e0 5f 76 61 6c 75 65 2a 5d 20 70 6f 69 6e 74 65 72 _value*] pointer
194f0 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 instead.** of a
19500 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a n [sqlite3_stmt*
19510 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e ] pointer and an
19520 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 integer column
19530 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 number..**.** Th
19540 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f e sqlite3_value_
19550 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 text16() interfa
19560 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 ce extracts a UT
19570 46 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e F16 string.** in
19580 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 the native byte
19590 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f -order of the ho
195a0 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 54 68 65 st machine. The
195b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 .** sqlite3_valu
195c0 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 e_text16be() and
195d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
195e0 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 ext16le() interf
195f0 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 aces.** extract
19600 55 54 46 31 36 20 73 74 72 69 6e 67 73 20 61 73 UTF16 strings as
19610 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 big-endian and
19620 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 little-endian re
19630 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a spectively..**.*
19640 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 * The sqlite3_va
19650 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 lue_numeric_type
19660 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 () interface att
19670 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a empts to apply.*
19680 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 * numeric affini
19690 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e ty to the value.
196a0 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 This means tha
196b0 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a t an attempt is.
196c0 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 ** made to conve
196d0 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 rt the value to
196e0 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c an integer or fl
196f0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 oating point. I
19700 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 f.** such a conv
19710 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 ersion is possib
19720 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 le without loss
19730 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 of information (
19740 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 77 6f 72 64 in order.** word
19750 73 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 s if the value i
19760 73 20 6f 72 69 67 69 6e 61 6c 20 61 20 73 74 72 s original a str
19770 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c ing that looks l
19780 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a ike a number).**
19790 20 74 68 65 6e 20 69 74 20 69 73 20 64 6f 6e 65 then it is done
197a0 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 . Otherwise no
197b0 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 conversion occur
197c0 73 2e 20 20 54 68 65 20 0a 2a 2a 20 5b 53 51 4c s. The .** [SQL
197d0 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 ITE_INTEGER | da
197e0 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f tatype] after co
197f0 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 nversion is retu
19800 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 rned..**.** Plea
19810 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 se pay particula
19820 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 r attention to t
19830 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65 he fact that the
19840 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a pointer that.**
19850 20 69 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f is returned fro
19860 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 m [sqlite3_value
19870 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 _blob()], [sqlit
19880 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d e3_value_text()]
19890 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 , or.** [sqlite3
198a0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d _value_text16()]
198b0 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 can be invalida
198c0 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 ted by a subsequ
198d0 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b ent call to.** [
198e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
198f0 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 tes()], [sqlite3
19900 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 _value_bytes16()
19910 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ], [sqlite3_valu
19920 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 e_text()],.** or
19930 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
19940 74 65 78 74 31 36 28 29 5d 2e 20 20 0a 2a 2a 0a text16()]. .**.
19950 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
19960 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 s must be called
19970 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 from the same t
19980 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 hread as.** the
19990 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 SQL function tha
199a0 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 73 t supplied the s
199b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 20 70 61 qlite3_value* pa
199c0 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 20 4f 72 2c rameters..** Or,
199d0 20 69 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f if the sqlite3_
199e0 76 61 6c 75 65 2a 20 61 72 67 75 6d 65 6e 74 20 value* argument
199f0 63 6f 6d 65 73 20 66 72 6f 6d 20 74 68 65 20 5b comes from the [
19a00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 sqlite3_column_v
19a10 61 6c 75 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 alue()].** inter
19a20 66 61 63 65 2c 20 74 68 65 6e 20 74 68 65 73 65 face, then these
19a30 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 routines should
19a40 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 be called from
19a50 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 0a the same thread.
19a60 2a 2a 20 74 68 61 74 20 72 61 6e 20 5b 73 71 6c ** that ran [sql
19a70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 ite3_column_valu
19a80 65 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 e()]..*/.const v
19a90 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c oid *sqlite3_val
19aa0 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f ue_blob(sqlite3_
19ab0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c value*);.int sql
19ac0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 ite3_value_bytes
19ad0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
19ae0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 ;.int sqlite3_va
19af0 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 lue_bytes16(sqli
19b00 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 te3_value*);.dou
19b10 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ble sqlite3_valu
19b20 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 e_double(sqlite3
19b30 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 _value*);.int sq
19b40 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 lite3_value_int(
19b50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
19b60 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 .sqlite3_int64 s
19b70 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 qlite3_value_int
19b80 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 64(sqlite3_value
19b90 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e *);.const unsign
19ba0 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 ed char *sqlite3
19bb0 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 _value_text(sqli
19bc0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e te3_value*);.con
19bd0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
19be0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 _value_text16(sq
19bf0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 lite3_value*);.c
19c00 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
19c10 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c e3_value_text16l
19c20 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a e(sqlite3_value*
19c30 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
19c40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
19c50 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 t16be(sqlite3_va
19c60 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 lue*);.int sqlit
19c70 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 e3_value_type(sq
19c80 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 lite3_value*);.i
19c90 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt sqlite3_value
19ca0 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 _numeric_type(sq
19cb0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a lite3_value*);..
19cc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
19cd0 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 Obtain Aggregate
19ce0 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 Function Contex
19cf0 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c t.**.** The impl
19d00 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67 ementation of ag
19d10 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 gregate SQL func
19d20 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72 tions use this r
19d30 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 outine to alloca
19d40 74 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72 te.** a structur
19d50 65 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 e for storing th
19d60 65 69 72 20 73 74 61 74 65 2e 20 20 54 68 65 20 eir state. The
19d70 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 first time this
19d80 72 6f 75 74 69 6e 65 0a 2a 2a 20 69 73 20 63 61 routine.** is ca
19d90 6c 6c 65 64 20 66 6f 72 20 61 20 70 61 72 74 69 lled for a parti
19da0 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c cular aggregate,
19db0 20 61 20 6e 65 77 20 73 74 72 75 63 74 75 72 65 a new structure
19dc0 20 6f 66 20 73 69 7a 65 20 6e 42 79 74 65 73 0a of size nBytes.
19dd0 2a 2a 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 2c ** is allocated,
19de0 20 7a 65 72 6f 65 64 2c 20 61 6e 64 20 72 65 74 zeroed, and ret
19df0 75 72 6e 65 64 2e 20 20 4f 6e 20 73 75 62 73 65 urned. On subse
19e00 71 75 65 6e 74 20 63 61 6c 6c 73 20 28 66 6f 72 quent calls (for
19e10 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 61 67 67 the.** same agg
19e20 72 65 67 61 74 65 20 69 6e 73 74 61 6e 63 65 29 regate instance)
19e30 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 the same buffer
19e40 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 is returned. T
19e50 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
19e60 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 61 67 67 72 n.** of the aggr
19e70 65 67 61 74 65 20 63 61 6e 20 75 73 65 20 74 68 egate can use th
19e80 65 20 72 65 74 75 72 6e 65 64 20 62 75 66 66 65 e returned buffe
19e90 72 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 65 20 r to accumulate
19ea0 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 data..**.** The
19eb0 62 75 66 66 65 72 20 61 6c 6c 6f 63 61 74 65 64 buffer allocated
19ec0 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 is freed automa
19ed0 74 69 63 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 tically by SQLit
19ee0 65 20 77 68 61 6e 20 74 68 65 20 61 67 67 72 65 e whan the aggre
19ef0 67 61 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f gate.** query co
19f00 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 ncludes..**.** T
19f10 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
19f20 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 er should be a c
19f30 6f 70 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20 5b opy of the .** [
19f40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 sqlite3_context
19f50 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 | SQL function c
19f60 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 ontext] that is
19f70 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 the first.** par
19f80 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 ameter to the ca
19f90 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 llback routine t
19fa0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 hat implements t
19fb0 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 he aggregate.**
19fc0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 function..**.**
19fd0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 This routine mus
19fe0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d t be called from
19ff0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 the same thread
1a000 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 in which.** the
1a010 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 aggregate SQL f
1a020 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 unction is runni
1a030 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c ng..*/.void *sql
1a040 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
1a050 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 ontext(sqlite3_c
1a060 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 ontext*, int nBy
1a070 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tes);../*.** CAP
1a080 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 I3REF: User Data
1a090 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a For Functions.*
1a0a0 2a 0a 2a 2a 20 54 68 65 20 70 55 73 65 72 44 61 *.** The pUserDa
1a0b0 74 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 ta parameter to
1a0c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 the [sqlite3_cre
1a0d0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a ate_function()].
1a0e0 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ** and [sqlite3_
1a0f0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
1a100 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 6()] routines.**
1a110 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 used to registe
1a120 72 20 75 73 65 72 20 66 75 6e 63 74 69 6f 6e 73 r user functions
1a130 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 74 6f is available to
1a140 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e .** the implemen
1a150 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 66 75 tation of the fu
1a160 6e 63 74 69 6f 6e 20 75 73 69 6e 67 20 74 68 69 nction using thi
1a170 73 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 s call..**.** Th
1a180 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 is routine must
1a190 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 be called from t
1a1a0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 he same thread i
1a1b0 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 n which.** the S
1a1c0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 QL function is r
1a1d0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 unning..*/.void
1a1e0 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 *sqlite3_user_da
1a1f0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ta(sqlite3_conte
1a200 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 xt*);../*.** CAP
1a210 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 I3REF: Function
1a220 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a Auxiliary Data.*
1a230 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 *.** The followi
1a240 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 ng two functions
1a250 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20 may be used by
1a260 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 scalar SQL funct
1a270 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 ions to.** assoc
1a280 69 61 74 65 20 6d 65 74 61 2d 64 61 74 61 20 77 iate meta-data w
1a290 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c ith argument val
1a2a0 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 ues. If the same
1a2b0 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 value is passed
1a2c0 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 to.** multiple
1a2d0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 invocations of t
1a2e0 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 he same SQL func
1a2f0 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 tion during quer
1a300 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 y execution, und
1a310 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 er.** some circu
1a320 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 mstances the ass
1a330 6f 63 69 61 74 65 64 20 6d 65 74 61 2d 64 61 74 ociated meta-dat
1a340 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 a may be preserv
1a350 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 ed. This may.**
1a360 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 be used, for exa
1a370 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 mple, to add a r
1a380 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f egular-expressio
1a390 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 n matching scala
1a3a0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 r.** function. T
1a3b0 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 he compiled vers
1a3c0 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c ion of the regul
1a3d0 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 ar expression is
1a3e0 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 stored as.** me
1a3f0 74 61 2d 64 61 74 61 20 61 73 73 6f 63 69 61 74 ta-data associat
1a400 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 ed with the SQL
1a410 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 value passed as
1a420 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 the regular expr
1a430 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 ession.** patter
1a440 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 n. The compiled
1a450 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 regular express
1a460 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 ion can be reuse
1a470 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a d on multiple.**
1a480 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 invocations of
1a490 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f the same functio
1a4a0 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 n so that the or
1a4b0 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 iginal pattern s
1a4c0 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f tring.** does no
1a4d0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 t need to be rec
1a4e0 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 ompiled on each
1a4f0 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a invocation..**.*
1a500 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 * The sqlite3_ge
1a510 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 t_auxdata() inte
1a520 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
1a530 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d pointer to the m
1a540 65 74 61 2d 64 61 74 61 0a 2a 2a 20 61 73 73 6f eta-data.** asso
1a550 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 ciated with the
1a560 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c Nth argument val
1a570 75 65 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e ue to the curren
1a580 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a t SQL function.*
1a590 2a 20 63 61 6c 6c 2c 20 77 68 65 72 65 20 4e 20 * call, where N
1a5a0 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 is the second pa
1a5b0 72 61 6d 65 74 65 72 2e 20 49 66 20 6e 6f 20 6d rameter. If no m
1a5c0 65 74 61 2d 64 61 74 61 20 68 61 73 20 62 65 65 eta-data has bee
1a5d0 6e 20 73 65 74 20 66 6f 72 0a 2a 2a 20 74 68 61 n set for.** tha
1a5e0 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 20 t value, then a
1a5f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 NULL pointer is
1a600 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
1a610 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f The sqlite3_set_
1a620 61 75 78 64 61 74 61 28 29 20 69 73 20 75 73 65 auxdata() is use
1a630 64 20 74 6f 20 61 73 73 6f 63 69 61 74 65 20 6d d to associate m
1a640 65 74 61 2d 64 61 74 61 20 77 69 74 68 20 61 6e eta-data with an
1a650 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e SQL.** function
1a660 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 65 20 74 argument. The t
1a670 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 hird parameter i
1a680 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 s a pointer to t
1a690 68 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a 2a 20 he meta-data.**
1a6a0 74 6f 20 62 65 20 61 73 73 6f 63 69 61 74 65 64 to be associated
1a6b0 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 75 73 with the Nth us
1a6c0 65 72 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 er function argu
1a6d0 6d 65 6e 74 20 76 61 6c 75 65 2e 20 54 68 65 20 ment value. The
1a6e0 66 6f 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65 fourth.** parame
1a6f0 74 65 72 20 73 70 65 63 69 66 69 65 73 20 61 20 ter specifies a
1a700 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 destructor that
1a710 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 6f will be called o
1a720 6e 20 74 68 65 20 6d 65 74 61 2d 0a 2a 2a 20 64 n the meta-.** d
1a730 61 74 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 72 ata pointer to r
1a740 65 6c 65 61 73 65 20 69 74 20 77 68 65 6e 20 69 elease it when i
1a750 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 t is no longer r
1a760 65 71 75 69 72 65 64 2e 20 49 66 20 74 68 65 20 equired. If the
1a770 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 20 69 .** destructor i
1a780 73 20 4e 55 4c 4c 2c 20 69 74 20 69 73 20 6e 6f s NULL, it is no
1a790 74 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a t invoked..**.**
1a7a0 20 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 In practice, me
1a7b0 74 61 2d 64 61 74 61 20 69 73 20 70 72 65 73 65 ta-data is prese
1a7c0 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e rved between fun
1a7d0 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a ction calls for.
1a7e0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 ** expressions t
1a7f0 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 hat are constant
1a800 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 at compile time
1a810 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 . This includes
1a820 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 literal.** value
1a830 73 20 61 6e 64 20 53 51 4c 20 76 61 72 69 61 62 s and SQL variab
1a840 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 les..**.** These
1a850 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 routines must b
1a860 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 e called from th
1a870 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e e same thread in
1a880 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 which.** the SQ
1a890 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 L function is ru
1a8a0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a nning..*/.void *
1a8b0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 sqlite3_get_auxd
1a8c0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ata(sqlite3_cont
1a8d0 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 ext*, int);.void
1a8e0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 sqlite3_set_aux
1a8f0 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e data(sqlite3_con
1a900 74 65 78 74 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 text*, int, void
1a910 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 *, void (*)(void
1a920 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 *));.../*.** CAP
1a930 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 I3REF: Constants
1a940 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 Defining Specia
1a950 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 l Destructor Beh
1a960 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 avior.**.** Thes
1a970 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 e are special va
1a980 6c 75 65 20 66 6f 72 20 74 68 65 20 64 65 73 74 lue for the dest
1a990 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 ructor that is p
1a9a0 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a assed in as the.
1a9b0 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e ** final argumen
1a9c0 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 t to routines li
1a9d0 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 ke [sqlite3_resu
1a9e0 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20 lt_blob()]. If
1a9f0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a the destructor.*
1aa00 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 * argument is SQ
1aa10 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 LITE_STATIC, it
1aa20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 means that the c
1aa30 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 ontent pointer i
1aa40 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e s constant.** an
1aa50 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 d will never cha
1aa60 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f nge. It does no
1aa70 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 t need to be des
1aa80 74 72 6f 79 65 64 2e 20 20 54 68 65 20 0a 2a 2a troyed. The .**
1aa90 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e SQLITE_TRANSIEN
1aaa0 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 T value means th
1aab0 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 at the content w
1aac0 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 ill likely chang
1aad0 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 e in.** the near
1aae0 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 future and that
1aaf0 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d SQLite should m
1ab00 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 ake its own priv
1ab10 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 ate copy of.** t
1ab20 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 he content befor
1ab30 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a e returning..**.
1ab40 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69 ** The typedef i
1ab50 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 s necessary to w
1ab60 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c ork around probl
1ab70 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a ems in certain.*
1ab80 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e * C++ compilers.
1ab90 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 31 See ticket #21
1aba0 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 91..*/.typedef v
1abb0 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 oid (*sqlite3_de
1abc0 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 structor_type)(v
1abd0 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 oid*);.#define S
1abe0 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 QLITE_STATIC
1abf0 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 ((sqlite3_dest
1ac00 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 ructor_type)0).#
1ac10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 define SQLITE_TR
1ac20 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 ANSIENT ((sqli
1ac30 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 te3_destructor_t
1ac40 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 ype)-1)../*.** C
1ac50 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 API3REF: Setting
1ac60 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 The Result Of A
1ac70 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a n SQL Function.*
1ac80 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
1ac90 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20 nes are used by
1aca0 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 the xFunc or xFi
1acb0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 nal callbacks th
1acc0 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 at.** implement
1acd0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e SQL functions an
1ace0 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 d aggregates. S
1acf0 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 ee.** [sqlite3_c
1ad00 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
1ad10 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 ] and [sqlite3_c
1ad20 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
1ad30 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 ()].** for addit
1ad40 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f ional informatio
1ad50 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 n..**.** These f
1ad60 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 unctions work ve
1ad70 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 ry much like the
1ad80 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 .** [sqlite3_bi
1ad90 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 nd_blob | sqlite
1ada0 33 5f 62 69 6e 64 5f 2a 5d 20 66 61 6d 69 6c 79 3_bind_*] family
1adb0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 of functions us
1adc0 65 64 0a 2a 2a 20 74 6f 20 62 69 6e 64 20 76 61 ed.** to bind va
1add0 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 lues to host par
1ade0 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 ameters in prepa
1adf0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a red statements..
1ae00 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 0a ** Refer to the.
1ae10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
1ae20 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f _blob | sqlite3_
1ae30 62 69 6e 64 5f 2a 20 64 6f 63 75 6d 65 6e 74 61 bind_* documenta
1ae40 74 69 6f 6e 5d 20 66 6f 72 0a 2a 2a 20 61 64 64 tion] for.** add
1ae50 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 itional informat
1ae60 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ion..**.** The s
1ae70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
1ae80 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 ror() and sqlite
1ae90 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
1aea0 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 () functions.**
1aeb0 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d cause the implem
1aec0 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 ented SQL functi
1aed0 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 on to throw an e
1aee0 78 63 65 70 74 69 6f 6e 2e 20 20 54 68 65 0a 2a xception. The.*
1aef0 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 * parameter to s
1af00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
1af10 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ror() or sqlite3
1af20 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
1af30 29 0a 2a 2a 20 69 73 20 74 68 65 20 74 65 78 74 ).** is the text
1af40 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 of an error mes
1af50 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 sage..**.** The
1af60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
1af70 6f 6f 62 69 67 28 29 20 63 61 75 73 65 20 74 68 oobig() cause th
1af80 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 e function imple
1af90 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 mentation.** to
1afa0 74 68 72 6f 77 20 61 6e 64 20 65 72 72 6f 72 20 throw and error
1afb0 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 indicating that
1afc0 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 a string or BLOB
1afd0 20 69 73 20 74 6f 20 6c 6f 6e 67 0a 2a 2a 20 74 is to long.** t
1afe0 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a o represent..**.
1aff0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
1b000 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 s must be called
1b010 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 from within the
1b020 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a same thread as.
1b030 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 ** the SQL funct
1b040 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77 ion associated w
1b050 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33 ith the [sqlite3
1b060 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 _context] pointe
1b070 72 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 r..*/.void sqlit
1b080 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 e3_result_blob(s
1b090 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
1b0a0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
1b0b0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a t, void(*)(void*
1b0c0 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 ));.void sqlite3
1b0d0 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 _result_double(s
1b0e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
1b0f0 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 double);.void s
1b100 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
1b110 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ror(sqlite3_cont
1b120 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 ext*, const char
1b130 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 *, int);.void sq
1b140 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
1b150 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e or16(sqlite3_con
1b160 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 text*, const voi
1b170 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 d*, int);.void s
1b180 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
1b190 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 ror_toobig(sqlit
1b1a0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f e3_context*);.vo
1b1b0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
1b1c0 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 t_error_nomem(sq
1b1d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b lite3_context*);
1b1e0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
1b1f0 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 sult_int(sqlite3
1b200 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b _context*, int);
1b210 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
1b220 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 sult_int64(sqlit
1b230 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c e3_context*, sql
1b240 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 ite3_int64);.voi
1b250 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
1b260 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f _null(sqlite3_co
1b270 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 ntext*);.void sq
1b280 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
1b290 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t(sqlite3_contex
1b2a0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c t*, const char*,
1b2b0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f int, void(*)(vo
1b2c0 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 id*));.void sqli
1b2d0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
1b2e0 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 6(sqlite3_contex
1b2f0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c t*, const void*,
1b300 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f int, void(*)(vo
1b310 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 id*));.void sqli
1b320 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
1b330 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 6le(sqlite3_cont
1b340 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 ext*, const void
1b350 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 *, int,void(*)(v
1b360 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c oid*));.void sql
1b370 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
1b380 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 16be(sqlite3_con
1b390 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 text*, const voi
1b3a0 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 d*, int,void(*)(
1b3b0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 void*));.void sq
1b3c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
1b3d0 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ue(sqlite3_conte
1b3e0 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c xt*, sqlite3_val
1b3f0 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 ue*);.void sqlit
1b400 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c e3_result_zerobl
1b410 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ob(sqlite3_conte
1b420 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a xt*, int n);../*
1b430 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
1b440 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 fine New Collati
1b450 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a ng Sequences.**.
1b460 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f ** These functio
1b470 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 ns are used to a
1b480 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e dd new collation
1b490 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74 68 sequences to th
1b4a0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 2a 5d 20 e.** [sqlite3*]
1b4b0 68 61 6e 64 6c 65 20 73 70 65 63 69 66 69 65 64 handle specified
1b4c0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 as the first ar
1b4d0 67 75 6d 65 6e 74 2e 20 0a 2a 2a 0a 2a 2a 20 54 gument. .**.** T
1b4e0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e he name of the n
1b4f0 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 ew collation seq
1b500 75 65 6e 63 65 20 69 73 20 73 70 65 63 69 66 69 uence is specifi
1b510 65 64 20 61 73 20 61 20 55 54 46 2d 38 20 73 74 ed as a UTF-8 st
1b520 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 ring.** for sqli
1b530 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
1b540 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 tion() and sqlit
1b550 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
1b560 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 ion_v2().** and
1b570 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 a UTF-16 string
1b580 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 for sqlite3_crea
1b590 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 te_collation16()
1b5a0 2e 20 20 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a . In all cases.
1b5b0 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20 70 ** the name is p
1b5c0 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 assed as the sec
1b5d0 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 ond function arg
1b5e0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ument..**.** The
1b5f0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 third argument
1b600 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 may be one of th
1b610 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c e constants [SQL
1b620 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 ITE_UTF8],.** [S
1b630 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 6f QLITE_UTF16LE] o
1b640 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 r [SQLITE_UTF16B
1b650 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 E], indicating t
1b660 68 61 74 20 74 68 65 20 75 73 65 72 2d 73 75 70 hat the user-sup
1b670 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 plied.** routine
1b680 20 65 78 70 65 63 74 73 20 74 6f 20 62 65 20 70 expects to be p
1b690 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73 20 74 assed pointers t
1b6a0 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 o strings encode
1b6b0 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a d using UTF-8,.*
1b6c0 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d * UTF-16 little-
1b6d0 65 6e 64 69 61 6e 20 6f 72 20 55 54 46 2d 31 36 endian or UTF-16
1b6e0 20 62 69 67 2d 65 6e 64 69 61 6e 20 72 65 73 70 big-endian resp
1b6f0 65 63 74 69 76 65 6c 79 2e 20 20 54 68 65 0a 2a ectively. The.*
1b700 2a 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 * third argument
1b710 20 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20 5b might also be [
1b720 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 SQLITE_UTF16_ALI
1b730 47 4e 45 44 5d 20 74 6f 20 69 6e 64 69 63 61 74 GNED] to indicat
1b740 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 72 6f e that.** the ro
1b750 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 70 6f utine expects po
1b760 69 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 69 74 inters to 16-bit
1b770 20 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 73 74 word aligned st
1b780 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46 31 rings.** of UTF1
1b790 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 6 in the native
1b7a0 62 79 74 65 20 6f 72 64 65 72 20 6f 66 20 74 68 byte order of th
1b7b0 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e e host computer.
1b7c0 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 .**.** A pointer
1b7d0 20 74 6f 20 74 68 65 20 75 73 65 72 20 73 75 70 to the user sup
1b7e0 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75 plied routine mu
1b7f0 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20 st be passed as
1b800 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67 the fifth.** arg
1b810 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 69 73 20 ument. If it is
1b820 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 74 68 NULL, this is th
1b830 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65 74 69 e same as deleti
1b840 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e ng the collation
1b850 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 73 6f .** sequence (so
1b860 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e that SQLite can
1b870 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d not call it anym
1b880 6f 72 65 29 2e 20 45 61 63 68 20 74 69 6d 65 20 ore). Each time
1b890 74 68 65 20 75 73 65 72 0a 2a 2a 20 73 75 70 70 the user.** supp
1b8a0 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 lied function is
1b8b0 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 invoked, it is
1b8c0 70 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66 passed a copy of
1b8d0 20 74 68 65 20 76 6f 69 64 2a 20 70 61 73 73 65 the void* passe
1b8e0 64 20 61 73 0a 2a 2a 20 74 68 65 20 66 6f 75 72 d as.** the four
1b8f0 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 th argument to s
1b900 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
1b910 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 0a 2a 2a 20 llation() or.**
1b920 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
1b930 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 20 61 73 20 ollation16() as
1b940 69 74 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 its first parame
1b950 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 ter..**.** The r
1b960 65 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e emaining argumen
1b970 74 73 20 74 6f 20 74 68 65 20 75 73 65 72 2d 73 ts to the user-s
1b980 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 upplied routine
1b990 61 72 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c are two strings,
1b9a0 0a 2a 2a 20 65 61 63 68 20 72 65 70 72 65 73 65 .** each represe
1b9b0 6e 74 65 64 20 62 79 20 61 20 5b 6c 65 6e 67 74 nted by a [lengt
1b9c0 68 2c 20 64 61 74 61 5d 20 70 61 69 72 20 61 6e h, data] pair an
1b9d0 64 20 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 d encoded in the
1b9e0 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 encoding.** tha
1b9f0 74 20 77 61 73 20 70 61 73 73 65 64 20 61 73 20 t was passed as
1ba00 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 the third argume
1ba10 6e 74 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c nt when the coll
1ba20 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 ation sequence w
1ba30 61 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 as.** registered
1ba40 2e 20 54 68 65 20 75 73 65 72 20 72 6f 75 74 69 . The user routi
1ba50 6e 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e ne should return
1ba60 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 negative, zero
1ba70 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66 0a 2a or positive if.*
1ba80 2a 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69 * the first stri
1ba90 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c ng is less than,
1baa0 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 equal to, or gr
1bab0 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 eater than the s
1bac0 65 63 6f 6e 64 0a 2a 2a 20 73 74 72 69 6e 67 2e econd.** string.
1bad0 20 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d i.e. (STRING1 -
1bae0 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a STRING2)..**.**
1baf0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 The sqlite3_cre
1bb00 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 ate_collation_v2
1bb10 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 () works like sq
1bb20 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
1bb30 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 61 lation().** exca
1bb40 70 74 20 74 68 61 74 20 69 74 20 74 61 6b 65 73 pt that it takes
1bb50 20 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d 65 an extra argume
1bb60 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 64 65 nt which is a de
1bb70 73 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 structor for.**
1bb80 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 the collation.
1bb90 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 The destructor i
1bba0 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 s called when th
1bbb0 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a e collation is.*
1bbc0 2a 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 * destroyed and
1bbd0 69 73 20 70 61 73 73 65 64 20 61 20 63 6f 70 79 is passed a copy
1bbe0 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 of the fourth p
1bbf0 61 72 61 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 arameter void* p
1bc00 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 ointer.** of the
1bc10 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
1bc20 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 20 collation_v2().
1bc30 20 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 Collations are
1bc40 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e 0a 2a destroyed when.*
1bc50 2a 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 * they are overr
1bc60 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63 idden by later c
1bc70 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c alls to the coll
1bc80 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 ation creation f
1bc90 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6f 72 20 77 unctions.** or w
1bca0 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 hen the [sqlite3
1bcb0 2a 5d 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 *] database hand
1bcc0 6c 65 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 le is closed usi
1bcd0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 ng [sqlite3_clos
1bce0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 e()]..**.** The
1bcf0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
1bd00 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 69 6e ollation_v2() in
1bd10 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72 terface is exper
1bd20 69 6d 65 6e 74 61 6c 20 61 6e 64 0a 2a 2a 20 73 imental and.** s
1bd30 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 ubject to change
1bd40 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 in future relea
1bd50 73 65 73 2e 20 20 54 68 65 20 6f 74 68 65 72 20 ses. The other
1bd60 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 collation creati
1bd70 6f 6e 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 on.** functions
1bd80 61 72 65 20 73 74 61 62 6c 65 2e 0a 2a 2f 0a 69 are stable..*/.i
1bd90 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 nt sqlite3_creat
1bda0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 e_collation(. s
1bdb0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 qlite3*, . cons
1bdc0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a t char *zName, .
1bdd0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 int eTextRep,
1bde0 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 . void*,. int(
1bdf0 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a *xCompare)(void*
1be00 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a ,int,const void*
1be10 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a ,int,const void*
1be20 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ).);.int sqlite3
1be30 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
1be40 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a n_v2(. sqlite3*
1be50 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 , . const char
1be60 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 *zName, . int e
1be70 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 TextRep, . void
1be80 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 *,. int(*xCompa
1be90 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f re)(void*,int,co
1bea0 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f nst void*,int,co
1beb0 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f nst void*),. vo
1bec0 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f id(*xDestroy)(vo
1bed0 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 id*).);.int sqli
1bee0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
1bef0 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 tion16(. sqlite
1bf00 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 3*, . const cha
1bf10 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 r *zName, . int
1bf20 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f eTextRep, . vo
1bf30 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d id*,. int(*xCom
1bf40 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c pare)(void*,int,
1bf50 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c const void*,int,
1bf60 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a const void*).);.
1bf70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1bf80 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 Collation Neede
1bf90 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a d Callbacks.**.*
1bfa0 2a 20 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e * To avoid havin
1bfb0 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c g to register al
1bfc0 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 l collation sequ
1bfd0 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 ences before a d
1bfe0 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 atabase.** can b
1bff0 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 e used, a single
1c000 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
1c010 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 on may be regist
1c020 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a ered with the.**
1c030 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 database handle
1c040 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 20 77 68 to be called wh
1c050 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 enever an undefi
1c060 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 ned collation se
1c070 71 75 65 6e 63 65 20 69 73 0a 2a 2a 20 72 65 71 quence is.** req
1c080 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 uired..**.** If
1c090 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 the function is
1c0a0 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 registered using
1c0b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c the sqlite3_col
1c0c0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 lation_needed()
1c0d0 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 API,.** then it
1c0e0 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 is passed the na
1c0f0 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 mes of undefined
1c100 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 collation seque
1c110 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a nces as strings.
1c120 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 ** encoded in UT
1c130 46 2d 38 2e 20 49 66 20 73 71 6c 69 74 65 33 5f F-8. If sqlite3_
1c140 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 collation_needed
1c150 31 36 28 29 20 69 73 20 75 73 65 64 2c 20 74 68 16() is used, th
1c160 65 20 6e 61 6d 65 73 0a 2a 2a 20 61 72 65 20 70 e names.** are p
1c170 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 assed as UTF-16
1c180 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 in machine nativ
1c190 65 20 62 79 74 65 20 6f 72 64 65 72 2e 20 41 20 e byte order. A
1c1a0 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 0a 2a call to either.*
1c1b0 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 * function repla
1c1c0 63 65 73 20 61 6e 79 20 65 78 69 73 74 69 6e 67 ces any existing
1c1d0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a callback..**.**
1c1e0 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 When the callba
1c1f0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 ck is invoked, t
1c200 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
1c210 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f t passed is a co
1c220 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 py.** of the sec
1c230 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ond argument to
1c240 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
1c250 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a n_needed() or.**
1c260 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 sqlite3_collati
1c270 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 54 on_needed16(). T
1c280 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
1c290 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61 nt is the databa
1c2a0 73 65 0a 2a 2a 20 68 61 6e 64 6c 65 2e 20 54 68 se.** handle. Th
1c2b0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
1c2c0 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 is one of [SQLI
1c2d0 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 TE_UTF8], [SQLIT
1c2e0 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 0a 2a E_UTF16BE], or.*
1c2f0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c * [SQLITE_UTF16L
1c300 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 E], indicating t
1c310 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c he most desirabl
1c320 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f e form of the co
1c330 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 llation.** seque
1c340 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 nce function req
1c350 75 69 72 65 64 2e 20 54 68 65 20 66 6f 75 72 74 uired. The fourt
1c360 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 h parameter is t
1c370 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a he name of the.*
1c380 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 * required colla
1c390 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a tion sequence..*
1c3a0 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 *.** The callbac
1c3b0 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c k function shoul
1c3c0 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64 d register the d
1c3d0 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e esired collation
1c3e0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 using.** [sqlit
1c3f0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
1c400 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 ion()], [sqlite3
1c410 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
1c420 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 n16()], or.** [s
1c430 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
1c440 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a llation_v2()]..*
1c450 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f /.int sqlite3_co
1c460 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a llation_needed(.
1c470 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 sqlite3*, . v
1c480 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 oid*, . void(*)
1c490 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c (void*,sqlite3*,
1c4a0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e int eTextRep,con
1c4b0 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 st char*).);.int
1c4c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 sqlite3_collati
1c4d0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 on_needed16(. s
1c4e0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 qlite3*, . void
1c4f0 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 *,. void(*)(voi
1c500 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 d*,sqlite3*,int
1c510 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 eTextRep,const v
1c520 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 oid*).);../*.**
1c530 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 Specify the key
1c540 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 for an encrypted
1c550 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 database. This
1c560 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 routine should
1c570 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 be.** called rig
1c580 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 ht after sqlite3
1c590 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 _open()..**.** T
1c5a0 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 he code to imple
1c5b0 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 ment this API is
1c5c0 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 not available i
1c5d0 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c n the public rel
1c5e0 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 ease.** of SQLit
1c5f0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 e..*/.int sqlite
1c600 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 3_key(. sqlite3
1c610 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
1c620 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 /* Datab
1c630 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 ase to be rekeye
1c640 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 d */. const voi
1c650 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 d *pKey, int nKe
1c660 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 y /* The key
1c670 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 */.);../*.** Ch
1c680 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 ange the key on
1c690 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 an open database
1c6a0 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e . If the curren
1c6b0 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f t database is no
1c6c0 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 t.** encrypted,
1c6d0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c this routine wil
1c6e0 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 l encrypt it. I
1c6f0 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 f pNew==0 or nNe
1c700 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 w==0, the.** dat
1c710 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74 abase is decrypt
1c720 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f ed..**.** The co
1c730 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 de to implement
1c740 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 this API is not
1c750 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 available in the
1c760 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a public release.
1c770 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f ** of SQLite..*/
1c780 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b .int sqlite3_rek
1c790 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 ey(. sqlite3 *d
1c7a0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 b,
1c7b0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
1c7c0 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a to be rekeyed *
1c7d0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a /. const void *
1c7e0 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 pKey, int nKey
1c7f0 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 /* The new ke
1c800 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 y */.);../*.** C
1c810 41 50 49 33 52 45 46 3a 20 20 53 75 73 70 65 6e API3REF: Suspen
1c820 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 d Execution For
1c830 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a A Short Time.**.
1c840 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e ** This function
1c850 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72 causes the curr
1c860 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 ent thread to su
1c870 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a spend execution.
1c880 2a 2a 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d ** a number of m
1c890 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 illiseconds spec
1c8a0 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 ified in its par
1c8b0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 ameter..**.** If
1c8c0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 the operating s
1c8d0 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 ystem does not s
1c8e0 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 upport sleep req
1c8f0 75 65 73 74 73 20 77 69 74 68 20 0a 2a 2a 20 6d uests with .** m
1c900 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 illisecond time
1c910 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e resolution, then
1c920 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 the time will b
1c930 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 20 e rounded up to
1c940 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 .** the nearest
1c950 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 second. The numb
1c960 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e er of millisecon
1c970 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 ds of sleep actu
1c980 61 6c 6c 79 20 0a 2a 2a 20 72 65 71 75 65 73 74 ally .** request
1c990 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 ed from the oper
1c9a0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 ating system is
1c9b0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
1c9c0 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 SQLite implement
1c9d0 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 s this interface
1c9e0 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 by calling the
1c9f0 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 xSleep().** meth
1ca00 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c od of the defaul
1ca10 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 t [sqlite3_vfs]
1ca20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73 object..*/.int s
1ca30 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 qlite3_sleep(int
1ca40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1ca50 45 46 3a 20 20 4e 61 6d 65 20 4f 66 20 54 68 65 EF: Name Of The
1ca60 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 Folder Holding
1ca70 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a Temporary Files.
1ca80 2a 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20 67 6c **.** If this gl
1ca90 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 obal variable is
1caa0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 made to point t
1cab0 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 o a string which
1cac0 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 is.** the name
1cad0 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b of a folder (a.k
1cae0 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 a. directory), t
1caf0 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 hen all temporar
1cb00 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 y files.** creat
1cb10 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 69 6c ed by SQLite wil
1cb20 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 l be placed in t
1cb30 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 20 20 hat directory.
1cb40 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 If this variable
1cb50 0a 2a 2a 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e .** is NULL poin
1cb60 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 ter, then SQLite
1cb70 20 64 6f 65 73 20 61 20 73 65 61 72 63 68 20 66 does a search f
1cb80 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 or an appropriat
1cb90 65 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 66 e temporary.** f
1cba0 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a ile directory..*
1cbb0 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 *.** It is not s
1cbc0 61 66 65 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 afe to modify th
1cbd0 69 73 20 76 61 72 69 61 62 6c 65 20 6f 6e 63 65 is variable once
1cbe0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a database conn
1cbf0 65 63 74 69 6f 6e 0a 2a 2a 20 68 61 73 20 62 65 ection.** has be
1cc00 65 6e 20 6f 70 65 6e 65 64 2e 20 20 49 74 20 69 en opened. It i
1cc10 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 s intended that
1cc20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 this variable be
1cc30 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 set once.** as
1cc40 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 part of process
1cc50 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 initialization a
1cc60 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 nd before any SQ
1cc70 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a Lite interface.*
1cc80 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 * routines have
1cc90 62 65 65 6e 20 63 61 6c 6c 20 61 6e 64 20 72 65 been call and re
1cca0 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 74 main unchanged t
1ccb0 68 65 72 65 61 66 74 65 72 2e 0a 2a 2f 0a 53 51 hereafter..*/.SQ
1ccc0 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 LITE_EXTERN char
1ccd0 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 *sqlite3_temp_d
1cce0 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a irectory;../*.**
1ccf0 20 43 41 50 49 33 52 45 46 3a 20 20 54 65 73 74 CAPI3REF: Test
1cd00 20 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 44 To See If The D
1cd10 61 74 61 62 61 73 65 20 49 73 20 49 6e 20 41 75 atabase Is In Au
1cd20 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a to-Commit Mode.*
1cd30 2a 0a 2a 2a 20 54 65 73 74 20 74 6f 20 73 65 65 *.** Test to see
1cd40 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
1cd50 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
1cd60 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20 61 75 nection is in au
1cd70 74 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 6d 6f 64 65 tocommit.** mode
1cd80 2e 20 20 52 65 74 75 72 6e 20 54 52 55 45 20 69 . Return TRUE i
1cd90 66 20 69 74 20 69 73 20 61 6e 64 20 46 41 4c 53 f it is and FALS
1cda0 45 20 69 66 20 6e 6f 74 2e 20 20 41 75 74 6f 63 E if not. Autoc
1cdb0 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e ommit mode is on
1cdc0 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2e 20 .** by default.
1cdd0 20 41 75 74 6f 63 6f 6d 6d 69 74 20 69 73 20 64 Autocommit is d
1cde0 69 73 61 62 6c 65 64 20 62 79 20 61 20 42 45 47 isabled by a BEG
1cdf0 49 4e 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 IN statement and
1ce00 20 72 65 65 6e 61 62 6c 65 64 0a 2a 2a 20 62 79 reenabled.** by
1ce10 20 74 68 65 20 6e 65 78 74 20 43 4f 4d 4d 49 54 the next COMMIT
1ce20 20 6f 72 20 52 4f 4c 4c 42 41 43 4b 2e 0a 2a 2a or ROLLBACK..**
1ce30 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b .** If certain k
1ce40 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f inds of errors o
1ce50 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d ccur on a statem
1ce60 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c ent within a mul
1ce70 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 ti-statement.**
1ce80 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 28 65 72 transactions (er
1ce90 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b rors including [
1cea0 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 SQLITE_FULL], [S
1ceb0 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 20 0a 2a QLITE_IOERR], .*
1cec0 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d * [SQLITE_NOMEM]
1ced0 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c , [SQLITE_BUSY],
1cee0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 and [SQLITE_INT
1cef0 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68 ERRUPT]) then th
1cf00 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e e.** transaction
1cf10 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 might be rolled
1cf20 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 back automatica
1cf30 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 lly. The only w
1cf40 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 ay to.** find ou
1cf50 74 20 69 66 20 53 51 4c 69 74 65 20 61 75 74 6f t if SQLite auto
1cf60 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 matically rolled
1cf70 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 back the transa
1cf80 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 ction after.** a
1cf90 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 n error is to us
1cfa0 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e e this function.
1cfb0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 .**.** If anothe
1cfc0 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 r thread changes
1cfd0 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 the autocommit
1cfe0 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 status of the da
1cff0 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 tabase.** connec
1d000 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 tion while this
1d010 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 routine is runni
1d020 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 ng, then the ret
1d030 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 urn value.** is
1d040 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e undefined..*/.in
1d050 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 t sqlite3_get_au
1d060 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 tocommit(sqlite3
1d070 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
1d080 52 45 46 3a 20 20 46 69 6e 64 20 54 68 65 20 44 REF: Find The D
1d090 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 41 atabase Handle A
1d0a0 73 73 6f 63 69 61 74 65 64 20 57 69 74 68 20 41 ssociated With A
1d0b0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d Prepared Statem
1d0c0 65 6e 74 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e ent.**.** Return
1d0d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 the [sqlite3*]
1d0e0 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 database handle
1d0f0 74 6f 20 77 68 69 63 68 20 61 0a 2a 2a 20 5b 73 to which a.** [s
1d100 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 qlite3_stmt | pr
1d110 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1d120 5d 20 62 65 6c 6f 6e 67 73 2e 0a 2a 2a 20 54 68 ] belongs..** Th
1d130 69 73 20 69 73 20 74 68 65 20 73 61 6d 65 20 64 is is the same d
1d140 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74 atabase handle t
1d150 68 61 74 20 77 61 73 0a 2a 2a 20 74 68 65 20 66 hat was.** the f
1d160 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
1d170 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 the [sqlite3_pr
1d180 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 epare_v2()] or i
1d190 74 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a 20 74 ts variants.** t
1d1a0 68 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 20 hat was used to
1d1b0 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65 create the state
1d1c0 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 ment in the firs
1d1d0 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 t place..*/.sqli
1d1e0 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f te3 *sqlite3_db_
1d1f0 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 handle(sqlite3_s
1d200 74 6d 74 2a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 tmt*);.../*.** C
1d210 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 API3REF: Commit
1d220 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 And Rollback Not
1d230 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 ification Callba
1d240 63 6b 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 cks.**.** These
1d250 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 72 65 67 69 routines.** regi
1d260 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 ster callback fu
1d270 6e 63 74 69 6f 6e 73 20 74 6f 20 62 65 20 69 6e nctions to be in
1d280 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 voked whenever a
1d290 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 transaction.**
1d2a0 69 73 20 63 6f 6d 6d 69 74 74 65 64 20 6f 72 20 is committed or
1d2b0 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 20 20 54 68 rolled back. Th
1d2c0 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 e pArg argument
1d2d0 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 is passed throug
1d2e0 68 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c h.** to the call
1d2f0 62 61 63 6b 2e 20 20 49 66 20 74 68 65 20 63 61 back. If the ca
1d300 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d llback on a comm
1d310 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e it hook function
1d320 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e .** returns non
1d330 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 -zero, then the
1d340 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 commit is conver
1d350 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 ted into a rollb
1d360 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e ack..**.** If an
1d370 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 other function w
1d380 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 as previously re
1d390 67 69 73 74 65 72 65 64 2c 20 69 74 73 20 70 41 gistered, its pA
1d3a0 72 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 rg value is retu
1d3b0 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 rned..** Otherwi
1d3c0 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 se NULL is retur
1d3d0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 ned..**.** Regis
1d3e0 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 tering a NULL fu
1d3f0 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 nction disables
1d400 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a the callback..**
1d410 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70 .** For the purp
1d420 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 oses of this API
1d430 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 , a transaction
1d440 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 is said to have
1d450 62 65 65 6e 20 0a 2a 2a 20 72 6f 6c 6c 65 64 20 been .** rolled
1d460 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 back if an expli
1d470 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 cit "ROLLBACK" s
1d480 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 tatement is exec
1d490 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 uted, or.** an e
1d4a0 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 rror or constrai
1d4b0 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 nt causes an imp
1d4c0 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 licit rollback t
1d4d0 6f 20 6f 63 63 75 72 2e 20 54 68 65 20 0a 2a 2a o occur. The .**
1d4e0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 callback is not
1d4f0 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 invoked if a tr
1d500 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 ansaction is aut
1d510 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 omatically rolle
1d520 64 0a 2a 2a 20 62 61 63 6b 20 62 65 63 61 75 73 d.** back becaus
1d530 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 e the database c
1d540 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f onnection is clo
1d550 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 sed..**.** These
1d560 20 61 72 65 20 65 78 70 65 72 69 6d 65 6e 74 61 are experimenta
1d570 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 6e 64 l interfaces and
1d580 20 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 are subject to
1d590 63 68 61 6e 67 65 2e 0a 2a 2f 0a 76 6f 69 64 20 change..*/.void
1d5a0 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f *sqlite3_commit_
1d5b0 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 hook(sqlite3*, i
1d5c0 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f nt(*)(void*), vo
1d5d0 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 id*);.void *sqli
1d5e0 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f te3_rollback_hoo
1d5f0 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 k(sqlite3*, void
1d600 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 (*)(void *), voi
1d610 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d*);../*.** CAPI
1d620 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 3REF: Data Chang
1d630 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 e Notification C
1d640 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 52 allbacks.**.** R
1d650 65 67 69 73 74 65 72 20 61 20 63 61 6c 6c 62 61 egister a callba
1d660 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 ck function with
1d670 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
1d680 6e 6e 65 63 74 69 6f 6e 20 69 64 65 6e 74 69 66 nnection identif
1d690 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 ied by the .** f
1d6a0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
1d6b0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e be invoked when
1d6c0 65 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 ever a row is up
1d6d0 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 dated, inserted
1d6e0 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 or deleted..** A
1d6f0 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 ny callback set
1d700 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 by a previous ca
1d710 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 ll to this funct
1d720 69 6f 6e 20 66 6f 72 20 74 68 65 20 73 61 6d 65 ion for the same
1d730 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f .** database co
1d740 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 nnection is over
1d750 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 ridden..**.** Th
1d760 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
1d770 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 t is a pointer t
1d780 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 o the function t
1d790 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 20 o invoke when a
1d7a0 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 .** row is updat
1d7b0 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 ed, inserted or
1d7c0 64 65 6c 65 74 65 64 2e 20 54 68 65 20 66 69 72 deleted. The fir
1d7d0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 st argument to t
1d7e0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a he callback is.*
1d7f0 2a 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 * a copy of the
1d800 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 third argument t
1d810 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 o sqlite3_update
1d820 5f 68 6f 6f 6b 28 29 2e 20 54 68 65 20 73 65 63 _hook(). The sec
1d830 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a ond callback .**
1d840 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 argument is one
1d850 20 6f 66 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 of SQLITE_INSER
1d860 54 2c 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 T, SQLITE_DELETE
1d870 20 6f 72 20 53 51 4c 49 54 45 5f 55 50 44 41 54 or SQLITE_UPDAT
1d880 45 2c 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 E, depending.**
1d890 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e on the operation
1d8a0 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65 that caused the
1d8b0 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 callback to be
1d8c0 69 6e 76 6f 6b 65 64 2e 20 54 68 65 20 74 68 69 invoked. The thi
1d8d0 72 64 20 61 6e 64 20 0a 2a 2a 20 66 6f 75 72 74 rd and .** fourt
1d8e0 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 h arguments to t
1d8f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 he callback cont
1d900 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 ain pointers to
1d910 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 the database and
1d920 20 0a 2a 2a 20 74 61 62 6c 65 20 6e 61 6d 65 20 .** table name
1d930 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 containing the a
1d940 66 66 65 63 74 65 64 20 72 6f 77 2e 20 54 68 65 ffected row. The
1d950 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 final callback
1d960 70 61 72 61 6d 65 74 65 72 20 69 73 20 0a 2a 2a parameter is .**
1d970 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 the rowid of th
1d980 65 20 72 6f 77 2e 20 49 6e 20 74 68 65 20 63 61 e row. In the ca
1d990 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65 2c se of an update,
1d9a0 20 74 68 69 73 20 69 73 20 74 68 65 20 72 6f 77 this is the row
1d9b0 69 64 20 61 66 74 65 72 20 0a 2a 2a 20 74 68 65 id after .** the
1d9c0 20 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c update takes pl
1d9d0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 ace..**.** The u
1d9e0 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f pdate hook is no
1d9f0 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 t invoked when i
1da00 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 nternal system t
1da10 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 ables are.** mod
1da20 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 ified (i.e. sqli
1da30 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 te_master and sq
1da40 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 0a lite_sequence)..
1da50 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 **.** If another
1da60 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 function was pr
1da70 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 eviously registe
1da80 72 65 64 2c 20 69 74 73 20 70 41 72 67 20 76 61 red, its pArg va
1da90 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e lue is returned.
1daa0 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 20 4e 55 .** Otherwise NU
1dab0 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a LL is returned..
1dac0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 */.void *sqlite3
1dad0 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 _update_hook(.
1dae0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 sqlite3*, . voi
1daf0 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 d(*)(void *,int
1db00 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 ,char const *,ch
1db10 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 ar const *,sqlit
1db20 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 e3_int64),. voi
1db30 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 d*.);../*.** CAP
1db40 49 33 52 45 46 3a 20 20 45 6e 61 62 6c 65 20 4f I3REF: Enable O
1db50 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64 r Disable Shared
1db60 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 0a Pager Cache.**.
1db70 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
1db80 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 enables or disab
1db90 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 les the sharing
1dba0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 of the database
1dbb0 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 cache.** and sch
1dbc0 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75 ema data structu
1dbd0 72 65 73 20 62 65 74 77 65 65 6e 20 63 6f 6e 6e res between conn
1dbe0 65 63 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 73 ections to the s
1dbf0 61 6d 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a ame database..**
1dc00 20 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 Sharing is enab
1dc10 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d led if the argum
1dc20 65 6e 74 20 69 73 20 74 72 75 65 20 61 6e 64 20 ent is true and
1dc30 64 69 73 61 62 6c 65 64 20 69 66 20 74 68 65 20 disabled if the
1dc40 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 66 argument.** is f
1dc50 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 42 65 67 69 alse..**.** Begi
1dc60 6e 6e 69 6e 67 20 69 6e 20 53 51 4c 69 74 65 20 nning in SQLite
1dc70 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 63 version 3.5.0, c
1dc80 61 63 68 65 20 73 68 61 72 69 6e 67 20 69 73 20 ache sharing is
1dc90 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73 61 enabled and disa
1dca0 62 6c 65 64 0a 2a 2a 20 66 6f 72 20 61 6e 20 65 bled.** for an e
1dcb0 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 20 20 ntire process.
1dcc0 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e In prior version
1dcd0 73 20 6f 66 20 53 51 4c 69 74 65 2c 20 73 68 61 s of SQLite, sha
1dce0 72 69 6e 67 20 77 61 73 0a 2a 2a 20 65 6e 61 62 ring was.** enab
1dcf0 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 led or disabled
1dd00 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20 for each thread
1dd10 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a separately..**.*
1dd20 2a 20 54 68 65 20 63 61 63 68 65 20 73 68 61 72 * The cache shar
1dd30 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20 ing mode set by
1dd40 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 65 this interface e
1dd50 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65 ffects all subse
1dd60 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 quent.** calls t
1dd70 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 o [sqlite3_open(
1dd80 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
1dd90 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 n_v2()], and [sq
1dda0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e lite3_open16()].
1ddb0 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74 .** Existing dat
1ddc0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1ddd0 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74 s continue use t
1dde0 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 he sharing mode
1ddf0 74 68 61 74 20 77 61 73 0a 2a 2a 20 69 6e 20 65 that was.** in e
1de00 66 66 65 63 74 20 61 74 20 74 68 65 20 74 69 6d ffect at the tim
1de10 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e e they were open
1de20 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 ed..**.** Virtua
1de30 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f 74 20 l tables cannot
1de40 62 65 20 75 73 65 64 20 77 69 74 68 20 61 20 73 be used with a s
1de50 68 61 72 65 64 20 63 61 63 68 65 2e 20 20 57 68 hared cache. Wh
1de60 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 en shared.** cac
1de70 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 74 he is enabled, t
1de80 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 he [sqlite3_crea
1de90 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41 50 49 te_module()] API
1dea0 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 used to registe
1deb0 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 r.** virtual tab
1dec0 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 les will always
1ded0 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e return an error.
1dee0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
1def0 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ine returns [SQL
1df00 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 ITE_OK] if share
1df10 64 20 63 61 63 68 65 20 77 61 73 0a 2a 2a 20 65 d cache was.** e
1df20 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c nabled or disabl
1df30 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e ed successfully.
1df40 20 20 41 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 An [SQLITE_ERR
1df50 4f 52 20 7c 20 65 72 72 6f 72 20 63 6f 64 65 5d OR | error code]
1df60 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 .** is returned
1df70 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a otherwise..**.**
1df80 20 53 68 61 72 65 64 20 63 61 63 68 65 20 69 73 Shared cache is
1df90 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 disabled by def
1dfa0 61 75 6c 74 2e 20 20 42 75 74 20 74 68 69 73 20 ault. But this
1dfb0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a might change in.
1dfc0 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 ** future releas
1dfd0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 es of SQLite. A
1dfe0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 pplications that
1dff0 20 63 61 72 65 20 61 62 6f 75 74 20 73 68 61 72 care about shar
1e000 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74 ed.** cache sett
1e010 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69 ing should set i
1e020 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2f t explicitly..*/
1e030 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 .int sqlite3_ena
1e040 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 ble_shared_cache
1e050 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 (int);../*.** CA
1e060 50 49 33 52 45 46 3a 20 20 41 74 74 65 6d 70 74 PI3REF: Attempt
1e070 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65 To Free Heap Me
1e080 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 41 74 74 65 6d mory.**.** Attem
1e090 70 74 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 pt to free N byt
1e0a0 65 73 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 es of heap memor
1e0b0 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e y by deallocatin
1e0c0 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 0a g non-essential.
1e0d0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ** memory alloca
1e0e0 74 69 6f 6e 73 20 68 65 6c 64 20 62 79 20 74 68 tions held by th
1e0f0 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61 e database libra
1e100 72 79 20 28 65 78 61 6d 70 6c 65 3a 20 6d 65 6d ry (example: mem
1e110 6f 72 79 20 0a 2a 2a 20 75 73 65 64 20 74 6f 20 ory .** used to
1e120 63 61 63 68 65 20 64 61 74 61 62 61 73 65 20 70 cache database p
1e130 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 ages to improve
1e140 70 65 72 66 6f 72 6d 61 6e 63 65 29 2e 0a 2a 2f performance)..*/
1e150 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c .int sqlite3_rel
1e160 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 ease_memory(int)
1e170 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1e180 46 3a 20 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d F: Impose A Lim
1e190 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a it On Heap Size.
1e1a0 2a 2a 0a 2a 2a 20 50 6c 61 63 65 20 61 20 22 73 **.** Place a "s
1e1b0 6f 66 74 22 20 6c 69 6d 69 74 20 6f 6e 20 74 68 oft" limit on th
1e1c0 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 e amount of heap
1e1d0 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 memory that may
1e1e0 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a be allocated.**
1e1f0 20 62 79 20 53 51 4c 69 74 65 2e 20 20 49 66 20 by SQLite. If
1e200 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f an internal allo
1e210 63 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 cation is reques
1e220 74 65 64 20 0a 2a 2a 20 74 68 61 74 20 77 6f 75 ted .** that wou
1e230 6c 64 20 65 78 63 65 65 64 20 74 68 65 20 73 70 ld exceed the sp
1e240 65 63 69 66 69 65 64 20 6c 69 6d 69 74 2c 20 5b ecified limit, [
1e250 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f sqlite3_release_
1e260 6d 65 6d 6f 72 79 28 29 5d 20 69 73 0a 2a 2a 20 memory()] is.**
1e270 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 20 6d invoked one or m
1e280 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 66 72 65 ore times to fre
1e290 65 20 75 70 20 73 6f 6d 65 20 73 70 61 63 65 20 e up some space
1e2a0 62 65 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63 before the alloc
1e2b0 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6d 61 64 65 ation.** is made
1e2c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 6d 69 ..**.** The limi
1e2d0 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73 6f 66 t is called "sof
1e2e0 74 22 2c 20 62 65 63 61 75 73 65 20 69 66 20 5b t", because if [
1e2f0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f sqlite3_release_
1e300 6d 65 6d 6f 72 79 28 29 5d 20 63 61 6e 6e 6f 74 memory()] cannot
1e310 0a 2a 2a 20 66 72 65 65 20 73 75 66 66 69 63 69 .** free suffici
1e320 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 ent memory to pr
1e330 65 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 event the limit
1e340 66 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65 65 from being excee
1e350 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f ded,.** the memo
1e360 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 ry is allocated
1e370 61 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20 63 anyway and the c
1e380 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e urrent operation
1e390 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a proceeds..**.**
1e3a0 20 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a A negative or z
1e3b0 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 ero value for N
1e3c0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 72 65 means that there
1e3d0 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65 61 70 is no soft heap
1e3e0 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 limit and.** [s
1e3f0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d qlite3_release_m
1e400 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e emory()] will on
1e410 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 ly be called whe
1e420 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78 68 61 n memory is exha
1e430 75 73 74 65 64 2e 0a 2a 2a 20 54 68 65 20 64 65 usted..** The de
1e440 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 fault value for
1e450 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 the soft heap li
1e460 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a mit is zero..**.
1e470 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 ** SQLite makes
1e480 61 20 62 65 73 74 20 65 66 66 6f 72 74 20 74 6f a best effort to
1e490 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f 66 74 20 honor the soft
1e4a0 68 65 61 70 20 6c 69 6d 69 74 2e 20 20 42 75 74 heap limit. But
1e4b0 20 69 66 20 69 74 0a 2a 2a 20 69 73 20 75 6e 61 if it.** is una
1e4c0 62 6c 65 20 74 6f 20 72 65 64 75 63 65 20 6d 65 ble to reduce me
1e4d0 6d 6f 72 79 20 75 73 61 67 65 20 62 65 6c 6f 77 mory usage below
1e4e0 20 74 68 65 20 73 6f 66 74 20 6c 69 6d 69 74 2c the soft limit,
1e4f0 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a execution will.
1e500 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 ** continue with
1e510 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 out error or not
1e520 69 66 69 63 61 74 69 6f 6e 2e 20 20 54 68 69 73 ification. This
1e530 20 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d 69 is why the limi
1e540 74 20 69 73 20 0a 2a 2a 20 63 61 6c 6c 65 64 20 t is .** called
1e550 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20 a "soft" limit.
1e560 20 49 74 20 69 73 20 61 64 76 69 73 6f 72 79 20 It is advisory
1e570 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f only..**.** Prio
1e580 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 r to SQLite vers
1e590 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20 ion 3.5.0, this
1e5a0 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e routine only con
1e5b0 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d strained the mem
1e5c0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 ory.** allocated
1e5d0 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 by a single thr
1e5e0 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74 ead - the same t
1e5f0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74 hread in which t
1e600 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 his routine.** r
1e610 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 uns. Beginning
1e620 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73 with SQLite vers
1e630 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73 ion 3.5.0, the s
1e640 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 oft heap limit i
1e650 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20 s.** applied to
1e660 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 20 54 68 all threads. Th
1e670 65 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 e value specifie
1e680 64 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 d for the soft h
1e690 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 eap limit.** is
1e6a0 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f an upper bound o
1e6b0 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f n the total memo
1e6c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f ry allocation fo
1e6d0 72 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 20 r all threads.
1e6e0 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e In.** version 3.
1e6f0 35 2e 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20 5.0 there is no
1e700 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 mechanism for li
1e710 6d 69 74 69 6e 67 20 74 68 65 20 68 65 61 70 20 miting the heap
1e720 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 usage for.** ind
1e730 69 76 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e ividual threads.
1e740 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 .*/.void sqlite3
1e750 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 _soft_heap_limit
1e760 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 (int);../*.** CA
1e770 50 49 33 52 45 46 3a 20 20 45 78 74 72 61 63 74 PI3REF: Extract
1e780 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74 20 Metadata About
1e790 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 A Column Of A Ta
1e7a0 62 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 ble.**.** This r
1e7b0 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 74 75 72 6e outine.** return
1e7c0 73 20 6d 65 74 61 2d 64 61 74 61 20 61 62 6f 75 s meta-data abou
1e7d0 74 20 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c t a specific col
1e7e0 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69 66 69 umn of a specifi
1e7f0 63 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 c database.** ta
1e800 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65 20 75 ble accessible u
1e810 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74 sing the connect
1e820 69 6f 6e 20 68 61 6e 64 6c 65 20 70 61 73 73 65 ion handle passe
1e830 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 66 d as the first f
1e840 75 6e 63 74 69 6f 6e 20 0a 2a 2a 20 61 72 67 75 unction .** argu
1e850 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ment..**.** The
1e860 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 column is identi
1e870 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63 6f fied by the seco
1e880 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66 6f nd, third and fo
1e890 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 urth parameters
1e8a0 74 6f 20 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 to .** this func
1e8b0 74 69 6f 6e 2e 20 54 68 65 20 73 65 63 6f 6e 64 tion. The second
1e8c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 65 69 parameter is ei
1e8d0 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 ther the name of
1e8e0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a the database.**
1e8f0 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 (i.e. "main", "
1e900 74 65 6d 70 22 20 6f 72 20 61 6e 20 61 74 74 61 temp" or an atta
1e910 63 68 65 64 20 64 61 74 61 62 61 73 65 29 20 63 ched database) c
1e920 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70 ontaining the sp
1e930 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 ecified.** table
1e940 20 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 69 74 20 or NULL. If it
1e950 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c is NULL, then al
1e960 6c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 l attached datab
1e970 61 73 65 73 20 61 72 65 20 73 65 61 72 63 68 65 ases are searche
1e980 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62 d.** for the tab
1e990 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d le using the sam
1e9a0 65 20 61 6c 67 6f 72 69 74 68 6d 20 61 73 20 74 e algorithm as t
1e9b0 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 he database engi
1e9c0 6e 65 20 75 73 65 73 20 74 6f 20 0a 2a 2a 20 72 ne uses to .** r
1e9d0 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 esolve unqualifi
1e9e0 65 64 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e ed table referen
1e9f0 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 ces..**.** The t
1ea00 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 hird and fourth
1ea10 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 parameters to th
1ea20 69 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 is function are
1ea30 74 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f the table and co
1ea40 6c 75 6d 6e 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66 lumn .** name of
1ea50 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c the desired col
1ea60 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c umn, respectivel
1ea70 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 y. Neither of th
1ea80 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 20 0a ese parameters .
1ea90 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a ** may be NULL..
1eaa0 2a 2a 0a 2a 2a 20 4d 65 74 61 20 69 6e 66 6f 72 **.** Meta infor
1eab0 6d 61 74 69 6f 6e 20 69 73 20 72 65 74 75 72 6e mation is return
1eac0 65 64 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f ed by writing to
1ead0 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 the memory loca
1eae0 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73 0a tions passed as.
1eaf0 2a 2a 20 74 68 65 20 35 74 68 20 61 6e 64 20 73 ** the 5th and s
1eb00 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 ubsequent parame
1eb10 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e ters to this fun
1eb20 63 74 69 6f 6e 2e 20 41 6e 79 20 6f 66 20 74 68 ction. Any of th
1eb30 65 73 65 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 ese .** argument
1eb40 73 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2c 20 69 s may be NULL, i
1eb50 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 n which case the
1eb60 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 corresponding e
1eb70 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 20 0a lement of meta .
1eb80 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 ** information i
1eb90 73 20 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a s ommitted..**.*
1eba0 2a 20 3c 70 72 65 3e 0a 2a 2a 20 50 61 72 61 6d * <pre>.** Param
1ebb0 65 74 65 72 20 20 20 20 20 4f 75 74 70 75 74 20 eter Output
1ebc0 54 79 70 65 20 20 20 20 20 20 44 65 73 63 72 69 Type Descri
1ebd0 70 74 69 6f 6e 0a 2a 2a 20 2d 2d 2d 2d 2d 2d 2d ption.** -------
1ebe0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
1ebf0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 0a ------------.**.
1ec00 2a 2a 20 20 20 35 74 68 20 20 20 20 20 20 20 20 ** 5th
1ec10 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 20 20 20 const char*
1ec20 20 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 20 Data type.**
1ec30 20 36 74 68 20 20 20 20 20 20 20 20 20 63 6f 6e 6th con
1ec40 73 74 20 63 68 61 72 2a 20 20 20 20 20 20 4e 61 st char* Na
1ec50 6d 65 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c me of the defaul
1ec60 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 t collation sequ
1ec70 65 6e 63 65 20 0a 2a 2a 20 20 20 37 74 68 20 20 ence .** 7th
1ec80 20 20 20 20 20 20 20 69 6e 74 20 20 20 20 20 20 int
1ec90 20 20 20 20 20 20 20 20 54 72 75 65 20 69 66 20 True if
1eca0 74 68 65 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 the column has a
1ecb0 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 NOT NULL constr
1ecc0 61 69 6e 74 0a 2a 2a 20 20 20 38 74 68 20 20 20 aint.** 8th
1ecd0 20 20 20 20 20 20 69 6e 74 20 20 20 20 20 20 20 int
1ece0 20 20 20 20 20 20 20 54 72 75 65 20 69 66 20 74 True if t
1ecf0 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 he column is par
1ed00 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59 t of the PRIMARY
1ed10 20 4b 45 59 0a 2a 2a 20 20 20 39 74 68 20 20 20 KEY.** 9th
1ed20 20 20 20 20 20 20 69 6e 74 20 20 20 20 20 20 20 int
1ed30 20 20 20 20 20 20 20 54 72 75 65 20 69 66 20 74 True if t
1ed40 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 41 55 54 he column is AUT
1ed50 4f 49 4e 43 52 45 4d 45 4e 54 0a 2a 2a 20 3c 2f OINCREMENT.** </
1ed60 70 72 65 3e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 pre>.**.**.** Th
1ed70 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 e memory pointed
1ed80 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 61 to by the chara
1ed90 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65 cter pointers re
1eda0 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 20 0a turned for the .
1edb0 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 ** declaration t
1edc0 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f ype and collatio
1edd0 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 n sequence is va
1ede0 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 lid only until t
1edf0 68 65 20 6e 65 78 74 20 0a 2a 2a 20 63 61 6c 6c he next .** call
1ee00 20 74 6f 20 61 6e 79 20 73 71 6c 69 74 65 20 41 to any sqlite A
1ee10 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a PI function..**.
1ee20 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63 69 66 ** If the specif
1ee30 69 65 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 ied table is act
1ee40 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 74 68 ually a view, th
1ee50 65 6e 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 en an error is r
1ee60 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 eturned..**.** I
1ee70 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 f the specified
1ee80 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 column is "rowid
1ee90 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f ", "oid" or "_ro
1eea0 77 69 64 5f 22 20 61 6e 64 20 61 6e 20 0a 2a 2a wid_" and an .**
1eeb0 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 INTEGER PRIMARY
1eec0 20 4b 45 59 20 63 6f 6c 75 6d 6e 20 68 61 73 20 KEY column has
1eed0 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 been explicitly
1eee0 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 declared, then t
1eef0 68 65 20 6f 75 74 70 75 74 20 0a 2a 2a 20 70 61 he output .** pa
1ef00 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 rameters are set
1ef10 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 for the explici
1ef20 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c tly declared col
1ef30 75 6d 6e 2e 20 49 66 20 74 68 65 72 65 20 69 73 umn. If there is
1ef40 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c no.** explicitl
1ef50 79 20 64 65 63 6c 61 72 65 64 20 49 50 4b 20 63 y declared IPK c
1ef60 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 olumn, then the
1ef70 6f 75 74 70 75 74 20 70 61 72 61 6d 65 74 65 72 output parameter
1ef80 73 20 61 72 65 20 73 65 74 20 61 73 20 0a 2a 2a s are set as .**
1ef90 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 follows:.**.**
1efa0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74 <pre>.** dat
1efb0 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52 a type: "INTEGER
1efc0 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69 ".** collati
1efd0 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49 on sequence: "BI
1efe0 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 NARY".** not
1eff0 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 null: 0.**
1f000 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a primary key: 1.*
1f010 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65 * auto incre
1f020 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 ment: 0.** </pre
1f030 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e >.**.** This fun
1f040 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f ction may load o
1f050 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d ne or more schem
1f060 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65 as from database
1f070 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a files. If an.**
1f080 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 error occurs du
1f090 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73 ring this proces
1f0a0 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 71 s, or if the req
1f0b0 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20 uested table or
1f0c0 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 column.** cannot
1f0d0 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 53 51 be found, an SQ
1f0e0 4c 49 54 45 20 65 72 72 6f 72 20 63 6f 64 65 20 LITE error code
1f0f0 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 is returned and
1f100 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 an error message
1f110 0a 2a 2a 20 6c 65 66 74 20 69 6e 20 74 68 65 20 .** left in the
1f120 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 database handle
1f130 28 74 6f 20 62 65 20 72 65 74 72 69 65 76 65 64 (to be retrieved
1f140 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 65 using sqlite3_e
1f150 72 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a 2a 20 rrmsg())..**.**
1f160 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 This API is only
1f170 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 available if th
1f180 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f e library was co
1f190 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a mpiled with the.
1f1a0 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 ** SQLITE_ENABLE
1f1b0 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 _COLUMN_METADATA
1f1c0 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 preprocessor sy
1f1d0 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f mbol defined..*/
1f1e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62 .int sqlite3_tab
1f1f0 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 le_column_metada
1f200 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 ta(. sqlite3 *d
1f210 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 b,
1f220 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 /* Connection
1f230 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
1f240 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c t char *zDbName,
1f250 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 /* Datab
1f260 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c ase name or NULL
1f270 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
1f280 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 *zTableName,
1f290 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 /* Table name
1f2a0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
1f2b0 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 *zColumnName,
1f2c0 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 /* Column name
1f2d0 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 */. char const
1f2e0 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20 **pzDataType,
1f2f0 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c /* OUTPUT: Decl
1f300 61 72 65 64 20 64 61 74 61 20 74 79 70 65 20 2a ared data type *
1f310 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a /. char const *
1f320 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 *pzCollSeq,
1f330 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 /* OUTPUT: Colla
1f340 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 tion sequence na
1f350 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f me */. int *pNo
1f360 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 tNull,
1f370 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 /* OUTPUT: T
1f380 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 rue if NOT NULL
1f390 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74 constraint exist
1f3a0 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 s */. int *pPri
1f3b0 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20 maryKey,
1f3c0 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 /* OUTPUT: Tr
1f3d0 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 ue if column par
1f3e0 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 t of PK */. int
1f3f0 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20 *pAutoinc
1f400 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 /* OUTP
1f410 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 UT: True if colu
1f420 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 mn is auto-incre
1f430 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a ment */.);../*.*
1f440 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 * CAPI3REF: Load
1f450 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a An Extension.**
1f460 0a 2a 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 6c .** Attempt to l
1f470 6f 61 64 20 61 6e 20 53 51 4c 69 74 65 20 65 78 oad an SQLite ex
1f480 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 tension library
1f490 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65 contained in the
1f4a0 20 66 69 6c 65 0a 2a 2a 20 7a 46 69 6c 65 2e 20 file.** zFile.
1f4b0 20 54 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 The entry point
1f4c0 20 69 73 20 7a 50 72 6f 63 2e 20 20 7a 50 72 6f is zProc. zPro
1f4d0 63 20 6d 61 79 20 62 65 20 30 20 69 6e 20 77 68 c may be 0 in wh
1f4e0 69 63 68 20 63 61 73 65 20 74 68 65 0a 2a 2a 20 ich case the.**
1f4f0 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72 name of the entr
1f500 79 20 70 6f 69 6e 74 20 64 65 66 61 75 6c 74 73 y point defaults
1f510 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74 to "sqlite3_ext
1f520 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a ension_init"..**
1f530 0a 2a 2a 20 52 65 74 75 72 6e 20 5b 53 51 4c 49 .** Return [SQLI
1f540 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 TE_OK] on succes
1f550 73 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52 s and [SQLITE_ER
1f560 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e ROR] if somethin
1f570 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a g goes wrong..**
1f580 0a 2a 2a 20 49 66 20 61 6e 20 65 72 72 6f 72 20 .** If an error
1f590 6f 63 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72 occurs and pzErr
1f5a0 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 Msg is not 0, th
1f5b0 65 6e 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 en fill *pzErrMs
1f5c0 67 20 77 69 74 68 20 0a 2a 2a 20 65 72 72 6f 72 g with .** error
1f5d0 20 6d 65 73 73 61 67 65 20 74 65 78 74 2e 20 20 message text.
1f5e0 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 The calling func
1f5f0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 66 72 65 65 tion should free
1f600 20 74 68 69 73 20 6d 65 6d 6f 72 79 0a 2a 2a 20 this memory.**
1f610 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 by calling [sqli
1f620 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a te3_free()]..**.
1f630 2a 2a 20 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 ** Extension loa
1f640 64 69 6e 67 20 6d 75 73 74 20 62 65 20 65 6e 61 ding must be ena
1f650 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 bled using [sqli
1f660 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f te3_enable_load_
1f670 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 extension()].**
1f680 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 prior to calling
1f690 20 74 68 69 73 20 41 50 49 20 6f 72 20 61 6e 20 this API or an
1f6a0 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 error will be re
1f6b0 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 turned..*/.int s
1f6c0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 qlite3_load_exte
1f6d0 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 nsion(. sqlite3
1f6e0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f *db, /
1f6f0 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65 6e * Load the exten
1f700 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20 64 sion into this d
1f710 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1f720 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 on */. const ch
1f730 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a ar *zFile, /*
1f740 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68 61 Name of the sha
1f750 72 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 red library cont
1f760 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e aining extension
1f770 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
1f780 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45 *zProc, /* E
1f790 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65 72 ntry point. Der
1f7a0 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20 ived from zFile
1f7b0 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a if 0 */. char *
1f7c0 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20 *pzErrMsg
1f7d0 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65 73 /* Put error mes
1f7e0 73 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f 74 sage here if not
1f7f0 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 0 */.);../*.**
1f800 43 41 50 49 33 52 45 46 3a 20 20 45 6e 61 62 6c CAPI3REF: Enabl
1f810 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 e Or Disable Ext
1f820 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a ension Loading.*
1f830 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f 74 20 74 *.** So as not t
1f840 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20 o open security
1f850 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61 holes in older a
1f860 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 pplications that
1f870 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72 are.** unprepar
1f880 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 ed to deal with
1f890 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e extension loadin
1f8a0 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e g, and as a mean
1f8b0 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a s of disabling.*
1f8c0 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 * extension load
1f8d0 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61 ing while evalua
1f8e0 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65 ting user-entere
1f8f0 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f d SQL, the follo
1f900 77 69 6e 67 0a 2a 2a 20 41 50 49 20 69 73 20 70 wing.** API is p
1f910 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20 rovided to turn
1f920 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 the [sqlite3_loa
1f930 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d d_extension()] m
1f940 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 0a echanism on and.
1f950 2a 2a 20 6f 66 66 2e 20 20 49 74 20 69 73 20 6f ** off. It is o
1f960 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 ff by default.
1f970 53 65 65 20 74 69 63 6b 65 74 20 23 31 38 36 33 See ticket #1863
1f980 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 20 74 68 69 ..**.** Call thi
1f990 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 6f s routine with o
1f9a0 6e 6f 66 66 3d 3d 31 20 74 6f 20 74 75 72 6e 20 noff==1 to turn
1f9b0 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e extension loadin
1f9c0 67 20 6f 6e 0a 2a 2a 20 61 6e 64 20 63 61 6c 6c g on.** and call
1f9d0 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d it with onoff==
1f9e0 30 20 74 6f 20 74 75 72 6e 20 69 74 20 62 61 63 0 to turn it bac
1f9f0 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2f 0a k off again..*/.
1fa00 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 int sqlite3_enab
1fa10 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f le_load_extensio
1fa20 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 69 n(sqlite3 *db, i
1fa30 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a nt onoff);../*.*
1fa40 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 6b 65 * CAPI3REF: Make
1fa50 20 41 72 72 61 6e 67 65 6d 65 6e 74 73 20 54 6f Arrangements To
1fa60 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c Automatically L
1fa70 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e oad An Extension
1fa80 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 20 .**.** Register
1fa90 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 an extension ent
1faa0 72 79 20 70 6f 69 6e 74 20 74 68 61 74 20 69 73 ry point that is
1fab0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 automatically i
1fac0 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 65 76 nvoked.** whenev
1fad0 65 72 20 61 20 6e 65 77 20 64 61 74 61 62 61 73 er a new databas
1fae0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
1faf0 6f 70 65 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 opened using.**
1fb00 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
1fb10 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 , [sqlite3_open1
1fb20 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 6()], or [sqlite
1fb30 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 3_open_v2()]..**
1fb40 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 63 61 6e .** This API can
1fb50 20 62 65 20 69 6e 76 6f 6b 65 64 20 61 74 20 70 be invoked at p
1fb60 72 6f 67 72 61 6d 20 73 74 61 72 74 75 70 20 69 rogram startup i
1fb70 6e 20 6f 72 64 65 72 20 74 6f 20 72 65 67 69 73 n order to regis
1fb80 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f ter.** one or mo
1fb90 72 65 20 73 74 61 74 69 63 61 6c 6c 79 20 6c 69 re statically li
1fba0 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f 6e 73 20 nked extensions
1fbb0 74 68 61 74 20 77 69 6c 6c 20 62 65 20 61 76 61 that will be ava
1fbc0 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c ilable.** to all
1fbd0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f new database co
1fbe0 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a nnections..**.**
1fbf0 20 44 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e Duplicate exten
1fc00 73 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74 sions are detect
1fc10 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68 ed so calling th
1fc20 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 6c 74 69 is routine multi
1fc30 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 ple.** times wit
1fc40 68 20 74 68 65 20 73 61 6d 65 20 65 78 74 65 6e h the same exten
1fc50 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73 73 sion is harmless
1fc60 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 ..**.** This rou
1fc70 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20 70 6f tine stores a po
1fc80 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65 78 74 inter to the ext
1fc90 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72 72 ension in an arr
1fca0 61 79 0a 2a 2a 20 74 68 61 74 20 69 73 20 6f 62 ay.** that is ob
1fcb0 74 61 69 6e 65 64 20 66 72 6f 6d 20 6d 61 6c 6c tained from mall
1fcc0 6f 63 28 29 2e 20 20 49 66 20 79 6f 75 20 72 75 oc(). If you ru
1fcd0 6e 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 0a n a memory leak.
1fce0 2a 2a 20 63 68 65 63 6b 65 72 20 6f 6e 20 79 6f ** checker on yo
1fcf0 75 72 20 70 72 6f 67 72 61 6d 20 61 6e 64 20 69 ur program and i
1fd00 74 20 72 65 70 6f 72 74 73 20 61 20 6c 65 61 6b t reports a leak
1fd10 20 62 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 because of this
1fd20 0a 2a 2a 20 61 72 72 61 79 2c 20 74 68 65 6e 20 .** array, then
1fd30 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f invoke [sqlite3_
1fd40 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e reset_auto_exten
1fd50 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 0a 2a 2a sion()] prior.**
1fd60 20 74 6f 20 73 68 75 74 64 6f 77 6e 20 74 6f 20 to shutdown to
1fd70 66 72 65 65 20 74 68 65 20 6d 65 6d 6f 72 79 2e free the memory.
1fd80 0a 2a 2a 0a 2a 2a 20 41 75 74 6f 6d 61 74 69 63 .**.** Automatic
1fd90 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c extensions appl
1fda0 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 y across all thr
1fdb0 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 eads..**.** This
1fdc0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 interface is ex
1fdd0 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 perimental and i
1fde0 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 s subject to cha
1fdf0 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 nge or.** remova
1fe00 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 l in future rele
1fe10 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ases of SQLite..
1fe20 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 */.int sqlite3_a
1fe30 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f uto_extension(vo
1fe40 69 64 20 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29 id *xEntryPoint)
1fe50 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 ;.../*.** CAPI3R
1fe60 45 46 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61 EF: Reset Automa
1fe70 74 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f tic Extension Lo
1fe80 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 44 69 73 61 ading.**.** Disa
1fe90 62 6c 65 20 61 6c 6c 20 70 72 65 76 69 6f 75 73 ble all previous
1fea0 6c 79 20 72 65 67 69 73 74 65 72 65 64 20 61 75 ly registered au
1feb0 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f tomatic extensio
1fec0 6e 73 2e 20 20 54 68 69 73 0a 2a 2a 20 72 6f 75 ns. This.** rou
1fed0 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 tine undoes the
1fee0 65 66 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72 effect of all pr
1fef0 69 6f 72 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 ior [sqlite3_aut
1ff00 6f 6d 61 74 69 63 5f 65 78 74 65 6e 73 69 6f 6e omatic_extension
1ff10 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 2e 0a 2a 2a ()].** calls..**
1ff20 0a 2a 2a 20 54 68 69 73 20 63 61 6c 6c 20 64 69 .** This call di
1ff30 73 61 62 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 sabled automatic
1ff40 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61 extensions in a
1ff50 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a ll threads..**.*
1ff60 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 * This interface
1ff70 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c is experimental
1ff80 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 and is subject
1ff90 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 to change or.**
1ffa0 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 removal in futur
1ffb0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
1ffc0 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 Lite..*/.void sq
1ffd0 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f lite3_reset_auto
1ffe0 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29 _extension(void)
1fff0 3b 0a 0a 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 ;.../*.****** EX
20000 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 PERIMENTAL - sub
20010 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 ject to change w
20020 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a ithout notice **
20030 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a ************.**.
20040 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 ** The interface
20050 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d to the virtual-
20060 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 table mechanism
20070 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e is currently con
20080 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 sidered.** to be
20090 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 experimental.
200a0 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 The interface mi
200b0 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e ght change in in
200c0 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e compatible ways.
200d0 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 .** If this is a
200e0 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 problem for you
200f0 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 , do not use the
20100 20 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 interface at th
20110 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 is time..**.** W
20120 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d hen the virtual-
20130 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 table mechanism
20140 73 74 61 62 6c 69 7a 65 73 2c 20 77 65 20 77 69 stablizes, we wi
20150 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a ll declare the.*
20160 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 * interface fixe
20170 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e d, support it in
20180 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 definitely, and
20190 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d remove this comm
201a0 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 ent..*/../*.** S
201b0 74 72 75 63 74 75 72 65 73 20 75 73 65 64 20 62 tructures used b
201c0 79 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 y the virtual ta
201d0 62 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f ble interface.*/
201e0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
201f0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c sqlite3_vtab sql
20200 69 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 ite3_vtab;.typed
20210 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
20220 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 3_index_info sql
20230 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b ite3_index_info;
20240 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
20250 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 sqlite3_vtab_cur
20260 73 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62 sor sqlite3_vtab
20270 5f 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 _cursor;.typedef
20280 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
20290 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d module sqlite3_m
202a0 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 41 20 odule;../*.** A
202b0 6d 6f 64 75 6c 65 20 69 73 20 61 20 63 6c 61 73 module is a clas
202c0 73 20 6f 66 20 76 69 72 74 75 61 6c 20 74 61 62 s of virtual tab
202d0 6c 65 73 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c les. Each modul
202e0 65 20 69 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20 e is defined.**
202f0 62 79 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f by an instance o
20300 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 f the following
20310 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 69 73 structure. This
20320 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69 structure consi
20330 73 74 73 0a 2a 2a 20 6d 6f 73 74 6c 79 20 6f 66 sts.** mostly of
20340 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 methods for the
20350 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a 73 74 72 75 module..*/.stru
20360 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c ct sqlite3_modul
20370 65 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 e {. int iVersi
20380 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 on;. int (*xCre
20390 61 74 65 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 ate)(sqlite3*, v
203a0 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 oid *pAux,.
203b0 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 int ar
203c0 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a gc, const char *
203d0 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 const*argv,.
203e0 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 sqlit
203f0 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 e3_vtab **ppVTab
20400 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 , char**);. int
20410 20 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c (*xConnect)(sql
20420 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 ite3*, void *pAu
20430 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 x,.
20440 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 int argc, cons
20450 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 t char *const*ar
20460 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 gv,.
20470 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 sqlite3_vtab
20480 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a **ppVTab, char**
20490 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 73 74 );. int (*xBest
204a0 49 6e 64 65 78 29 28 73 71 6c 69 74 65 33 5f 76 Index)(sqlite3_v
204b0 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 tab *pVTab, sqli
204c0 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 te3_index_info*)
204d0 3b 0a 20 20 69 6e 74 20 28 2a 78 44 69 73 63 6f ;. int (*xDisco
204e0 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 5f 76 nnect)(sqlite3_v
204f0 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 tab *pVTab);. i
20500 6e 74 20 28 2a 78 44 65 73 74 72 6f 79 29 28 73 nt (*xDestroy)(s
20510 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
20520 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 ab);. int (*xOp
20530 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 en)(sqlite3_vtab
20540 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 *pVTab, sqlite3
20550 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 _vtab_cursor **p
20560 70 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 pCursor);. int
20570 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 (*xClose)(sqlite
20580 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 3_vtab_cursor*);
20590 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 . int (*xFilter
205a0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 )(sqlite3_vtab_c
205b0 75 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e ursor*, int idxN
205c0 75 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a um, const char *
205d0 69 64 78 53 74 72 2c 0a 20 20 20 20 20 20 20 20 idxStr,.
205e0 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 int argc
205f0 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 , sqlite3_value
20600 2a 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 **argv);. int (
20610 2a 78 4e 65 78 74 29 28 73 71 6c 69 74 65 33 5f *xNext)(sqlite3_
20620 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 vtab_cursor*);.
20630 20 69 6e 74 20 28 2a 78 45 6f 66 29 28 73 71 6c int (*xEof)(sql
20640 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 ite3_vtab_cursor
20650 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c *);. int (*xCol
20660 75 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 umn)(sqlite3_vta
20670 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 b_cursor*, sqlit
20680 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 e3_context*, int
20690 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 );. int (*xRowi
206a0 64 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f d)(sqlite3_vtab_
206b0 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 cursor*, sqlite3
206c0 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69 64 29 3b _int64 *pRowid);
206d0 0a 20 20 69 6e 74 20 28 2a 78 55 70 64 61 74 65 . int (*xUpdate
206e0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a )(sqlite3_vtab *
206f0 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 , int, sqlite3_v
20700 61 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 alue **, sqlite3
20710 5f 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 _int64 *);. int
20720 20 28 2a 78 42 65 67 69 6e 29 28 73 71 6c 69 74 (*xBegin)(sqlit
20730 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b e3_vtab *pVTab);
20740 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 . int (*xSync)(
20750 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 sqlite3_vtab *pV
20760 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 Tab);. int (*xC
20770 6f 6d 6d 69 74 29 28 73 71 6c 69 74 65 33 5f 76 ommit)(sqlite3_v
20780 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 tab *pVTab);. i
20790 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 nt (*xRollback)(
207a0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 sqlite3_vtab *pV
207b0 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 Tab);. int (*xF
207c0 69 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c indFunction)(sql
207d0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 ite3_vtab *pVtab
207e0 2c 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 , int nArg, cons
207f0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 t char *zName,.
20800 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
20810 20 20 20 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 void (**px
20820 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f Func)(sqlite3_co
20830 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 ntext*,int,sqlit
20840 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 e3_value**),.
20850 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
20860 20 20 20 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 void **ppArg
20870 29 3b 0a 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e );.. int (*xRen
20880 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 ame)(sqlite3_vta
20890 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 b *pVtab, const
208a0 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a char *zNew);.};.
208b0 0a 2f 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 ./*.** The sqlit
208c0 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 e3_index_info st
208d0 72 75 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 ructure and its
208e0 73 75 62 73 74 72 75 63 74 75 72 65 73 20 69 73 substructures is
208f0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73 used to.** pass
20900 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 information int
20910 6f 20 61 6e 64 20 72 65 63 65 69 76 65 20 74 68 o and receive th
20920 65 20 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 e reply from the
20930 20 78 42 65 73 74 49 6e 64 65 78 0a 2a 2a 20 6d xBestIndex.** m
20940 65 74 68 6f 64 20 6f 66 20 61 6e 20 73 71 6c 69 ethod of an sqli
20950 74 65 33 5f 6d 6f 64 75 6c 65 2e 20 20 54 68 65 te3_module. The
20960 20 66 69 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a fields under **
20970 49 6e 70 75 74 73 2a 2a 20 61 72 65 20 74 68 65 Inputs** are the
20980 0a 2a 2a 20 69 6e 70 75 74 73 20 74 6f 20 78 42 .** inputs to xB
20990 65 73 74 49 6e 64 65 78 20 61 6e 64 20 61 72 65 estIndex and are
209a0 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 read-only. xBe
209b0 73 74 49 6e 64 65 78 20 69 6e 73 65 72 74 73 20 stIndex inserts
209c0 69 74 73 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 its.** results i
209d0 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 nto the **Output
209e0 73 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a s** fields..**.*
209f0 2a 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e * The aConstrain
20a00 74 5b 5d 20 61 72 72 61 79 20 72 65 63 6f 72 64 t[] array record
20a10 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 s WHERE clause c
20a20 6f 6e 73 74 72 61 69 6e 74 73 20 6f 66 20 74 68 onstraints of th
20a30 65 0a 2a 2a 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a e.** form:.**.**
20a40 20 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 20 column
20a50 4f 50 20 65 78 70 72 0a 2a 2a 0a 2a 2a 20 57 68 OP expr.**.** Wh
20a60 65 72 65 20 4f 50 20 69 73 20 3d 2c 20 3c 2c 20 ere OP is =, <,
20a70 3c 3d 2c 20 3e 2c 20 6f 72 20 3e 3d 2e 20 20 54 <=, >, or >=. T
20a80 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70 he particular op
20a90 65 72 61 74 6f 72 20 69 73 20 73 74 6f 72 65 64 erator is stored
20aa0 0a 2a 2a 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 .** in aConstrai
20ab0 6e 74 5b 5d 2e 6f 70 2e 20 20 54 68 65 20 69 6e nt[].op. The in
20ac0 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d dex of the colum
20ad0 6e 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 0a n is stored in .
20ae0 2a 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d ** aConstraint[]
20af0 2e 69 43 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73 .iColumn. aCons
20b00 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 traint[].usable
20b10 69 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a is TRUE if the.*
20b20 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 * expr on the ri
20b30 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 ght-hand side ca
20b40 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 n be evaluated (
20b50 61 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e and thus the con
20b60 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 straint.** is us
20b70 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 able) and false
20b80 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a 2a if it cannot..**
20b90 0a 2a 2a 20 54 68 65 20 6f 70 74 69 6d 69 7a 65 .** The optimize
20ba0 72 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 r automatically
20bb0 69 6e 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66 inverts terms of
20bc0 20 74 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20 the form "expr
20bd0 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e OP column".** an
20be0 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69 d makes other si
20bf0 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 6f mplifications to
20c00 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 the WHERE claus
20c10 65 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 e in an attempt
20c20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e to.** get as man
20c30 79 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 y WHERE clause t
20c40 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f erms into the fo
20c50 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 rm shown above a
20c60 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 54 s possible..** T
20c70 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d he aConstraint[]
20c80 20 61 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f array only repo
20c90 72 74 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 rts WHERE clause
20ca0 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 63 6f terms in the co
20cb0 72 72 65 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 68 rrect.** form th
20cc0 61 74 20 72 65 66 65 72 20 74 6f 20 74 68 65 20 at refer to the
20cd0 70 61 72 74 69 63 75 6c 61 72 20 76 69 72 74 75 particular virtu
20ce0 61 6c 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71 al table being q
20cf0 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e ueried..**.** In
20d00 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 formation about
20d10 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 the ORDER BY cla
20d20 75 73 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e use is stored in
20d30 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 aOrderBy[]..**
20d40 45 61 63 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 Each term of aOr
20d50 64 65 72 42 79 20 72 65 63 6f 72 64 73 20 61 20 derBy records a
20d60 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 column of the OR
20d70 44 45 52 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a DER BY clause..*
20d80 2a 0a 2a 2a 20 54 68 65 20 78 42 65 73 74 49 6e *.** The xBestIn
20d90 64 65 78 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 dex method must
20da0 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 fill aConstraint
20db0 55 73 61 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 Usage[] with inf
20dc0 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 ormation.** abou
20dd0 74 20 77 68 61 74 20 70 61 72 61 6d 65 74 65 72 t what parameter
20de0 73 20 74 6f 20 70 61 73 73 20 74 6f 20 78 46 69 s to pass to xFi
20df0 6c 74 65 72 2e 20 20 49 66 20 61 72 67 76 49 6e lter. If argvIn
20e00 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 dex>0 then.** th
20e10 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 e right-hand sid
20e20 65 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70 e of the corresp
20e30 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 onding aConstrai
20e40 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65 nt[] is evaluate
20e50 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 d.** and becomes
20e60 20 74 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74 the argvIndex-t
20e70 68 20 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e h entry in argv.
20e80 20 20 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 If aConstraint
20e90 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 Usage[].omit.**
20ea0 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 is true, then th
20eb0 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 e constraint is
20ec0 61 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75 assumed to be fu
20ed0 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74 lly handled by t
20ee0 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 he.** virtual ta
20ef0 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 ble and is not c
20f00 68 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20 hecked again by
20f10 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 SQLite..**.** Th
20f20 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 e idxNum and idx
20f30 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 20 72 Ptr values are r
20f40 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73 ecorded and pass
20f50 65 64 20 69 6e 74 6f 20 78 46 69 6c 74 65 72 2e ed into xFilter.
20f60 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 .** sqlite3_free
20f70 28 29 20 69 73 20 75 73 65 64 20 74 6f 20 66 72 () is used to fr
20f80 65 65 20 69 64 78 50 74 72 20 69 66 20 6e 65 65 ee idxPtr if nee
20f90 64 54 6f 46 72 65 65 49 64 78 50 74 72 20 69 73 dToFreeIdxPtr is
20fa0 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 true..**.** The
20fb0 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 orderByConsumed
20fc0 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 75 74 70 means that outp
20fd0 75 74 20 66 72 6f 6d 20 78 46 69 6c 74 65 72 20 ut from xFilter
20fe0 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a will occur in.**
20ff0 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64 the correct ord
21000 65 72 20 74 6f 20 73 61 74 69 73 66 79 20 74 68 er to satisfy th
21010 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 e ORDER BY claus
21020 65 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 e so that no sep
21030 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 arate.** sorting
21040 20 73 74 65 70 20 69 73 20 72 65 71 75 69 72 65 step is require
21050 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 73 74 d..**.** The est
21060 69 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65 imatedCost value
21070 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20 is an estimate
21080 6f 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64 of the cost of d
21090 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 oing the.** part
210a0 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 icular lookup.
210b0 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 A full scan of a
210c0 20 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e table with N en
210d0 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 tries should hav
210e0 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e e.** a cost of N
210f0 2e 20 20 41 20 62 69 6e 61 72 79 20 73 65 61 72 . A binary sear
21100 63 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 ch of a table of
21110 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c N entries shoul
21120 64 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 d have a.** cost
21130 20 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c of approximatel
21140 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 y log(N)..*/.str
21150 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 uct sqlite3_inde
21160 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e x_info {. /* In
21170 70 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 puts */. int nC
21180 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 onstraint;
21190 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f /* Number o
211a0 66 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f f entries in aCo
211b0 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 nstraint */. st
211c0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 ruct sqlite3_ind
211d0 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a ex_constraint {.
211e0 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e int iColumn
211f0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f ; /
21200 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 * Column on left
21210 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f -hand side of co
21220 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 nstraint */.
21230 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f unsigned char o
21240 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f p; /* Co
21250 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f nstraint operato
21260 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e r */. unsign
21270 65 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 ed char usable;
21280 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74 /* True if t
21290 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 his constraint i
212a0 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 s usable */.
212b0 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 int iTermOffset
212c0 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 ; /* Us
212d0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 ed internally -
212e0 78 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c xBestIndex shoul
212f0 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 d ignore */. }
21300 2a 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 *aConstraint;
21310 20 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c /* Tabl
21320 65 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73 e of WHERE claus
21330 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f e constraints */
21340 0a 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b . int nOrderBy;
21350 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
21360 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 Number of terms
21370 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 in the ORDER BY
21380 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 clause */. str
21390 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 uct sqlite3_inde
213a0 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20 x_orderby {.
213b0 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 int iColumn;
213c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f /* Co
213d0 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 lumn number */.
213e0 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 unsigned cha
213f0 72 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a r desc; /*
21400 20 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20 True for DESC.
21410 20 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 False for ASC.
21420 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 */. } *aOrderBy
21430 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ;
21440 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59 20 /* The ORDER BY
21450 63 6c 61 75 73 65 20 2a 2f 0a 0a 20 20 2f 2a 20 clause */.. /*
21460 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 Outputs */. str
21470 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 uct sqlite3_inde
21480 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 x_constraint_usa
21490 67 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 ge {. int arg
214a0 76 49 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20 vIndex;
214b0 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 /* if >0, cons
214c0 74 72 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f traint is part o
214d0 66 20 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65 f argv to xFilte
214e0 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 r */. unsigne
214f0 64 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 d char omit;
21500 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 /* Do not code
21510 20 61 20 74 65 73 74 20 66 6f 72 20 74 68 69 73 a test for this
21520 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 constraint */.
21530 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 } *aConstraintU
21540 73 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e sage;. int idxN
21550 75 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 um;
21560 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 /* Number use
21570 64 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68 d to identify th
21580 65 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 e index */. cha
21590 72 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20 r *idxStr;
215a0 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e /* Strin
215b0 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 g, possibly obta
215c0 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 ined from sqlite
215d0 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 3_malloc */. in
215e0 74 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 t needToFreeIdxS
215f0 74 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65 tr; /* Free
21600 20 69 64 78 53 74 72 20 75 73 69 6e 67 20 73 71 idxStr using sq
21610 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 66 20 lite3_free() if
21620 74 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 true */. int or
21630 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 derByConsumed;
21640 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 /* True if
21650 6f 75 74 70 75 74 20 69 73 20 61 6c 72 65 61 64 output is alread
21660 79 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 y ordered */. d
21670 6f 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43 ouble estimatedC
21680 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 ost; /* Est
21690 69 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75 imated cost of u
216a0 73 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20 sing this index
216b0 2a 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51 */.};.#define SQ
216c0 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 LITE_INDEX_CONST
216d0 52 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 RAINT_EQ 2.#d
216e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 efine SQLITE_IND
216f0 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 EX_CONSTRAINT_GT
21700 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4.#define SQ
21710 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 LITE_INDEX_CONST
21720 52 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 RAINT_LE 8.#d
21730 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 efine SQLITE_IND
21740 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 EX_CONSTRAINT_LT
21750 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 16.#define S
21760 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 QLITE_INDEX_CONS
21770 54 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a TRAINT_GE 32.
21780 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
21790 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f NDEX_CONSTRAINT_
217a0 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 MATCH 64../*.**
217b0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 This routine is
217c0 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 used to register
217d0 20 61 20 6e 65 77 20 6d 6f 64 75 6c 65 20 6e 61 a new module na
217e0 6d 65 20 77 69 74 68 20 61 6e 20 53 51 4c 69 74 me with an SQLit
217f0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e e.** connection.
21800 20 20 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d Module names m
21810 75 73 74 20 62 65 20 72 65 67 69 73 74 65 72 65 ust be registere
21820 64 20 62 65 66 6f 72 65 20 63 72 65 61 74 69 6e d before creatin
21830 67 20 6e 65 77 0a 2a 2a 20 76 69 72 74 75 61 6c g new.** virtual
21840 20 74 61 62 6c 65 73 20 6f 6e 20 74 68 65 20 6d tables on the m
21850 6f 64 75 6c 65 2c 20 6f 72 20 62 65 66 6f 72 65 odule, or before
21860 20 75 73 69 6e 67 20 70 72 65 65 78 69 73 74 69 using preexisti
21870 6e 67 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 ng virtual.** ta
21880 62 6c 65 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 bles of the modu
21890 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 le..*/.int sqlit
218a0 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 e3_create_module
218b0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
218c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
218d0 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 * SQLite connect
218e0 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 ion to register
218f0 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 module with */.
21900 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
21910 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e me, /* N
21920 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c ame of the modul
21930 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c e */. const sql
21940 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 ite3_module *,
21950 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 /* Methods for
21960 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 the module */.
21970 20 76 6f 69 64 20 2a 20 20 20 20 20 20 20 20 20 void *
21980 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 /* C
21990 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 lient data for x
219a0 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 Create/xConnect
219b0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 */.);../*.** Thi
219c0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 64 65 s routine is ide
219d0 6e 74 69 63 61 6c 20 74 6f 20 74 68 65 20 73 71 ntical to the sq
219e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 lite3_create_mod
219f0 75 6c 65 28 29 20 6d 65 74 68 6f 64 20 61 62 6f ule() method abo
21a00 76 65 2c 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 ve,.** except th
21a10 61 74 20 69 74 20 61 6c 6c 6f 77 73 20 61 20 64 at it allows a d
21a20 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 estructor functi
21a30 6f 6e 20 74 6f 20 62 65 20 73 70 65 63 69 66 69 on to be specifi
21a40 65 64 2e 20 49 74 20 69 73 0a 2a 2a 20 65 76 65 ed. It is.** eve
21a50 6e 20 6d 6f 72 65 20 65 78 70 65 72 69 6d 65 6e n more experimen
21a60 74 61 6c 20 74 68 61 6e 20 74 68 65 20 72 65 73 tal than the res
21a70 74 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c t of the virtual
21a80 20 74 61 62 6c 65 73 20 41 50 49 2e 0a 2a 2f 0a tables API..*/.
21a90 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 int sqlite3_crea
21aa0 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 te_module_v2(.
21ab0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
21ac0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 /* SQ
21ad0 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 Lite connection
21ae0 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 to register modu
21af0 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e le with */. con
21b00 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
21b10 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 /* Name
21b20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f of the module */
21b30 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 . const sqlite3
21b40 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a _module *, /*
21b50 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 Methods for the
21b60 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 module */. voi
21b70 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 d *,
21b80 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e /* Clien
21b90 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 t data for xCrea
21ba0 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 te/xConnect */.
21bb0 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 void(*xDestroy)
21bc0 28 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d (void*) /* M
21bd0 6f 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72 odule destructor
21be0 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a function */.);.
21bf0 0a 2f 2a 0a 2a 2a 20 45 76 65 72 79 20 6d 6f 64 ./*.** Every mod
21c00 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ule implementati
21c10 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 on uses a subcla
21c20 73 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 ss of the follow
21c30 69 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a 2a ing structure.**
21c40 20 74 6f 20 64 65 73 63 72 69 62 65 20 61 20 70 to describe a p
21c50 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e articular instan
21c60 63 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 ce of the module
21c70 2e 20 20 45 61 63 68 20 73 75 62 63 6c 61 73 73 . Each subclass
21c80 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c will.** be tail
21c90 6f 72 65 64 20 74 6f 20 74 68 65 20 73 70 65 63 ored to the spec
21ca0 69 66 69 63 20 6e 65 65 64 73 20 6f 66 20 74 68 ific needs of th
21cb0 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 e module impleme
21cc0 6e 74 61 74 69 6f 6e 2e 20 20 20 54 68 65 0a 2a ntation. The.*
21cd0 2a 20 70 75 72 70 6f 73 65 20 6f 66 20 74 68 69 * purpose of thi
21ce0 73 20 73 75 70 65 72 63 6c 61 73 73 20 69 73 20 s superclass is
21cf0 74 6f 20 64 65 66 69 6e 65 20 63 65 72 74 61 69 to define certai
21d00 6e 20 66 69 65 6c 64 73 20 74 68 61 74 20 61 72 n fields that ar
21d10 65 20 63 6f 6d 6d 6f 6e 0a 2a 2a 20 74 6f 20 61 e common.** to a
21d20 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d ll module implem
21d30 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a entations..**.**
21d40 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 Virtual tables
21d50 6d 65 74 68 6f 64 73 20 63 61 6e 20 73 65 74 20 methods can set
21d60 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 an error message
21d70 20 62 79 20 61 73 73 69 67 6e 69 6e 67 20 61 0a by assigning a.
21d80 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e ** string obtain
21d90 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ed from sqlite3_
21da0 6d 70 72 69 6e 74 66 28 29 20 74 6f 20 7a 45 72 mprintf() to zEr
21db0 72 4d 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f rMsg. The metho
21dc0 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 d should.** take
21dd0 20 63 61 72 65 20 74 68 61 74 20 61 6e 79 20 70 care that any p
21de0 72 69 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66 rior string is f
21df0 72 65 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 reed by a call t
21e00 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 o sqlite3_free()
21e10 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 73 73 .** prior to ass
21e20 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 74 72 igning a new str
21e30 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 ing to zErrMsg.
21e40 20 41 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 After the error
21e50 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 message.** is d
21e60 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f 20 74 elivered up to t
21e70 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 he client applic
21e80 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e ation, the strin
21e90 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 g will be automa
21ea0 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 tically.** freed
21eb0 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65 by sqlite3_free
21ec0 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72 72 4d () and the zErrM
21ed0 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 sg field will be
21ee0 20 7a 65 72 6f 65 64 2e 20 20 4e 6f 74 65 0a 2a zeroed. Note.*
21ef0 2a 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 6d * that sqlite3_m
21f00 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c printf() and sql
21f10 69 74 65 33 5f 66 72 65 65 28 29 20 61 72 65 20 ite3_free() are
21f20 75 73 65 64 20 6f 6e 20 74 68 65 20 7a 45 72 72 used on the zErr
21f30 4d 73 67 20 66 69 65 6c 64 0a 2a 2a 20 73 69 6e Msg field.** sin
21f40 63 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 ce virtual table
21f50 73 20 61 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 69 s are commonly i
21f60 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 6c 6f mplemented in lo
21f70 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e adable extension
21f80 73 20 77 68 69 63 68 0a 2a 2a 20 64 6f 20 6e 6f s which.** do no
21f90 74 20 68 61 76 65 20 61 63 63 65 73 73 20 74 6f t have access to
21fa0 20 73 71 6c 69 74 65 33 4d 50 72 69 6e 74 66 28 sqlite3MPrintf(
21fb0 29 20 6f 72 20 73 71 6c 69 74 65 33 46 72 65 65 ) or sqlite3Free
21fc0 28 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 ()..*/.struct sq
21fd0 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 lite3_vtab {. c
21fe0 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 onst sqlite3_mod
21ff0 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f ule *pModule; /
22000 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 * The module for
22010 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 74 61 this virtual ta
22020 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 ble */. int nRe
22030 66 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 f;
22040 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 /* Used
22050 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2a 2f 0a 20 internally */.
22060 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20 char *zErrMsg;
22070 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
22080 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67 /* Error messag
22090 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d e from sqlite3_m
220a0 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a printf() */. /*
220b0 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 Virtual table i
220c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 mplementations w
220d0 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 ill typically ad
220e0 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 d additional fie
220f0 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 20 45 76 lds */.};../* Ev
22100 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 ery module imple
22110 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 mentation uses a
22120 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 subclass of the
22130 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 following struc
22140 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63 72 ture.** to descr
22150 69 62 65 20 63 75 72 73 6f 72 73 20 74 68 61 74 ibe cursors that
22160 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65 20 point into the
22170 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e virtual table an
22180 64 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f d are used.** to
22190 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68 loop through th
221a0 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e e virtual table.
221b0 20 20 43 75 72 73 6f 72 73 20 61 72 65 20 63 72 Cursors are cr
221c0 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a eated using the.
221d0 2a 2a 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 ** xOpen method
221e0 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 of the module.
221f0 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c Each module impl
22200 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 ementation will
22210 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f define.** the co
22220 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73 6f ntent of a curso
22230 72 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 73 r structure to s
22240 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65 64 uit its own need
22250 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75 s..**.** This su
22260 70 65 72 63 6c 61 73 73 20 65 78 69 73 74 73 20 perclass exists
22270 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66 69 in order to defi
22280 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65 ne fields of the
22290 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20 cursor that.**
222a0 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c are common to al
222b0 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e l implementation
222c0 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c s..*/.struct sql
222d0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 ite3_vtab_cursor
222e0 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 74 61 {. sqlite3_vta
222f0 62 20 2a 70 56 74 61 62 3b 20 20 20 20 20 20 2f b *pVtab; /
22300 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 * Virtual table
22310 6f 66 20 74 68 69 73 20 63 75 72 73 6f 72 20 2a of this cursor *
22320 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 /. /* Virtual t
22330 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 able implementat
22340 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 ions will typica
22350 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e lly add addition
22360 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a al fields */.};.
22370 0a 2f 2a 0a 2a 2a 20 54 68 65 20 78 43 72 65 61 ./*.** The xCrea
22380 74 65 20 61 6e 64 20 78 43 6f 6e 6e 65 63 74 20 te and xConnect
22390 6d 65 74 68 6f 64 73 20 6f 66 20 61 20 6d 6f 64 methods of a mod
223a0 75 6c 65 20 75 73 65 20 74 68 65 20 66 6f 6c 6c ule use the foll
223b0 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 74 6f 20 owing API.** to
223c0 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d declare the form
223d0 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e at (the names an
223e0 64 20 64 61 74 61 74 79 70 65 73 20 6f 66 20 74 d datatypes of t
223f0 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a he columns) of.*
22400 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 * the virtual ta
22410 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d bles they implem
22420 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ent..*/.int sqli
22430 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 te3_declare_vtab
22440 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 (sqlite3*, const
22450 20 63 68 61 72 20 2a 7a 43 72 65 61 74 65 54 61 char *zCreateTa
22460 62 6c 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 56 69 72 ble);../*.** Vir
22470 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 20 tual tables can
22480 70 72 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 74 provide alternat
22490 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ive implementati
224a0 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 ons of functions
224b0 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 78 46 .** using the xF
224c0 69 6e 64 46 75 6e 63 74 69 6f 6e 20 6d 65 74 68 indFunction meth
224d0 6f 64 2e 20 20 42 75 74 20 67 6c 6f 62 61 6c 20 od. But global
224e0 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73 versions of thos
224f0 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d e functions.** m
22500 75 73 74 20 65 78 69 73 74 20 69 6e 20 6f 72 64 ust exist in ord
22510 65 72 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61 er to be overloa
22520 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ded..**.** This
22530 41 50 49 20 6d 61 6b 65 73 20 73 75 72 65 20 61 API makes sure a
22540 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20 global version
22550 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 of a function wi
22560 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a th a particular.
22570 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62 ** name and numb
22580 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 er of parameters
22590 20 65 78 69 73 74 73 2e 20 20 49 66 20 6e 6f 20 exists. If no
225a0 73 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 65 78 such function ex
225b0 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74 ists.** before t
225c0 68 69 73 20 41 50 49 20 69 73 20 63 61 6c 6c 65 his API is calle
225d0 64 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 69 6f d, a new functio
225e0 6e 20 69 73 20 63 72 65 61 74 65 64 2e 20 20 54 n is created. T
225f0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
22600 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 n.** of the new
22610 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 function always
22620 63 61 75 73 65 73 20 61 6e 20 65 78 63 65 70 74 causes an except
22630 69 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f 77 6e ion to be thrown
22640 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 . So.** the new
22650 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 function is not
22660 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 good for anythi
22670 6e 67 20 62 79 20 69 74 73 65 6c 66 2e 20 20 49 ng by itself. I
22680 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f ts only.** purpo
22690 73 65 20 69 73 20 74 6f 20 62 65 20 61 20 70 6c se is to be a pl
226a0 61 63 65 2d 68 6f 6c 64 65 72 20 66 75 6e 63 74 ace-holder funct
226b0 69 6f 6e 20 74 68 61 74 20 63 61 6e 20 62 65 20 ion that can be
226c0 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 overloaded.** by
226d0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 2e virtual tables.
226e0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 .**.** This API
226f0 73 68 6f 75 6c 64 20 62 65 20 63 6f 6e 73 69 64 should be consid
22700 65 72 65 64 20 70 61 72 74 20 6f 66 20 74 68 65 ered part of the
22710 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 virtual table i
22720 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 77 68 69 nterface,.** whi
22730 63 68 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 ch is experiment
22740 61 6c 20 61 6e 64 20 73 75 62 6a 65 63 74 20 74 al and subject t
22750 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 o change..*/.int
22760 20 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61 sqlite3_overloa
22770 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74 d_function(sqlit
22780 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 e3*, const char
22790 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 *zFuncName, int
227a0 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 nArg);../*.** Th
227b0 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 e interface to t
227c0 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 he virtual-table
227d0 20 6d 65 63 68 61 6e 69 73 6d 20 64 65 66 69 6e mechanism defin
227e0 65 64 20 61 62 6f 76 65 20 28 62 61 63 6b 20 75 ed above (back u
227f0 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e p.** to a commen
22800 74 20 72 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d t remarkably sim
22810 69 6c 61 72 20 74 6f 20 74 68 69 73 20 6f 6e 65 ilar to this one
22820 29 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 ) is currently c
22830 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 onsidered.** to
22840 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e be experimental.
22850 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 The interface
22860 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 might change in
22870 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 incompatible way
22880 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73 s..** If this is
22890 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 a problem for y
228a0 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 ou, do not use t
228b0 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 20 he interface at
228c0 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a this time..**.**
228d0 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 When the virtua
228e0 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 l-table mechanis
228f0 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 m stabilizes, we
22900 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 will declare th
22910 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 e.** interface f
22920 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74 ixed, support it
22930 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 indefinitely, a
22940 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63 nd remove this c
22950 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a omment..**.*****
22960 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d * EXPERIMENTAL -
22970 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e subject to chan
22980 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 ge without notic
22990 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a e **************
229a0 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .*/../*.** CAPI3
229b0 52 45 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f REF: A Handle To
229c0 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a An Open BLOB.**
229d0 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 .** An instance
229e0 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 of the following
229f0 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 opaque structur
22a00 65 20 69 73 20 75 73 65 64 20 74 6f 20 0a 2a 2a e is used to .**
22a10 20 72 65 70 72 65 73 65 6e 74 20 61 6e 20 62 6c represent an bl
22a20 6f 62 2d 68 61 6e 64 6c 65 2e 20 20 41 20 62 6c ob-handle. A bl
22a30 6f 62 2d 68 61 6e 64 6c 65 20 69 73 20 63 72 65 ob-handle is cre
22a40 61 74 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 ated by.** [sqli
22a50 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d te3_blob_open()]
22a60 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20 62 and destroyed b
22a70 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f y [sqlite3_blob_
22a80 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 close()]..** The
22a90 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 [sqlite3_blob_r
22aa0 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 ead()] and [sqli
22ab0 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 te3_blob_write()
22ac0 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 ] interfaces.**
22ad0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 can be used to r
22ae0 65 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61 ead or write sma
22af0 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f ll subsections o
22b00 66 20 74 68 65 20 62 6c 6f 62 2e 0a 2a 2a 20 54 f the blob..** T
22b10 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 he [sqlite3_blob
22b20 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 _bytes()] interf
22b30 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ace returns the
22b40 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 62 size of the.** b
22b50 6c 6f 62 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f lob in bytes..*/
22b60 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
22b70 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c sqlite3_blob sql
22b80 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a ite3_blob;../*.*
22b90 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e * CAPI3REF: Open
22ba0 20 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72 A BLOB For Incr
22bb0 65 6d 65 6e 74 61 6c 20 49 2f 4f 0a 2a 2a 0a 2a emental I/O.**.*
22bc0 2a 20 4f 70 65 6e 20 61 20 68 61 6e 64 6c 65 20 * Open a handle
22bd0 74 6f 20 74 68 65 20 62 6c 6f 62 20 6c 6f 63 61 to the blob loca
22be0 74 65 64 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c ted in row iRow,
22bf0 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e , column zColumn
22c00 2c 20 0a 2a 2a 20 74 61 62 6c 65 20 7a 54 61 62 , .** table zTab
22c10 6c 65 20 69 6e 20 64 61 74 61 62 61 73 65 20 7a le in database z
22c20 44 62 2e 20 69 2e 65 2e 20 74 68 65 20 73 61 6d Db. i.e. the sam
22c30 65 20 62 6c 6f 62 20 74 68 61 74 20 77 6f 75 6c e blob that woul
22c40 64 0a 2a 2a 20 62 65 20 73 65 6c 65 63 74 65 64 d.** be selected
22c50 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e by:.**.** <pre>
22c60 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a .** SELECT z
22c70 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e Column FROM zDb.
22c80 7a 54 61 62 6c 65 20 57 48 45 52 45 20 72 6f 77 zTable WHERE row
22c90 69 64 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f id = iRow;.** </
22ca0 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 pre>.**.** If th
22cb0 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 e flags paramete
22cc0 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 r is non-zero, t
22cd0 68 65 20 62 6c 6f 62 20 69 73 20 6f 70 65 6e 65 he blob is opene
22ce0 64 20 66 6f 72 20 0a 2a 2a 20 72 65 61 64 20 61 d for .** read a
22cf0 6e 64 20 77 72 69 74 65 20 61 63 63 65 73 73 2e nd write access.
22d00 20 49 66 20 69 74 20 69 73 20 7a 65 72 6f 2c 20 If it is zero,
22d10 74 68 65 20 62 6c 6f 62 20 69 73 20 6f 70 65 6e the blob is open
22d20 65 64 20 66 6f 72 20 72 65 61 64 20 0a 2a 2a 20 ed for read .**
22d30 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 4f 6e access..**.** On
22d40 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 success, [SQLIT
22d50 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 E_OK] is returne
22d60 64 20 61 6e 64 20 74 68 65 20 6e 65 77 20 0a 2a d and the new .*
22d70 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 * [sqlite3_blob
22d80 7c 20 62 6c 6f 62 20 68 61 6e 64 6c 65 5d 20 69 | blob handle] i
22d90 73 20 77 72 69 74 74 65 6e 20 74 6f 20 2a 70 70 s written to *pp
22da0 42 6c 6f 62 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 Blob..** Otherwi
22db0 73 65 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 se an error code
22dc0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 is returned and
22dd0 20 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 77 .** any value w
22de0 72 69 74 74 65 6e 20 74 6f 20 2a 70 70 42 6c 6f ritten to *ppBlo
22df0 62 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 b should not be
22e00 75 73 65 64 20 62 79 20 74 68 65 20 63 61 6c 6c used by the call
22e10 65 72 2e 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 er..** This func
22e20 74 69 6f 6e 20 73 65 74 73 20 74 68 65 20 64 61 tion sets the da
22e30 74 61 62 61 73 65 2d 68 61 6e 64 6c 65 20 65 72 tabase-handle er
22e40 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 ror code and mes
22e50 73 61 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 sage.** accessib
22e60 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f le via [sqlite3_
22e70 65 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b errcode()] and [
22e80 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
22e90 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 ]..*/.int sqlite
22ea0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 3_blob_open(. s
22eb0 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 qlite3*,. const
22ec0 20 63 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f char *zDb,. co
22ed0 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 nst char *zTable
22ee0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a ,. const char *
22ef0 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 zColumn,. sqlit
22f00 65 33 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20 e3_int64 iRow,.
22f10 20 69 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73 71 int flags,. sq
22f20 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 lite3_blob **ppB
22f30 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 lob.);../*.** CA
22f40 50 49 33 52 45 46 3a 20 20 43 6c 6f 73 65 20 41 PI3REF: Close A
22f50 20 42 4c 4f 42 20 48 61 6e 64 6c 65 0a 2a 2a 0a BLOB Handle.**.
22f60 2a 2a 20 43 6c 6f 73 65 20 61 6e 20 6f 70 65 6e ** Close an open
22f70 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c [sqlite3_blob |
22f80 20 62 6c 6f 62 20 68 61 6e 64 6c 65 5d 2e 0a 2a blob handle]..*
22f90 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c /.int sqlite3_bl
22fa0 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 ob_close(sqlite3
22fb0 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a _blob *);../*.**
22fc0 20 43 41 50 49 33 52 45 46 3a 20 20 52 65 74 75 CAPI3REF: Retu
22fd0 72 6e 20 54 68 65 20 53 69 7a 65 20 4f 66 20 41 rn The Size Of A
22fe0 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a n Open BLOB.**.*
22ff0 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a * Return the siz
23000 65 20 69 6e 20 62 79 74 65 73 20 6f 66 20 74 68 e in bytes of th
23010 65 20 62 6c 6f 62 20 61 63 63 65 73 73 69 62 6c e blob accessibl
23020 65 20 76 69 61 20 74 68 65 20 6f 70 65 6e 20 0a e via the open .
23030 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 ** [sqlite3_blob
23040 20 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 | blob-handle]
23050 70 61 73 73 65 64 20 61 73 20 61 6e 20 61 72 67 passed as an arg
23060 75 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ument..*/.int sq
23070 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 lite3_blob_bytes
23080 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 (sqlite3_blob *)
23090 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
230a0 46 3a 20 20 52 65 61 64 20 44 61 74 61 20 46 72 F: Read Data Fr
230b0 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d om A BLOB Increm
230c0 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 54 68 entally.**.** Th
230d0 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 is function is u
230e0 73 65 64 20 74 6f 20 72 65 61 64 20 64 61 74 61 sed to read data
230f0 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 0a 2a from an open .*
23100 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 * [sqlite3_blob
23110 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 69 | blob-handle] i
23120 6e 74 6f 20 61 20 63 61 6c 6c 65 72 20 73 75 70 nto a caller sup
23130 70 6c 69 65 64 20 62 75 66 66 65 72 2e 0a 2a 2a plied buffer..**
23140 20 6e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 n bytes of data
23150 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f are copied into
23160 20 62 75 66 66 65 72 0a 2a 2a 20 7a 20 66 72 6f buffer.** z fro
23170 6d 20 74 68 65 20 6f 70 65 6e 20 62 6c 6f 62 2c m the open blob,
23180 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 starting at off
23190 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a set iOffset..**.
231a0 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 53 ** On success, S
231b0 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 QLITE_OK is retu
231c0 72 6e 65 64 2e 20 4f 74 68 65 72 77 69 73 65 2c rned. Otherwise,
231d0 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f an .** [SQLITE_
231e0 45 52 52 4f 52 20 7c 20 53 51 4c 69 74 65 20 65 ERROR | SQLite e
231f0 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e rror code] or an
23200 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 .** [SQLITE_IOER
23210 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 R_READ | extende
23220 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 d error code] is
23230 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e returned..*/.in
23240 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 t sqlite3_blob_r
23250 65 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 ead(sqlite3_blob
23260 20 2a 2c 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 *, void *z, int
23270 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 n, int iOffset)
23280 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
23290 46 3a 20 20 57 72 69 74 65 20 44 61 74 61 20 49 F: Write Data I
232a0 6e 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 nto A BLOB Incre
232b0 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 54 mentally.**.** T
232c0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 his function is
232d0 75 73 65 64 20 74 6f 20 77 72 69 74 65 20 64 61 used to write da
232e0 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 ta into an open
232f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f .** [sqlite3_blo
23300 62 20 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d b | blob-handle]
23310 20 66 72 6f 6d 20 61 20 75 73 65 72 20 73 75 70 from a user sup
23320 70 6c 69 65 64 20 62 75 66 66 65 72 2e 0a 2a 2a plied buffer..**
23330 20 6e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 n bytes of data
23340 20 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d are copied from
23350 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 70 the buffer.** p
23360 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 7a 20 69 ointed to by z i
23370 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 62 6c 6f nto the open blo
23380 62 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f b, starting at o
23390 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a ffset iOffset..*
233a0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c *.** If the [sql
233b0 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 ite3_blob | blob
233c0 2d 68 61 6e 64 6c 65 5d 20 70 61 73 73 65 64 20 -handle] passed
233d0 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 as the first arg
233e0 75 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 ument.** was not
233f0 20 6f 70 65 6e 65 64 20 66 6f 72 20 77 72 69 74 opened for writ
23400 69 6e 67 20 28 74 68 65 20 66 6c 61 67 73 20 70 ing (the flags p
23410 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c arameter to [sql
23420 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 ite3_blob_open()
23430 5d 0a 2a 2a 2a 20 77 61 73 20 7a 65 72 6f 29 2c ].*** was zero),
23440 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 this function r
23450 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 eturns [SQLITE_R
23460 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20 EADONLY]..**.**
23470 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 This function ma
23480 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74 68 y only modify th
23490 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 e contents of th
234a0 65 20 62 6c 6f 62 2c 20 69 74 20 69 73 0a 2a 2a e blob, it is.**
234b0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f not possible to
234c0 20 69 6e 63 72 65 61 73 65 20 74 68 65 20 73 69 increase the si
234d0 7a 65 20 6f 66 20 61 20 62 6c 6f 62 20 75 73 69 ze of a blob usi
234e0 6e 67 20 74 68 69 73 20 41 50 49 2e 20 49 66 0a ng this API. If.
234f0 2a 2a 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 ** offset iOffse
23500 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6e t is less than n
23510 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20 bytes from the
23520 65 6e 64 20 6f 66 20 74 68 65 20 62 6c 6f 62 2c end of the blob,
23530 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 .** [SQLITE_ERR
23540 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 OR] is returned
23550 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 and no data is w
23560 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 4f 6e ritten..**.** On
23570 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54 45 success, SQLITE
23580 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e _OK is returned.
23590 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20 0a Otherwise, an .
235a0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ** [SQLITE_ERROR
235b0 20 7c 20 53 51 4c 69 74 65 20 65 72 72 6f 72 20 | SQLite error
235c0 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b code] or an.** [
235d0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 SQLITE_IOERR_REA
235e0 44 20 7c 20 65 78 74 65 6e 64 65 64 20 65 72 72 D | extended err
235f0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 or code] is retu
23600 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c rned..*/.int sql
23610 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 ite3_blob_write(
23620 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 sqlite3_blob *,
23630 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20 69 const void *z, i
23640 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65 nt n, int iOffse
23650 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
23660 52 45 46 3a 20 20 56 69 72 74 75 61 6c 20 46 69 REF: Virtual Fi
23670 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 74 le System Object
23680 73 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61 s.**.** A virtua
23690 6c 20 66 69 6c 65 73 79 73 74 65 6d 20 28 56 46 l filesystem (VF
236a0 53 29 20 69 73 20 61 6e 20 5b 73 71 6c 69 74 65 S) is an [sqlite
236b0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a 3_vfs] object.**
236c0 20 74 68 61 74 20 53 51 4c 69 74 65 20 75 73 65 that SQLite use
236d0 73 20 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a 2a s to interact.**
236e0 20 77 69 74 68 20 74 68 65 20 75 6e 64 65 72 6c with the underl
236f0 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 ying operating s
23700 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20 62 75 69 ystem. Most bui
23710 6c 64 73 20 63 6f 6d 65 20 77 69 74 68 20 61 0a lds come with a.
23720 2a 2a 20 73 69 6e 67 6c 65 20 64 65 66 61 75 6c ** single defaul
23730 74 20 56 46 53 20 74 68 61 74 20 69 73 20 61 70 t VFS that is ap
23740 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 propriate for th
23750 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e e host computer.
23760 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73 20 63 61 .** New VFSes ca
23770 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 n be registered
23780 61 6e 64 20 65 78 69 73 74 69 6e 67 20 56 46 53 and existing VFS
23790 65 73 20 63 61 6e 20 62 65 20 75 6e 72 65 67 69 es can be unregi
237a0 73 74 65 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 stered..** The f
237b0 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 ollowing interfa
237c0 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 ces are provided
237d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
237e0 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 20 69 te3_vfs_find() i
237f0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
23800 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
23810 56 46 53 20 67 69 76 65 6e 20 69 74 73 0a 2a 2a VFS given its.**
23820 20 6e 61 6d 65 2e 20 20 4e 61 6d 65 73 20 61 72 name. Names ar
23830 65 20 63 61 73 65 20 73 65 6e 73 69 74 69 76 65 e case sensitive
23840 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e . If there is n
23850 6f 20 6d 61 74 63 68 2c 20 61 20 4e 55 4c 4c 0a o match, a NULL.
23860 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 ** pointer is re
23870 74 75 72 6e 65 64 2e 20 20 49 66 20 7a 56 66 73 turned. If zVfs
23880 4e 61 6d 65 20 69 73 20 4e 55 4c 4c 20 74 68 65 Name is NULL the
23890 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 0a 2a n the default .*
238a0 2a 20 56 46 53 20 69 73 20 72 65 74 75 72 6e 65 * VFS is returne
238b0 64 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 56 46 53 d..**.** New VFS
238c0 65 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65 es are registere
238d0 64 20 77 69 74 68 20 73 71 6c 69 74 65 33 5f 76 d with sqlite3_v
238e0 66 73 5f 72 65 67 69 73 74 65 72 28 29 2e 20 20 fs_register().
238f0 45 61 63 68 0a 2a 2a 20 6e 65 77 20 56 46 53 20 Each.** new VFS
23900 62 65 63 6f 6d 65 73 20 74 68 65 20 64 65 66 61 becomes the defa
23910 75 6c 74 20 56 46 53 20 69 66 20 74 68 65 20 6d ult VFS if the m
23920 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 69 73 20 akeDflt flag is
23930 73 65 74 2e 0a 2a 2a 20 54 68 65 20 73 61 6d 65 set..** The same
23940 20 56 46 53 20 63 61 6e 20 62 65 20 72 65 67 69 VFS can be regi
23950 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 stered multiple
23960 74 69 6d 65 73 20 77 69 74 68 6f 75 74 20 69 6e times without in
23970 6a 75 72 79 2e 0a 2a 2a 20 54 6f 20 6d 61 6b 65 jury..** To make
23980 20 61 6e 20 65 78 69 73 74 69 6e 67 20 56 46 53 an existing VFS
23990 20 69 6e 74 6f 20 74 68 65 20 64 65 66 61 75 6c into the defaul
239a0 74 20 56 46 53 2c 20 72 65 67 69 73 74 65 72 20 t VFS, register
239b0 69 74 20 61 67 61 69 6e 0a 2a 2a 20 77 69 74 68 it again.** with
239c0 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c the makeDflt fl
239d0 61 67 20 73 65 74 2e 20 20 49 66 20 74 77 6f 20 ag set. If two
239e0 64 69 66 66 65 72 65 6e 74 20 56 46 53 65 73 20 different VFSes
239f0 77 69 74 68 20 74 68 65 0a 2a 2a 20 73 61 6d 65 with the.** same
23a00 20 6e 61 6d 65 20 61 72 65 20 72 65 67 69 73 74 name are regist
23a10 65 72 65 64 2c 20 74 68 65 20 62 65 68 61 76 69 ered, the behavi
23a20 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e or is undefined.
23a30 20 20 49 66 20 61 0a 2a 2a 20 56 46 53 20 69 73 If a.** VFS is
23a40 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 registered with
23a50 20 61 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20 a name that is
23a60 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 NULL or an empty
23a70 20 73 74 72 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e string,.** then
23a80 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
23a90 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 0a undefined..** .
23aa0 2a 2a 20 55 6e 72 65 67 69 73 74 65 72 20 61 20 ** Unregister a
23ab0 56 46 53 20 77 69 74 68 20 74 68 65 20 73 71 6c VFS with the sql
23ac0 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 ite3_vfs_unregis
23ad0 74 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e ter() interface.
23ae0 0a 2a 2a 20 49 66 20 74 68 65 20 64 65 66 61 75 .** If the defau
23af0 6c 74 20 56 46 53 20 69 73 20 75 6e 72 65 67 69 lt VFS is unregi
23b00 73 74 65 72 65 64 2c 20 61 6e 6f 74 68 65 72 20 stered, another
23b10 56 46 53 20 69 73 20 63 68 6f 73 65 6e 20 61 73 VFS is chosen as
23b20 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e .** the default.
23b30 20 20 54 68 65 20 63 68 6f 69 63 65 20 66 6f 72 The choice for
23b40 20 74 68 65 20 6e 65 77 20 56 46 53 20 69 73 20 the new VFS is
23b50 61 72 62 69 74 72 61 72 79 2e 0a 2a 2f 0a 73 71 arbitrary..*/.sq
23b60 6c 69 74 65 33 5f 76 66 73 20 2a 73 71 6c 69 74 lite3_vfs *sqlit
23b70 65 33 5f 76 66 73 5f 66 69 6e 64 28 63 6f 6e 73 e3_vfs_find(cons
23b80 74 20 63 68 61 72 20 2a 7a 56 66 73 4e 61 6d 65 t char *zVfsName
23b90 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 );.int sqlite3_v
23ba0 66 73 5f 72 65 67 69 73 74 65 72 28 73 71 6c 69 fs_register(sqli
23bb0 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 61 te3_vfs*, int ma
23bc0 6b 65 44 66 6c 74 29 3b 0a 69 6e 74 20 73 71 6c keDflt);.int sql
23bd0 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 ite3_vfs_unregis
23be0 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ter(sqlite3_vfs*
23bf0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
23c00 45 46 3a 20 4d 75 74 65 78 65 73 0a 2a 2a 0a 2a EF: Mutexes.**.*
23c10 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 * The SQLite cor
23c20 65 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 e uses these rou
23c30 74 69 6e 65 73 20 66 6f 72 20 74 68 72 65 61 64 tines for thread
23c40 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74 .** synchronizat
23c50 69 6f 6e 2e 20 20 54 68 6f 75 67 68 20 74 68 65 ion. Though the
23c60 79 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 y are intended f
23c70 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 or internal.** u
23c80 73 65 20 62 79 20 53 51 4c 69 74 65 2c 20 63 6f se by SQLite, co
23c90 64 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 de that links ag
23ca0 61 69 6e 73 74 20 53 51 4c 69 74 65 20 69 73 0a ainst SQLite is.
23cb0 2a 2a 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 ** permitted to
23cc0 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 use any of these
23cd0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a routines..**.**
23ce0 20 54 68 65 20 53 51 4c 69 74 65 20 73 6f 75 72 The SQLite sour
23cf0 63 65 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73 ce code contains
23d00 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d multiple implem
23d10 65 6e 74 61 74 69 6f 6e 73 20 0a 2a 2a 20 6f 66 entations .** of
23d20 20 74 68 65 73 65 20 6d 75 74 65 78 20 72 6f 75 these mutex rou
23d30 74 69 6e 65 73 2e 20 20 41 6e 20 61 70 70 72 6f tines. An appro
23d40 70 72 69 61 74 65 20 69 6d 70 6c 65 6d 65 6e 74 priate implement
23d50 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c 65 ation.** is sele
23d60 63 74 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c cted automatical
23d70 6c 79 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 ly at compile-ti
23d80 6d 65 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 me. The followi
23d90 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 ng.** implementa
23da0 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61 tions are availa
23db0 62 6c 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 ble in the SQLit
23dc0 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 e core:.**.** <u
23dd0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c l>.** <li> SQL
23de0 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a ITE_MUTEX_OS2.**
23df0 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d <li> SQLITE_M
23e00 55 54 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a 20 UTEX_PTHREAD.**
23e10 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 <li> SQLITE_MU
23e20 54 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20 TEX_W32.** <li>
23e30 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e SQLITE_MUTEX_N
23e40 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a OOP.** </ul>.**.
23e50 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 ** The SQLITE_MU
23e60 54 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 TEX_NOOP impleme
23e70 6e 74 61 74 69 6f 6e 20 69 73 20 61 20 73 65 74 ntation is a set
23e80 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 0a 2a 2a of routines .**
23e90 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 20 72 65 that does no re
23ea0 61 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69 al locking and i
23eb0 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f s appropriate fo
23ec0 72 20 75 73 65 20 69 6e 20 0a 2a 2a 20 61 20 73 r use in .** a s
23ed0 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 20 61 ingle-threaded a
23ee0 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 pplication. The
23ef0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 SQLITE_MUTEX_OS
23f00 32 2c 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 2,.** SQLITE_MUT
23f10 45 58 5f 50 54 48 52 45 41 44 2c 20 61 6e 64 20 EX_PTHREAD, and
23f20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 SQLITE_MUTEX_W32
23f30 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
23f40 0a 2a 2a 20 61 72 65 20 61 70 70 72 6f 70 72 69 .** are appropri
23f50 61 74 65 20 66 6f 72 20 75 73 65 20 6f 6e 20 6f ate for use on o
23f60 73 2f 32 2c 20 75 6e 69 78 2c 20 61 6e 64 20 77 s/2, unix, and w
23f70 69 6e 64 6f 77 73 2e 0a 2a 2a 20 0a 2a 2a 20 49 indows..** .** I
23f80 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 f SQLite is comp
23f90 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 iled with the SQ
23fa0 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 LITE_MUTEX_APPDE
23fb0 46 20 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a F preprocessor.*
23fc0 2a 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20 * macro defined
23fd0 28 77 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f (with "-DSQLITE_
23fe0 4d 55 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29 MUTEX_APPDEF=1")
23ff0 2c 20 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a , then no mutex.
24000 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
24010 6e 20 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69 n is included wi
24020 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20 th the library.
24030 20 54 68 65 0a 2a 2a 20 6d 75 74 65 78 20 69 6e The.** mutex in
24040 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 terface routines
24050 20 64 65 66 69 6e 65 64 20 68 65 72 65 20 62 65 defined here be
24060 63 6f 6d 65 20 65 78 74 65 72 6e 61 6c 0a 2a 2a come external.**
24070 20 72 65 66 65 72 65 6e 63 65 73 20 69 6e 20 74 references in t
24080 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 he SQLite librar
24090 79 20 66 6f 72 20 77 68 69 63 68 20 69 6d 70 6c y for which impl
240a0 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6d ementations.** m
240b0 75 73 74 20 62 65 20 70 72 6f 76 69 64 65 64 20 ust be provided
240c0 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 by the applicati
240d0 6f 6e 2e 20 20 54 68 69 73 20 66 61 63 69 6c 69 on. This facili
240e0 74 79 20 61 6c 6c 6f 77 73 20 61 6e 0a 2a 2a 20 ty allows an.**
240f0 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 application that
24100 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 links against S
24110 51 4c 69 74 65 20 74 6f 20 70 72 6f 76 69 64 65 QLite to provide
24120 20 69 74 73 20 6f 77 6e 20 6d 75 74 65 78 0a 2a its own mutex.*
24130 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
24140 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 without having
24150 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 to modify the SQ
24160 4c 69 74 65 20 63 6f 72 65 2e 0a 2a 2a 0a 2a 2a Lite core..**.**
24170 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 The sqlite3_mut
24180 65 78 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 ex_alloc() routi
24190 6e 65 20 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e ne allocates a n
241a0 65 77 0a 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20 ew.** mutex and
241b0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
241c0 72 20 74 6f 20 69 74 2e 20 20 49 66 20 69 74 20 r to it. If it
241d0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 returns NULL.**
241e0 74 68 61 74 20 6d 65 61 6e 73 20 74 68 61 74 20 that means that
241f0 61 20 6d 75 74 65 78 20 63 6f 75 6c 64 20 6e 6f a mutex could no
24200 74 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 2e 20 t be allocated.
24210 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 SQLite.** will
24220 75 6e 77 69 6e 64 20 69 74 73 20 73 74 61 63 6b unwind its stack
24230 20 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 65 and return an e
24240 72 72 6f 72 2e 20 20 54 68 65 20 61 72 67 75 6d rror. The argum
24250 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 ent.** to sqlite
24260 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 3_mutex_alloc()
24270 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 is one of these
24280 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 integer constant
24290 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a s:.**.** <ul>.**
242a0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 <li> SQLITE_MU
242b0 54 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e TEX_FAST.** <li>
242c0 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 SQLITE_MUTEX_R
242d0 45 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e ECURSIVE.** <li>
242e0 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 SQLITE_MUTEX_S
242f0 54 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20 TATIC_MASTER.**
24300 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 <li> SQLITE_MUT
24310 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a EX_STATIC_MEM.**
24320 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 <li> SQLITE_MU
24330 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a TEX_STATIC_MEM2.
24340 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f ** <li> SQLITE_
24350 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e MUTEX_STATIC_PRN
24360 47 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 G.** <li> SQLIT
24370 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c E_MUTEX_STATIC_L
24380 52 55 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a RU.** </ul>.**.*
24390 2a 20 54 68 65 20 66 69 72 73 74 20 74 77 6f 20 * The first two
243a0 63 6f 6e 73 74 61 6e 74 73 20 63 61 75 73 65 20 constants cause
243b0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c sqlite3_mutex_al
243c0 6c 6f 63 28 29 20 74 6f 20 63 72 65 61 74 65 0a loc() to create.
243d0 2a 2a 20 61 20 6e 65 77 20 6d 75 74 65 78 2e 20 ** a new mutex.
243e0 20 54 68 65 20 6e 65 77 20 6d 75 74 65 78 20 69 The new mutex i
243f0 73 20 72 65 63 75 72 73 69 76 65 20 77 68 65 6e s recursive when
24400 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 SQLITE_MUTEX_RE
24410 43 55 52 53 49 56 45 0a 2a 2a 20 69 73 20 75 73 CURSIVE.** is us
24420 65 64 20 62 75 74 20 6e 6f 74 20 6e 65 63 65 73 ed but not neces
24430 73 61 72 69 6c 79 20 73 6f 20 77 68 65 6e 20 53 sarily so when S
24440 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 QLITE_MUTEX_FAST
24450 20 69 73 20 75 73 65 64 2e 0a 2a 2a 20 54 68 65 is used..** The
24460 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 mutex implement
24470 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e ation does not n
24480 65 65 64 20 74 6f 20 6d 61 6b 65 20 61 20 64 69 eed to make a di
24490 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 stinction.** bet
244a0 77 65 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 ween SQLITE_MUTE
244b0 58 5f 52 45 43 55 52 53 49 56 45 20 61 6e 64 20 X_RECURSIVE and
244c0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 SQLITE_MUTEX_FAS
244d0 54 20 69 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20 T if it does.**
244e0 6e 6f 74 20 77 61 6e 74 20 74 6f 2e 20 20 42 75 not want to. Bu
244f0 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e t SQLite will on
24500 6c 79 20 72 65 71 75 65 73 74 20 61 20 72 65 63 ly request a rec
24510 75 72 73 69 76 65 20 6d 75 74 65 78 20 69 6e 0a ursive mutex in.
24520 2a 2a 20 63 61 73 65 73 20 77 68 65 72 65 20 69 ** cases where i
24530 74 20 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f t really needs o
24540 6e 65 2e 20 20 49 66 20 61 20 66 61 73 74 65 72 ne. If a faster
24550 20 6e 6f 6e 2d 72 65 63 75 72 73 69 76 65 20 6d non-recursive m
24560 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e utex.** implemen
24570 74 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 tation is availa
24580 62 6c 65 20 6f 6e 20 74 68 65 20 68 6f 73 74 20 ble on the host
24590 70 6c 61 74 66 6f 72 6d 2c 20 74 68 65 20 6d 75 platform, the mu
245a0 74 65 78 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a tex subsystem.**
245b0 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 73 75 might return su
245c0 63 68 20 61 20 6d 75 74 65 78 20 69 6e 20 72 65 ch a mutex in re
245d0 73 70 6f 6e 73 65 20 74 6f 20 53 51 4c 49 54 45 sponse to SQLITE
245e0 5f 4d 55 54 45 58 5f 46 41 53 54 2e 0a 2a 2a 0a _MUTEX_FAST..**.
245f0 2a 2a 20 54 68 65 20 6f 74 68 65 72 20 61 6c 6c ** The other all
24600 6f 77 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 owed parameters
24610 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 to sqlite3_mutex
24620 5f 61 6c 6c 6f 63 28 29 20 65 61 63 68 20 72 65 _alloc() each re
24630 74 75 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 turn.** a pointe
24640 72 20 74 6f 20 61 20 73 74 61 74 69 63 20 70 72 r to a static pr
24650 65 65 78 69 73 74 69 6e 67 20 6d 75 74 65 78 2e eexisting mutex.
24660 20 20 46 6f 75 72 20 73 74 61 74 69 63 20 6d 75 Four static mu
24670 74 65 78 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 texes are.** use
24680 64 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 d by the current
24690 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 version of SQLi
246a0 74 65 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 te. Future vers
246b0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a ions of SQLite.*
246c0 2a 20 6d 61 79 20 61 64 64 20 61 64 64 69 74 69 * may add additi
246d0 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d 75 74 65 onal static mute
246e0 78 65 73 2e 20 20 53 74 61 74 69 63 20 6d 75 74 xes. Static mut
246f0 65 78 65 73 20 61 72 65 20 66 6f 72 20 69 6e 74 exes are for int
24700 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 ernal.** use by
24710 53 51 4c 69 74 65 20 6f 6e 6c 79 2e 20 20 41 70 SQLite only. Ap
24720 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 plications that
24730 75 73 65 20 53 51 4c 69 74 65 20 6d 75 74 65 78 use SQLite mutex
24740 65 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 75 73 65 es should.** use
24750 20 6f 6e 6c 79 20 74 68 65 20 64 79 6e 61 6d 69 only the dynami
24760 63 20 6d 75 74 65 78 65 73 20 72 65 74 75 72 6e c mutexes return
24770 65 64 20 62 79 20 53 51 4c 49 54 45 5f 4d 55 54 ed by SQLITE_MUT
24780 45 58 5f 46 41 53 54 20 6f 72 0a 2a 2a 20 53 51 EX_FAST or.** SQ
24790 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 LITE_MUTEX_RECUR
247a0 53 49 56 45 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 SIVE..**.** Note
247b0 20 74 68 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 that if one of
247c0 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 the dynamic mute
247d0 78 20 70 61 72 61 6d 65 74 65 72 73 20 28 53 51 x parameters (SQ
247e0 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a LITE_MUTEX_FAST.
247f0 2a 2a 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 ** or SQLITE_MUT
24800 45 58 5f 52 45 43 55 52 53 49 56 45 29 20 69 73 EX_RECURSIVE) is
24810 20 75 73 65 64 20 74 68 65 6e 20 73 71 6c 69 74 used then sqlit
24820 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 e3_mutex_alloc()
24830 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 64 69 .** returns a di
24840 66 66 65 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e fferent mutex on
24850 20 65 76 65 72 79 20 63 61 6c 6c 2e 20 20 42 75 every call. Bu
24860 74 20 66 6f 72 20 74 68 65 20 73 74 61 74 69 63 t for the static
24870 20 0a 2a 2a 20 6d 75 74 65 78 20 74 79 70 65 73 .** mutex types
24880 2c 20 74 68 65 20 73 61 6d 65 20 6d 75 74 65 78 , the same mutex
24890 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 6e 20 is returned on
248a0 65 76 65 72 79 20 63 61 6c 6c 20 74 68 61 74 20 every call that
248b0 68 61 73 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 has.** the same
248c0 74 79 70 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a type number..**.
248d0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d ** The sqlite3_m
248e0 75 74 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74 utex_free() rout
248f0 69 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 ine deallocates
24900 61 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 a previously.**
24910 61 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69 allocated dynami
24920 63 20 6d 75 74 65 78 2e 20 20 53 51 4c 69 74 65 c mutex. SQLite
24930 20 69 73 20 63 61 72 65 66 75 6c 20 74 6f 20 64 is careful to d
24940 65 61 6c 6c 6f 63 61 74 65 20 65 76 65 72 79 0a eallocate every.
24950 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 ** dynamic mutex
24960 20 74 68 61 74 20 69 74 20 61 6c 6c 6f 63 61 74 that it allocat
24970 65 73 2e 20 20 54 68 65 20 64 79 6e 61 6d 69 63 es. The dynamic
24980 20 6d 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f mutexes must no
24990 74 20 62 65 20 69 6e 20 0a 2a 2a 20 75 73 65 20 t be in .** use
249a0 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 64 65 when they are de
249b0 61 6c 6c 6f 63 61 74 65 64 2e 20 20 41 74 74 65 allocated. Atte
249c0 6d 70 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f mpting to deallo
249d0 63 61 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a cate a static.**
249e0 20 6d 75 74 65 78 20 72 65 73 75 6c 74 73 20 69 mutex results i
249f0 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 n undefined beha
24a00 76 69 6f 72 2e 20 20 53 51 4c 69 74 65 20 6e 65 vior. SQLite ne
24a10 76 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a ver deallocates.
24a20 2a 2a 20 61 20 73 74 61 74 69 63 20 6d 75 74 65 ** a static mute
24a30 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c x..**.** The sql
24a40 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 ite3_mutex_enter
24a50 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d () and sqlite3_m
24a60 75 74 65 78 5f 74 72 79 28 29 20 72 6f 75 74 69 utex_try() routi
24a70 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74 nes attempt.** t
24a80 6f 20 65 6e 74 65 72 20 61 20 6d 75 74 65 78 2e o enter a mutex.
24a90 20 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 If another thr
24aa0 65 61 64 20 69 73 20 61 6c 72 65 61 64 79 20 77 ead is already w
24ab0 69 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78 2c ithin the mutex,
24ac0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 .** sqlite3_mute
24ad0 78 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20 62 x_enter() will b
24ae0 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65 33 lock and sqlite3
24af0 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69 6c _mutex_try() wil
24b00 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 l return.** SQLI
24b10 54 45 5f 42 55 53 59 2e 20 20 54 68 65 20 73 71 TE_BUSY. The sq
24b20 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 lite3_mutex_try(
24b30 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
24b40 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 0a 2a 2a rns SQLITE_OK.**
24b50 20 75 70 6f 6e 20 73 75 63 63 65 73 73 66 75 6c upon successful
24b60 20 65 6e 74 72 79 2e 20 20 4d 75 74 65 78 65 73 entry. Mutexes
24b70 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 53 created using S
24b80 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 QLITE_MUTEX_RECU
24b90 52 53 49 56 45 20 63 61 6e 0a 2a 2a 20 62 65 20 RSIVE can.** be
24ba0 65 6e 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 entered multiple
24bb0 20 74 69 6d 65 73 20 62 79 20 74 68 65 20 73 61 times by the sa
24bc0 6d 65 20 74 68 72 65 61 64 2e 20 20 49 6e 20 73 me thread. In s
24bd0 75 63 68 20 63 61 73 65 73 20 74 68 65 2c 0a 2a uch cases the,.*
24be0 2a 20 6d 75 74 65 78 20 6d 75 73 74 20 62 65 20 * mutex must be
24bf0 65 78 69 74 65 64 20 61 6e 20 65 71 75 61 6c 20 exited an equal
24c00 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 number of times
24c10 62 65 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 74 before another t
24c20 68 72 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74 hread.** can ent
24c30 65 72 2e 20 20 49 66 20 74 68 65 20 73 61 6d 65 er. If the same
24c40 20 74 68 72 65 61 64 20 74 72 69 65 73 20 74 6f thread tries to
24c50 20 65 6e 74 65 72 20 61 6e 79 20 6f 74 68 65 72 enter any other
24c60 20 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78 0a 2a kind of mutex.*
24c70 2a 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 * more than once
24c80 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 , the behavior i
24c90 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 20 53 s undefined. S
24ca0 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 QLite will never
24cb0 20 65 78 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 exhibit.** such
24cc0 20 62 65 68 61 76 69 6f 72 20 69 6e 20 69 74 73 behavior in its
24cd0 20 6f 77 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 own use of mute
24ce0 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 xes..**.** Some
24cf0 73 79 73 74 65 6d 73 20 28 65 78 3a 20 77 69 6e systems (ex: win
24d00 64 6f 77 73 39 35 29 20 64 6f 20 6e 6f 74 20 74 dows95) do not t
24d10 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 6d 70 he operation imp
24d20 6c 65 6d 65 6e 74 65 64 20 62 79 0a 2a 2a 20 73 lemented by.** s
24d30 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 qlite3_mutex_try
24d40 28 29 2e 20 20 4f 6e 20 74 68 6f 73 65 20 73 79 (). On those sy
24d50 73 74 65 6d 73 2c 20 73 71 6c 69 74 65 33 5f 6d stems, sqlite3_m
24d60 75 74 65 78 5f 74 72 79 28 29 20 77 69 6c 6c 0a utex_try() will.
24d70 2a 2a 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e ** always return
24d80 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 54 SQLITE_BUSY. T
24d90 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6f he SQLite core o
24da0 6e 6c 79 20 65 76 65 72 20 75 73 65 73 0a 2a 2a nly ever uses.**
24db0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 sqlite3_mutex_t
24dc0 72 79 28 29 20 61 73 20 61 6e 20 6f 70 74 69 6d ry() as an optim
24dd0 69 7a 61 74 69 6f 6e 20 73 6f 20 74 68 69 73 20 ization so this
24de0 69 73 20 61 63 63 65 70 74 61 62 6c 65 20 62 65 is acceptable be
24df0 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 havior..**.** Th
24e00 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f e sqlite3_mutex_
24e10 6c 65 61 76 65 28 29 20 72 6f 75 74 69 6e 65 20 leave() routine
24e20 65 78 69 74 73 20 61 20 6d 75 74 65 78 20 74 68 exits a mutex th
24e30 61 74 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f at was.** previo
24e40 75 73 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20 usly entered by
24e50 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e the same thread.
24e60 20 20 54 68 65 20 62 65 68 61 76 69 6f 72 0a 2a The behavior.*
24e70 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 69 * is undefined i
24e80 66 20 74 68 65 20 6d 75 74 65 78 20 69 73 20 6e f the mutex is n
24e90 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 ot currently ent
24ea0 65 72 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 63 ered by the.** c
24eb0 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 6f 72 alling thread or
24ec0 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c is not currentl
24ed0 79 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 53 51 y allocated. SQ
24ee0 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 Lite will.** nev
24ef0 65 72 20 64 6f 20 65 69 74 68 65 72 2e 0a 2a 2a er do either..**
24f00 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
24f10 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c qlite3_mutex_hel
24f20 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 d()] and [sqlite
24f30 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 3_mutex_notheld(
24f40 29 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d )]..*/.sqlite3_m
24f50 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75 utex *sqlite3_mu
24f60 74 65 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a tex_alloc(int);.
24f70 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 void sqlite3_mut
24f80 65 78 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f ex_free(sqlite3_
24f90 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 mutex*);.void sq
24fa0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 lite3_mutex_ente
24fb0 72 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a r(sqlite3_mutex*
24fc0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d );.int sqlite3_m
24fd0 75 74 65 78 5f 74 72 79 28 73 71 6c 69 74 65 33 utex_try(sqlite3
24fe0 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 _mutex*);.void s
24ff0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 qlite3_mutex_lea
25000 76 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ve(sqlite3_mutex
25010 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
25020 52 45 46 3a 20 4d 75 74 65 78 20 56 65 72 69 66 REF: Mutex Verif
25030 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a cation Routines.
25040 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
25050 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 61 3_mutex_held() a
25060 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 nd sqlite3_mutex
25070 5f 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75 74 69 _notheld() routi
25080 6e 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e nes.** are inten
25090 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 ded for use insi
250a0 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74 de assert() stat
250b0 65 6d 65 6e 74 73 2e 20 20 54 68 65 20 53 51 4c ements. The SQL
250c0 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65 ite core.** neve
250d0 72 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 r uses these rou
250e0 74 69 6e 65 73 20 65 78 63 65 70 74 20 69 6e 73 tines except ins
250f0 69 64 65 20 61 6e 20 61 73 73 65 72 74 28 29 20 ide an assert()
25100 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 and applications
25110 0a 2a 2a 20 61 72 65 20 61 64 76 69 73 65 64 20 .** are advised
25120 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65 to follow the le
25130 61 64 20 6f 66 20 74 68 65 20 63 6f 72 65 2e 20 ad of the core.
25140 20 54 68 65 20 63 6f 72 65 20 6f 6e 6c 79 0a 2a The core only.*
25150 2a 20 70 72 6f 76 69 64 65 73 20 69 6d 70 6c 65 * provides imple
25160 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 74 mentations for t
25170 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 68 hese routines wh
25180 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 en it is compile
25190 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 53 51 d.** with the SQ
251a0 4c 49 54 45 5f 44 45 42 55 47 20 66 6c 61 67 2e LITE_DEBUG flag.
251b0 20 20 45 78 74 65 72 6e 61 6c 20 6d 75 74 65 78 External mutex
251c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
251d0 0a 2a 2a 20 61 72 65 20 6f 6e 6c 79 20 72 65 71 .** are only req
251e0 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 uired to provide
251f0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
25200 69 66 20 53 51 4c 49 54 45 5f 44 45 42 55 47 20 if SQLITE_DEBUG
25210 69 73 0a 2a 2a 20 64 65 66 69 6e 65 64 20 61 6e is.** defined an
25220 64 20 69 66 20 4e 44 45 42 55 47 20 69 73 20 6e d if NDEBUG is n
25230 6f 74 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a ot defined..**.*
25240 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
25250 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 should return t
25260 72 75 65 20 69 66 20 74 68 65 20 6d 75 74 65 78 rue if the mutex
25270 20 69 6e 20 74 68 65 69 72 20 61 72 67 75 6d 65 in their argume
25280 6e 74 0a 2a 2a 20 69 73 20 68 65 6c 64 20 6f 72 nt.** is held or
25290 20 6e 6f 74 20 68 65 6c 64 2c 20 72 65 73 70 65 not held, respe
252a0 63 74 69 76 65 6c 79 2c 20 62 79 20 74 68 65 20 ctively, by the
252b0 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 2e 0a calling thread..
252c0 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d **.** The implem
252d0 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 entation is not
252e0 72 65 71 75 69 72 65 64 20 74 6f 20 70 72 6f 76 required to prov
252f0 69 64 65 64 20 76 65 72 73 69 6f 6e 73 20 6f 66 ided versions of
25300 20 74 68 65 73 65 0a 2a 2a 20 72 6f 75 74 69 6e these.** routin
25310 65 73 20 74 68 61 74 20 61 63 74 75 61 6c 6c 79 es that actually
25320 20 77 6f 72 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 work..** If the
25330 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
25340 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 does not provide
25350 20 77 6f 72 6b 69 6e 67 0a 2a 2a 20 76 65 72 73 working.** vers
25360 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 20 72 6f ions of these ro
25370 75 74 69 6e 65 73 2c 20 69 74 20 73 68 6f 75 6c utines, it shoul
25380 64 20 61 74 20 6c 65 61 73 74 20 70 72 6f 76 69 d at least provi
25390 64 65 20 73 74 75 62 73 0a 2a 2a 20 74 68 61 74 de stubs.** that
253a0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 always return t
253b0 72 75 65 20 73 6f 20 74 68 61 74 20 6f 6e 65 20 rue so that one
253c0 64 6f 65 73 20 6e 6f 74 20 67 65 74 20 73 70 75 does not get spu
253d0 72 69 6f 75 73 0a 2a 2a 20 61 73 73 65 72 74 69 rious.** asserti
253e0 6f 6e 20 66 61 69 6c 75 72 65 73 2e 0a 2a 2a 0a on failures..**.
253f0 2a 2a 20 49 66 20 74 68 65 20 61 72 67 75 6d 65 ** If the argume
25400 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 nt to sqlite3_mu
25410 74 65 78 5f 68 65 6c 64 28 29 20 69 73 20 61 20 tex_held() is a
25420 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 NULL pointer the
25430 6e 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 n.** the routine
25440 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 31 should return 1
25450 2e 20 20 54 68 69 73 20 73 65 65 6d 73 20 63 6f . This seems co
25460 75 6e 74 65 72 2d 69 6e 74 75 69 74 69 76 65 20 unter-intuitive
25470 73 69 6e 63 65 0a 2a 2a 20 63 6c 65 61 72 6c 79 since.** clearly
25480 20 74 68 65 20 6d 75 74 65 78 20 63 61 6e 6e 6f the mutex canno
25490 74 20 62 65 20 68 65 6c 64 20 69 66 20 69 74 20 t be held if it
254a0 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 2e 20 does not exist.
254b0 20 42 75 74 20 74 68 65 0a 2a 2a 20 74 68 65 20 But the.** the
254c0 72 65 61 73 6f 6e 20 74 68 65 20 6d 75 74 65 78 reason the mutex
254d0 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20 does not exist
254e0 69 73 20 62 65 63 61 75 73 65 20 74 68 65 20 62 is because the b
254f0 75 69 6c 64 20 69 73 20 6e 6f 74 0a 2a 2a 20 75 uild is not.** u
25500 73 69 6e 67 20 6d 75 74 65 78 65 73 2e 20 20 41 sing mutexes. A
25510 6e 64 20 77 65 20 64 6f 20 6e 6f 74 20 77 61 6e nd we do not wan
25520 74 20 74 68 65 20 61 73 73 65 72 74 28 29 20 63 t the assert() c
25530 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a ontaining the.**
25540 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
25550 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 74 6f _mutex_held() to
25560 20 66 61 69 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d fail, so a non-
25570 7a 65 72 6f 20 72 65 74 75 72 6e 20 69 73 0a 2a zero return is.*
25580 2a 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 * the appropriat
25590 65 20 74 68 69 6e 67 20 74 6f 20 64 6f 2e 20 20 e thing to do.
255a0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 The sqlite3_mute
255b0 78 5f 6e 6f 74 68 65 6c 64 28 29 20 0a 2a 2a 20 x_notheld() .**
255c0 69 6e 74 65 72 66 61 63 65 20 73 68 6f 75 6c 64 interface should
255d0 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 31 20 77 also return 1 w
255e0 68 65 6e 20 67 69 76 65 6e 20 61 20 4e 55 4c 4c hen given a NULL
255f0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 69 6e 74 pointer..*/.int
25600 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 sqlite3_mutex_h
25610 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 eld(sqlite3_mute
25620 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 x*);.int sqlite3
25630 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 73 _mutex_notheld(s
25640 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a qlite3_mutex*);.
25650 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
25660 20 4d 75 74 65 78 20 54 79 70 65 73 0a 2a 2a 0a Mutex Types.**.
25670 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f ** The [sqlite3_
25680 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 69 mutex_alloc()] i
25690 6e 74 65 72 66 61 63 65 20 74 61 6b 65 73 20 61 nterface takes a
256a0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
256b0 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 6f 6e 65 .** which is one
256c0 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 of these intege
256d0 72 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2f 0a r constants..*/.
256e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d #define SQLITE_M
256f0 55 54 45 58 5f 46 41 53 54 20 20 20 20 20 20 20 UTEX_FAST
25700 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 0.#define
25710 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 SQLITE_MUTEX_REC
25720 55 52 53 49 56 45 20 20 20 20 20 20 20 20 31 0a URSIVE 1.
25730 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d #define SQLITE_M
25740 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 UTEX_STATIC_MAST
25750 45 52 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 ER 2.#define
25760 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 SQLITE_MUTEX_STA
25770 54 49 43 5f 4d 45 4d 20 20 20 20 20 20 20 33 20 TIC_MEM 3
25780 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c /* sqlite3_mall
25790 6f 63 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 oc() */.#define
257a0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 SQLITE_MUTEX_STA
257b0 54 49 43 5f 4d 45 4d 32 20 20 20 20 20 20 34 20 TIC_MEM2 4
257c0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 /* sqlite3_rele
257d0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 2a 2f 0a ase_memory() */.
257e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d #define SQLITE_M
257f0 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 UTEX_STATIC_PRNG
25800 20 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 5 /* sqli
25810 74 65 33 5f 72 61 6e 64 6f 6d 28 29 20 2a 2f 0a te3_random() */.
25820 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d #define SQLITE_M
25830 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 20 UTEX_STATIC_LRU
25840 20 20 20 20 20 20 36 20 20 2f 2a 20 6c 72 75 20 6 /* lru
25850 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a 0a 2f 2a page list */../*
25860 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f .** CAPI3REF: Lo
25870 77 2d 4c 65 76 65 6c 20 43 6f 6e 74 72 6f 6c 20 w-Level Control
25880 4f 66 20 44 61 74 61 62 61 73 65 20 46 69 6c 65 Of Database File
25890 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c s.**.** The [sql
258a0 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
258b0 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 6d l()] interface m
258c0 61 6b 65 73 20 61 20 64 69 72 65 63 74 20 63 61 akes a direct ca
258d0 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 78 46 69 ll to the.** xFi
258e0 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 leControl method
258f0 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 for the [sqlite
25900 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
25910 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 0a ject associated.
25920 2a 2a 20 77 69 74 68 20 61 20 70 61 72 74 69 63 ** with a partic
25930 75 6c 61 72 20 64 61 74 61 62 61 73 65 20 69 64 ular database id
25940 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 entified by the
25950 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e second argument.
25960 20 20 54 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 The.** name of
25970 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 the database is
25980 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e the name assign
25990 65 64 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 ed to the databa
259a0 73 65 20 62 79 20 74 68 65 0a 2a 2a 20 3c 61 20 se by the.** <a
259b0 68 72 65 66 3d 22 6c 61 6e 67 5f 61 74 74 61 63 href="lang_attac
259c0 68 2e 68 74 6d 6c 22 3e 41 54 54 41 43 48 3c 2f h.html">ATTACH</
259d0 61 3e 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 a> SQL command t
259e0 68 61 74 20 6f 70 65 6e 65 64 20 74 68 65 0a 2a hat opened the.*
259f0 2a 20 64 61 74 61 62 61 73 65 2e 20 20 54 6f 20 * database. To
25a00 63 6f 6e 74 72 6f 6c 20 74 68 65 20 6d 61 69 6e control the main
25a10 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 database file,
25a20 75 73 65 20 74 68 65 20 6e 61 6d 65 20 22 6d 61 use the name "ma
25a30 69 6e 22 0a 2a 2a 20 6f 72 20 61 20 4e 55 4c 4c in".** or a NULL
25a40 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 74 pointer. The t
25a50 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 hird and fourth
25a60 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 parameters to th
25a70 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 61 72 is routine.** ar
25a80 65 20 70 61 73 73 65 64 20 64 69 72 65 63 74 6c e passed directl
25a90 79 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 y through to the
25aa0 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 second and thir
25ab0 64 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 0a d parameters of.
25ac0 2a 2a 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 ** the xFileCont
25ad0 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 20 54 68 65 rol method. The
25ae0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 return value of
25af0 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f the xFileContro
25b00 6c 0a 2a 2a 20 6d 65 74 68 6f 64 20 62 65 63 6f l.** method beco
25b10 6d 65 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 mes the return v
25b20 61 6c 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75 alue of this rou
25b30 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 tine..**.** If t
25b40 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
25b50 74 65 72 20 28 7a 44 62 4e 61 6d 65 29 20 64 6f ter (zDbName) do
25b60 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 74 68 65 es not match the
25b70 20 6e 61 6d 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 name of any.**
25b80 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 66 69 open database fi
25b90 6c 65 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f le, then SQLITE_
25ba0 45 52 52 4f 52 20 69 73 20 72 65 74 75 72 6e 65 ERROR is returne
25bb0 64 2e 20 20 54 68 69 73 20 65 72 72 6f 72 0a 2a d. This error.*
25bc0 2a 20 63 6f 64 65 20 69 73 20 6e 6f 74 20 72 65 * code is not re
25bd0 6d 65 6d 62 65 72 65 64 20 61 6e 64 20 77 69 6c membered and wil
25be0 6c 20 6e 6f 74 20 62 65 20 72 65 63 61 6c 6c 65 l not be recalle
25bf0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 d by [sqlite3_er
25c00 72 63 6f 64 65 28 29 5d 0a 2a 2a 20 6f 72 20 5b rcode()].** or [
25c10 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
25c20 5d 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 ]. The underlyi
25c30 6e 67 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 ng xFileControl
25c40 6d 65 74 68 6f 64 20 6d 69 67 68 74 0a 2a 2a 20 method might.**
25c50 61 6c 73 6f 20 72 65 74 75 72 6e 20 53 51 4c 49 also return SQLI
25c60 54 45 5f 45 52 52 4f 52 2e 20 20 54 68 65 72 65 TE_ERROR. There
25c70 20 69 73 20 6e 6f 20 77 61 79 20 74 6f 20 64 69 is no way to di
25c80 73 74 69 6e 67 75 69 73 68 20 62 65 74 77 65 65 stinguish betwee
25c90 6e 0a 2a 2a 20 61 6e 20 69 6e 63 6f 72 72 65 63 n.** an incorrec
25ca0 74 20 7a 44 62 4e 61 6d 65 20 61 6e 64 20 61 6e t zDbName and an
25cb0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 72 65 SQLITE_ERROR re
25cc0 74 75 72 6e 20 66 72 6f 6d 20 74 68 65 20 75 6e turn from the un
25cd0 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 78 46 69 6c derlying.** xFil
25ce0 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e eControl method.
25cf0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
25d00 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c [SQLITE_FCNTL_L
25d10 4f 43 4b 53 54 41 54 45 5d 0a 2a 2f 0a 69 6e 74 OCKSTATE].*/.int
25d20 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f sqlite3_file_co
25d30 6e 74 72 6f 6c 28 73 71 6c 69 74 65 33 2a 2c 20 ntrol(sqlite3*,
25d40 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e const char *zDbN
25d50 61 6d 65 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 ame, int op, voi
25d60 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 55 6e 64 6f d*);../*.** Undo
25d70 20 74 68 65 20 68 61 63 6b 20 74 68 61 74 20 63 the hack that c
25d80 6f 6e 76 65 72 74 73 20 66 6c 6f 61 74 69 6e 67 onverts floating
25d90 20 70 6f 69 6e 74 20 74 79 70 65 73 20 74 6f 20 point types to
25da0 69 6e 74 65 67 65 72 20 66 6f 72 0a 2a 2a 20 62 integer for.** b
25db0 75 69 6c 64 73 20 6f 6e 20 70 72 6f 63 65 73 73 uilds on process
25dc0 6f 72 73 20 77 69 74 68 6f 75 74 20 66 6c 6f 61 ors without floa
25dd0 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f ting point suppo
25de0 72 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 rt..*/.#ifdef SQ
25df0 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 LITE_OMIT_FLOATI
25e00 4e 47 5f 50 4f 49 4e 54 0a 23 20 75 6e 64 65 66 NG_POINT.# undef
25e10 20 64 6f 75 62 6c 65 0a 23 65 6e 64 69 66 0a 0a double.#endif..
25e20 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c #ifdef __cpluspl
25e30 75 73 0a 7d 20 20 2f 2a 20 45 6e 64 20 6f 66 20 us.} /* End of
25e40 74 68 65 20 27 65 78 74 65 72 6e 20 22 43 22 27 the 'extern "C"'
25e50 20 62 6c 6f 63 6b 20 2a 2f 0a 23 65 6e 64 69 66 block */.#endif
25e60 0a 23 65 6e 64 69 66 0a .#endif.