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 0a 2a 2a 20 74 6f 20 e changes.** to
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65 erfaces but rese
03b0: 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f rve to make mino
03c0: 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a 20 r changes if.**
03d0: 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20 experience from
03e0: 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64 use "in the wild
03f0: 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20 63 " suggest such c
0400: 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 65 hanges are prude
0410: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66 nt..**.** The of
0420: 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67 ficial C-languag
0430: 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74 e API documentat
0440: 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69 ion for SQLite i
0450: 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f s derived.** fro
0460: 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68 m comments in th
0470: 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66 is file. This f
0480: 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 6f ile is the autho
0490: 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a ritative source.
04a0: 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65 ** on how SQLite
04b0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
04c0: 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61 suppose to opera
04d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 te..**.** The na
04e0: 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 me of this file
04f0: 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74 under configurat
0500: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69 ion management i
0510: 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e s "sqlite.h.in".
0520: 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65 .** The makefile
0530: 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f makes some mino
0540: 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69 r changes to thi
0550: 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20 s file (such as
0560: 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65 inserting.** the
0570: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29 version number)
0580: 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73 and changes its
0590: 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65 name to "sqlite
05a0: 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20 3.h" as.** part
05b0: 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f of the build pro
05c0: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23 29 cess..**.** @(#)
05d0: 20 24 49 64 3a 20 73 71 6c 69 74 65 33 2e 68 2c $Id: sqlite3.h,
05e0: 76 20 31 2e 31 20 32 30 30 38 2f 30 38 2f 30 36 v 1.1 2008/08/06
05f0: 20 32 31 3a 34 38 3a 30 37 20 72 6d 73 69 6d 70 21:48:07 rmsimp
0600: 73 6f 6e 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66 son Exp $.*/.#if
0610: 6e 64 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f ndef _SQLITE3_H_
0620: 0a 23 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 .#define _SQLITE
0630: 33 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 3_H_.#include <s
0640: 74 64 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 tdarg.h> /*
0650: 4e 65 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 Needed for the d
0660: 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f efinition of va_
0670: 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d list */../*.** M
0680: 61 6b 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 ake sure we can
0690: 63 61 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 call this stuff
06a0: 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 from C++..*/.#if
06b0: 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a def __cplusplus.
06c0: 65 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e extern "C" {.#en
06d0: 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 dif.../*.** Add
06e0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f the ability to o
06f0: 76 65 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 verride 'extern'
0700: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 .*/.#ifndef SQLI
0710: 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 TE_EXTERN.# defi
0720: 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e ne SQLITE_EXTERN
0730: 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a extern.#endif..
0740: 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 /*.** Ensure the
0750: 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 se symbols were
0760: 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 not defined by s
0770: 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 ome previous hea
0780: 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 der file..*/.#if
0790: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 def SQLITE_VERSI
07a0: 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 ON.# undef SQLIT
07b0: 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 E_VERSION.#endif
07c0: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 .#ifdef SQLITE_V
07d0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 ERSION_NUMBER.#
07e0: 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 undef SQLITE_VER
07f0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 SION_NUMBER.#end
0800: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 if../*.** CAPI3R
0810: 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 EF: Compile-Time
0820: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e Library Version
0830: 20 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 31 30 Numbers {H10010
0840: 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a 2a } <S60100>.**.**
0850: 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 The SQLITE_VERS
0860: 49 4f 4e 20 61 6e 64 20 53 51 4c 49 54 45 5f 56 ION and SQLITE_V
0870: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 23 64 ERSION_NUMBER #d
0880: 65 66 69 6e 65 73 20 69 6e 0a 2a 2a 20 74 68 65 efines in.** the
0890: 20 73 71 6c 69 74 65 33 2e 68 20 66 69 6c 65 20 sqlite3.h file
08a0: 73 70 65 63 69 66 79 20 74 68 65 20 76 65 72 73 specify the vers
08b0: 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 77 69 ion of SQLite wi
08c0: 74 68 20 77 68 69 63 68 0a 2a 2a 20 74 68 61 74 th which.** that
08d0: 20 68 65 61 64 65 72 20 66 69 6c 65 20 69 73 20 header file is
08e0: 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a 2a associated..**.*
08f0: 2a 20 54 68 65 20 22 76 65 72 73 69 6f 6e 22 20 * The "version"
0900: 6f 66 20 53 51 4c 69 74 65 20 69 73 20 61 20 73 of SQLite is a s
0910: 74 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6f 72 tring of the for
0920: 6d 20 22 58 2e 59 2e 5a 22 2e 0a 2a 2a 20 54 68 m "X.Y.Z"..** Th
0930: 65 20 70 68 72 61 73 65 20 22 61 6c 70 68 61 22 e phrase "alpha"
0940: 20 6f 72 20 22 62 65 74 61 22 20 6d 69 67 68 74 or "beta" might
0950: 20 62 65 20 61 70 70 65 6e 64 65 64 20 61 66 74 be appended aft
0960: 65 72 20 74 68 65 20 5a 2e 0a 2a 2a 20 54 68 65 er the Z..** The
0970: 20 58 20 76 61 6c 75 65 20 69 73 20 6d 61 6a 6f X value is majo
0980: 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 r version number
0990: 20 61 6c 77 61 79 73 20 33 20 69 6e 20 53 51 4c always 3 in SQL
09a0: 69 74 65 33 2e 0a 2a 2a 20 54 68 65 20 58 20 76 ite3..** The X v
09b0: 61 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67 65 alue only change
09c0: 73 20 77 68 65 6e 20 62 61 63 6b 77 61 72 64 73 s when backwards
09d0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 69 compatibility i
09e0: 73 0a 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64 20 s.** broken and
09f0: 77 65 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65 76 we intend to nev
0a00: 65 72 20 62 72 65 61 6b 20 62 61 63 6b 77 61 72 er break backwar
0a10: 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ds compatibility
0a20: 2e 0a 2a 2a 20 54 68 65 20 59 20 76 61 6c 75 65 ..** The Y value
0a30: 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 is the minor ve
0a40: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 rsion number and
0a50: 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77 68 only changes wh
0a60: 65 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72 65 20 en.** there are
0a70: 6d 61 6a 6f 72 20 66 65 61 74 75 72 65 20 65 6e major feature en
0a80: 68 61 6e 63 65 6d 65 6e 74 73 20 74 68 61 74 20 hancements that
0a90: 61 72 65 20 66 6f 72 77 61 72 64 73 20 63 6f 6d are forwards com
0aa0: 70 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20 6e patible.** but n
0ab0: 6f 74 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d ot backwards com
0ac0: 70 61 74 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 20 patible..** The
0ad0: 5a 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 72 Z value is the r
0ae0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 20 61 6e elease number an
0af0: 64 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 d is incremented
0b00: 20 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72 65 with.** each re
0b10: 6c 65 61 73 65 20 62 75 74 20 72 65 73 65 74 73 lease but resets
0b20: 20 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e 65 back to 0 whene
0b30: 76 65 72 20 59 20 69 73 20 69 6e 63 72 65 6d 65 ver Y is increme
0b40: 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 nted..**.** See
0b50: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c also: [sqlite3_l
0b60: 69 62 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 ibversion()] and
0b70: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 [sqlite3_libver
0b80: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2e 0a sion_number()]..
0b90: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
0ba0: 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 31 31 7d :.**.** {H10011}
0bb0: 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 The SQLITE_VERS
0bc0: 49 4f 4e 20 23 64 65 66 69 6e 65 20 69 6e 20 74 ION #define in t
0bd0: 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61 he sqlite3.h hea
0be0: 64 65 72 20 66 69 6c 65 20 73 68 61 6c 6c 0a 2a der file shall.*
0bf0: 2a 20 20 20 20 20 20 20 20 20 20 65 76 61 6c 75 * evalu
0c00: 61 74 65 20 74 6f 20 61 20 73 74 72 69 6e 67 20 ate to a string
0c10: 6c 69 74 65 72 61 6c 20 74 68 61 74 20 69 73 20 literal that is
0c20: 74 68 65 20 53 51 4c 69 74 65 20 76 65 72 73 69 the SQLite versi
0c30: 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 on.** w
0c40: 69 74 68 20 77 68 69 63 68 20 74 68 65 20 68 65 ith which the he
0c50: 61 64 65 72 20 66 69 6c 65 20 69 73 20 61 73 73 ader file is ass
0c60: 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b ociated..**.** {
0c70: 48 31 30 30 31 34 7d 20 54 68 65 20 53 51 4c 49 H10014} The SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 TE_VERSION_NUMBE
0c90: 52 20 23 64 65 66 69 6e 65 20 73 68 61 6c 6c 20 R #define shall
0ca0: 72 65 73 6f 6c 76 65 20 74 6f 20 61 6e 20 69 6e resolve to an in
0cb0: 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 teger.**
0cc0: 20 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 with the value
0cd0: 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a (X*1000000 + Y*
0ce0: 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 1000 + Z) where
0cf0: 58 2c 20 59 2c 20 61 6e 64 20 5a 0a 2a 2a 20 20 X, Y, and Z.**
0d00: 20 20 20 20 20 20 20 20 61 72 65 20 74 68 65 20 are the
0d10: 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 2c 20 6d major version, m
0d20: 69 6e 6f 72 20 76 65 72 73 69 6f 6e 2c 20 61 6e inor version, an
0d30: 64 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 d release number
0d40: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
0d50: 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 ITE_VERSION
0d60: 20 20 20 20 22 33 2e 36 2e 31 22 0a 23 64 65 66 "3.6.1".#def
0d70: 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 ine SQLITE_VERSI
0d80: 4f 4e 5f 4e 55 4d 42 45 52 20 20 33 30 30 36 30 ON_NUMBER 30060
0d90: 30 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 01../*.** CAPI3R
0da0: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 EF: Run-Time Lib
0db0: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d rary Version Num
0dc0: 62 65 72 73 20 7b 48 31 30 30 32 30 7d 20 3c 53 bers {H10020} <S
0dd0: 36 30 31 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 60100>.** KEYWOR
0de0: 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 DS: sqlite3_vers
0df0: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ion.**.** These
0e00: 66 65 61 74 75 72 65 73 20 70 72 6f 76 69 64 65 features provide
0e10: 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d the same inform
0e20: 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 ation as the [SQ
0e30: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a LITE_VERSION].**
0e40: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 56 45 52 and [SQLITE_VER
0e50: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 23 64 65 SION_NUMBER] #de
0e60: 66 69 6e 65 73 20 69 6e 20 74 68 65 20 68 65 61 fines in the hea
0e70: 64 65 72 2c 20 62 75 74 20 61 72 65 20 61 73 73 der, but are ass
0e80: 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 ociated.** with
0e90: 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 the library inst
0ea0: 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 ead of the heade
0eb0: 72 20 66 69 6c 65 2e 20 20 43 61 75 74 69 6f 75 r file. Cautiou
0ec0: 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 s programmers mi
0ed0: 67 68 74 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 61 ght.** include a
0ee0: 20 63 68 65 63 6b 20 69 6e 20 74 68 65 69 72 20 check in their
0ef0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 76 application to v
0f00: 65 72 69 66 79 20 74 68 61 74 0a 2a 2a 20 73 71 erify that.** sq
0f10: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e lite3_libversion
0f20: 5f 6e 75 6d 62 65 72 28 29 20 61 6c 77 61 79 73 _number() always
0f30: 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c returns the val
0f40: 75 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 ue.** [SQLITE_VE
0f50: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a RSION_NUMBER]..*
0f60: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 _libversion() fu
0f80: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 nction returns t
0f90: 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 he same informat
0fa0: 69 6f 6e 20 61 73 20 69 73 0a 2a 2a 20 69 6e 20 ion as is.** in
0fb0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 the sqlite3_vers
0fc0: 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e ion[] string con
0fd0: 73 74 61 6e 74 2e 20 20 54 68 65 20 66 75 6e 63 stant. The func
0fe0: 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 tion is provided
0ff0: 0a 2a 2a 20 66 6f 72 20 75 73 65 20 69 6e 20 44 .** for use in D
1000: 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 LLs since DLL us
1010: 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e ers usually do n
1020: 6f 74 20 68 61 76 65 20 64 69 72 65 63 74 20 61 ot have direct a
1030: 63 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 0a ccess to string.
1040: 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 ** constants wit
1050: 68 69 6e 20 74 68 65 20 44 4c 4c 2e 0a 2a 2a 0a hin the DLL..**.
1060: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
1070: 2a 0a 2a 2a 20 7b 48 31 30 30 32 31 7d 20 54 68 *.** {H10021} Th
1080: 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 e [sqlite3_libve
1090: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 20 rsion_number()]
10a0: 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 interface shall
10b0: 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 return.**
10c0: 20 20 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71 an integer eq
10d0: 75 61 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 56 ual to [SQLITE_V
10e0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a ERSION_NUMBER]..
10f0: 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32 32 7d 20 54 **.** {H10022} T
1100: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 73 he [sqlite3_vers
1110: 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 ion] string cons
1120: 74 61 6e 74 20 73 68 61 6c 6c 20 63 6f 6e 74 61 tant shall conta
1130: 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 in.** t
1140: 68 65 20 74 65 78 74 20 6f 66 20 74 68 65 20 5b he text of the [
1150: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 SQLITE_VERSION]
1160: 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 string..**.** {H
1170: 31 30 30 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 10023} The [sqli
1180: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 te3_libversion()
1190: 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c ] function shall
11a0: 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 return.**
11b0: 20 20 20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f a pointer to
11c0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 65 the [sqlite3_ve
11d0: 72 73 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f rsion] string co
11e0: 6e 73 74 61 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 nstant..*/.SQLIT
11f0: 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 E_EXTERN const c
1200: 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 har sqlite3_vers
1210: 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 ion[];.const cha
1220: 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 r *sqlite3_libve
1230: 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 rsion(void);.int
1240: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 sqlite3_libvers
1250: 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 ion_number(void)
1260: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1270: 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 F: Test To See I
1280: 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 f The Library Is
1290: 20 54 68 72 65 61 64 73 61 66 65 20 7b 48 31 30 Threadsafe {H10
12a0: 31 30 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 100} <S60100>.**
12b0: 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 .** SQLite can b
12c0: 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 e compiled with
12d0: 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 or without mutex
12e0: 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 es. When.** the
12f0: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
1300: 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 AFE] C preproces
1310: 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 74 72 75 sor macro is tru
1320: 65 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 e, mutexes.** ar
1330: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 e enabled and SQ
1340: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61 Lite is threadsa
1350: 66 65 2e 20 20 57 68 65 6e 20 74 68 61 74 20 6d fe. When that m
1360: 61 63 72 6f 20 69 73 20 66 61 6c 73 65 2c 0a 2a acro is false,.*
1370: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72 * the mutexes ar
1380: 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68 e omitted. With
1390: 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c out the mutexes,
13a0: 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a it is not safe.
13b0: 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 ** to use SQLite
13c0: 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 concurrently fr
13d0: 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 om more than one
13e0: 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 thread..**.** E
13f0: 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 nabling mutexes
1400: 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61 incurs a measura
1410: 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 ble performance
1420: 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 penalty..** So i
1430: 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74 f speed is of ut
1440: 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c most importance,
1450: 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 it makes sense
1460: 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 to disable.** th
1470: 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20 e mutexes. But
1480: 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 for maximum safe
1490: 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75 ty, mutexes shou
14a0: 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a ld be enabled..*
14b0: 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 * The default be
14c0: 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 havior is for mu
14d0: 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 texes to be enab
14e0: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 led..**.** This
14f0: 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 interface can be
1500: 20 75 73 65 64 20 62 79 20 61 20 70 72 6f 67 72 used by a progr
1510: 61 6d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 am to make sure
1520: 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 that the.** vers
1530: 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 ion of SQLite th
1540: 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 at it is linking
1550: 20 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d against was com
1560: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 piled with.** th
1570: 65 20 64 65 73 69 72 65 64 20 73 65 74 74 69 6e e desired settin
1580: 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 g of the [SQLITE
1590: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 _THREADSAFE] mac
15a0: 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 ro..**.** This i
15b0: 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 nterface only re
15c0: 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d ports on the com
15d0: 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 pile-time mutex
15e0: 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 setting.** of th
15f0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
1600: 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 SAFE] flag. If
1610: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
1620: 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 ed with.** SQLIT
1630: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20 74 E_THREADSAFE=1 t
1640: 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 hen mutexes are
1650: 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 enabled by defau
1660: 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 lt but.** can be
1670: 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 fully or partia
1680: 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 lly disabled usi
1690: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 ng a call to [sq
16a0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a lite3_config()].
16b0: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 ** with the verb
16c0: 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 s [SQLITE_CONFIG
16d0: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 _SINGLETHREAD],
16e0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
16f0: 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 ULTITHREAD],.**
1700: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 or [SQLITE_CONFI
1710: 47 5f 4d 55 54 45 58 5d 2e 20 20 54 68 65 20 72 G_MUTEX]. The r
1720: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 eturn value of t
1730: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f his function sho
1740: 77 73 0a 2a 2a 20 6f 6e 6c 79 20 74 68 65 20 64 ws.** only the d
1750: 65 66 61 75 6c 74 20 63 6f 6d 70 69 6c 65 2d 74 efault compile-t
1760: 69 6d 65 20 73 65 74 74 69 6e 67 2c 20 6e 6f 74 ime setting, not
1770: 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 any run-time ch
1780: 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 74 68 61 74 anges.** to that
1790: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 setting..**.**
17a0: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
17b0: 2a 20 7b 48 31 30 31 30 31 7d 20 54 68 65 20 5b * {H10101} The [
17c0: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 sqlite3_threadsa
17d0: 66 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 fe()] function s
17e0: 68 61 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 7a hall return nonz
17f0: 65 72 6f 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 ero if.**
1800: 20 20 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f SQLite was co
1810: 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 mpiled with the
1820: 69 74 73 20 6d 75 74 65 78 65 73 20 65 6e 61 62 its mutexes enab
1830: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 0a 2a led by default.*
1840: 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 7a 65 * or ze
1850: 72 6f 20 69 66 20 53 51 4c 69 74 65 20 77 61 73 ro if SQLite was
1860: 20 63 6f 6d 70 69 6c 65 64 20 73 75 63 68 20 74 compiled such t
1870: 68 61 74 20 6d 75 74 65 78 65 73 20 61 72 65 0a hat mutexes are.
1880: 2a 2a 20 20 20 20 20 20 20 20 20 20 70 65 72 6d ** perm
1890: 61 6e 65 6e 74 6c 79 20 64 69 73 61 62 6c 65 64 anently disabled
18a0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 31 30 32 7d ..**.** {H10102}
18b0: 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 The value retur
18c0: 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 ned by the [sqli
18d0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 te3_threadsafe()
18e0: 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 ] function.**
18f0: 20 20 20 20 20 20 20 73 68 61 6c 6c 20 6e 6f 74 shall not
1900: 20 63 68 61 6e 67 65 20 77 68 65 6e 20 6d 75 74 change when mut
1910: 65 78 20 73 65 74 74 69 6e 67 20 61 72 65 20 6d ex setting are m
1920: 6f 64 69 66 69 65 64 20 61 74 0a 2a 2a 20 20 20 odified at.**
1930: 20 20 20 20 20 20 20 72 75 6e 74 69 6d 65 20 75 runtime u
1940: 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 sing the [sqlite
1950: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 3_config()] inte
1960: 72 66 61 63 65 20 61 6e 64 20 0a 2a 2a 20 20 20 rface and .**
1970: 20 20 20 20 20 20 20 65 73 70 65 63 69 61 6c 6c especiall
1980: 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f y the [SQLITE_CO
1990: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 NFIG_SINGLETHREA
19a0: 44 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 D],.**
19b0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
19c0: 55 4c 54 49 54 48 52 45 41 44 5d 2c 20 5b 53 51 ULTITHREAD], [SQ
19d0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 LITE_CONFIG_SERI
19e0: 41 4c 49 5a 45 44 5d 2c 0a 2a 2a 20 20 20 20 20 ALIZED],.**
19f0: 20 20 20 20 20 61 6e 64 20 5b 53 51 4c 49 54 45 and [SQLITE
1a00: 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 76 _CONFIG_MUTEX] v
1a10: 65 72 62 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c erbs..*/.int sql
1a20: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 ite3_threadsafe(
1a30: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 void);../*.** CA
1a40: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 PI3REF: Database
1a50: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 Connection Hand
1a60: 6c 65 20 7b 48 31 32 30 30 30 7d 20 3c 53 34 30 le {H12000} <S40
1a70: 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 200>.** KEYWORDS
1a80: 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e : {database conn
1a90: 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 ection} {databas
1aa0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a e connections}.*
1ab0: 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 *.** Each open S
1ac0: 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 QLite database i
1ad0: 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 s represented by
1ae0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
1af0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 instance of.**
1b00: 74 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 the opaque struc
1b10: 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 ture named "sqli
1b20: 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 te3". It is use
1b30: 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 ful to think of
1b40: 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f an sqlite3.** po
1b50: 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 inter as an obje
1b60: 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 ct. The [sqlite
1b70: 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 3_open()], [sqli
1b80: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 te3_open16()], a
1b90: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f nd.** [sqlite3_o
1ba0: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 pen_v2()] interf
1bb0: 61 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e aces are its con
1bc0: 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b structors, and [
1bd0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d sqlite3_close()]
1be0: 0a 2a 2a 20 69 73 20 69 74 73 20 64 65 73 74 72 .** is its destr
1bf0: 75 63 74 6f 72 2e 20 20 54 68 65 72 65 20 61 72 uctor. There ar
1c00: 65 20 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e 74 e many other int
1c10: 65 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73 erfaces (such as
1c20: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
1c30: 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c pare_v2()], [sql
1c40: 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
1c50: 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 tion()], and.**
1c60: 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 [sqlite3_busy_ti
1c70: 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 meout()] to name
1c80: 20 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 but three) that
1c90: 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 are methods on
1ca0: 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 an.** sqlite3 ob
1cb0: 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 ject..*/.typedef
1cc0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 struct sqlite3
1cd0: 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 sqlite3;../*.**
1ce0: 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 CAPI3REF: 64-Bit
1cf0: 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 20 7b Integer Types {
1d00: 48 31 30 32 30 30 7d 20 3c 53 31 30 31 31 30 3e H10200} <S10110>
1d10: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 .** KEYWORDS: sq
1d20: 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 lite_int64 sqlit
1d30: 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 e_uint64.**.** B
1d40: 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20 ecause there is
1d50: 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 no cross-platfor
1d60: 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79 m way to specify
1d70: 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 64-bit integer
1d80: 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 types.** SQLite
1d90: 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66 includes typedef
1da0: 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 s for 64-bit sig
1db0: 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 ned and unsigned
1dc0: 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a integers..**.**
1dd0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 The sqlite3_int
1de0: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 64 and sqlite3_u
1df0: 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72 int64 are the pr
1e00: 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65 66 eferred type def
1e10: 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 initions..** The
1e20: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e sqlite_int64 an
1e30: 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 d sqlite_uint64
1e40: 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f 72 types are suppor
1e50: 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 ted for backward
1e60: 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 s.** compatibili
1e70: 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 ty only..**.** I
1e80: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
1e90: 20 7b 48 31 30 32 30 31 7d 20 54 68 65 20 5b 73 {H10201} The [s
1ea0: 71 6c 69 74 65 5f 69 6e 74 36 34 5d 20 61 6e 64 qlite_int64] and
1eb0: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 5d [sqlite3_int64]
1ec0: 20 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65 63 type shall spec
1ed0: 69 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ify.**
1ee0: 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 a 64-bit signed
1ef0: 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b integer..**.** {
1f00: 48 31 30 32 30 32 7d 20 54 68 65 20 5b 73 71 6c H10202} The [sql
1f10: 69 74 65 5f 75 69 6e 74 36 34 5d 20 61 6e 64 20 ite_uint64] and
1f20: 5b 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 5d [sqlite3_uint64]
1f30: 20 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65 63 type shall spec
1f40: 69 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ify.**
1f50: 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 a 64-bit unsigne
1f60: 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2f 0a 23 69 d integer..*/.#i
1f70: 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 fdef SQLITE_INT6
1f80: 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 4_TYPE. typedef
1f90: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 SQLITE_INT64_TY
1fa0: 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b PE sqlite_int64;
1fb0: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 . typedef unsig
1fc0: 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 ned SQLITE_INT64
1fd0: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e _TYPE sqlite_uin
1fe0: 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e t64;.#elif defin
1ff0: 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 ed(_MSC_VER) ||
2000: 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e defined(__BORLAN
2010: 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 DC__). typedef
2020: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 __int64 sqlite_i
2030: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 nt64;. typedef
2040: 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 unsigned __int64
2050: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a sqlite_uint64;.
2060: 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 #else. typedef
2070: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 long long int sq
2080: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 lite_int64;. ty
2090: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c pedef unsigned l
20a0: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c ong long int sql
20b0: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 ite_uint64;.#end
20c0: 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 if.typedef sqlit
20d0: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f e_int64 sqlite3_
20e0: 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 int64;.typedef s
20f0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c qlite_uint64 sql
2100: 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a ite3_uint64;../*
2110: 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 .** If compiling
2120: 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 for a processor
2130: 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 that lacks floa
2140: 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f ting point suppo
2150: 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 rt,.** substitut
2160: 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c e integer for fl
2170: 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f oating-point..*/
2180: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f .#ifdef SQLITE_O
2190: 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 MIT_FLOATING_POI
21a0: 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 NT.# define doub
21b0: 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 le sqlite3_int64
21c0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 .#endif../*.** C
21d0: 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 API3REF: Closing
21e0: 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e A Database Conn
21f0: 65 63 74 69 6f 6e 20 7b 48 31 32 30 31 30 7d 20 ection {H12010}
2200: 3c 53 33 30 31 30 30 3e 3c 53 34 30 32 30 30 3e <S30100><S40200>
2210: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
2220: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 ine is the destr
2230: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 uctor for the [s
2240: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a qlite3] object..
2250: 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f **.** Applicatio
2260: 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 ns should [sqlit
2270: 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 e3_finalize | fi
2280: 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 nalize] all [pre
2290: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
22a0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 ].** and [sqlite
22b0: 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 3_blob_close | c
22c0: 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 lose] all [BLOB
22d0: 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 handles] associa
22e0: 74 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 ted with.** the
22f0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 [sqlite3] object
2300: 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 prior to attemp
2310: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 ting to close th
2320: 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 65 e object..** The
2330: 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 [sqlite3_next_s
2340: 74 6d 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 tmt()] interface
2350: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
2360: 6c 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a 20 5b 70 locate all.** [p
2370: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2380: 74 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 ts] associated w
2390: 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 ith a [database
23a0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 66 20 64 connection] if d
23b0: 65 73 69 72 65 64 2e 0a 2a 2a 20 54 79 70 69 63 esired..** Typic
23c0: 61 6c 20 63 6f 64 65 20 6d 69 67 68 74 20 6c 6f al code might lo
23d0: 6f 6b 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a ok like this:.**
23e0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
23f0: 3c 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 74 65 33 <pre>.** sqlite3
2400: 5f 73 74 6d 74 20 2a 70 53 74 6d 74 3b 0a 2a 2a _stmt *pStmt;.**
2410: 20 77 68 69 6c 65 28 20 28 70 53 74 6d 74 20 3d while( (pStmt =
2420: 20 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 sqlite3_next_st
2430: 6d 74 28 64 62 2c 20 30 29 29 21 3d 30 20 29 7b mt(db, 0))!=0 ){
2440: 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 73 71 6c .** sql
2450: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 70 53 ite3_finalize(pS
2460: 74 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c 2f tmt);.** }.** </
2470: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
2480: 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 >.**.** If [sqli
2490: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20 te3_close()] is
24a0: 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20 invoked while a
24b0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f transaction is o
24c0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e pen,.** the tran
24d0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d saction is autom
24e0: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 atically rolled
24f0: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 back..**.** INVA
2500: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
2510: 31 32 30 31 31 7d 20 41 20 73 75 63 63 65 73 73 12011} A success
2520: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ful call to [sql
2530: 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 73 ite3_close(C)] s
2540: 68 61 6c 6c 20 64 65 73 74 72 6f 79 20 74 68 65 hall destroy the
2550: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 .** [da
2560: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2570: 6e 5d 20 6f 62 6a 65 63 74 20 43 2e 0a 2a 2a 0a n] object C..**.
2580: 2a 2a 20 7b 48 31 32 30 31 32 7d 20 41 20 73 75 ** {H12012} A su
2590: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f ccessful call to
25a0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 [sqlite3_close(
25b0: 43 29 5d 20 73 68 61 6c 6c 20 72 65 74 75 72 6e C)] shall return
25c0: 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a SQLITE_OK..**.*
25d0: 2a 20 7b 48 31 32 30 31 33 7d 20 41 20 73 75 63 * {H12013} A suc
25e0: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 cessful call to
25f0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 [sqlite3_close(C
2600: 29 5d 20 73 68 61 6c 6c 20 72 65 6c 65 61 73 65 )] shall release
2610: 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 all.**
2620: 20 6d 65 6d 6f 72 79 20 61 6e 64 20 73 79 73 74 memory and syst
2630: 65 6d 20 72 65 73 6f 75 72 63 65 73 20 61 73 73 em resources ass
2640: 6f 63 69 61 74 65 64 20 77 69 74 68 20 5b 64 61 ociated with [da
2650: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2660: 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 n].** C
2670: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 34 7d ..**.** {H12014}
2680: 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 A call to [sqli
2690: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6f 6e te3_close(C)] on
26a0: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e a [database con
26b0: 6e 65 63 74 69 6f 6e 5d 20 43 20 74 68 61 74 0a nection] C that.
26c0: 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61 73 20 ** has
26d0: 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 70 65 6e one or more open
26e0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
26f0: 6d 65 6e 74 73 5d 20 73 68 61 6c 6c 20 66 61 69 ments] shall fai
2700: 6c 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 l with.**
2710: 20 20 20 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 an [SQLITE_BU
2720: 53 59 5d 20 65 72 72 6f 72 20 63 6f 64 65 2e 0a SY] error code..
2730: 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 35 7d 20 41 **.** {H12015} A
2740: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
2750: 33 5f 63 6c 6f 73 65 28 43 29 5d 20 77 68 65 72 3_close(C)] wher
2760: 65 20 43 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f e C is a NULL po
2770: 69 6e 74 65 72 20 73 68 61 6c 6c 0a 2a 2a 20 20 inter shall.**
2780: 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 53 return S
2790: 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 QLITE_OK..**.**
27a0: 7b 48 31 32 30 31 39 7d 20 57 68 65 6e 20 5b 73 {H12019} When [s
27b0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d qlite3_close(C)]
27c0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 is invoked on a
27d0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
27e0: 63 74 69 6f 6e 5d 20 43 0a 2a 2a 20 20 20 20 20 ction] C.**
27f0: 20 20 20 20 20 74 68 61 74 20 68 61 73 20 61 20 that has a
2800: 70 65 6e 64 69 6e 67 20 74 72 61 6e 73 61 63 74 pending transact
2810: 69 6f 6e 2c 20 74 68 65 20 74 72 61 6e 73 61 63 ion, the transac
2820: 74 69 6f 6e 20 73 68 61 6c 6c 20 62 65 0a 2a 2a tion shall be.**
2830: 20 20 20 20 20 20 20 20 20 20 72 6f 6c 6c 65 64 rolled
2840: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 back..**.** ASS
2850: 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 UMPTIONS:.**.**
2860: 7b 41 31 32 30 31 36 7d 20 54 68 65 20 43 20 70 {A12016} The C p
2870: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c arameter to [sql
2880: 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d ite3_close(C)] m
2890: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 ust be either a
28a0: 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 NULL.**
28b0: 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b pointer or an [
28c0: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 sqlite3] object
28d0: 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 pointer obtained
28e0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f .** fro
28f0: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 m [sqlite3_open(
2900: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
2910: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 n16()], or.**
2920: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
2930: 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 open_v2()], and
2940: 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 not previously c
2950: 6c 6f 73 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 losed..*/.int sq
2960: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 lite3_close(sqli
2970: 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 te3 *);../*.** T
2980: 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61 he type for a ca
2990: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e llback function.
29a0: 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61 .** This is lega
29b0: 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 cy and deprecate
29c0: 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64 d. It is includ
29d0: 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 ed for historica
29e0: 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 l.** compatibili
29f0: 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f ty and is not do
2a00: 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 cumented..*/.typ
2a10: 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 edef int (*sqlit
2a20: 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 e3_callback)(voi
2a30: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 d*,int,char**, c
2a40: 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 har**);../*.** C
2a50: 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 API3REF: One-Ste
2a60: 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f p Query Executio
2a70: 6e 20 49 6e 74 65 72 66 61 63 65 20 7b 48 31 32 n Interface {H12
2a80: 31 30 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 100} <S10000>.**
2a90: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
2aa0: 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 exec() interface
2ab0: 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 74 is a convenient
2ac0: 20 77 61 79 20 6f 66 20 72 75 6e 6e 69 6e 67 20 way of running
2ad0: 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 53 one or more.** S
2ae0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 77 69 QL statements wi
2af0: 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 thout having to
2b00: 77 72 69 74 65 20 61 20 6c 6f 74 20 6f 66 20 43 write a lot of C
2b10: 20 63 6f 64 65 2e 20 20 54 68 65 20 55 54 46 2d code. The UTF-
2b20: 38 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 53 51 4c 8 encoded.** SQL
2b30: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 statements are
2b40: 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 passed in as the
2b50: 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
2b60: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 r to sqlite3_exe
2b70: 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 74 61 74 c()..** The stat
2b80: 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 ements are evalu
2b90: 61 74 65 64 20 6f 6e 65 20 62 79 20 6f 6e 65 20 ated one by one
2ba0: 75 6e 74 69 6c 20 65 69 74 68 65 72 20 61 6e 20 until either an
2bb0: 65 72 72 6f 72 20 6f 72 0a 2a 2a 20 61 6e 20 69 error or.** an i
2bc0: 6e 74 65 72 72 75 70 74 20 69 73 20 65 6e 63 6f nterrupt is enco
2bd0: 75 6e 74 65 72 65 64 2c 20 6f 72 20 75 6e 74 69 untered, or unti
2be0: 6c 20 74 68 65 79 20 61 72 65 20 61 6c 6c 20 64 l they are all d
2bf0: 6f 6e 65 2e 20 20 54 68 65 20 33 72 64 20 70 61 one. The 3rd pa
2c00: 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 61 6e rameter.** is an
2c10: 20 6f 70 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 optional callba
2c20: 63 6b 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b ck that is invok
2c30: 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 ed once for each
2c40: 20 72 6f 77 20 6f 66 20 61 6e 79 20 71 75 65 72 row of any quer
2c50: 79 0a 2a 2a 20 72 65 73 75 6c 74 73 20 70 72 6f y.** results pro
2c60: 64 75 63 65 64 20 62 79 20 74 68 65 20 53 51 4c duced by the SQL
2c70: 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 54 68 statements. Th
2c80: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 5th parameter
2c90: 74 65 6c 6c 73 20 77 68 65 72 65 0a 2a 2a 20 74 tells where.** t
2ca0: 6f 20 77 72 69 74 65 20 61 6e 79 20 65 72 72 6f o write any erro
2cb0: 72 20 6d 65 73 73 61 67 65 73 2e 0a 2a 2a 0a 2a r messages..**.*
2cc0: 2a 20 54 68 65 20 65 72 72 6f 72 20 6d 65 73 73 * The error mess
2cd0: 61 67 65 20 70 61 73 73 65 64 20 62 61 63 6b 20 age passed back
2ce0: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 through the 5th
2cf0: 70 61 72 61 6d 65 74 65 72 20 69 73 20 68 65 6c parameter is hel
2d00: 64 0a 2a 2a 20 69 6e 20 6d 65 6d 6f 72 79 20 6f d.** in memory o
2d10: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
2d20: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e lite3_malloc()].
2d30: 20 20 54 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d To avoid a mem
2d40: 6f 72 79 20 6c 65 61 6b 2c 0a 2a 2a 20 74 68 65 ory leak,.** the
2d50: 20 63 61 6c 6c 69 6e 67 20 61 70 70 6c 69 63 61 calling applica
2d60: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 63 61 6c 6c tion should call
2d70: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
2d80: 5d 20 6f 6e 20 61 6e 79 20 65 72 72 6f 72 0a 2a ] on any error.*
2d90: 2a 20 6d 65 73 73 61 67 65 20 72 65 74 75 72 6e * message return
2da0: 65 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 ed through the 5
2db0: 74 68 20 70 61 72 61 6d 65 74 65 72 20 77 68 65 th parameter whe
2dc0: 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 n it has finishe
2dd0: 64 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 65 d using.** the e
2de0: 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a rror message..**
2df0: 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 .** If the SQL s
2e00: 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 tatement in the
2e10: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 2nd parameter is
2e20: 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 NULL or an empt
2e30: 79 20 73 74 72 69 6e 67 0a 2a 2a 20 6f 72 20 61 y string.** or a
2e40: 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 string containi
2e50: 6e 67 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 ng only whitespa
2e60: 63 65 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 2c ce and comments,
2e70: 20 74 68 65 6e 20 6e 6f 20 53 51 4c 0a 2a 2a 20 then no SQL.**
2e80: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 statements are e
2e90: 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65 valuated and the
2ea0: 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 database is not
2eb0: 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 changed..**.**
2ec0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 The sqlite3_exec
2ed0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
2ee0: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 74 implemented in t
2ef0: 65 72 6d 73 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 erms of.** [sqli
2f00: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
2f10: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ], [sqlite3_step
2f20: 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 ()], and [sqlite
2f30: 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 3_finalize()]..*
2f40: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 * The sqlite3_ex
2f50: 65 63 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 ec() routine doe
2f60: 73 20 6e 6f 74 68 69 6e 67 20 74 6f 20 74 68 65 s nothing to the
2f70: 20 64 61 74 61 62 61 73 65 20 74 68 61 74 20 63 database that c
2f80: 61 6e 6e 6f 74 20 62 65 20 64 6f 6e 65 0a 2a 2a annot be done.**
2f90: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 by [sqlite3_pre
2fa0: 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c pare_v2()], [sql
2fb0: 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e ite3_step()], an
2fc0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c d [sqlite3_final
2fd0: 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e ize()]..**.** IN
2fe0: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
2ff0: 7b 48 31 32 31 30 31 7d 20 41 20 73 75 63 63 65 {H12101} A succe
3000: 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e ssful invocation
3010: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 of [sqlite3_exe
3020: 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 0a 2a 2a c(D,S,C,A,E)].**
3030: 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 shall
3040: 73 65 71 75 65 6e 74 69 61 6c 6c 79 20 65 76 61 sequentially eva
3050: 6c 75 61 74 65 20 61 6c 6c 20 6f 66 20 74 68 65 luate all of the
3060: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a UTF-8 encoded,.
3070: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 65 6d 69 ** semi
3080: 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 colon-separated
3090: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 SQL statements i
30a0: 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 n the zero-termi
30b0: 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 nated.**
30c0: 20 20 73 74 72 69 6e 67 20 53 20 77 69 74 68 69 string S withi
30d0: 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 n the context of
30e0: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
30f0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a onnection] D..**
3100: 0a 2a 2a 20 7b 48 31 32 31 30 32 7d 20 49 66 20 .** {H12102} If
3110: 74 68 65 20 53 20 70 61 72 61 6d 65 74 65 72 20 the S parameter
3120: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 to [sqlite3_exec
3130: 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 69 73 20 (D,S,C,A,E)] is
3140: 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 NULL then.**
3150: 20 20 20 20 20 20 74 68 65 20 61 63 74 69 6f 6e the action
3160: 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61 s of the interfa
3170: 63 65 20 73 68 61 6c 6c 20 62 65 20 74 68 65 20 ce shall be the
3180: 73 61 6d 65 20 61 73 20 69 66 20 74 68 65 0a 2a same as if the.*
3190: 2a 20 20 20 20 20 20 20 20 20 20 53 20 70 61 72 * S par
31a0: 61 6d 65 74 65 72 20 77 65 72 65 20 61 6e 20 65 ameter were an e
31b0: 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a mpty string..**.
31c0: 2a 2a 20 7b 48 31 32 31 30 34 7d 20 54 68 65 20 ** {H12104} The
31d0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
31e0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
31f0: 20 73 68 61 6c 6c 20 62 65 20 5b 53 51 4c 49 54 shall be [SQLIT
3200: 45 5f 4f 4b 5d 20 69 66 20 61 6c 6c 0a 2a 2a 20 E_OK] if all.**
3210: 20 20 20 20 20 20 20 20 20 53 51 4c 20 73 74 61 SQL sta
3220: 74 65 6d 65 6e 74 73 20 72 75 6e 20 73 75 63 63 tements run succ
3230: 65 73 73 66 75 6c 6c 79 20 61 6e 64 20 74 6f 20 essfully and to
3240: 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a completion..**.*
3250: 2a 20 7b 48 31 32 31 30 35 7d 20 54 68 65 20 72 * {H12105} The r
3260: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 5b eturn value of [
3270: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 sqlite3_exec()]
3280: 73 68 61 6c 6c 20 62 65 20 61 6e 20 61 70 70 72 shall be an appr
3290: 6f 70 72 69 61 74 65 0a 2a 2a 20 20 20 20 20 20 opriate.**
32a0: 20 20 20 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 non-zero [er
32b0: 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 ror code] if any
32c0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 SQL statement f
32d0: 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 ails..**.** {H12
32e0: 31 30 37 7d 20 49 66 20 6f 6e 65 20 6f 72 20 6d 107} If one or m
32f0: 6f 72 65 20 6f 66 20 74 68 65 20 53 51 4c 20 73 ore of the SQL s
3300: 74 61 74 65 6d 65 6e 74 73 20 68 61 6e 64 65 64 tatements handed
3310: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 to [sqlite3_exe
3320: 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 c()].**
3330: 20 72 65 74 75 72 6e 20 72 65 73 75 6c 74 73 20 return results
3340: 61 6e 64 20 74 68 65 20 33 72 64 20 70 61 72 61 and the 3rd para
3350: 6d 65 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c meter is not NUL
3360: 4c 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 L, then.**
3370: 20 20 20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b the callback
3380: 20 66 75 6e 63 74 69 6f 6e 20 73 70 65 63 69 66 function specif
3390: 69 65 64 20 62 79 20 74 68 65 20 33 72 64 20 70 ied by the 3rd p
33a0: 61 72 61 6d 65 74 65 72 20 73 68 61 6c 6c 20 62 arameter shall b
33b0: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e e.** in
33c0: 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 voked once for e
33d0: 61 63 68 20 72 6f 77 20 6f 66 20 72 65 73 75 6c ach row of resul
33e0: 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 31 30 t..**.** {H12110
33f0: 7d 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 } If the callbac
3400: 6b 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d k returns a non-
3410: 7a 65 72 6f 20 76 61 6c 75 65 20 74 68 65 6e 20 zero value then
3420: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
3430: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 .** sha
3440: 6c 6c 20 61 62 6f 72 74 20 74 68 65 20 53 51 4c ll abort the SQL
3450: 20 73 74 61 74 65 6d 65 6e 74 20 69 74 20 69 73 statement it is
3460: 20 63 75 72 72 65 6e 74 6c 79 20 65 76 61 6c 75 currently evalu
3470: 61 74 69 6e 67 2c 0a 2a 2a 20 20 20 20 20 20 20 ating,.**
3480: 20 20 20 73 6b 69 70 20 61 6c 6c 20 73 75 62 73 skip all subs
3490: 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 equent SQL state
34a0: 6d 65 6e 74 73 2c 20 61 6e 64 20 72 65 74 75 72 ments, and retur
34b0: 6e 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d n [SQLITE_ABORT]
34c0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 31 33 7d ..**.** {H12113}
34d0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 The [sqlite3_ex
34e0: 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 ec()] routine sh
34f0: 61 6c 6c 20 70 61 73 73 20 69 74 73 20 34 74 68 all pass its 4th
3500: 20 70 61 72 61 6d 65 74 65 72 20 74 68 72 6f 75 parameter throu
3510: 67 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 gh.** a
3520: 73 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 s the 1st parame
3530: 74 65 72 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 ter of the callb
3540: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 ack..**.** {H121
3550: 31 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 16} The [sqlite3
3560: 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 _exec()] routine
3570: 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 32 shall set the 2
3580: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 nd parameter of
3590: 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 its.**
35a0: 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 74 callback to be t
35b0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c he number of col
35c0: 75 6d 6e 73 20 69 6e 20 74 68 65 20 63 75 72 72 umns in the curr
35d0: 65 6e 74 20 72 6f 77 20 6f 66 0a 2a 2a 20 20 20 ent row of.**
35e0: 20 20 20 20 20 20 20 72 65 73 75 6c 74 2e 0a 2a result..*
35f0: 2a 0a 2a 2a 20 7b 48 31 32 31 31 39 7d 20 54 68 *.** {H12119} Th
3600: 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 e [sqlite3_exec(
3610: 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c )] routine shall
3620: 20 73 65 74 20 74 68 65 20 33 72 64 20 70 61 72 set the 3rd par
3630: 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a ameter of its.**
3640: 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 callba
3650: 63 6b 20 74 6f 20 62 65 20 61 6e 20 61 72 72 61 ck to be an arra
3660: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f y of pointers to
3670: 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e 67 strings holding
3680: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
3690: 20 76 61 6c 75 65 73 20 66 6f 72 20 65 61 63 68 values for each
36a0: 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 column in the c
36b0: 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20 73 65 urrent result se
36c0: 74 20 72 6f 77 20 61 73 0a 2a 2a 20 20 20 20 20 t row as.**
36d0: 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66 72 obtained fr
36e0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 om [sqlite3_colu
36f0: 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a mn_text()]..**.*
3700: 2a 20 7b 48 31 32 31 32 32 7d 20 54 68 65 20 5b * {H12122} The [
3710: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 sqlite3_exec()]
3720: 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 routine shall se
3730: 74 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 t the 4th parame
3740: 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 ter of its.**
3750: 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 callback
3760: 74 6f 20 62 65 20 61 6e 20 61 72 72 61 79 20 6f to be an array o
3770: 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 f pointers to st
3780: 72 69 6e 67 73 20 68 6f 6c 64 69 6e 67 20 74 68 rings holding th
3790: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61 e.** na
37a0: 6d 65 73 20 6f 66 20 72 65 73 75 6c 74 20 63 6f mes of result co
37b0: 6c 75 6d 6e 73 20 61 73 20 6f 62 74 61 69 6e 65 lumns as obtaine
37c0: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
37d0: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a column_name()]..
37e0: 2a 2a 0a 2a 2a 20 7b 48 31 32 31 32 35 7d 20 49 **.** {H12125} I
37f0: 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 f the 3rd parame
3800: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
3810: 65 78 65 63 28 29 5d 20 69 73 20 4e 55 4c 4c 20 exec()] is NULL
3820: 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 then.**
3830: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 [sqlite3_exec()
3840: 5d 20 73 68 61 6c 6c 20 73 69 6c 65 6e 74 6c 79 ] shall silently
3850: 20 64 69 73 63 61 72 64 20 71 75 65 72 79 20 72 discard query r
3860: 65 73 75 6c 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 esults..**.** {H
3870: 31 32 31 33 31 7d 20 49 66 20 61 6e 20 65 72 72 12131} If an err
3880: 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 or occurs while
3890: 70 61 72 73 69 6e 67 20 6f 72 20 65 76 61 6c 75 parsing or evalu
38a0: 61 74 69 6e 67 20 61 6e 79 20 6f 66 20 74 68 65 ating any of the
38b0: 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 SQL.**
38c0: 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 statements in t
38d0: 68 65 20 53 20 70 61 72 61 6d 65 74 65 72 20 6f he S parameter o
38e0: 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 f [sqlite3_exec(
38f0: 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 61 6e 64 20 D,S,C,A,E)] and
3900: 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 if.** t
3910: 68 65 20 45 20 70 61 72 61 6d 65 74 65 72 20 69 he E parameter i
3920: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e s not NULL, then
3930: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 [sqlite3_exec()
3940: 5d 20 73 68 61 6c 6c 20 73 74 6f 72 65 0a 2a 2a ] shall store.**
3950: 20 20 20 20 20 20 20 20 20 20 69 6e 20 2a 45 20 in *E
3960: 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 an appropriate e
3970: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 77 72 69 rror message wri
3980: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 tten into memory
3990: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 20 20 20 obtained.**
39a0: 20 20 20 20 20 20 66 72 6f 6d 20 5b 73 71 6c 69 from [sqli
39b0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a te3_malloc()]..*
39c0: 2a 0a 2a 2a 20 7b 48 31 32 31 33 34 7d 20 54 68 *.** {H12134} Th
39d0: 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 e [sqlite3_exec(
39e0: 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 72 6f 75 74 D,S,C,A,E)] rout
39f0: 69 6e 65 20 73 68 61 6c 6c 20 73 65 74 20 74 68 ine shall set th
3a00: 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 20 20 e value of.**
3a10: 20 20 20 20 20 20 20 2a 45 20 74 6f 20 4e 55 4c *E to NUL
3a20: 4c 20 69 66 20 45 20 69 73 20 6e 6f 74 20 4e 55 L if E is not NU
3a30: 4c 4c 20 61 6e 64 20 74 68 65 72 65 20 61 72 65 LL and there are
3a40: 20 6e 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a no errors..**.*
3a50: 2a 20 7b 48 31 32 31 33 37 7d 20 54 68 65 20 5b * {H12137} The [
3a60: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53 sqlite3_exec(D,S
3a70: 2c 43 2c 41 2c 45 29 5d 20 66 75 6e 63 74 69 6f ,C,A,E)] functio
3a80: 6e 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 n shall set the
3a90: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 [error code].**
3aa0: 20 20 20 20 20 20 20 20 20 61 6e 64 20 6d 65 73 and mes
3ab0: 73 61 67 65 20 61 63 63 65 73 73 69 62 6c 65 20 sage accessible
3ac0: 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 via [sqlite3_err
3ad0: 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 code()],.**
3ae0: 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 [sqlite3_er
3af0: 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71 rmsg()], and [sq
3b00: 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 lite3_errmsg16()
3b10: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 38 ]..**.** {H12138
3b20: 7d 20 49 66 20 74 68 65 20 53 20 70 61 72 61 6d } If the S param
3b30: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 eter to [sqlite3
3b40: 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 _exec(D,S,C,A,E)
3b50: 5d 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 0a ] is NULL or an.
3b60: 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6d 70 74 ** empt
3b70: 79 20 73 74 72 69 6e 67 20 6f 72 20 63 6f 6e 74 y string or cont
3b80: 61 69 6e 73 20 6e 6f 74 68 69 6e 67 20 6f 74 68 ains nothing oth
3b90: 65 72 20 74 68 61 6e 20 77 68 69 74 65 73 70 61 er than whitespa
3ba0: 63 65 2c 20 63 6f 6d 6d 65 6e 74 73 2c 0a 2a 2a ce, comments,.**
3bb0: 20 20 20 20 20 20 20 20 20 20 61 6e 64 2f 6f 72 and/or
3bc0: 20 73 65 6d 69 63 6f 6c 6f 6e 73 2c 20 74 68 65 semicolons, the
3bd0: 6e 20 72 65 73 75 6c 74 73 20 6f 66 20 5b 73 71 n results of [sq
3be0: 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d lite3_errcode()]
3bf0: 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 ,.** [s
3c00: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d qlite3_errmsg()]
3c10: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 , and [sqlite3_e
3c20: 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20 rrmsg16()].**
3c30: 20 20 20 20 20 20 20 73 68 61 6c 6c 20 72 65 73 shall res
3c40: 65 74 20 74 6f 20 69 6e 64 69 63 61 74 65 20 6e et to indicate n
3c50: 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 o errors..**.**
3c60: 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a ASSUMPTIONS:.**.
3c70: 2a 2a 20 7b 41 31 32 31 34 31 7d 20 54 68 65 20 ** {A12141} The
3c80: 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
3c90: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 to [sqlite3_exec
3ca0: 28 29 5d 20 6d 75 73 74 20 62 65 20 61 6e 20 76 ()] must be an v
3cb0: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a alid and open.**
3cc0: 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 [datab
3cd0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e ase connection].
3ce0: 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31 34 32 7d 20 .**.** {A12142}
3cf0: 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e The database con
3d00: 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 nection must not
3d10: 20 62 65 20 63 6c 6f 73 65 64 20 77 68 69 6c 65 be closed while
3d20: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
3d30: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 lite3_exec()] is
3d40: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 running..**.**
3d50: 7b 41 31 32 31 34 33 7d 20 54 68 65 20 63 61 6c {A12143} The cal
3d60: 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68 ling function sh
3d70: 6f 75 6c 64 20 75 73 65 20 5b 73 71 6c 69 74 65 ould use [sqlite
3d80: 33 5f 66 72 65 65 28 29 5d 20 74 6f 20 66 72 65 3_free()] to fre
3d90: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 e.** th
3da0: 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 2a 65 e memory that *e
3db0: 72 72 6d 73 67 20 69 73 20 6c 65 66 74 20 70 6f rrmsg is left po
3dc0: 69 6e 74 69 6e 67 20 61 74 20 6f 6e 63 65 20 74 inting at once t
3dd0: 68 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20 he error.**
3de0: 20 20 20 20 20 6d 65 73 73 61 67 65 20 69 73 20 message is
3df0: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 no longer needed
3e00: 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31 34 35 7d ..**.** {A12145}
3e10: 20 54 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 The SQL stateme
3e20: 6e 74 20 74 65 78 74 20 69 6e 20 74 68 65 20 32 nt text in the 2
3e30: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 nd parameter to
3e40: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
3e50: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 75 73 .** mus
3e60: 74 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 t remain unchang
3e70: 65 64 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 ed while [sqlite
3e80: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 3_exec()] is run
3e90: 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c ning..*/.int sql
3ea0: 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c ite3_exec(. sql
3eb0: 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 ite3*,
3ec0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3ed0: 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 /* An op
3ee0: 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 en database */.
3ef0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c const char *sql
3f00: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
3f10: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 /* S
3f20: 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 QL to be evaluat
3f30: 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 ed */. int (*ca
3f40: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e llback)(void*,in
3f50: 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 t,char**,char**)
3f60: 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 , /* Callback f
3f70: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 unction */. voi
3f80: 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 d *,
3f90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3fa0: 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61 /* 1st a
3fb0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 rgument to callb
3fc0: 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a ack */. char **
3fd0: 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20 errmsg
3fe0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3ff0: 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 /* Error msg
4000: 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f written here */
4010: 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
4020: 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 REF: Result Code
4030: 73 20 7b 48 31 30 32 31 30 7d 20 3c 53 31 30 37 s {H10210} <S107
4040: 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 00>.** KEYWORDS:
4050: 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f SQLITE_OK {erro
4060: 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63 r code} {error c
4070: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 odes}.** KEYWORD
4080: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d S: {result code}
4090: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a {result codes}.
40a0: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 **.** Many SQLit
40b0: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 e functions retu
40c0: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65 rn an integer re
40d0: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 sult code from t
40e0: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 he set shown.**
40f0: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f here in order to
4100: 20 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65 indicates succe
4110: 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a ss or failure..*
4120: 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 *.** New error c
4130: 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 odes may be adde
4140: 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 d in future vers
4150: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ions of SQLite..
4160: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
4170: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 [SQLITE_IOERR_RE
4180: 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 AD | extended re
4190: 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23 sult codes].*/.#
41a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b define SQLITE_OK
41b0: 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 0 /
41c0: 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73 * Successful res
41d0: 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e ult */./* beginn
41e0: 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 ing-of-error-cod
41f0: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 es */.#define SQ
4200: 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20 LITE_ERROR
4210: 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 1 /* SQL err
4220: 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 or or missing da
4230: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e tabase */.#defin
4240: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 e SQLITE_INTERNA
4250: 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 L 2 /* Int
4260: 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f ernal logic erro
4270: 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 r in SQLite */.#
4280: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 define SQLITE_PE
4290: 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f RM 3 /
42a0: 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73 * Access permiss
42b0: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 ion denied */.#d
42c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f efine SQLITE_ABO
42d0: 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a RT 4 /*
42e0: 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e Callback routin
42f0: 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61 e requested an a
4300: 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 bort */.#define
4310: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20 SQLITE_BUSY
4320: 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64 5 /* The d
4330: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 atabase file is
4340: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e locked */.#defin
4350: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 e SQLITE_LOCKED
4360: 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74 6 /* A t
4370: 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61 able in the data
4380: 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a base is locked *
4390: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
43a0: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20 _NOMEM 7
43b0: 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 /* A malloc()
43c0: 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e failed */.#defin
43d0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c e SQLITE_READONL
43e0: 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74 Y 8 /* Att
43f0: 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20 empt to write a
4400: 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 readonly databas
4410: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
4420: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20 ITE_INTERRUPT
4430: 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 9 /* Operatio
4440: 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20 n terminated by
4450: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
4460: 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 t()*/.#define SQ
4470: 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20 LITE_IOERR
4480: 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 10 /* Some ki
4490: 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 nd of disk I/O e
44a0: 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f rror occurred */
44b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
44c0: 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20 CORRUPT 11
44d0: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 /* The database
44e0: 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d disk image is m
44f0: 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 alformed */.#def
4500: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f ine SQLITE_NOTFO
4510: 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 4e UND 12 /* N
4520: 4f 54 20 55 53 45 44 2e 20 54 61 62 6c 65 20 6f OT USED. Table o
4530: 72 20 72 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75 r record not fou
4540: 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 nd */.#define SQ
4550: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 LITE_FULL
4560: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 13 /* Inserti
4570: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 on failed becaus
4580: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 e database is fu
4590: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ll */.#define SQ
45a0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 LITE_CANTOPEN
45b0: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 14 /* Unable
45c0: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 to open the data
45d0: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 base file */.#de
45e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 fine SQLITE_PROT
45f0: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 OCOL 15 /*
4600: 4e 4f 54 20 55 53 45 44 2e 20 44 61 74 61 62 61 NOT USED. Databa
4610: 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c se lock protocol
4620: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e error */.#defin
4630: 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 e SQLITE_EMPTY
4640: 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 16 /* Dat
4650: 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a abase is empty *
4660: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4670: 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 _SCHEMA 17
4680: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 /* The databas
4690: 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 e schema changed
46a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
46b0: 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 TE_TOOBIG 1
46c0: 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 8 /* String or
46d0: 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 BLOB exceeds si
46e0: 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 ze limit */.#def
46f0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 ine SQLITE_CONST
4700: 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 RAINT 19 /* A
4710: 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 bort due to cons
4720: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e traint violation
4730: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4740: 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 TE_MISMATCH 2
4750: 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 0 /* Data type
4760: 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 mismatch */.#de
4770: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 fine SQLITE_MISU
4780: 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 SE 21 /*
4790: 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 Library used inc
47a0: 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 orrectly */.#def
47b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 ine SQLITE_NOLFS
47c0: 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 22 /* U
47d0: 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 ses OS features
47e0: 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e not supported on
47f0: 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 host */.#define
4800: 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 SQLITE_AUTH
4810: 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 23 /* Auth
4820: 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 orization denied
4830: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4840: 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 TE_FORMAT 2
4850: 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 4 /* Auxiliary
4860: 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 database format
4870: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e error */.#defin
4880: 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 e SQLITE_RANGE
4890: 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 25 /* 2nd
48a0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
48b0: 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f lite3_bind out o
48c0: 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 f range */.#defi
48d0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 ne SQLITE_NOTADB
48e0: 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 26 /* Fi
48f0: 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 le opened that i
4900: 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 s not a database
4910: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 file */.#define
4920: 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 SQLITE_ROW
4930: 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 100 /* sqli
4940: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 te3_step() has a
4950: 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 nother row ready
4960: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4970: 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 TE_DONE 1
4980: 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 01 /* sqlite3_s
4990: 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 tep() has finish
49a0: 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a ed executing */.
49b0: 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d /* end-of-error-
49c0: 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 codes */../*.**
49d0: 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 CAPI3REF: Extend
49e0: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 ed Result Codes
49f0: 7b 48 31 30 32 32 30 7d 20 3c 53 31 30 37 30 30 {H10220} <S10700
4a00: 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b >.** KEYWORDS: {
4a10: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 extended error c
4a20: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 ode} {extended e
4a30: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b rror codes}.** K
4a40: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 EYWORDS: {extend
4a50: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 ed result code}
4a60: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 {extended result
4a70: 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e codes}.**.** In
4a80: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e its default con
4a90: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 figuration, SQLi
4aa0: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 te API routines
4ab0: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 return one of 26
4ac0: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c integer.** [SQL
4ad0: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 ITE_OK | result
4ae0: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 codes]. However
4af0: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 , experience has
4b00: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 shown that many
4b10: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 of.** these res
4b20: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f ult codes are to
4b30: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 o coarse-grained
4b40: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 . They do not p
4b50: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 rovide as.** muc
4b60: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 h information ab
4b70: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 out problems as
4b80: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 programmers migh
4b90: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 t like. In an e
4ba0: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 ffort to.** addr
4bb0: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 ess this, newer
4bc0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
4bd0: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e te (version 3.3.
4be0: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 8 and later) inc
4bf0: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 lude.** support
4c00: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 for additional r
4c10: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 esult codes that
4c20: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 provide more de
4c30: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 tailed informati
4c40: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f on.** about erro
4c50: 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 rs. The extended
4c60: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 result codes ar
4c70: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 e enabled or dis
4c80: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 abled.** on a pe
4c90: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 r database conne
4ca0: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e ction basis usin
4cb0: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 g the.** [sqlite
4cc0: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 3_extended_resul
4cd0: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a t_codes()] API..
4ce0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 **.** Some of th
4cf0: 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 e available exte
4d00: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
4d10: 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 s are listed her
4d20: 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 e..** One may ex
4d30: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 pect the number
4d40: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 of extended resu
4d50: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 lt codes will be
4d60: 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 expand.** over
4d70: 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 time. Software
4d80: 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 that uses extend
4d90: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 ed result codes
4da0: 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a should expect.**
4db0: 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 to see new resu
4dc0: 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 lt codes in futu
4dd0: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 re releases of S
4de0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 QLite..**.** The
4df0: 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c SQLITE_OK resul
4e00: 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 t code will neve
4e10: 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 r be extended.
4e20: 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a It will always.*
4e30: 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 * be exactly zer
4e40: 6f 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 o..**.** INVARIA
4e50: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 NTS:.**.** {H102
4e60: 32 33 7d 20 54 68 65 20 73 79 6d 62 6f 6c 69 63 23} The symbolic
4e70: 20 6e 61 6d 65 20 66 6f 72 20 61 6e 20 65 78 74 name for an ext
4e80: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
4e90: 65 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 73 e shall contains
4ea0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 72 .** a r
4eb0: 65 6c 61 74 65 64 20 70 72 69 6d 61 72 79 20 72 elated primary r
4ec0: 65 73 75 6c 74 20 63 6f 64 65 20 61 73 20 61 20 esult code as a
4ed0: 70 72 65 66 69 78 2e 0a 2a 2a 0a 2a 2a 20 7b 48 prefix..**.** {H
4ee0: 31 30 32 32 34 7d 20 50 72 69 6d 61 72 79 20 72 10224} Primary r
4ef0: 65 73 75 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73 esult code names
4f00: 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 20 61 shall contain a
4f10: 20 73 69 6e 67 6c 65 20 22 5f 22 20 63 68 61 72 single "_" char
4f20: 61 63 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 acter..**.** {H1
4f30: 30 32 32 35 7d 20 45 78 74 65 6e 64 65 64 20 72 0225} Extended r
4f40: 65 73 75 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73 esult code names
4f50: 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 20 74 shall contain t
4f60: 77 6f 20 6f 72 20 6d 6f 72 65 20 22 5f 22 20 63 wo or more "_" c
4f70: 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a haracters..**.**
4f80: 20 7b 48 31 30 32 32 36 7d 20 54 68 65 20 6e 75 {H10226} The nu
4f90: 6d 65 72 69 63 20 76 61 6c 75 65 20 6f 66 20 61 meric value of a
4fa0: 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c n extended resul
4fb0: 74 20 63 6f 64 65 20 73 68 61 6c 6c 20 63 6f 6e t code shall con
4fc0: 74 61 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 tain the.**
4fd0: 20 20 20 20 20 6e 75 6d 65 72 69 63 20 76 61 6c numeric val
4fe0: 75 65 20 6f 66 20 69 74 73 20 63 6f 72 72 65 73 ue of its corres
4ff0: 70 6f 6e 64 69 6e 67 20 70 72 69 6d 61 72 79 20 ponding primary
5000: 72 65 73 75 6c 74 20 63 6f 64 65 20 69 6e 0a 2a result code in.*
5010: 2a 20 20 20 20 20 20 20 20 20 20 69 74 73 20 6c * its l
5020: 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 east significant
5030: 20 38 20 62 69 74 73 2e 0a 2a 2f 0a 23 64 65 66 8 bits..*/.#def
5040: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5050: 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 _READ
5060: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5070: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 | (1<<8)).#defi
5080: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
5090: 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 SHORT_READ
50a0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
50b0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (2<<8)).#defin
50c0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 e SQLITE_IOERR_W
50d0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 RITE
50e0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
50f0: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (3<<8)).#define
5100: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 SQLITE_IOERR_FS
5110: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 YNC
5120: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5130: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (4<<8)).#define
5140: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 SQLITE_IOERR_DIR
5150: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 _FSYNC (
5160: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
5170: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 5<<8)).#define S
5180: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e QLITE_IOERR_TRUN
5190: 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53 CATE (S
51a0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 QLITE_IOERR | (6
51b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
51c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 LITE_IOERR_FSTAT
51d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
51e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c LITE_IOERR | (7<
51f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5200: 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b ITE_IOERR_UNLOCK
5210: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
5220: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c ITE_IOERR | (8<<
5230: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5240: 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 TE_IOERR_RDLOCK
5250: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
5260: 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 TE_IOERR | (9<<8
5270: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5280: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 E_IOERR_DELETE
5290: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
52a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 E_IOERR | (10<<8
52b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
52c0: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 E_IOERR_BLOCKED
52d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
52e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 E_IOERR | (11<<8
52f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5300: 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 E_IOERR_NOMEM
5310: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
5320: 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 E_IOERR | (12<<8
5330: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5340: 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 E_IOERR_ACCESS
5350: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
5360: 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 E_IOERR | (13<<8
5370: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5380: 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 E_IOERR_CHECKRES
5390: 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 ERVEDLOCK (SQLIT
53a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 E_IOERR | (14<<8
53b0: 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 ))../*.** CAPI3R
53c0: 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 EF: Flags For Fi
53d0: 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f le Open Operatio
53e0: 6e 73 20 7b 48 31 30 32 33 30 7d 20 3c 48 31 31 ns {H10230} <H11
53f0: 31 32 30 3e 20 3c 48 31 32 37 30 30 3e 0a 2a 2a 120> <H12700>.**
5400: 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 .** These bit va
5410: 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 lues are intende
5420: 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 d for use in the
5430: 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 .** 3rd paramete
5440: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 r to the [sqlite
5450: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 3_open_v2()] int
5460: 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e erface and.** in
5470: 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 the 4th paramet
5480: 65 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 er to the xOpen
5490: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a method of the.**
54a0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f [sqlite3_vfs] o
54b0: 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e bject..*/.#defin
54c0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 e SQLITE_OPEN_RE
54d0: 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 ADONLY 0
54e0: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e x00000001.#defin
54f0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 e SQLITE_OPEN_RE
5500: 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30 ADWRITE 0
5510: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e x00000002.#defin
5520: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 e SQLITE_OPEN_CR
5530: 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30 EATE 0
5540: 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e x00000004.#defin
5550: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 e SQLITE_OPEN_DE
5560: 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 LETEONCLOSE 0
5570: 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e x00000008.#defin
5580: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 e SQLITE_OPEN_EX
5590: 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30 CLUSIVE 0
55a0: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e x00000010.#defin
55b0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 e SQLITE_OPEN_MA
55c0: 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 IN_DB 0
55d0: 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e x00000100.#defin
55e0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 e SQLITE_OPEN_TE
55f0: 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 MP_DB 0
5600: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e x00000200.#defin
5610: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 e SQLITE_OPEN_TR
5620: 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 ANSIENT_DB 0
5630: 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e x00000400.#defin
5640: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 e SQLITE_OPEN_MA
5650: 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 IN_JOURNAL 0
5660: 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e x00000800.#defin
5670: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 e SQLITE_OPEN_TE
5680: 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 MP_JOURNAL 0
5690: 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e x00001000.#defin
56a0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 e SQLITE_OPEN_SU
56b0: 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 BJOURNAL 0
56c0: 78 30 30 30 30 32 30 30 30 0a 23 64 65 66 69 6e x00002000.#defin
56d0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 e SQLITE_OPEN_MA
56e0: 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 STER_JOURNAL 0
56f0: 78 30 30 30 30 34 30 30 30 0a 23 64 65 66 69 6e x00004000.#defin
5700: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f e SQLITE_OPEN_NO
5710: 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20 30 MUTEX 0
5720: 78 30 30 30 30 38 30 30 30 0a 0a 2f 2a 0a 2a 2a x00008000../*.**
5730: 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 CAPI3REF: Devic
5740: 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63 e Characteristic
5750: 73 20 7b 48 31 30 32 34 30 7d 20 3c 48 31 31 31 s {H10240} <H111
5760: 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 20>.**.** The xD
5770: 65 76 69 63 65 43 61 70 61 62 69 6c 69 74 69 65 eviceCapabilitie
5780: 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 s method of the
5790: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
57a0: 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 ods].** object r
57b0: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 eturns an intege
57c0: 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 r which is a vec
57d0: 74 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73 65 tor of the these
57e0: 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 .** bit values e
57f0: 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 xpressing I/O ch
5800: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 aracteristics of
5810: 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 the mass storag
5820: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 e.** device that
5830: 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 holds the file
5840: 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 that the [sqlite
5850: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 3_io_methods].**
5860: 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a refers to..**.*
5870: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 * The SQLITE_IOC
5880: 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 AP_ATOMIC proper
5890: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c ty means that al
58a0: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 l writes of.** a
58b0: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d ny size are atom
58c0: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f ic. The SQLITE_
58d0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 IOCAP_ATOMICnnn
58e0: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 values.** mean t
58f0: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c hat writes of bl
5900: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e ocks that are nn
5910: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 n bytes in size
5920: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e and.** are align
5930: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 ed to an address
5940: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 which is an int
5950: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 eger multiple of
5960: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d .** nnn are atom
5970: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f ic. The SQLITE_
5980: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e IOCAP_SAFE_APPEN
5990: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a D value means.**
59a0: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 that when data
59b0: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 is appended to a
59c0: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 file, the data
59d0: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 is appended.** f
59e0: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 irst then the si
59f0: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 ze of the file i
5a00: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 s extended, neve
5a10: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 r the other.** w
5a20: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 ay around. The
5a30: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 SQLITE_IOCAP_SEQ
5a40: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 UENTIAL property
5a50: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 means that.** i
5a60: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 nformation is wr
5a70: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e itten to disk in
5a80: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 the same order
5a90: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 as calls.** to x
5aa0: 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 Write()..*/.#def
5ab0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
5ac0: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 _ATOMIC
5ad0: 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 0x00000001.#def
5ae0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
5af0: 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 _ATOMIC512
5b00: 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 0x00000002.#def
5b10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
5b20: 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 _ATOMIC1K
5b30: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 0x00000004.#def
5b40: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
5b50: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 _ATOMIC2K
5b60: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 0x00000008.#def
5b70: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
5b80: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 _ATOMIC4K
5b90: 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 0x00000010.#def
5ba0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
5bb0: 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 _ATOMIC8K
5bc0: 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 0x00000020.#def
5bd0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
5be0: 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 _ATOMIC16K
5bf0: 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 0x00000040.#def
5c00: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
5c10: 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 _ATOMIC32K
5c20: 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 0x00000080.#def
5c30: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
5c40: 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 _ATOMIC64K
5c50: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 0x00000100.#def
5c60: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
5c70: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 _SAFE_APPEND
5c80: 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 0x00000200.#def
5c90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
5ca0: 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 _SEQUENTIAL
5cb0: 20 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 0x00000400../*.
5cc0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c ** CAPI3REF: Fil
5cd0: 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 e Locking Levels
5ce0: 20 7b 48 31 30 32 35 30 7d 20 3c 48 31 31 31 32 {H10250} <H1112
5cf0: 30 3e 20 3c 48 31 31 33 31 30 3e 0a 2a 2a 0a 2a 0> <H11310>.**.*
5d00: 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e * SQLite uses on
5d10: 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 e of these integ
5d20: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 er values as the
5d30: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d second.** argum
5d40: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 ent to calls it
5d50: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f makes to the xLo
5d60: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b ck() and xUnlock
5d70: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 () methods.** of
5d80: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f an [sqlite3_io_
5d90: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e methods] object.
5da0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
5db0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 TE_LOCK_NONE
5dc0: 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 0.#define
5dd0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 SQLITE_LOCK_SHAR
5de0: 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 ED 1.#def
5df0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f ine SQLITE_LOCK_
5e00: 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a RESERVED 2.
5e10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
5e20: 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 OCK_PENDING
5e30: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 3.#define SQLI
5e40: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 TE_LOCK_EXCLUSIV
5e50: 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 E 4../*.** C
5e60: 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f API3REF: Synchro
5e70: 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c nization Type Fl
5e80: 61 67 73 20 7b 48 31 30 32 36 30 7d 20 3c 48 31 ags {H10260} <H1
5e90: 31 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 1120>.**.** When
5ea0: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 SQLite invokes
5eb0: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 the xSync() meth
5ec0: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c od of an.** [sql
5ed0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
5ee0: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 object it uses
5ef0: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 a combination of
5f00: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 .** these intege
5f10: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 r values as the
5f20: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e second argument.
5f30: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 .**.** When the
5f40: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 SQLITE_SYNC_DATA
5f50: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 ONLY flag is use
5f60: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 d, it means that
5f70: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 the.** sync ope
5f80: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 ration only need
5f90: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 s to flush data
5fa0: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e to mass storage.
5fb0: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 Inode.** infor
5fc0: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 mation need not
5fd0: 62 65 20 66 6c 75 73 68 65 64 2e 20 54 68 65 20 be flushed. The
5fe0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d SQLITE_SYNC_NORM
5ff0: 41 4c 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a AL flag means.**
6000: 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 to use normal f
6010: 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 sync() semantics
6020: 2e 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e . The SQLITE_SYN
6030: 43 5f 46 55 4c 4c 20 66 6c 61 67 20 6d 65 61 6e C_FULL flag mean
6040: 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 s.** to use Mac
6050: 4f 53 2d 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 OS-X style fulls
6060: 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 ync instead of f
6070: 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 sync()..*/.#defi
6080: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e ne SQLITE_SYNC_N
6090: 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 ORMAL 0x0
60a0: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 0002.#define SQL
60b0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 ITE_SYNC_FULL
60c0: 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 0x00003.#
60d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 define SQLITE_SY
60e0: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 NC_DATAONLY
60f0: 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 0x00010../*.**
6100: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 CAPI3REF: OS Int
6110: 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 erface Open File
6120: 20 48 61 6e 64 6c 65 20 7b 48 31 31 31 31 30 7d Handle {H11110}
6130: 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 <S20110>.**.**
6140: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 An [sqlite3_file
6150: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 ] object represe
6160: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 nts an open file
6170: 20 69 6e 20 74 68 65 20 4f 53 0a 2a 2a 20 69 6e in the OS.** in
6180: 74 65 72 66 61 63 65 20 6c 61 79 65 72 2e 20 20 terface layer.
6190: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e Individual OS in
61a0: 74 65 72 66 61 63 65 20 69 6d 70 6c 65 6d 65 6e terface implemen
61b0: 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 tations will.**
61c0: 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 want to subclass
61d0: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 this object by
61e0: 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 appending additi
61f0: 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 onal fields.** f
6200: 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 or their own use
6210: 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 . The pMethods
6220: 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 entry is a point
6230: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c er to an.** [sql
6240: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
6250: 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 object that def
6260: 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 ines methods for
6270: 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 performing.** I
6280: 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e /O operations on
6290: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a the open file..
62a0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
62b0: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 t sqlite3_file s
62c0: 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 qlite3_file;.str
62d0: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 uct sqlite3_file
62e0: 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 {. const struc
62f0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 t sqlite3_io_met
6300: 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 hods *pMethods;
6310: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 /* Methods for
6320: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a an open file */.
6330: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 };../*.** CAPI3R
6340: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 EF: OS Interface
6350: 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 File Virtual Me
6360: 74 68 6f 64 73 20 4f 62 6a 65 63 74 20 7b 48 31 thods Object {H1
6370: 31 31 32 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 1120} <S20110>.*
6380: 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 *.** Every file
6390: 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 opened by the [s
63a0: 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 qlite3_vfs] xOpe
63b0: 6e 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 n method populat
63c0: 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 es an.** [sqlite
63d0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 3_file] object (
63e0: 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c or, more commonl
63f0: 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 y, a subclass of
6400: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
6410: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 _file] object) w
6420: 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f ith a pointer to
6430: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 an instance of
6440: 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 this object..**
6450: 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 This object defi
6460: 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 nes the methods
6470: 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 used to perform
6480: 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f various operatio
6490: 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 ns.** against th
64a0: 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 e open file repr
64b0: 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b esented by the [
64c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 sqlite3_file] ob
64d0: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ject..**.** The
64e0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 flags argument t
64f0: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f o xSync may be o
6500: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 ne of [SQLITE_SY
6510: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a NC_NORMAL] or.**
6520: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 [SQLITE_SYNC_FU
6530: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 LL]. The first
6540: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f choice is the no
6550: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a rmal fsync()..**
6560: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 The second choi
6570: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 2d 58 ce is a Mac OS-X
6580: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e style fullsync.
6590: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 The [SQLITE_SY
65a0: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 NC_DATAONLY].**
65b0: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 flag may be ORed
65c0: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 in to indicate
65d0: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 that only the da
65e0: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a ta of the file.*
65f0: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e * and not its in
6600: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 ode needs to be
6610: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 synced..**.** Th
6620: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 e integer values
6630: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 to xLock() and
6640: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e xUnlock() are on
6650: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 e of.** <ul>.**
6660: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 <li> [SQLITE_LOC
6670: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e K_NONE],.** <li>
6680: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 [SQLITE_LOCK_SH
6690: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b ARED],.** <li> [
66a0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 SQLITE_LOCK_RESE
66b0: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b RVED],.** <li> [
66c0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 SQLITE_LOCK_PEND
66d0: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e ING], or.** <li>
66e0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 [SQLITE_LOCK_EX
66f0: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 CLUSIVE]..** </u
6700: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e l>.** xLock() in
6710: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b creases the lock
6720: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 . xUnlock() decr
6730: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a eases the lock..
6740: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 ** The xCheckRes
6750: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 ervedLock() meth
6760: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 od checks whethe
6770: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 r any database c
6780: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 onnection,.** ei
6790: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f ther in this pro
67a0: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 cess or in some
67b0: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 other process, i
67c0: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 s holding a RESE
67d0: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 RVED,.** PENDING
67e0: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c , or EXCLUSIVE l
67f0: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e ock on the file.
6800: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 It returns tru
6810: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c e.** if such a l
6820: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 ock exists and f
6830: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a alse otherwise..
6840: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 **.** The xFileC
6850: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 ontrol() method
6860: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 is a generic int
6870: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f erface that allo
6880: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 ws custom.** VFS
6890: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
68a0: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e to directly con
68b0: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c trol an open fil
68c0: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b e using the.** [
68d0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e sqlite3_file_con
68e0: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 trol()] interfac
68f0: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 e. The second "
6900: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 op" argument is
6910: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 an.** integer op
6920: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 code. The third
6930: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 argument is a g
6940: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 eneric pointer i
6950: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f ntended to.** po
6960: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 int to a structu
6970: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 re that may cont
6980: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 ain arguments or
6990: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 space in which
69a0: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 to.** write retu
69b0: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 rn values. Pote
69c0: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 ntial uses for x
69d0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 FileControl() mi
69e0: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 ght be.** functi
69f0: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c ons to enable bl
6a00: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 ocking locks wit
6a10: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 h timeouts, to c
6a20: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 hange the.** loc
6a30: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 king strategy (f
6a40: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 or example to us
6a50: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 e dot-file locks
6a60: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a ), to inquire.**
6a70: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 about the statu
6a80: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 s of a lock, or
6a90: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c to break stale l
6aa0: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 ocks. The SQLit
6ab0: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 e.** core reserv
6ac0: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c es all opcodes l
6ad0: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 ess than 100 for
6ae0: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a its own use..**
6af0: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c A [SQLITE_FCNTL
6b00: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 _LOCKSTATE | lis
6b10: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 t of opcodes] le
6b20: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 ss than 100 is a
6b30: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 vailable..** App
6b40: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 lications that d
6b50: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 efine a custom x
6b60: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 FileControl meth
6b70: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 od should use op
6b80: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 codes.** greater
6b90: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f than 100 to avo
6ba0: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a id conflicts..**
6bb0: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 .** The xSectorS
6bc0: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 ize() method ret
6bd0: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 urns the sector
6be0: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 size of the.** d
6bf0: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 evice that under
6c00: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 lies the file.
6c10: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 The sector size
6c20: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 is the.** minimu
6c30: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e m write that can
6c40: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 be performed wi
6c50: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 thout disturbing
6c60: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 .** other bytes
6c70: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 in the file. Th
6c80: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 e xDeviceCharact
6c90: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 eristics().** me
6ca0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 thod returns a b
6cb0: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 it vector descri
6cc0: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f bing behaviors o
6cd0: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 f the.** underly
6ce0: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a ing device:.**.*
6cf0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b * <ul>.** <li> [
6d00: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
6d10: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 MIC].** <li> [SQ
6d20: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
6d30: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 C512].** <li> [S
6d40: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
6d50: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 IC1K].** <li> [S
6d60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
6d70: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 IC2K].** <li> [S
6d80: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
6d90: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 IC4K].** <li> [S
6da0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
6db0: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 IC8K].** <li> [S
6dc0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
6dd0: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b IC16K].** <li> [
6de0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
6df0: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 MIC32K].** <li>
6e00: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
6e10: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e OMIC64K].** <li>
6e20: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 [SQLITE_IOCAP_S
6e30: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c AFE_APPEND].** <
6e40: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
6e50: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a P_SEQUENTIAL].**
6e60: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 </ul>.**.** The
6e70: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
6e80: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 OMIC property me
6e90: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 ans that all wri
6ea0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 tes of.** any si
6eb0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 ze are atomic.
6ec0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
6ed0: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 _ATOMICnnn value
6ee0: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 s.** mean that w
6ef0: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 rites of blocks
6f00: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 that are nnn byt
6f10: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a es in size and.*
6f20: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f * are aligned to
6f30: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 an address whic
6f40: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 h is an integer
6f50: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e multiple of.** n
6f60: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 nn are atomic.
6f70: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
6f80: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c _SAFE_APPEND val
6f90: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 ue means.** that
6fa0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 when data is ap
6fb0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 pended to a file
6fc0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 , the data is ap
6fd0: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 pended.** first
6fe0: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 then the size of
6ff0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 the file is ext
7000: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 ended, never the
7010: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 other.** way ar
7020: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 ound. The SQLIT
7030: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 E_IOCAP_SEQUENTI
7040: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e AL property mean
7050: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d s that.** inform
7060: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e ation is written
7070: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 to disk in the
7080: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 same order as ca
7090: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 lls.** to xWrite
70a0: 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 ()..*/.typedef s
70b0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f truct sqlite3_io
70c0: 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 _methods sqlite3
70d0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 _io_methods;.str
70e0: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d uct sqlite3_io_m
70f0: 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 ethods {. int i
7100: 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 Version;. int (
7110: 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 *xClose)(sqlite3
7120: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 _file*);. int (
7130: 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f *xRead)(sqlite3_
7140: 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e file*, void*, in
7150: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f t iAmt, sqlite3_
7160: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 int64 iOfst);.
7170: 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 int (*xWrite)(sq
7180: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e lite3_file*, con
7190: 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 st void*, int iA
71a0: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 mt, sqlite3_int6
71b0: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 4 iOfst);. int
71c0: 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c (*xTruncate)(sql
71d0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 ite3_file*, sqli
71e0: 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b te3_int64 size);
71f0: 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 . int (*xSync)(
7200: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
7210: 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 nt flags);. int
7220: 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 (*xFileSize)(sq
7230: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c lite3_file*, sql
7240: 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a ite3_int64 *pSiz
7250: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 e);. int (*xLoc
7260: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a k)(sqlite3_file*
7270: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a , int);. int (*
7280: 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 xUnlock)(sqlite3
7290: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 _file*, int);.
72a0: 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 int (*xCheckRese
72b0: 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 rvedLock)(sqlite
72c0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 3_file*, int *pR
72d0: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a esOut);. int (*
72e0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 xFileControl)(sq
72f0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 lite3_file*, int
7300: 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 op, void *pArg)
7310: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f ;. int (*xSecto
7320: 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 rSize)(sqlite3_f
7330: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 ile*);. int (*x
7340: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 DeviceCharacteri
7350: 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 stics)(sqlite3_f
7360: 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41 64 64 69 ile*);. /* Addi
7370: 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d tional methods m
7380: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 ay be added in f
7390: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a uture releases *
73a0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.};../*.** CAPI
73b0: 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 3REF: Standard F
73c0: 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f ile Control Opco
73d0: 64 65 73 20 7b 48 31 31 33 31 30 7d 20 3c 53 33 des {H11310} <S3
73e0: 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 0800>.**.** Thes
73f0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 e integer consta
7400: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 nts are opcodes
7410: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e for the xFileCon
7420: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f trol method.** o
7430: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 f the [sqlite3_i
7440: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 o_methods] objec
7450: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 t and for the [s
7460: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
7470: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 rol()].** interf
7480: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b ace..**.** The [
7490: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 SQLITE_FCNTL_LOC
74a0: 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 KSTATE] opcode i
74b0: 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 s used for debug
74c0: 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f ging. This.** o
74d0: 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 pcode causes the
74e0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 xFileControl me
74f0: 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 thod to write th
7500: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 e current state
7510: 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 of.** the lock (
7520: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c one of [SQLITE_L
7530: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 OCK_NONE], [SQLI
7540: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c TE_LOCK_SHARED],
7550: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b .** [SQLITE_LOCK
7560: 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c _RESERVED], [SQL
7570: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 ITE_LOCK_PENDING
7580: 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f ], or [SQLITE_LO
7590: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a CK_EXCLUSIVE]).*
75a0: 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 * into an intege
75b0: 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20 r that the pArg
75c0: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 argument points
75d0: 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c to. This capabil
75e0: 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 ity.** is used d
75f0: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e uring testing an
7600: 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 d only needs to
7610: 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 be supported whe
7620: 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a n SQLITE_TEST.**
7630: 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a is defined..*/.
7640: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
7650: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 CNTL_LOCKSTATE
7660: 20 20 20 20 20 20 31 0a 0a 2f 2a 0a 2a 2a 20 43 1../*.** C
7670: 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 API3REF: Mutex H
7680: 61 6e 64 6c 65 20 7b 48 31 37 31 31 30 7d 20 3c andle {H17110} <
7690: 53 32 30 31 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S20130>.**.** Th
76a0: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 e mutex module w
76b0: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 ithin SQLite def
76c0: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 ines [sqlite3_mu
76d0: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a tex] to be an.**
76e0: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 abstract type f
76f0: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 or a mutex objec
7700: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 t. The SQLite c
7710: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a ore never looks.
7720: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e ** at the intern
7730: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f al representatio
7740: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 n of an [sqlite3
7750: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c _mutex]. It onl
7760: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 y.** deals with
7770: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 pointers to the
7780: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 [sqlite3_mutex]
7790: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 object..**.** Mu
77a0: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 texes are create
77b0: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
77c0: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e _mutex_alloc()].
77d0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
77e0: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ct sqlite3_mutex
77f0: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a sqlite3_mutex;.
7800: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
7810: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 OS Interface Ob
7820: 6a 65 63 74 20 7b 48 31 31 31 34 30 7d 20 3c 53 ject {H11140} <S
7830: 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 20100>.**.** An
7840: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
7850: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 sqlite3_vfs obje
7860: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 ct defines the i
7870: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e nterface between
7880: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 .** the SQLite c
7890: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 ore and the unde
78a0: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 rlying operating
78b0: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 system. The "v
78c0: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 fs".** in the na
78d0: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 me of the object
78e0: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 stands for "vir
78f0: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d tual file system
7900: 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c "..**.** The val
7910: 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 ue of the iVersi
7920: 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 on field is init
7930: 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 ially 1 but may
7940: 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 be larger in.**
7950: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 future versions
7960: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 of SQLite. Addi
7970: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 tional fields ma
7980: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f y be appended to
7990: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 this.** object
79a0: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f when the iVersio
79b0: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 n value is incre
79c0: 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 ased. Note that
79d0: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a the structure.*
79e0: 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 * of the sqlite3
79f0: 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e _vfs object chan
7a00: 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 ges in the trans
7a10: 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a action between.*
7a20: 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e * SQLite version
7a30: 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 3.5.9 and 3.6.0
7a40: 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 and yet the iVe
7a50: 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 rsion field was
7a60: 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e not.** modified.
7a70: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 .**.** The szOsF
7a80: 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 ile field is the
7a90: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 size of the sub
7aa0: 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 classed [sqlite3
7ab0: 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 _file].** struct
7ac0: 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 ure used by this
7ad0: 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d VFS. mxPathnam
7ae0: 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d e is the maximum
7af0: 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 length of.** a
7b00: 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 pathname in this
7b10: 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 VFS..**.** Regi
7b20: 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 stered sqlite3_v
7b30: 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b fs objects are k
7b40: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 ept on a linked
7b50: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a list formed by.*
7b60: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e * the pNext poin
7b70: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 ter. The [sqlit
7b80: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 e3_vfs_register(
7b90: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 )].** and [sqlit
7ba0: 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 e3_vfs_unregiste
7bb0: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 r()] interfaces
7bc0: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 manage this list
7bd0: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d .** in a thread-
7be0: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b safe way. The [
7bf0: 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 sqlite3_vfs_find
7c00: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a ()] interface.**
7c10: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 searches the li
7c20: 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 st. Neither the
7c30: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 application cod
7c40: 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a e nor the VFS.**
7c50: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
7c60: 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 should use the p
7c70: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a Next pointer..**
7c80: 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 .** The pNext fi
7c90: 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 eld is the only
7ca0: 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c field in the sql
7cb0: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 ite3_vfs.** stru
7cc0: 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 cture that SQLit
7cd0: 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 e will ever modi
7ce0: 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c fy. SQLite will
7cf0: 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 only access.**
7d00: 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 or modify this f
7d10: 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 ield while holdi
7d20: 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 ng a particular
7d30: 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a static mutex..**
7d40: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
7d50: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f should never mo
7d60: 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 dify anything wi
7d70: 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 thin the sqlite3
7d80: 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f _vfs.** object o
7d90: 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 nce the object h
7da0: 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 as been register
7db0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e ed..**.** The zN
7dc0: 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 ame field holds
7dd0: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
7de0: 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 VFS module. The
7df0: 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 name must.** be
7e00: 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 unique across a
7e10: 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a ll VFS modules..
7e20: 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 31 7d 20 53 **.** {H11141} S
7e30: 51 4c 69 74 65 20 77 69 6c 6c 20 67 75 61 72 61 QLite will guara
7e40: 6e 74 65 65 20 74 68 61 74 20 74 68 65 20 7a 46 ntee that the zF
7e50: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 ilename paramete
7e60: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 r to xOpen.** is
7e70: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 either a NULL p
7e80: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 ointer or string
7e90: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f obtained.** fro
7ea0: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 m xFullPathname(
7eb0: 29 2e 20 20 53 51 4c 69 74 65 20 66 75 72 74 68 ). SQLite furth
7ec0: 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 er guarantees th
7ed0: 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 at.** the string
7ee0: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 will be valid a
7ef0: 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 nd unchanged unt
7f00: 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a il xClose() is.*
7f10: 2a 20 63 61 6c 6c 65 64 2e 20 7b 45 4e 44 7d 20 * called. {END}
7f20: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 Because of the
7f30: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 73 previous sentens
7f40: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 e,.** the [sqlit
7f50: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 e3_file] can saf
7f60: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e ely store a poin
7f70: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 ter to the.** fi
7f80: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 lename if it nee
7f90: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 ds to remember t
7fa0: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 he filename for
7fb0: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 some reason..**
7fc0: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 If the zFilename
7fd0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 78 4f parameter is xO
7fe0: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f pen is a NULL po
7ff0: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e inter then xOpen
8000: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 69 74 65 20 .** must invite
8010: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 its own temporar
8020: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 y name for the f
8030: 69 6c 65 2e 20 20 57 68 65 6e 65 76 65 72 20 74 ile. Whenever t
8040: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 he .** xFilename
8050: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 parameter is NU
8060: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 LL it will also
8070: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 be the case that
8080: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 the.** flags pa
8090: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 rameter will inc
80a0: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 lude [SQLITE_OPE
80b0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d N_DELETEONCLOSE]
80c0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 32 7d ..**.** {H11142}
80d0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d The flags argum
80e0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 ent to xOpen() i
80f0: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 ncludes all bits
8100: 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 set in.** the f
8110: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f lags argument to
8120: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
8130: 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 2()]. Or if [sq
8140: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a lite3_open()].**
8150: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 or [sqlite3_ope
8160: 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 n16()] is used,
8170: 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 then flags inclu
8180: 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 des at least.**
8190: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 [SQLITE_OPEN_REA
81a0: 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 DWRITE] | [SQLIT
81b0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 E_OPEN_CREATE].
81c0: 7b 45 4e 44 7d 0a 2a 2a 20 49 66 20 78 4f 70 65 {END}.** If xOpe
81d0: 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 n() opens a file
81e0: 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 read-only then
81f0: 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 it sets *pOutFla
8200: 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 gs to.** include
8210: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 [SQLITE_OPEN_RE
8220: 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 ADONLY]. Other
8230: 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 bits in *pOutFla
8240: 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a gs may be set..*
8250: 2a 0a 2a 2a 20 7b 48 31 31 31 34 33 7d 20 53 51 *.** {H11143} SQ
8260: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 Lite will also a
8270: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f dd one of the fo
8280: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f llowing flags to
8290: 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 the xOpen().**
82a0: 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 call, depending
82b0: 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 on the object be
82c0: 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a ing opened:.**.*
82d0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 * <ul>.** <li>
82e0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 [SQLITE_OPEN_MAI
82f0: 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b N_DB].** <li> [
8300: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e SQLITE_OPEN_MAIN
8310: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 _JOURNAL].** <li
8320: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
8330: 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e TEMP_DB].** <li>
8340: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 [SQLITE_OPEN_T
8350: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 EMP_JOURNAL].**
8360: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
8370: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d EN_TRANSIENT_DB]
8380: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
8390: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 E_OPEN_SUBJOURNA
83a0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c L].** <li> [SQL
83b0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f ITE_OPEN_MASTER_
83c0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c JOURNAL].** </ul
83d0: 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 > {END}.**.** Th
83e0: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 e file I/O imple
83f0: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 mentation can us
8400: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 e the object typ
8410: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 e flags to.** ch
8420: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20 ange the way it
8430: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 deals with files
8440: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 . For example,
8450: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a an application.*
8460: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 * that does not
8470: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 care about crash
8480: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c recovery or rol
8490: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 lback might make
84a0: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 .** the open of
84b0: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 a journal file a
84c0: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 no-op. Writes
84d0: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 to this journal
84e0: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 would.** also be
84f0: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 no-ops, and any
8500: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 attempt to read
8510: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 the journal wou
8520: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c ld return.** SQL
8530: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 ITE_IOERR. Or t
8540: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
8550: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a n might recogniz
8560: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73 e that a databas
8570: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 e.** file will b
8580: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 e doing page-ali
8590: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 gned sector read
85a0: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 s and writes in
85b0: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 a random.** orde
85c0: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 r and set up its
85d0: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 I/O subsystem a
85e0: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a ccordingly..**.*
85f0: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 * SQLite might a
8600: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 lso add one of t
8610: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 he following fla
8620: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 gs to the xOpen
8630: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 method:.**.** <u
8640: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 l>.** <li> [SQLI
8650: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e TE_OPEN_DELETEON
8660: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b CLOSE].** <li> [
8670: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c SQLITE_OPEN_EXCL
8680: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a USIVE].** </ul>.
8690: 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 35 7d 20 54 **.** {H11145} T
86a0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f he [SQLITE_OPEN_
86b0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 DELETEONCLOSE] f
86c0: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 lag means the fi
86d0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 le should be.**
86e0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 deleted when it
86f0: 69 73 20 63 6c 6f 73 65 64 2e 20 20 7b 48 31 31 is closed. {H11
8700: 31 34 36 7d 20 54 68 65 20 5b 53 51 4c 49 54 45 146} The [SQLITE
8710: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c _OPEN_DELETEONCL
8720: 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 OSE].** will be
8730: 73 65 74 20 66 6f 72 20 54 45 4d 50 20 20 64 61 set for TEMP da
8740: 74 61 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c tabases, journal
8750: 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 s and for subjou
8760: 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 rnals..**.** {H1
8770: 31 31 34 37 7d 20 54 68 65 20 5b 53 51 4c 49 54 1147} The [SQLIT
8780: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 E_OPEN_EXCLUSIVE
8790: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 ] flag means the
87a0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 file should be
87b0: 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f 72 20 65 78 opened.** for ex
87c0: 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 20 clusive access.
87d0: 20 54 68 69 73 20 66 6c 61 67 20 69 73 20 73 65 This flag is se
87e0: 74 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65 73 20 t for all files
87f0: 65 78 63 65 70 74 0a 2a 2a 20 66 6f 72 20 74 68 except.** for th
8800: 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 e main database
8810: 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 file..**.** {H11
8820: 31 34 38 7d 20 41 74 20 6c 65 61 73 74 20 73 7a 148} At least sz
8830: 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 OsFile bytes of
8840: 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 memory are alloc
8850: 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a ated by SQLite.*
8860: 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b * to hold the [
8870: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 sqlite3_file] st
8880: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61 ructure passed a
8890: 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 s the third.** a
88a0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e rgument to xOpen
88b0: 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20 78 4f 70 . {END} The xOp
88c0: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e en method does n
88d0: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c ot have to.** al
88e0: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 locate the struc
88f0: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 ture; it should
8900: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e just fill it in.
8910: 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 39 7d 20 .**.** {H11149}
8920: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 The flags argume
8930: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 nt to xAccess()
8940: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 may be [SQLITE_A
8950: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a CCESS_EXISTS].**
8960: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 to test for the
8970: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 existence of a
8980: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 file, or [SQLITE
8990: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 _ACCESS_READWRIT
89a0: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 E] to.** test wh
89b0: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 ether a file is
89c0: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 readable and wri
89d0: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 table, or [SQLIT
89e0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a E_ACCESS_READ].*
89f0: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 * to test whethe
8a00: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c r a file is at l
8a10: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 7b east readable. {
8a20: 45 4e 44 7d 20 20 54 68 65 20 66 69 6c 65 20 63 END} The file c
8a30: 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 an be a.** direc
8a40: 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 tory..**.** {H11
8a50: 31 35 30 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 150} SQLite will
8a60: 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 always allocate
8a70: 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 at least mxPath
8a80: 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 name+1 bytes for
8a90: 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 the.** output b
8aa0: 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e uffer xFullPathn
8ab0: 61 6d 65 2e 20 7b 48 31 31 31 35 31 7d 20 54 68 ame. {H11151} Th
8ac0: 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 e exact size of
8ad0: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 the output buffe
8ae0: 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 r.** is also pas
8af0: 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 sed as a paramet
8b00: 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 er to both meth
8b10: 6f 64 73 2e 20 7b 45 4e 44 7d 20 20 49 66 20 74 ods. {END} If t
8b20: 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 he output buffer
8b30: 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 .** is not large
8b40: 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 enough, [SQLITE
8b50: 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c _CANTOPEN] shoul
8b60: 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 d be returned. S
8b70: 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 ince this is.**
8b80: 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 handled as a fat
8b90: 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 al error by SQLi
8ba0: 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e te, vfs implemen
8bb0: 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 tations should e
8bc0: 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 ndeavor.** to pr
8bd0: 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 event this by se
8be0: 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 tting mxPathname
8bf0: 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 to a sufficient
8c00: 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a ly large value..
8c10: 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f **.** The xRando
8c20: 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 mness(), xSleep(
8c30: 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 ), and xCurrentT
8c40: 69 6d 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 ime() interfaces
8c50: 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73 74 72 69 .** are not stri
8c60: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 ctly a part of t
8c70: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 he filesystem, b
8c80: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 ut they are.** i
8c90: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 ncluded in the V
8ca0: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 FS structure for
8cb0: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a completeness..*
8cc0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 * The xRandomnes
8cd0: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 s() function att
8ce0: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 empts to return
8cf0: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 nBytes bytes.**
8d00: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 of good-quality
8d10: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 randomness into
8d20: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 zOut. The retur
8d30: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 n value is.** th
8d40: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 e actual number
8d50: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 of bytes of rand
8d60: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e omness obtained.
8d70: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 .** The xSleep()
8d80: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 method causes t
8d90: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 he calling threa
8da0: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 d to sleep for a
8db0: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e t.** least the n
8dc0: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 umber of microse
8dd0: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 54 68 conds given. Th
8de0: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 e xCurrentTime()
8df0: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 .** method retur
8e00: 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 ns a Julian Day
8e10: 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 Number for the c
8e20: 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 urrent date and
8e30: 74 69 6d 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 time..*/.typedef
8e40: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
8e50: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b vfs sqlite3_vfs;
8e60: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
8e70: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 vfs {. int iVer
8e80: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 sion;
8e90: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 /* Structure ve
8ea0: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a rsion number */.
8eb0: 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 int szOsFile;
8ec0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 /* Si
8ed0: 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 ze of subclassed
8ee0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f sqlite3_file */
8ef0: 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d . int mxPathnam
8f00: 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d e; /* M
8f10: 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 aximum file path
8f20: 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 name length */.
8f30: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e sqlite3_vfs *pN
8f40: 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 ext; /* Nex
8f50: 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 t registered VFS
8f60: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
8f70: 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f *zName; /
8f80: 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 * Name of this v
8f90: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 irtual file syst
8fa0: 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 em */. void *pA
8fb0: 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 ppData;
8fc0: 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 /* Pointer to a
8fd0: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 pplication-speci
8fe0: 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e fic data */. in
8ff0: 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 t (*xOpen)(sqlit
9000: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
9010: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 har *zName, sqli
9020: 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 te3_file*,.
9030: 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c int fl
9040: 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c ags, int *pOutFl
9050: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 ags);. int (*xD
9060: 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 elete)(sqlite3_v
9070: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
9080: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 *zName, int sync
9090: 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 Dir);. int (*xA
90a0: 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 ccess)(sqlite3_v
90b0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
90c0: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 *zName, int flag
90d0: 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 s, int *pResOut)
90e0: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 ;. int (*xFullP
90f0: 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 athname)(sqlite3
9100: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
9110: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f r *zName, int nO
9120: 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b ut, char *zOut);
9130: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 . void *(*xDlOp
9140: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a en)(sqlite3_vfs*
9150: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 , const char *zF
9160: 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 ilename);. void
9170: 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c (*xDlError)(sql
9180: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e ite3_vfs*, int n
9190: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 Byte, char *zErr
91a0: 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a Msg);. void *(*
91b0: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f xDlSym)(sqlite3_
91c0: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 vfs*,void*, cons
91d0: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 t char *zSymbol)
91e0: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c ;. void (*xDlCl
91f0: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ose)(sqlite3_vfs
9200: 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 *, void*);. int
9210: 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 (*xRandomness)(
9220: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e sqlite3_vfs*, in
9230: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a t nByte, char *z
9240: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 Out);. int (*xS
9250: 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 leep)(sqlite3_vf
9260: 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 s*, int microsec
9270: 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 onds);. int (*x
9280: 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c CurrentTime)(sql
9290: 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c ite3_vfs*, doubl
92a0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 e*);. int (*xGe
92b0: 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 tLastError)(sqli
92c0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 te3_vfs*, int, c
92d0: 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 har *);. /* New
92e0: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 fields may be a
92f0: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 ppended in figur
9300: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 e versions. The
9310: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 iVersion. ** v
9320: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d alue will increm
9330: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 ent whenever thi
9340: 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b s happens. */.};
9350: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
9360: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 : Flags for the
9370: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 xAccess VFS meth
9380: 6f 64 20 7b 48 31 31 31 39 30 7d 20 3c 48 31 31 od {H11190} <H11
9390: 31 34 30 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 140>.**.** {H111
93a0: 39 31 7d 20 54 68 65 73 65 20 69 6e 74 65 67 65 91} These intege
93b0: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 r constants can
93c0: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 be used as the t
93d0: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 hird parameter t
93e0: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 o.** the xAccess
93f0: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 method of an [s
9400: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
9410: 63 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79 20 ct. {END} They
9420: 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 determine.** wha
9430: 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 t kind of permis
9440: 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 sions the xAcces
9450: 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b s method is look
9460: 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 7b 48 31 31 ing for..** {H11
9470: 31 39 32 7d 20 57 69 74 68 20 53 51 4c 49 54 45 192} With SQLITE
9480: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 _ACCESS_EXISTS,
9490: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 the xAccess meth
94a0: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 od.** simply che
94b0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 cks whether the
94c0: 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 file exists..**
94d0: 7b 48 31 31 31 39 33 7d 20 57 69 74 68 20 53 51 {H11193} With SQ
94e0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
94f0: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 WRITE, the xAcce
9500: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 ss method.** che
9510: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 cks whether the
9520: 66 69 6c 65 20 69 73 20 62 6f 74 68 20 72 65 61 file is both rea
9530: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 dable and writab
9540: 6c 65 2e 0a 2a 2a 20 7b 48 31 31 31 39 34 7d 20 le..** {H11194}
9550: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 With SQLITE_ACCE
9560: 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 SS_READ, the xAc
9570: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 cess method.** c
9580: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 hecks whether th
9590: 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 e file is readab
95a0: 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 le..*/.#define S
95b0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 QLITE_ACCESS_EXI
95c0: 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 STS 0.#define
95d0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 SQLITE_ACCESS_R
95e0: 45 41 44 57 52 49 54 45 20 31 0a 23 64 65 66 69 EADWRITE 1.#defi
95f0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 ne SQLITE_ACCESS
9600: 5f 52 45 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a _READ 2../*
9610: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e .** CAPI3REF: In
9620: 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c itialize The SQL
9630: 69 74 65 20 4c 69 62 72 61 72 79 20 7b 48 31 30 ite Library {H10
9640: 31 33 30 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33 130} <S20000><S3
9650: 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 0100>.**.** The
9660: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
9670: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 ze() routine ini
9680: 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 tializes the.**
9690: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 SQLite library.
96a0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 The sqlite3_shu
96b0: 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a tdown() routine.
96c0: 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 ** deallocates a
96d0: 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 ny resources tha
96e0: 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 t were allocated
96f0: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 by sqlite3_init
9700: 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 ialize()..**.**
9710: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 A call to sqlite
9720: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 3_initialize() i
9730: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 s an "effective"
9740: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a call if it is.*
9750: 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 * the first time
9760: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
9770: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 ize() is invoked
9780: 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 during the life
9790: 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 time of.** the p
97a0: 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 rocess, or if it
97b0: 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 is the first ti
97c0: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 me sqlite3_initi
97d0: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b alize() is invok
97e0: 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 ed.** following
97f0: 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 a call to sqlite
9800: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 4f 3_shutdown(). O
9810: 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 nly an effective
9820: 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 call.** of sqli
9830: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
9840: 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 does any initia
9850: 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f lization. All o
9860: 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 ther calls.** ar
9870: 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 e harmless no-op
9880: 73 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f s..**.** Among o
9890: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 73 71 6c ther things, sql
98a0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
98b0: 29 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 0a 2a ) shall invoke.*
98c0: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 * sqlite3_os_ini
98d0: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c t(). Similarly,
98e0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
98f0: 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c 20 69 6e 76 n().** shall inv
9900: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 oke sqlite3_os_e
9910: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 nd()..**.** The
9920: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
9930: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 ze() routine ret
9940: 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 20 6f urns SQLITE_OK o
9950: 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 49 66 n success..** If
9960: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e for some reason
9970: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 , sqlite3_initia
9980: 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 lize() is unable
9990: 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a to initialize.*
99a0: 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 * the library (p
99b0: 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 erhaps it is una
99c0: 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 ble to allocate
99d0: 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 a needed resourc
99e0: 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d e such.** as a m
99f0: 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 utex) it returns
9a00: 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d an [error code]
9a10: 20 6f 74 68 65 72 20 74 68 61 6e 20 53 51 4c 49 other than SQLI
9a20: 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 TE_OK..**.** The
9a30: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
9a40: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 ize() routine is
9a50: 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c called internal
9a60: 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 ly by many other
9a70: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 .** SQLite inter
9a80: 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e faces so that an
9a90: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 application usu
9aa0: 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 ally does not ne
9ab0: 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 ed to.** invoke
9ac0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
9ad0: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 ze() directly.
9ae0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 For example, [sq
9af0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a lite3_open()].**
9b00: 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 calls sqlite3_i
9b10: 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 nitialize() so t
9b20: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 he SQLite librar
9b30: 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 y will be automa
9b40: 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 tically.** initi
9b50: 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c alized when [sql
9b60: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 ite3_open()] is
9b70: 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 called if it has
9b80: 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 not be initiali
9b90: 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 zed.** already.
9ba0: 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c However, if SQL
9bb0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
9bc0: 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f with the SQLITE_
9bd0: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 0a 2a 2a OMIT_AUTOINIT.**
9be0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
9bf0: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 tion, then the a
9c00: 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 utomatic calls t
9c10: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 o sqlite3_initia
9c20: 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d lize().** are om
9c30: 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 itted and the ap
9c40: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 plication must c
9c50: 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 all sqlite3_init
9c60: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c ialize() directl
9c70: 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 y.** prior to us
9c80: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 ing any other SQ
9c90: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 Lite interface.
9ca0: 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 For maximum por
9cb0: 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 tability,.** it
9cc0: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 is recommended t
9cd0: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 hat applications
9ce0: 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 always invoke s
9cf0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
9d00: 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 e().** directly
9d10: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 prior to using a
9d20: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 ny other SQLite
9d30: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 interface. Futu
9d40: 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f re releases.** o
9d50: 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 f SQLite may req
9d60: 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f uire this. In o
9d70: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 ther words, the
9d80: 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 behavior exhibit
9d90: 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 ed.** when SQLit
9da0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
9db0: 74 68 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 th SQLITE_OMIT_A
9dc0: 55 54 4f 49 4e 49 54 20 6d 69 67 68 74 20 62 65 UTOINIT might be
9dd0: 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 come the.** defa
9de0: 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 ult behavior in
9df0: 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 some future rele
9e00: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a ase of SQLite..*
9e10: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
9e20: 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 _os_init() routi
9e30: 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e ne does operatin
9e40: 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 g-system specifi
9e50: 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 c.** initializat
9e60: 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 ion of the SQLit
9e70: 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 e library. The
9e80: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 sqlite3_os_end()
9e90: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f .** routine undo
9ea0: 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 es the effect of
9eb0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
9ec0: 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 (). Typical tas
9ed0: 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 ks.** performed
9ee0: 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 by these routine
9ef0: 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 s include alloca
9f00: 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 tion or dealloca
9f10: 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 tion.** of stati
9f20: 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 c resources, ini
9f30: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 tialization of g
9f40: 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c lobal variables,
9f50: 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 .** setting up a
9f60: 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 default [sqlite
9f70: 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 3_vfs] module, o
9f80: 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 r setting up.**
9f90: 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 a default config
9fa0: 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 uration using [s
9fb0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
9fc0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c ..**.** The appl
9fd0: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e ication should n
9fe0: 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 ever invoke eith
9ff0: 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e er sqlite3_os_in
a000: 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 it().** or sqlit
a010: 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 e3_os_end() dire
a020: 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 ctly. The appli
a030: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e cation should on
a040: 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c ly invoke.** sql
a050: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
a060: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 ) and sqlite3_sh
a070: 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 utdown(). The s
a080: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
a090: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 .** interface is
a0a0: 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 called automati
a0b0: 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 cally by sqlite3
a0c0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e _initialize() an
a0d0: 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f d.** sqlite3_os_
a0e0: 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 end() is called
a0f0: 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 by sqlite3_shutd
a100: 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 own(). Appropri
a110: 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 ate.** implement
a120: 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 ations for sqlit
a130: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 e3_os_init() and
a140: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
a150: 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 ).** are built i
a160: 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 nto SQLite when
a170: 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 it is compiled f
a180: 6f 72 20 75 6e 69 78 2c 20 77 69 6e 64 6f 77 73 or unix, windows
a190: 2c 20 6f 72 20 6f 73 2f 32 2e 0a 2a 2a 20 57 68 , or os/2..** Wh
a1a0: 65 6e 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 en built for oth
a1b0: 65 72 20 70 6c 61 74 66 6f 72 6d 73 20 28 75 73 er platforms (us
a1c0: 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f ing the SQLITE_O
a1d0: 53 5f 4f 54 48 45 52 3d 31 20 63 6f 6d 70 69 6c S_OTHER=1 compil
a1e0: 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e e-time.** option
a1f0: 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f ) the applicatio
a200: 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 n must supply a
a210: 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 suitable impleme
a220: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 ntation for.** s
a230: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
a240: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f and sqlite3_os_
a250: 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 end(). An appli
a260: 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a cation-supplied.
a270: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
a280: 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f n of sqlite3_os_
a290: 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 init() or sqlite
a2a0: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 3_os_end().** mu
a2b0: 73 74 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 st return SQLITE
a2c0: 5f 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73 20 61 _OK on success a
a2d0: 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 nd some other [e
a2e0: 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a rror code] upon.
a2f0: 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 ** failure..*/.i
a300: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 nt sqlite3_initi
a310: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 alize(void);.int
a320: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
a330: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c n(void);.int sql
a340: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 ite3_os_init(voi
a350: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f d);.int sqlite3_
a360: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f os_end(void);../
a370: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
a380: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 onfiguring The S
a390: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b 48 QLite Library {H
a3a0: 31 30 31 34 35 7d 20 3c 53 32 30 30 30 30 3e 3c 10145} <S20000><
a3b0: 53 33 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 S30200>.** EXPER
a3c0: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 IMENTAL.**.** Th
a3d0: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 e sqlite3_config
a3e0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
a3f0: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f used to make glo
a400: 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f bal configuratio
a410: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 n.** changes to
a420: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 SQLite in order
a430: 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 to tune SQLite t
a440: 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e o the specific n
a450: 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 eeds of.** the a
a460: 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 pplication. The
a470: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 default configu
a480: 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d ration is recomm
a490: 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a ended for most.*
a4a0: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 * applications a
a4b0: 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 nd so this routi
a4c0: 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f ne is usually no
a4d0: 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 t necessary. It
a4e0: 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 is.** provided
a4f0: 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 to support rare
a500: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 applications wit
a510: 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e h unusual needs.
a520: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
a530: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 e3_config() inte
a540: 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 rface is not thr
a550: 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 eadsafe. The ap
a560: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 plication.** mus
a570: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f t insure that no
a580: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e other SQLite in
a590: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 terfaces are inv
a5a0: 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a oked by other.**
a5b0: 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 threads while s
a5c0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
a5d0: 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 is running. Fur
a5e0: 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 thermore, sqlite
a5f0: 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 3_config().** ma
a600: 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 y only be invoke
a610: 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 d prior to libra
a620: 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f ry initializatio
a630: 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 n using.** [sqli
a640: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
a650: 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 ] or after shutd
a660: 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f own by [sqlite3_
a670: 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 shutdown()]..**
a680: 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 Note, however, t
a690: 68 61 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 hat sqlite3_conf
a6a0: 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c ig() can be call
a6b0: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 ed as part of th
a6c0: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
a6d0: 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 ion of an applic
a6e0: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 ation-defined [s
a6f0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
a700: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 ]..**.** The fir
a710: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 st argument to s
a720: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
a730: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a is an integer.**
a740: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
a750: 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 SINGLETHREAD | c
a760: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
a770: 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d ion] that determ
a780: 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f ines.** what pro
a790: 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 perty of SQLite
a7a0: 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 is to be configu
a7b0: 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 red. Subsequent
a7c0: 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 arguments.** va
a7d0: 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 ry depending on
a7e0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 the [SQLITE_CONF
a7f0: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 IG_SINGLETHREAD
a800: 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 | configuration
a810: 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 option].** in th
a820: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
a830: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 63 ..**.** When a c
a840: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
a850: 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 ion is set, sqli
a860: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 te3_config() ret
a870: 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a urns SQLITE_OK..
a880: 2a 2a 20 49 66 20 74 68 65 20 6f 70 74 69 6f 6e ** If the option
a890: 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 is unknown or S
a8a0: 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 QLite is unable
a8b0: 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f to set the optio
a8c0: 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 n.** then this r
a8d0: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 outine returns a
a8e0: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 non-zero [error
a8f0: 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 code]..*/.int s
a900: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e qlite3_config(in
a910: 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 t, ...);../*.**
a920: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 CAPI3REF: Config
a930: 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e ure database con
a940: 6e 65 63 74 69 6f 6e 73 20 20 7b 48 31 30 31 38 nections {H1018
a950: 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 0} <S20000>.** E
a960: 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a XPERIMENTAL.**.*
a970: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 * The sqlite3_db
a980: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 _config() interf
a990: 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d ace is used to m
a9a0: 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ake configuratio
a9b0: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 n.** changes to
a9c0: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a [database conn
a9d0: 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e ection]. The in
a9e0: 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c terface is simil
a9f0: 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ar to.** [sqlite
aa00: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 3_config()] exce
aa10: 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e pt that the chan
aa20: 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 ges apply to a s
aa30: 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 ingle.** [databa
aa40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 se connection] (
aa50: 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 specified in the
aa60: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 first argument)
aa70: 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 . The.** sqlite
aa80: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 3_db_config() in
aa90: 74 65 72 66 61 63 65 20 63 61 6e 20 6f 6e 6c 79 terface can only
aaa0: 20 62 65 20 75 73 65 64 20 69 6d 6d 65 64 69 61 be used immedia
aab0: 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74 68 tely after.** th
aac0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
aad0: 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64 ction is created
aae0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
aaf0: 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c open()],.** [sql
ab00: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 ite3_open16()],
ab10: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e or [sqlite3_open
ab20: 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 _v2()]. .**.**
ab30: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d The second argum
ab40: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 ent to sqlite3_d
ab50: 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e b_config(D,V,...
ab60: 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6e ) is the.** con
ab70: 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 20 figuration verb
ab80: 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 - an integer cod
ab90: 65 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 e that indicates
aba0: 20 77 68 61 74 0a 2a 2a 20 61 73 70 65 63 74 20 what.** aspect
abb0: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 of the [database
abc0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 connection] is
abd0: 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 being configured
abe0: 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63 68 ..** The only ch
abf0: 6f 69 63 65 20 66 6f 72 20 74 68 69 73 20 76 61 oice for this va
ac00: 6c 75 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 lue is [SQLITE_D
ac10: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
ac20: 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73 E]..** New verbs
ac30: 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62 are likely to b
ac40: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
ac50: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
ac60: 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69 6f Lite..** Additio
ac70: 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 64 65 nal arguments de
ac80: 70 65 6e 64 20 6f 6e 20 74 68 65 20 76 65 72 62 pend on the verb
ac90: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
aca0: 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 _db_config(sqlit
acb0: 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e e3*, int op, ...
acc0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
acd0: 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 EF: Memory Alloc
ace0: 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b ation Routines {
acf0: 48 31 30 31 35 35 7d 20 3c 53 32 30 31 32 30 3e H10155} <S20120>
ad00: 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c .** EXPERIMENTAL
ad10: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e .**.** An instan
ad20: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 ce of this objec
ad30: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e t defines the in
ad40: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 terface between
ad50: 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f SQLite.** and lo
ad60: 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 w-level memory a
ad70: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e llocation routin
ad80: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f es..**.** This o
ad90: 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e bject is used in
ada0: 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 only one place
adb0: 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e in the SQLite in
adc0: 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f terface..** A po
add0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 inter to an inst
ade0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a ance of this obj
adf0: 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d ect is the argum
ae00: 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 ent to.** [sqlit
ae10: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 e3_config()] whe
ae20: 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 n the configurat
ae30: 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a ion option is.**
ae40: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
ae50: 4d 41 4c 4c 4f 43 5d 2e 20 20 42 79 20 63 72 65 MALLOC]. By cre
ae60: 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 ating an instanc
ae70: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 e of this object
ae80: 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 .** and passing
ae90: 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 it to [sqlite3_c
aea0: 6f 6e 66 69 67 28 29 5d 20 64 75 72 69 6e 67 20 onfig()] during
aeb0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 configuration, a
aec0: 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e n.** application
aed0: 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 can specify an
aee0: 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f alternative memo
aef0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 ry allocation su
af00: 62 73 79 73 74 65 6d 0a 2a 2a 20 66 6f 72 20 53 bsystem.** for S
af10: 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 QLite to use for
af20: 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 all of its dyna
af30: 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 mic memory needs
af40: 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ..**.** Note tha
af50: 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 t SQLite comes w
af60: 69 74 68 20 61 20 62 75 69 6c 74 2d 69 6e 20 6d ith a built-in m
af70: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 emory allocator
af80: 74 68 61 74 20 69 73 0a 2a 2a 20 70 65 72 66 65 that is.** perfe
af90: 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f ctly adequate fo
afa0: 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 r the overwhelmi
afb0: 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 ng majority of a
afc0: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 pplications.** a
afd0: 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a nd that this obj
afe0: 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 ect is only usef
aff0: 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e ul to a tiny min
b000: 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 ority of applica
b010: 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 tions.** with sp
b020: 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 ecialized memory
b030: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 allocation requ
b040: 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 irements. This
b050: 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 object is.** als
b060: 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 o used during te
b070: 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 sting of SQLite
b080: 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 in order to spec
b090: 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 ify an alternati
b0a0: 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c ve.** memory all
b0b0: 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 ocator that simu
b0c0: 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 lates memory out
b0d0: 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 -of-memory condi
b0e0: 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 tions in.** orde
b0f0: 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 r to verify that
b100: 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 SQLite recovers
b110: 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d gracefully from
b120: 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 such.** conditi
b130: 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ons..**.** The x
b140: 4d 61 6c 6c 6f 63 2c 20 78 46 72 65 65 2c 20 61 Malloc, xFree, a
b150: 6e 64 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68 nd xRealloc meth
b160: 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 ods must work li
b170: 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 ke the.** malloc
b180: 28 29 2c 20 66 72 65 65 28 29 2c 20 61 6e 64 20 (), free(), and
b190: 72 65 61 6c 6c 6f 63 28 29 20 66 75 6e 63 74 69 realloc() functi
b1a0: 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 ons from the sta
b1b0: 6e 64 61 72 64 20 6c 69 62 72 61 72 79 2e 0a 2a ndard library..*
b1c0: 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c *.** xSize shoul
b1d0: 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c d return the all
b1e0: 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 ocated size of a
b1f0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
b200: 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 on.** previously
b210: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 obtained from x
b220: 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c Malloc or xReall
b230: 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 oc. The allocat
b240: 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c ed size.** is al
b250: 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 ways at least as
b260: 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75 big as the requ
b270: 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d ested size but m
b280: 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a ay be larger..**
b290: 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 .** The xRoundup
b2a0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 method returns
b2b0: 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 what would be th
b2c0: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 e allocated size
b2d0: 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 of.** a memory
b2e0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e allocation given
b2f0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 a particular re
b300: 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d quested size. M
b310: 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c ost memory.** al
b320: 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 locators round u
b330: 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 p memory allocat
b340: 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f ions at least to
b350: 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 the next multip
b360: 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d le.** of 8. Som
b370: 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 e allocators rou
b380: 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 nd up to a large
b390: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f r multiple or to
b3a0: 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a a power of 2..*
b3b0: 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d *.** The xInit m
b3c0: 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 ethod initialize
b3d0: 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c s the memory all
b3e0: 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 ocator. (For ex
b3f0: 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 ample,.** it mig
b400: 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 ht allocate any
b410: 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 require mutexes
b420: 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e or initialize in
b430: 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 ternal data.** s
b440: 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 tructures. The
b450: 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 xShutdown method
b460: 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 is invoked (ind
b470: 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b irectly) by.** [
b480: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
b490: 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 ()] and should d
b4a0: 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 eallocate any re
b4b0: 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 sources acquired
b4c0: 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 .** by xInit. T
b4d0: 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e he pAppData poin
b4e0: 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 ter is used as t
b4f0: 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 he only paramete
b500: 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e r to.** xInit an
b510: 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2f 0a d xShutdown..*/.
b520: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
b530: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
b540: 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d ds sqlite3_mem_m
b550: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 ethods;.struct s
b560: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
b570: 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 ds {. void *(*x
b580: 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 Malloc)(int);
b590: 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 /* Memory
b5a0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 allocation funct
b5b0: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a ion */. void (*
b5c0: 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 xFree)(void*);
b5d0: 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 /* Free
b5e0: 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 a prior allocati
b5f0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a on */. void *(*
b600: 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c xRealloc)(void*,
b610: 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 int); /* Resize
b620: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a an allocation *
b630: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 /. int (*xSize)
b640: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 (void*);
b650: 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 /* Return the
b660: 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f size of an allo
b670: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 cation */. int
b680: 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 (*xRoundup)(int)
b690: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f ; /* Ro
b6a0: 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 und up request s
b6b0: 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f ize to allocatio
b6c0: 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 n size */. int
b6d0: 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b (*xInit)(void*);
b6e0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e /* In
b6f0: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d itialize the mem
b700: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f ory allocator */
b710: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 . void (*xShutd
b720: 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 own)(void*);
b730: 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a /* Deinitializ
b740: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c e the memory all
b750: 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 ocator */. void
b760: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 *pAppData;
b770: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 /* Ar
b780: 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 gument to xInit(
b790: 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 ) and xShutdown(
b7a0: 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ) */.};../*.** C
b7b0: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 API3REF: Configu
b7c0: 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b ration Options {
b7d0: 48 31 30 31 36 30 7d 20 3c 53 32 30 30 30 30 3e H10160} <S20000>
b7e0: 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c .** EXPERIMENTAL
b7f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e .**.** These con
b800: 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 stants are the a
b810: 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 vailable integer
b820: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
b830: 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 ptions that.** c
b840: 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 an be passed as
b850: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
b860: 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 nt to the [sqlit
b870: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 e3_config()] int
b880: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 erface..**.** Ne
b890: 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 w configuration
b8a0: 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 options may be a
b8b0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 dded in future r
b8c0: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 eleases of SQLit
b8d0: 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 e..** Existing c
b8e0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
b8f0: 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 ions might be di
b900: 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 scontinued. App
b910: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f lications.** sho
b920: 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 uld check the re
b930: 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b turn code from [
b940: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
b950: 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 ] to make sure t
b960: 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 hat.** the call
b970: 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 worked. The [sq
b980: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
b990: 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 interface will r
b9a0: 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a eturn a.** non-z
b9b0: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d ero [error code]
b9c0: 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 if a discontinu
b9d0: 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 ed or unsupporte
b9e0: 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 d configuration
b9f0: 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 option.** is inv
ba00: 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e oked..**.** <dl>
ba10: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
ba20: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
ba30: 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 AD</dt>.** <dd>T
ba40: 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 here are no argu
ba50: 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 ments to this op
ba60: 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 tion. This opti
ba70: 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 on disables.** a
ba80: 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 ll mutexing and
ba90: 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f puts SQLite into
baa0: 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 a mode where it
bab0: 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 can only be use
bac0: 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 d.** by a single
bad0: 20 74 68 72 65 61 64 2e 3c 2f 64 64 3e 0a 2a 2a thread.</dd>.**
bae0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
baf0: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 ONFIG_MULTITHREA
bb00: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 D</dt>.** <dd>Th
bb10: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d ere are no argum
bb20: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 ents to this opt
bb30: 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f ion. This optio
bb40: 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 n disables.** mu
bb50: 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 texing on [datab
bb60: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
bb70: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 and [prepared st
bb80: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 atement] objects
bb90: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 ..** The applica
bba0: 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 tion is responsi
bbb0: 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a ble for serializ
bbc0: 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a ing access to.**
bbd0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
bbe0: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 ctions] and [pre
bbf0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
bc00: 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 ]. But other mu
bc10: 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 texes.** are ena
bc20: 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c bled so that SQL
bc30: 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 ite will be safe
bc40: 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c to use in a mul
bc50: 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 ti-threaded.** e
bc60: 6e 76 69 72 6f 6e 6d 65 6e 74 2e 3c 2f 64 64 3e nvironment.</dd>
bc70: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
bc80: 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 E_CONFIG_SERIALI
bc90: 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ZED</dt>.** <dd>
bca0: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 There are no arg
bcb0: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f uments to this o
bcc0: 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 ption. This opt
bcd0: 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 ion enables.** a
bce0: 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 ll mutexes inclu
bcf0: 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 ding the recursi
bd00: 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e ve.** mutexes on
bd10: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
bd20: 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 ction] and [prep
bd30: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
bd40: 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 objects..** In t
bd50: 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 his mode (which
bd60: 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 is the default w
bd70: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f hen SQLite is co
bd80: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b mpiled with.** [
bd90: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
bda0: 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 E=1]) the SQLite
bdb0: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 library will it
bdc0: 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 self serialize a
bdd0: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 ccess.** to [dat
bde0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
bdf0: 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 s] and [prepared
be00: 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 statements] so
be10: 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c that the.** appl
be20: 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 ication is free
be30: 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 to use the same
be40: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
be50: 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 tion] or the.**
be60: 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 same [prepared s
be70: 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 tatement] in dif
be80: 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 ferent threads a
be90: 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e t the same time.
bea0: 0a 2a 2a 0a 2a 2a 20 3c 70 3e 54 68 69 73 20 63 .**.** <p>This c
beb0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
bec0: 69 6f 6e 20 6d 65 72 65 6c 79 20 73 65 74 73 20 ion merely sets
bed0: 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 the default mute
bee0: 78 20 0a 2a 2a 20 62 65 68 61 76 69 6f 72 20 74 x .** behavior t
bef0: 6f 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 o serialize acce
bf00: 73 73 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 ss to [database
bf10: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 2e 20 20 49 connections]. I
bf20: 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 5b 64 61 ndividual.** [da
bf30: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
bf40: 6e 73 5d 20 63 61 6e 20 6f 76 65 72 72 69 64 65 ns] can override
bf50: 20 74 68 69 73 20 73 65 74 74 69 6e 67 0a 2a 2a this setting.**
bf60: 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 using the [SQLI
bf70: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d TE_OPEN_NOMUTEX]
bf80: 20 66 6c 61 67 20 74 6f 20 5b 73 71 6c 69 74 65 flag to [sqlite
bf90: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 3c 2f 70 3_open_v2()].</p
bfa0: 3e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 ></dd>.**.** <dt
bfb0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d >SQLITE_CONFIG_M
bfc0: 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ALLOC</dt>.** <d
bfd0: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 d>This option ta
bfe0: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
bff0: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 ument which is a
c000: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a pointer to an.*
c010: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 * instance of th
c020: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d e [sqlite3_mem_m
c030: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 ethods] structur
c040: 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 e. The argument
c050: 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c specifies.** al
c060: 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 ternative low-le
c070: 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 vel memory alloc
c080: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 ation routines t
c090: 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 o be used in pla
c0a0: 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d ce of.** the mem
c0b0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
c0c0: 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e outines built in
c0d0: 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a to SQLite.</dd>.
c0e0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
c0f0: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f _CONFIG_GETMALLO
c100: 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 C</dt>.** <dd>Th
c110: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
c120: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
c130: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 t which is a poi
c140: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e nter to an.** in
c150: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 stance of the [s
c160: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
c170: 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 ds] structure.
c180: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d The [sqlite3_mem
c190: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 _methods].** str
c1a0: 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 ucture is filled
c1b0: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e with the curren
c1c0: 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f tly defined memo
c1d0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f ry allocation ro
c1e0: 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20 utines..** This
c1f0: 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 option can be us
c200: 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 ed to overload t
c210: 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 he default memor
c220: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 y allocation.**
c230: 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 routines with a
c240: 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d wrapper that sim
c250: 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 ulations memory
c260: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 allocation failu
c270: 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 re or.** tracks
c280: 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f memory usage, fo
c290: 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a r example.</dd>.
c2a0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
c2b0: 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 _CONFIG_MEMSTATU
c2c0: 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 S</dt>.** <dd>Th
c2d0: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
c2e0: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
c2f0: 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 of type int, int
c300: 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a erpreted as a .*
c310: 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 * boolean, which
c320: 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 enables or disa
c330: 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 bles the collect
c340: 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c ion of memory al
c350: 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 location .** sta
c360: 74 69 73 74 69 63 73 2e 20 57 68 65 6e 20 64 69 tistics. When di
c370: 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c sabled, the foll
c380: 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 owing SQLite int
c390: 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 0a erfaces become .
c3a0: 2a 2a 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e ** non-operation
c3b0: 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a al:.** <ul>.**
c3c0: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 <li> [sqlite3
c3d0: 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a _memory_used()].
c3e0: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 ** <li> [sqlit
c3f0: 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
c400: 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e ter()].** <li>
c410: 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 [sqlite3_soft_h
c420: 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 eap_limit()].**
c430: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f <li> [sqlite3_
c440: 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c status()].** <
c450: 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a /ul>.** </dd>.**
c460: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
c470: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 ONFIG_SCRATCH</d
c480: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f t>.** <dd>This o
c490: 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 ption specifies
c4a0: 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 a static memory
c4b0: 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 buffer that SQLi
c4c0: 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a te can use for.*
c4d0: 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 * scratch memory
c4e0: 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72 . There are thr
c4f0: 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 ee arguments: A
c500: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
c510: 6d 65 6d 6f 72 79 2c 20 74 68 65 0a 2a 2a 20 73 memory, the.** s
c520: 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 ize of each scra
c530: 74 63 68 20 62 75 66 66 65 72 20 28 73 7a 29 2c tch buffer (sz),
c540: 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 and the number
c550: 6f 66 20 62 75 66 66 65 72 73 20 28 4e 29 2e 20 of buffers (N).
c560: 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d The sz.** argum
c570: 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 ent must be a mu
c580: 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 20 54 68 ltiple of 16. Th
c590: 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 73 e sz parameter s
c5a0: 68 6f 75 6c 64 20 62 65 20 61 20 66 65 77 20 62 hould be a few b
c5b0: 79 74 65 73 0a 2a 2a 20 6c 61 72 67 65 72 20 74 ytes.** larger t
c5c0: 68 61 6e 20 74 68 65 20 61 63 74 75 61 6c 20 73 han the actual s
c5d0: 63 72 61 74 63 68 20 73 70 61 63 65 20 72 65 71 cratch space req
c5e0: 75 69 72 65 64 20 64 75 65 20 69 6e 74 65 72 6e uired due intern
c5f0: 61 6c 20 6f 76 65 72 68 65 61 64 2e 0a 2a 2a 20 al overhead..**
c600: 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 The first.** arg
c610: 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 ument should poi
c620: 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 nt to an allocat
c630: 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 ion of at least
c640: 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 sz*N bytes of me
c650: 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 mory..** SQLite
c660: 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 will use no more
c670: 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 than one scratc
c680: 68 20 62 75 66 66 65 72 20 61 74 20 6f 6e 63 65 h buffer at once
c690: 20 70 65 72 20 74 68 72 65 61 64 2c 20 73 6f 0a per thread, so.
c6a0: 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 ** N should be s
c6b0: 65 74 20 74 6f 20 74 68 65 20 65 78 70 65 63 74 et to the expect
c6c0: 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 ed maximum numbe
c6d0: 72 20 6f 66 20 74 68 72 65 61 64 73 2e 20 20 54 r of threads. T
c6e0: 68 65 20 73 7a 0a 2a 2a 20 70 61 72 61 6d 65 74 he sz.** paramet
c6f0: 65 72 20 73 68 6f 75 6c 64 20 62 65 20 36 20 74 er should be 6 t
c700: 69 6d 65 73 20 74 68 65 20 73 69 7a 65 20 6f 66 imes the size of
c710: 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 the largest dat
c720: 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e abase page size.
c730: 0a 2a 2a 20 53 63 72 61 74 63 68 20 62 75 66 66 .** Scratch buff
c740: 65 72 73 20 61 72 65 20 75 73 65 64 20 61 73 20 ers are used as
c750: 70 61 72 74 20 6f 66 20 74 68 65 20 62 74 72 65 part of the btre
c760: 65 20 62 61 6c 61 6e 63 65 20 6f 70 65 72 61 74 e balance operat
c770: 69 6f 6e 2e 20 20 49 66 0a 2a 2a 20 54 68 65 20 ion. If.** The
c780: 62 74 72 65 65 20 62 61 6c 61 6e 63 65 72 20 6e btree balancer n
c790: 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 20 eeds additional
c7a0: 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 memory beyond wh
c7b0: 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 at is provided b
c7c0: 79 0a 2a 2a 20 73 63 72 61 74 63 68 20 62 75 66 y.** scratch buf
c7d0: 66 65 72 73 20 6f 72 20 69 66 20 6e 6f 20 73 63 fers or if no sc
c7e0: 72 61 74 63 68 20 62 75 66 66 65 72 20 73 70 61 ratch buffer spa
c7f0: 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64 2c ce is specified,
c800: 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 then SQLite.**
c810: 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 goes to [sqlite3
c820: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 74 6f 20 6f 62 _malloc()] to ob
c830: 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 tain the memory
c840: 69 74 20 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a 2a it needs.</dd>.*
c850: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
c860: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
c870: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 </dt>.** <dd>Thi
c880: 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 s option specifi
c890: 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f es a static memo
c8a0: 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 ry buffer that S
c8b0: 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f QLite can use fo
c8c0: 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 r.** the databas
c8d0: 65 20 70 61 67 65 20 63 61 63 68 65 2e 20 20 54 e page cache. T
c8e0: 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 here are three a
c8f0: 72 67 75 6d 65 6e 74 73 3a 20 41 20 70 6f 69 6e rguments: A poin
c900: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 6d 65 ter to the.** me
c910: 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f mory, the size o
c920: 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66 f each page buff
c930: 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 er (sz), and the
c940: 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 number of pages
c950: 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 (N)..** The sz
c960: 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 argument must be
c970: 20 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 a power of two
c980: 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 between 512 and
c990: 33 32 37 36 38 2e 20 20 54 68 65 20 66 69 72 73 32768. The firs
c9a0: 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 t.** argument sh
c9b0: 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e ould point to an
c9c0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 allocation of a
c9d0: 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 t least sz*N byt
c9e0: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a es of memory..**
c9f0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 SQLite will use
ca00: 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 the memory prov
ca10: 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73 ided by the firs
ca20: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 t argument to sa
ca30: 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d tisfy its.** mem
ca40: 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 ory needs for th
ca50: 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 e first N pages
ca60: 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 that it adds to
ca70: 63 61 63 68 65 2e 20 20 49 66 20 61 64 64 69 74 cache. If addit
ca80: 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 ional.** page ca
ca90: 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 che memory is ne
caa0: 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 eded beyond what
cab0: 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 is provided by
cac0: 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 this option, the
cad0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 n.** SQLite goes
cae0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c to [sqlite3_mal
caf0: 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 loc()] for the a
cb00: 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 dditional storag
cb10: 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 e space..** The
cb20: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d implementation m
cb30: 69 67 68 74 20 75 73 65 20 6f 6e 65 20 6f 72 20 ight use one or
cb40: 6d 6f 72 65 20 6f 66 20 74 68 65 20 4e 20 62 75 more of the N bu
cb50: 66 66 65 72 73 20 74 6f 20 68 6f 6c 64 20 0a 2a ffers to hold .*
cb60: 2a 20 6d 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 * memory account
cb70: 69 6e 67 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e ing information.
cb80: 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 </dd>.**.** <dt
cb90: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 >SQLITE_CONFIG_H
cba0: 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e EAP</dt>.** <dd>
cbb0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 This option spec
cbc0: 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d ifies a static m
cbd0: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 emory buffer tha
cbe0: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 t SQLite will us
cbf0: 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 e.** for all of
cc00: 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f its dynamic memo
cc10: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 ry allocation ne
cc20: 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 eds beyond those
cc30: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 provided.** for
cc40: 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 by [SQLITE_CONF
cc50: 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 IG_SCRATCH] and
cc60: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 [SQLITE_CONFIG_P
cc70: 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 AGECACHE]..** Th
cc80: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 ere are three ar
cc90: 67 75 6d 65 6e 74 73 3a 20 41 20 70 6f 69 6e 74 guments: A point
cca0: 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 er to the memory
ccb0: 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a , the number of.
ccc0: 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 ** bytes in the
ccd0: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 memory buffer, a
cce0: 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 nd the minimum a
ccf0: 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 20 llocation size.
cd00: 20 49 66 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 If.** the first
cd10: 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 pointer (the me
cd20: 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 mory pointer) is
cd30: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 NULL, then SQLi
cd40: 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f te reverts.** to
cd50: 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 using its defau
cd60: 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 lt memory alloca
cd70: 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 tor (the system
cd80: 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 malloc() impleme
cd90: 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 ntation),.** und
cda0: 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 oing any prior i
cdb0: 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 nvocation of [SQ
cdc0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c LITE_CONFIG_MALL
cdd0: 4f 43 5d 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 OC]. If the.**
cde0: 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 memory pointer i
cdf0: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 s not NULL and e
ce00: 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e ither [SQLITE_EN
ce10: 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 ABLE_MEMSYS3] or
ce20: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 .** [SQLITE_ENAB
ce30: 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 LE_MEMSYS5] are
ce40: 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 defined, then th
ce50: 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 e alternative me
ce60: 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f mory.** allocato
ce70: 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 r is engaged to
ce80: 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 handle all of SQ
ce90: 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c Lites memory all
cea0: 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 3c 2f ocation needs.</
ceb0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
cec0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 LITE_CONFIG_MUTE
ced0: 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 X</dt>.** <dd>Th
cee0: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
cef0: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
cf00: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 t which is a poi
cf10: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e nter to an.** in
cf20: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 stance of the [s
cf30: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
cf40: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e hods] structure.
cf50: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 The argument s
cf60: 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 pecifies.** alte
cf70: 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 rnative low-leve
cf80: 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 l mutex routines
cf90: 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 to be used in p
cfa0: 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 lace.** the mute
cfb0: 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 x routines built
cfc0: 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 into SQLite.</d
cfd0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
cfe0: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 ITE_CONFIG_GETMU
cff0: 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TEX</dt>.** <dd>
d000: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
d010: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
d020: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 ent which is a p
d030: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 ointer to an.**
d040: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
d050: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d [sqlite3_mutex_m
d060: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 ethods] structur
d070: 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 e. The.** [sqli
d080: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 te3_mutex_method
d090: 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 s].** structure
d0a0: 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 is filled with t
d0b0: 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 he currently def
d0c0: 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 ined mutex routi
d0d0: 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 nes..** This opt
d0e0: 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 ion can be used
d0f0: 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 to overload the
d100: 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c default mutex al
d110: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 location.** rout
d120: 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 ines with a wrap
d130: 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 per used to trac
d140: 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f k mutex usage fo
d150: 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a r performance.**
d160: 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 profiling or te
d170: 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 sting, for examp
d180: 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c le.</dd>.**.** <
d190: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
d1a0: 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a _LOOKASIDE</dt>.
d1b0: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 ** <dd>This opti
d1c0: 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 on takes two arg
d1d0: 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 uments that dete
d1e0: 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c rmine the defaul
d1f0: 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 63 t.** memory allc
d200: 61 74 69 6f 6e 20 6c 6f 6f 6b 61 73 69 64 65 20 ation lookaside
d210: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e 20 20 54 optimization. T
d220: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
d230: 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 t is the.** size
d240: 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 of each lookasi
d250: 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 de buffer slot a
d260: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 nd the second is
d270: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a the number of.*
d280: 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 * slots allocate
d290: 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 d to each databa
d2a0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 3c 2f se connection.</
d2b0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a dd>.**.** </dl>.
d2c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
d2d0: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
d2e0: 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c HREAD 1 /* nil
d2f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
d300: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 TE_CONFIG_MULTIT
d310: 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 HREAD 2 /* ni
d320: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c l */.#define SQL
d330: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 ITE_CONFIG_SERIA
d340: 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e LIZED 3 /* n
d350: 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 il */.#define SQ
d360: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c LITE_CONFIG_MALL
d370: 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 OC 4 /*
d380: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
d390: 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ods* */.#define
d3a0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
d3b0: 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f TMALLOC 5 /
d3c0: 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 * sqlite3_mem_me
d3d0: 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e thods* */.#defin
d3e0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
d3f0: 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 SCRATCH 6
d400: 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 /* void*, int s
d410: 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 z, int N */.#def
d420: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
d430: 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 G_PAGECACHE
d440: 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 7 /* void*, int
d450: 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 sz, int N */.#d
d460: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
d470: 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 FIG_HEAP
d480: 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 8 /* void*, i
d490: 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 nt nByte, int mi
d4a0: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c n */.#define SQL
d4b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 ITE_CONFIG_MEMST
d4c0: 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 ATUS 9 /* b
d4d0: 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e oolean */.#defin
d4e0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
d4f0: 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 MUTEX 10
d500: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 /* sqlite3_mute
d510: 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 x_methods* */.#d
d520: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
d530: 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 FIG_GETMUTEX
d540: 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 11 /* sqlite3_
d550: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a mutex_methods* *
d560: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
d570: 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c _CONFIG_CHUNKALL
d580: 4f 43 20 20 20 31 32 20 20 2f 2a 20 69 6e 74 20 OC 12 /* int
d590: 74 68 72 65 73 68 6f 6c 64 20 2a 2f 0a 23 64 65 threshold */.#de
d5a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
d5b0: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 IG_LOOKASIDE
d5c0: 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 13 /* int int *
d5d0: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
d5e0: 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e F: Configuration
d5f0: 20 4f 70 74 69 6f 6e 73 20 7b 48 31 30 31 37 30 Options {H10170
d600: 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 } <S20000>.** EX
d610: 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a PERIMENTAL.**.**
d620: 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 These constants
d630: 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 are the availab
d640: 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 le integer confi
d650: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 guration options
d660: 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 that.** can be
d670: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 passed as the se
d680: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
d690: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 the [sqlite3_db
d6a0: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 _config()] inter
d6b0: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 face..**.** New
d6c0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
d6d0: 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 tions may be add
d6e0: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c ed in future rel
d6f0: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e eases of SQLite.
d700: 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e .** Existing con
d710: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
d720: 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 ns might be disc
d730: 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 ontinued. Appli
d740: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c cations.** shoul
d750: 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 d check the retu
d760: 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 rn code from [sq
d770: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
d780: 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 )] to make sure
d790: 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c that.** the call
d7a0: 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 worked. The [s
d7b0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
d7c0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 ()] interface wi
d7d0: 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e ll return a.** n
d7e0: 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 on-zero [error c
d7f0: 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e ode] if a discon
d800: 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 tinued or unsupp
d810: 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 orted configurat
d820: 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 ion option.** is
d830: 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 invoked..**.**
d840: 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 <dl>.** <dt>SQLI
d850: 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
d860: 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ASIDE</dt>.** <d
d870: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 d>This option ta
d880: 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69 kes three additi
d890: 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 onal arguments t
d8a0: 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 hat determine th
d8b0: 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 e .** [lookaside
d8c0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
d8d0: 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e r] configuration
d8e0: 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 for the [databa
d8f0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a se connection]..
d900: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 ** The first arg
d910: 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 ument (the third
d920: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 parameter to [s
d930: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
d940: 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e ()] is a.** poin
d950: 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 ter to a memory
d960: 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f buffer to use fo
d970: 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f r lookaside memo
d980: 72 79 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a ry. The first.*
d990: 2a 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 * argument may b
d9a0: 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 e NULL in which
d9b0: 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c case SQLite will
d9c0: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 6c 6f allocate the lo
d9d0: 6f 6b 61 73 69 64 65 0a 2a 2a 20 62 75 66 66 65 okaside.** buffe
d9e0: 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b r itself using [
d9f0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
da00: 5d 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 ]. The second a
da10: 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a rgument is the.*
da20: 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c * size of each l
da30: 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 ookaside buffer
da40: 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 74 68 69 slot and the thi
da50: 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 rd argument is t
da60: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 he number of.**
da70: 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 slots. The size
da80: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69 of the buffer i
da90: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 n the first argu
daa0: 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 ment must be gre
dab0: 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 ater than.** or
dac0: 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f equal to the pro
dad0: 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f duct of the seco
dae0: 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 nd and third arg
daf0: 75 6d 65 6e 74 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a uments.</dd>.**.
db00: 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 ** </dl>.*/.#def
db10: 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e ine SQLITE_DBCON
db20: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 FIG_LOOKASIDE
db30: 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 1001 /* void*
db40: 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a int int */.../*.
db50: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 ** CAPI3REF: Ena
db60: 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 ble Or Disable E
db70: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 xtended Result C
db80: 6f 64 65 73 20 7b 48 31 32 32 30 30 7d 20 3c 53 odes {H12200} <S
db90: 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 10700>.**.** The
dba0: 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 sqlite3_extende
dbb0: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 d_result_codes()
dbc0: 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 routine enables
dbd0: 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 or disables the
dbe0: 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 .** [extended re
dbf0: 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 sult codes] feat
dc00: 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 54 ure of SQLite. T
dc10: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 he extended resu
dc20: 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 lt.** codes are
dc30: 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 disabled by defa
dc40: 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 ult for historic
dc50: 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 al compatibility
dc60: 20 63 6f 6e 73 69 64 65 72 61 74 69 6f 6e 73 2e considerations.
dc70: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
dc80: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 30 31 S:.**.** {H12201
dc90: 7d 20 45 61 63 68 20 6e 65 77 20 5b 64 61 74 61 } Each new [data
dca0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
dcb0: 20 73 68 61 6c 6c 20 68 61 76 65 20 74 68 65 0a shall have the.
dcc0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 65 78 74 ** [ext
dcd0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
dce0: 65 73 5d 20 66 65 61 74 75 72 65 20 64 69 73 61 es] feature disa
dcf0: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e bled by default.
dd00: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 30 32 7d 20 .**.** {H12202}
dd10: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 The [sqlite3_ext
dd20: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 ended_result_cod
dd30: 65 73 28 44 2c 46 29 5d 20 69 6e 74 65 72 66 61 es(D,F)] interfa
dd40: 63 65 20 73 68 61 6c 6c 20 65 6e 61 62 6c 65 0a ce shall enable.
dd50: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 65 78 74 ** [ext
dd60: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
dd70: 65 73 5d 20 66 6f 72 20 74 68 65 20 20 5b 64 61 es] for the [da
dd80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
dd90: 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 n] D.**
dda0: 20 69 66 20 74 68 65 20 46 20 70 61 72 61 6d 65 if the F parame
ddb0: 74 65 72 20 69 73 20 74 72 75 65 2c 20 6f 72 20 ter is true, or
ddc0: 64 69 73 61 62 6c 65 20 74 68 65 6d 20 69 66 20 disable them if
ddd0: 46 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2f 0a 69 F is false..*/.i
dde0: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e nt sqlite3_exten
ddf0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 ded_result_codes
de00: 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f (sqlite3*, int o
de10: 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 noff);../*.** CA
de20: 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 PI3REF: Last Ins
de30: 65 72 74 20 52 6f 77 69 64 20 7b 48 31 32 32 32 ert Rowid {H1222
de40: 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 0} <S10700>.**.*
de50: 2a 20 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 * Each entry in
de60: 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 an SQLite table
de70: 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d has a unique 64-
de80: 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e bit signed.** in
de90: 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 teger key called
dea0: 20 74 68 65 20 22 72 6f 77 69 64 22 2e 20 54 68 the "rowid". Th
deb0: 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 e rowid is alway
dec0: 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 s available.** a
ded0: 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 s an undeclared
dee0: 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 column named ROW
def0: 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 ID, OID, or _ROW
df00: 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 ID_ as long as t
df10: 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 hose.** names ar
df20: 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 e not also used
df30: 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 by explicitly de
df40: 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 clared columns.
df50: 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 If.** the table
df60: 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 has a column of
df70: 74 79 70 65 20 49 4e 54 45 47 45 52 20 50 52 49 type INTEGER PRI
df80: 4d 41 52 59 20 4b 45 59 20 74 68 65 6e 20 74 68 MARY KEY then th
df90: 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 at column.** is
dfa0: 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f another alias fo
dfb0: 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a r the rowid..**.
dfc0: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
dfd0: 72 65 74 75 72 6e 73 20 74 68 65 20 72 6f 77 69 returns the rowi
dfe0: 64 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 d of the most re
dff0: 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 cent.** successf
e000: 75 6c 20 49 4e 53 45 52 54 20 69 6e 74 6f 20 74 ul INSERT into t
e010: 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d he database from
e020: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
e030: 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e onnection].** in
e040: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
e050: 65 6e 74 2e 20 20 49 66 20 6e 6f 20 73 75 63 63 ent. If no succ
e060: 65 73 73 66 75 6c 20 49 4e 53 45 52 54 73 0a 2a essful INSERTs.*
e070: 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 * have ever occu
e080: 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 rred on that dat
e090: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
e0a0: 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e , zero is return
e0b0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 ed..**.** If an
e0c0: 49 4e 53 45 52 54 20 6f 63 63 75 72 73 20 77 69 INSERT occurs wi
e0d0: 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 thin a trigger,
e0e0: 74 68 65 6e 20 74 68 65 20 72 6f 77 69 64 20 6f then the rowid o
e0f0: 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a f the inserted.*
e100: 2a 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65 * row is returne
e110: 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e d by this routin
e120: 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 e as long as the
e130: 20 74 72 69 67 67 65 72 20 69 73 20 72 75 6e 6e trigger is runn
e140: 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 ing..** But once
e150: 20 74 68 65 20 74 72 69 67 67 65 72 20 74 65 72 the trigger ter
e160: 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c minates, the val
e170: 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 ue returned by t
e180: 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 his routine.** r
e190: 65 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 everts to the la
e1a0: 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 st value inserte
e1b0: 64 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 d before the tri
e1c0: 67 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a gger fired..**.*
e1d0: 2a 20 41 6e 20 49 4e 53 45 52 54 20 74 68 61 74 * An INSERT that
e1e0: 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 fails due to a
e1f0: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 constraint viola
e200: 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a tion is not a.**
e210: 20 73 75 63 63 65 73 73 66 75 6c 20 49 4e 53 45 successful INSE
e220: 52 54 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 RT and does not
e230: 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 change the value
e240: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 returned by thi
e250: 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54 s.** routine. T
e260: 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 hus INSERT OR FA
e270: 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 IL, INSERT OR IG
e280: 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 NORE, INSERT OR
e290: 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 ROLLBACK,.** and
e2a0: 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 INSERT OR ABORT
e2b0: 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 make no changes
e2c0: 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 to the return v
e2d0: 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 alue of this.**
e2e0: 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 routine when the
e2f0: 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 ir insertion fai
e300: 6c 73 2e 20 20 57 68 65 6e 20 49 4e 53 45 52 54 ls. When INSERT
e310: 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 OR REPLACE.** e
e320: 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 ncounters a cons
e330: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e traint violation
e340: 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 , it does not fa
e350: 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 il. The.** INSE
e360: 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 RT continues to
e370: 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 completion after
e380: 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 deleting rows t
e390: 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 hat caused.** th
e3a0: 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f e constraint pro
e3b0: 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f blem so INSERT O
e3c0: 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 R REPLACE will a
e3d0: 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 lways change.**
e3e0: 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
e3f0: 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 of this interfa
e400: 63 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 ce..**.** For th
e410: 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 e purposes of th
e420: 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 49 is routine, an I
e430: 4e 53 45 52 54 20 69 73 20 63 6f 6e 73 69 64 65 NSERT is conside
e440: 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 red to.** be suc
e450: 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 cessful even if
e460: 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 it is subsequent
e470: 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a ly rolled back..
e480: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
e490: 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 32 31 7d :.**.** {H12221}
e4a0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 The [sqlite3_la
e4b0: 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 st_insert_rowid(
e4c0: 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 )] function retu
e4d0: 72 6e 73 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a rns the rowid.**
e4e0: 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 of the
e4f0: 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63 most recent suc
e500: 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54 20 70 cessful INSERT p
e510: 65 72 66 6f 72 6d 65 64 20 6f 6e 20 74 68 65 20 erformed on the
e520: 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 same.**
e530: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
e540: 63 74 69 6f 6e 5d 20 61 6e 64 20 77 69 74 68 69 ction] and withi
e550: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 20 68 69 n the same or hi
e560: 67 68 65 72 20 6c 65 76 65 6c 0a 2a 2a 20 20 20 gher level.**
e570: 20 20 20 20 20 20 20 74 72 69 67 67 65 72 20 63 trigger c
e580: 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20 ontext, or zero
e590: 69 66 20 74 68 65 72 65 20 68 61 76 65 20 62 65 if there have be
e5a0: 65 6e 20 6e 6f 20 71 75 61 6c 69 66 79 69 6e 67 en no qualifying
e5b0: 20 69 6e 73 65 72 74 73 2e 0a 2a 2a 0a 2a 2a 20 inserts..**.**
e5c0: 7b 48 31 32 32 32 33 7d 20 54 68 65 20 5b 73 71 {H12223} The [sq
e5d0: 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 lite3_last_inser
e5e0: 74 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 74 t_rowid()] funct
e5f0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a ion returns the.
e600: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 61 6d 65 ** same
e610: 20 76 61 6c 75 65 20 77 68 65 6e 20 63 61 6c 6c value when call
e620: 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 ed from the same
e630: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 trigger context
e640: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6d 6d .** imm
e650: 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20 ediately before
e660: 61 6e 64 20 61 66 74 65 72 20 61 20 52 4f 4c 4c and after a ROLL
e670: 42 41 43 4b 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 BACK..**.** ASSU
e680: 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b MPTIONS:.**.** {
e690: 41 31 32 32 33 32 7d 20 49 66 20 61 20 73 65 70 A12232} If a sep
e6a0: 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 arate thread per
e6b0: 66 6f 72 6d 73 20 61 20 6e 65 77 20 49 4e 53 45 forms a new INSE
e6c0: 52 54 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a RT on the same.*
e6d0: 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62 * datab
e6e0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 ase connection w
e6f0: 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 hile the [sqlite
e700: 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 3_last_insert_ro
e710: 77 69 64 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 wid()].**
e720: 20 20 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 function is r
e730: 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 unning and thus
e740: 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 changes the last
e750: 20 69 6e 73 65 72 74 20 72 6f 77 69 64 2c 0a 2a insert rowid,.*
e760: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 * then
e770: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
e780: 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c ed by [sqlite3_l
e790: 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 ast_insert_rowid
e7a0: 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 ()] is.**
e7b0: 20 20 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 unpredictable
e7c0: 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 and might not e
e7d0: 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 qual either the
e7e0: 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a old or the new.*
e7f0: 2a 20 20 20 20 20 20 20 20 20 20 6c 61 73 74 20 * last
e800: 69 6e 73 65 72 74 20 72 6f 77 69 64 2e 0a 2a 2f insert rowid..*/
e810: 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 .sqlite3_int64 s
e820: 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 qlite3_last_inse
e830: 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 rt_rowid(sqlite3
e840: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
e850: 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e REF: Count The N
e860: 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f umber Of Rows Mo
e870: 64 69 66 69 65 64 20 7b 48 31 32 32 34 30 7d 20 dified {H12240}
e880: 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S10600>.**.** T
e890: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 his function ret
e8a0: 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
e8b0: 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 of database rows
e8c0: 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 that were chang
e8d0: 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 ed.** or inserte
e8e0: 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 d or deleted by
e8f0: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c the most recentl
e900: 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 y completed SQL
e910: 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 statement.** on
e920: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
e930: 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 nnection] specif
e940: 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 ied by the first
e950: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 4f parameter..** O
e960: 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 nly changes that
e970: 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 are directly sp
e980: 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 49 ecified by the I
e990: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 0a 2a NSERT, UPDATE,.*
e9a0: 2a 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 * or DELETE stat
e9b0: 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 ement are counte
e9c0: 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 d. Auxiliary ch
e9d0: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a anges caused by.
e9e0: 2a 2a 20 74 72 69 67 67 65 72 73 20 61 72 65 20 ** triggers are
e9f0: 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 55 73 65 not counted. Use
ea00: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f the [sqlite3_to
ea10: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 tal_changes()] f
ea20: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69 unction.** to fi
ea30: 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d nd the total num
ea40: 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 ber of changes i
ea50: 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 ncluding changes
ea60: 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67 caused by trigg
ea70: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 72 6f ers..**.** A "ro
ea80: 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 w change" is a c
ea90: 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c hange to a singl
eaa0: 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c e row of a singl
eab0: 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 e table.** cause
eac0: 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 d by an INSERT,
ead0: 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 DELETE, or UPDAT
eae0: 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f E statement. Ro
eaf0: 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 ws that.** are c
eb00: 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 hanged as side e
eb10: 66 66 65 63 74 73 20 6f 66 20 52 45 50 4c 41 43 ffects of REPLAC
eb20: 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 E constraint res
eb30: 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c olution,.** roll
eb40: 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 back, ABORT proc
eb50: 65 73 73 69 6e 67 2c 20 44 52 4f 50 20 54 41 42 essing, DROP TAB
eb60: 4c 45 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 LE, or by any ot
eb70: 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d her.** mechanism
eb80: 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 s do not count a
eb90: 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 s direct row cha
eba0: 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 nges..**.** A "t
ebb0: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 rigger context"
ebc0: 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 is a scope of ex
ebd0: 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 ecution that beg
ebe0: 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 ins and.** ends
ebf0: 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20 with the script
ec00: 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20 20 4d of a trigger. M
ec10: 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ost SQL statemen
ec20: 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 ts are.** evalua
ec30: 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61 ted outside of a
ec40: 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69 ny trigger. Thi
ec50: 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65 s is the "top le
ec60: 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 vel".** trigger
ec70: 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74 context. If a t
ec80: 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f rigger fires fro
ec90: 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c m the top level,
eca0: 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 a.** new trigge
ecb0: 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 r context is ent
ecc0: 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72 ered for the dur
ecd0: 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e ation of that on
ece0: 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53 e.** trigger. S
ecf0: 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74 ubtriggers creat
ed00: 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f e subcontexts fo
ed10: 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e r their duration
ed20: 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 ..**.** Calling
ed30: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
ed40: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 or [sqlite3_ste
ed50: 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79 p()] recursively
ed60: 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 does.** not cre
ed70: 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65 ate a new trigge
ed80: 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a r context..**.**
ed90: 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 This function r
eda0: 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
edb0: 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 r of direct row
edc0: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a changes in the.*
edd0: 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e * most recent IN
ede0: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 SERT, UPDATE, or
edf0: 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e DELETE statemen
ee00: 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d t within the sam
ee10: 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e e.** trigger con
ee20: 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 75 73 text..**.** Thus
ee30: 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 , when called fr
ee40: 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c om the top level
ee50: 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 , this function
ee60: 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e returns the.** n
ee70: 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 umber of changes
ee80: 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 in the most rec
ee90: 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 ent INSERT, UPDA
eea0: 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a TE, or DELETE.**
eeb0: 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 that also occur
eec0: 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c red at the top l
eed0: 65 76 65 6c 2e 20 20 57 69 74 68 69 6e 20 74 68 evel. Within th
eee0: 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 e body of a trig
eef0: 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 ger,.** the sqli
ef00: 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e te3_changes() in
ef10: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 terface can be c
ef20: 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 alled to find th
ef30: 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 e number of.** c
ef40: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f hanges in the mo
ef50: 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 st recently comp
ef60: 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 leted INSERT, UP
ef70: 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a DATE, or DELETE.
ef80: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 ** statement wit
ef90: 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 hin the body of
efa0: 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 the same trigger
efb0: 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 ..** However, th
efc0: 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 e number returne
efd0: 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 d does not inclu
efe0: 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 de changes.** ca
eff0: 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67 used by subtrigg
f000: 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 ers since those
f010: 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 have their own c
f020: 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 ontext..**.** SQ
f030: 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 Lite implements
f040: 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c the command "DEL
f050: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 ETE FROM table"
f060: 77 69 74 68 6f 75 74 20 61 20 57 48 45 52 45 20 without a WHERE
f070: 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f clause.** by dro
f080: 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61 pping and recrea
f090: 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20 ting the table.
f0a0: 20 28 54 68 69 73 20 69 73 20 6d 75 63 68 20 66 (This is much f
f0b0: 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 aster than going
f0c0: 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20 .** through and
f0d0: 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64 deleting individ
f0e0: 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f ual elements fro
f0f0: 6d 20 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42 m the table.) B
f100: 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 0a 2a ecause of this.*
f110: 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 * optimization,
f120: 74 68 65 20 64 65 6c 65 74 69 6f 6e 73 20 69 6e the deletions in
f130: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 "DELETE FROM ta
f140: 62 6c 65 22 20 61 72 65 20 6e 6f 74 20 72 6f 77 ble" are not row
f150: 20 63 68 61 6e 67 65 73 20 61 6e 64 0a 2a 2a 20 changes and.**
f160: 77 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f 75 6e will not be coun
f170: 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 ted by the sqlit
f180: 65 33 5f 63 68 61 6e 67 65 73 28 29 20 6f 72 20 e3_changes() or
f190: 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 [sqlite3_total_c
f1a0: 68 61 6e 67 65 73 28 29 5d 0a 2a 2a 20 66 75 6e hanges()].** fun
f1b0: 63 74 69 6f 6e 73 2c 20 72 65 67 61 72 64 6c 65 ctions, regardle
f1c0: 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 ss of the number
f1d0: 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 of elements tha
f1e0: 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c t were originall
f1f0: 79 0a 2a 2a 20 69 6e 20 74 68 65 20 74 61 62 6c y.** in the tabl
f200: 65 2e 20 20 54 6f 20 67 65 74 20 61 6e 20 61 63 e. To get an ac
f210: 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 curate count of
f220: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f the number of ro
f230: 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a ws deleted, use.
f240: 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 ** "DELETE FROM
f250: 74 61 62 6c 65 20 57 48 45 52 45 20 31 22 20 69 table WHERE 1" i
f260: 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e nstead..**.** IN
f270: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
f280: 7b 48 31 32 32 34 31 7d 20 54 68 65 20 5b 73 71 {H12241} The [sq
f290: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d lite3_changes()]
f2a0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 function shall
f2b0: 72 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 return the numbe
f2c0: 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 r of.**
f2d0: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 row changes cau
f2e0: 73 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 sed by the most
f2f0: 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 recent INSERT, U
f300: 50 44 41 54 45 2c 0a 2a 2a 20 20 20 20 20 20 20 PDATE,.**
f310: 20 20 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 or DELETE sta
f320: 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 73 61 tement on the sa
f330: 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e me database conn
f340: 65 63 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 ection and.**
f350: 20 20 20 20 20 20 20 77 69 74 68 69 6e 20 74 68 within th
f360: 65 20 73 61 6d 65 20 6f 72 20 68 69 67 68 65 72 e same or higher
f370: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 trigger context
f380: 2c 20 6f 72 20 7a 65 72 6f 20 69 66 20 74 68 65 , or zero if the
f390: 72 65 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 re have.**
f3a0: 20 20 20 20 6e 6f 74 20 62 65 65 6e 20 61 6e 79 not been any
f3b0: 20 71 75 61 6c 69 66 79 69 6e 67 20 72 6f 77 20 qualifying row
f3c0: 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b changes..**.** {
f3d0: 48 31 32 32 34 33 7d 20 53 74 61 74 65 6d 65 6e H12243} Statemen
f3e0: 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 ts of the form "
f3f0: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c DELETE FROM tabl
f400: 65 6e 61 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a ename" with no.*
f410: 2a 20 20 20 20 20 20 20 20 20 20 57 48 45 52 45 * WHERE
f420: 20 63 6c 61 75 73 65 20 73 68 61 6c 6c 20 63 61 clause shall ca
f430: 75 73 65 20 73 75 62 73 65 71 75 65 6e 74 20 63 use subsequent c
f440: 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 alls to.**
f450: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 [sqlite3_cha
f460: 6e 67 65 73 28 29 5d 20 74 6f 20 72 65 74 75 72 nges()] to retur
f470: 6e 20 7a 65 72 6f 2c 20 72 65 67 61 72 64 6c 65 n zero, regardle
f480: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 ss of the.**
f490: 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 number of
f4a0: 72 6f 77 73 20 6f 72 69 67 69 6e 61 6c 6c 79 20 rows originally
f4b0: 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 0a 2a 2a in the table..**
f4c0: 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a .** ASSUMPTIONS:
f4d0: 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 35 32 7d 20 .**.** {A12252}
f4e0: 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 If a separate th
f4f0: 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 read makes chang
f500: 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 es on the same d
f510: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
f520: 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 on.** w
f530: 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 hile [sqlite3_ch
f540: 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e anges()] is runn
f550: 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c ing then the val
f560: 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 ue returned.**
f570: 20 20 20 20 20 20 20 20 69 73 20 75 6e 70 72 65 is unpre
f580: 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 dictable and not
f590: 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a meaningful..*/.
f5a0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e int sqlite3_chan
f5b0: 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a ges(sqlite3*);..
f5c0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
f5d0: 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 Total Number Of
f5e0: 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 48 Rows Modified {H
f5f0: 31 32 32 36 30 7d 20 3c 53 31 30 36 30 30 3e 0a 12260} <S10600>.
f600: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 **.** This funct
f610: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 ion returns the
f620: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 number of row ch
f630: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 anges caused by
f640: 49 4e 53 45 52 54 2c 0a 2a 2a 20 55 50 44 41 54 INSERT,.** UPDAT
f650: 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 E or DELETE stat
f660: 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 ements since the
f670: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
f680: 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 ction] was opene
f690: 64 2e 0a 2a 2a 20 54 68 65 20 63 6f 75 6e 74 20 d..** The count
f6a0: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 includes all cha
f6b0: 6e 67 65 73 20 66 72 6f 6d 20 61 6c 6c 20 74 72 nges from all tr
f6c0: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 73 2e 20 igger contexts.
f6d0: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 However,.** the
f6e0: 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 count does not
f6f0: 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 include changes
f700: 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e used to implemen
f710: 74 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 t REPLACE constr
f720: 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c aints,.** do rol
f730: 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 lbacks or ABORT
f740: 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 44 processing, or D
f750: 52 4f 50 20 74 61 62 6c 65 20 70 72 6f 63 65 73 ROP table proces
f760: 73 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 63 68 61 sing..** The cha
f770: 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 nges are counted
f780: 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 as soon as the
f790: 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d statement that m
f7a0: 61 6b 65 73 20 74 68 65 6d 20 69 73 0a 2a 2a 20 akes them is.**
f7b0: 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 completed (when
f7c0: 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 the statement ha
f7d0: 6e 64 6c 65 20 69 73 20 70 61 73 73 65 64 20 74 ndle is passed t
f7e0: 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 o [sqlite3_reset
f7f0: 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 ()] or.** [sqlit
f800: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e e3_finalize()]).
f810: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d .**.** SQLite im
f820: 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d plements the com
f830: 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f mand "DELETE FRO
f840: 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 M table" without
f850: 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a a WHERE clause.
f860: 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 ** by dropping a
f870: 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 nd recreating th
f880: 65 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20 e table. (This
f890: 69 73 20 6d 75 63 68 20 66 61 73 74 65 72 20 74 is much faster t
f8a0: 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 han going.** thr
f8b0: 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e ough and deletin
f8c0: 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 g individual ele
f8d0: 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74 ments from the t
f8e0: 61 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20 able.) Because
f8f0: 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d of this.** optim
f900: 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c ization, the del
f910: 65 74 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54 etions in "DELET
f920: 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72 E FROM table" ar
f930: 65 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65 e not row change
f940: 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f s and.** will no
f950: 74 20 62 65 20 63 6f 75 6e 74 65 64 20 62 79 20 t be counted by
f960: 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e the sqlite3_chan
f970: 67 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65 ges() or [sqlite
f980: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 3_total_changes(
f990: 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c )].** functions,
f9a0: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 regardless of t
f9b0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 he number of ele
f9c0: 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 20 ments that were
f9d0: 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e originally.** in
f9e0: 20 74 68 65 20 74 61 62 6c 65 2e 20 20 54 6f 20 the table. To
f9f0: 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 get an accurate
fa00: 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d count of the num
fa10: 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 ber of rows dele
fa20: 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c ted, use.** "DEL
fa30: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 ETE FROM table W
fa40: 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e HERE 1" instead.
fa50: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 .**.** See also
fa60: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 the [sqlite3_cha
fa70: 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 nges()] interfac
fa80: 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 e..**.** INVARIA
fa90: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 NTS:.**.** {H122
faa0: 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 61} The [sqlite3
fab0: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 _total_changes()
fac0: 5d 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f ] returns the to
fad0: 74 61 6c 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 tal number.**
fae0: 20 20 20 20 20 20 20 6f 66 20 72 6f 77 20 63 68 of row ch
faf0: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 anges caused by
fb00: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 INSERT, UPDATE,
fb10: 61 6e 64 2f 6f 72 20 44 45 4c 45 54 45 0a 2a 2a and/or DELETE.**
fb20: 20 20 20 20 20 20 20 20 20 20 73 74 61 74 65 6d statem
fb30: 65 6e 74 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 ents on the same
fb40: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
fb50: 63 74 69 6f 6e 5d 2c 20 69 6e 20 61 6e 79 0a 2a ction], in any.*
fb60: 2a 20 20 20 20 20 20 20 20 20 20 74 72 69 67 67 * trigg
fb70: 65 72 20 63 6f 6e 74 65 78 74 2c 20 73 69 6e 63 er context, sinc
fb80: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 e the database c
fb90: 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 63 72 onnection was cr
fba0: 65 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 eated..**.** {H1
fbb0: 32 32 36 33 7d 20 53 74 61 74 65 6d 65 6e 74 73 2263} Statements
fbc0: 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 44 45 of the form "DE
fbd0: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e LETE FROM tablen
fbe0: 61 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 ame" with no.**
fbf0: 20 20 20 20 20 20 20 20 20 57 48 45 52 45 20 63 WHERE c
fc00: 6c 61 75 73 65 20 73 68 61 6c 6c 20 6e 6f 74 20 lause shall not
fc10: 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 change the value
fc20: 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 returned.**
fc30: 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 by [sqlite
fc40: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 3_total_changes(
fc50: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 )]..**.** ASSUMP
fc60: 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 TIONS:.**.** {A1
fc70: 32 32 36 34 7d 20 49 66 20 61 20 73 65 70 61 72 2264} If a separ
fc80: 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 ate thread makes
fc90: 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 changes on the
fca0: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f same database co
fcb0: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 nnection.**
fcc0: 20 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 while [sqli
fcd0: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
fce0: 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 s()] is running
fcf0: 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a then the value.*
fd00: 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 * retur
fd10: 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 ned is unpredict
fd20: 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 able and not mea
fd30: 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 ningful..*/.int
fd40: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
fd50: 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b anges(sqlite3*);
fd60: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
fd70: 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f : Interrupt A Lo
fd80: 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 ng-Running Query
fd90: 20 7b 48 31 32 32 37 30 7d 20 3c 53 33 30 35 30 {H12270} <S3050
fda0: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 0>.**.** This fu
fdb0: 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e nction causes an
fdc0: 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 y pending databa
fdd0: 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 se operation to
fde0: 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 abort and.** ret
fdf0: 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 urn at its earli
fe00: 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e est opportunity.
fe10: 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 This routine is
fe20: 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 typically.** ca
fe30: 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 lled in response
fe40: 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f to a user actio
fe50: 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69 n such as pressi
fe60: 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f ng "Cancel".** o
fe70: 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 r Ctrl-C where t
fe80: 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 he user wants a
fe90: 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 long query opera
fea0: 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 tion to halt.**
feb0: 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a immediately..**.
fec0: 2a 2a 20 49 74 20 69 73 20 73 61 66 65 20 74 6f ** It is safe to
fed0: 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 call this routi
fee0: 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 ne from a thread
fef0: 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 different from
ff00: 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 the.** thread th
ff10: 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 at is currently
ff20: 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 running the data
ff30: 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 base operation.
ff40: 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f But it.** is no
ff50: 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 t safe to call t
ff60: 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 his routine with
ff70: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e a [database con
ff80: 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a nection] that.**
ff90: 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 is closed or mi
ffa0: 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 ght close before
ffb0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
ffc0: 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a pt() returns..**
ffd0: 0a 2a 2a 20 49 66 20 61 6e 20 53 51 4c 20 6f 70 .** If an SQL op
ffe0: 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 eration is very
fff0: 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 nearly finished
10000 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e at the time when
10010 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 .** sqlite3_inte
10020 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 rrupt() is calle
10030 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 d, then it might
10040 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 not have an opp
10050 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 ortunity.** to b
10060 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e e interrupted an
10070 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 d might continue
10080 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a to completion..
10090 2a 2a 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f 70 65 **.** An SQL ope
100a0 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 ration that is i
100b0 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 nterrupted will
100c0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 return [SQLITE_I
100d0 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 49 66 NTERRUPT]..** If
100e0 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 the interrupted
100f0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 SQL operation i
10100 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 s an INSERT, UPD
10110 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a ATE, or DELETE.*
10120 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 * that is inside
10130 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 an explicit tra
10140 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 nsaction, then t
10150 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 he entire transa
10160 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 ction.** will be
10170 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 rolled back aut
10180 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a omatically..**.*
10190 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 * A call to sqli
101a0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 te3_interrupt()
101b0 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e has no effect on
101c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a SQL statements.
101d0 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 ** that are star
101e0 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 ted after sqlite
101f0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 3_interrupt() re
10200 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 turns..**.** INV
10210 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
10220 48 31 32 32 37 31 7d 20 54 68 65 20 5b 73 71 6c H12271} The [sql
10230 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
10240 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c ] interface will
10250 20 66 6f 72 63 65 20 61 6c 6c 20 72 75 6e 6e 69 force all runni
10260 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 ng.** S
10270 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 QL statements as
10280 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 sociated with th
10290 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 e same database
102a0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 connection.**
102b0 20 20 20 20 20 20 20 74 6f 20 68 61 6c 74 20 61 to halt a
102c0 66 74 65 72 20 70 72 6f 63 65 73 73 69 6e 67 20 fter processing
102d0 61 74 20 6d 6f 73 74 20 6f 6e 65 20 61 64 64 69 at most one addi
102e0 74 69 6f 6e 61 6c 20 72 6f 77 20 6f 66 20 64 61 tional row of da
102f0 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 37 ta..**.** {H1227
10300 32 7d 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 2} Any SQL state
10310 6d 65 6e 74 20 74 68 61 74 20 69 73 20 69 6e 74 ment that is int
10320 65 72 72 75 70 74 65 64 20 62 79 20 5b 73 71 6c errupted by [sql
10330 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
10340 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 ].** wi
10350 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ll return [SQLIT
10360 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a E_INTERRUPT]..**
10370 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a .** ASSUMPTIONS:
10380 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 37 39 7d 20 .**.** {A12279}
10390 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 If the database
103a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 connection close
103b0 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 s while [sqlite3
103c0 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a _interrupt()].**
103d0 20 20 20 20 20 20 20 20 20 20 69 73 20 72 75 6e is run
103e0 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 ning then bad th
103f0 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 ings will likely
10400 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 happen..*/.void
10410 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
10420 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f pt(sqlite3*);../
10430 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
10440 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 etermine If An S
10450 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 QL Statement Is
10460 43 6f 6d 70 6c 65 74 65 20 7b 48 31 30 35 31 30 Complete {H10510
10470 7d 20 3c 53 37 30 32 30 30 3e 0a 2a 2a 0a 2a 2a } <S70200>.**.**
10480 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
10490 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 are useful for c
104a0 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 ommand-line inpu
104b0 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 t to determine i
104c0 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 f the.** current
104d0 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 ly entered text
104e0 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 63 6f seems to form co
104f0 6d 70 6c 65 74 65 20 61 20 53 51 4c 20 73 74 61 mplete a SQL sta
10500 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 tement or.** if
10510 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 additional input
10520 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 is needed befor
10530 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 e sending the te
10540 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 xt into.** SQLit
10550 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 e for parsing.
10560 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
10570 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 eturn true if th
10580 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a e input string.*
10590 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 * appears to be
105a0 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 a complete SQL s
105b0 74 61 74 65 6d 65 6e 74 2e 20 20 41 20 73 74 61 tatement. A sta
105c0 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 tement is judged
105d0 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 to be.** comple
105e0 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 te if it ends wi
105f0 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 th a semicolon t
10600 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 oken and is not
10610 61 20 66 72 61 67 6d 65 6e 74 20 6f 66 20 61 0a a fragment of a.
10620 2a 2a 20 43 52 45 41 54 45 20 54 52 49 47 47 45 ** CREATE TRIGGE
10630 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 65 R statement. Se
10640 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 micolons that ar
10650 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 e embedded withi
10660 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 n.** string lite
10670 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 rals or quoted i
10680 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 dentifier names
10690 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 or comments are
106a0 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 not.** independe
106b0 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 nt tokens (they
106c0 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 are part of the
106d0 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 token in which t
106e0 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 hey are.** embed
106f0 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f ded) and thus do
10700 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 not count as a
10710 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e statement termin
10720 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ator..**.** Thes
10730 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f e routines do no
10740 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 t parse the SQL
10750 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a statements thus.
10760 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 ** will not dete
10770 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 ct syntactically
10780 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a incorrect SQL..
10790 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
107a0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 31 31 7d :.**.** {H10511}
107b0 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 A successful ev
107c0 61 6c 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c aluation of [sql
107d0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d ite3_complete()]
107e0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 or.**
107f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 [sqlite3_complet
10800 65 31 36 28 29 5d 20 66 75 6e 63 74 69 6f 6e 73 e16()] functions
10810 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 shall.**
10820 20 20 20 72 65 74 75 72 6e 20 61 20 6e 75 6d 65 return a nume
10830 72 69 63 20 31 20 69 66 20 61 6e 64 20 6f 6e 6c ric 1 if and onl
10840 79 20 69 66 20 74 68 65 20 6c 61 73 74 20 6e 6f y if the last no
10850 6e 2d 77 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 n-whitespace.**
10860 20 20 20 20 20 20 20 20 20 74 6f 6b 65 6e 20 69 token i
10870 6e 20 74 68 65 69 72 20 69 6e 70 75 74 20 69 73 n their input is
10880 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 68 61 a semicolon tha
10890 74 20 69 73 20 6e 6f 74 20 69 6e 20 62 65 74 77 t is not in betw
108a0 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 een.**
108b0 74 68 65 20 42 45 47 49 4e 20 61 6e 64 20 45 4e the BEGIN and EN
108c0 44 20 6f 66 20 61 20 43 52 45 41 54 45 20 54 52 D of a CREATE TR
108d0 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e IGGER statement.
108e0 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 31 32 7d 20 .**.** {H10512}
108f0 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f If a memory allo
10900 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 cation error occ
10910 75 72 73 20 64 75 72 69 6e 67 20 61 6e 20 69 6e urs during an in
10920 76 6f 63 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 vocation.**
10930 20 20 20 20 20 6f 66 20 5b 73 71 6c 69 74 65 33 of [sqlite3
10940 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6f 72 20 _complete()] or
10950 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 [sqlite3_complet
10960 65 31 36 28 29 5d 20 74 68 65 6e 20 74 68 65 0a e16()] then the.
10970 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75 74 ** rout
10980 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e ine shall return
10990 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e [SQLITE_NOMEM].
109a0 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f .**.** ASSUMPTIO
109b0 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31 NS:.**.** {A1051
109c0 32 7d 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 2} The input to
109d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 [sqlite3_complet
109e0 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a e()] must be a z
109f0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a ero-terminated.*
10a00 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 * UTF-8
10a10 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b string..**.** {
10a20 41 31 30 35 31 33 7d 20 54 68 65 20 69 6e 70 75 A10513} The inpu
10a30 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f t to [sqlite3_co
10a40 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 mplete16()] must
10a50 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 be a zero-termi
10a60 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 nated.**
10a70 20 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 UTF-16 string
10a80 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f in native byte o
10a90 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c rder..*/.int sql
10aa0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f ite3_complete(co
10ab0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a nst char *sql);.
10ac0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 int sqlite3_comp
10ad0 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 lete16(const voi
10ae0 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 d *sql);../*.**
10af0 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 CAPI3REF: Regist
10b00 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f er A Callback To
10b10 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 Handle SQLITE_B
10b20 55 53 59 20 45 72 72 6f 72 73 20 7b 48 31 32 33 USY Errors {H123
10b30 31 30 7d 20 3c 53 34 30 34 30 30 3e 0a 2a 2a 0a 10} <S40400>.**.
10b40 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
10b50 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 sets a callback
10b60 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 function that mi
10b70 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 ght be invoked w
10b80 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 henever.** an at
10b90 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f tempt is made to
10ba0 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 open a database
10bb0 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 table that anot
10bc0 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 her thread.** or
10bd0 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 process has loc
10be0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ked..**.** If th
10bf0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 e busy callback
10c00 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 is NULL, then [S
10c10 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b QLITE_BUSY] or [
10c20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f SQLITE_IOERR_BLO
10c30 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 CKED].** is retu
10c40 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 rned immediately
10c50 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 upon encounteri
10c60 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 49 66 20 ng the lock. If
10c70 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 the busy callbac
10c80 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c k.** is not NULL
10c90 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 , then the callb
10ca0 61 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f ack will be invo
10cb0 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 ked with two arg
10cc0 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 uments..**.** Th
10cd0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
10ce0 20 74 6f 20 74 68 65 20 68 61 6e 64 6c 65 72 20 to the handler
10cf0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 is a copy of the
10d00 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 void* pointer w
10d10 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 hich.** is the t
10d20 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f hird argument to
10d30 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 sqlite3_busy_ha
10d40 6e 64 6c 65 72 28 29 2e 20 20 54 68 65 20 73 65 ndler(). The se
10d50 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
10d60 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 .** the handler
10d70 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 callback is the
10d80 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 number of times
10d90 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61 that the busy ha
10da0 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 ndler has.** bee
10db0 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 n invoked for th
10dc0 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 is locking event
10dd0 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 . If the.** bus
10de0 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 y callback retur
10df0 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 ns 0, then no ad
10e00 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 ditional attempt
10e10 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a s are made to.**
10e20 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 access the data
10e30 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 base and [SQLITE
10e40 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 _BUSY] or [SQLIT
10e50 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d E_IOERR_BLOCKED]
10e60 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
10e70 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b If the callback
10e80 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 returns non-zer
10e90 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 o, then another
10ea0 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 attempt.** is ma
10eb0 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 de to open the d
10ec0 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 atabase for read
10ed0 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c ing and the cycl
10ee0 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a e repeats..**.**
10ef0 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 The presence of
10f00 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 a busy handler
10f10 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 does not guarant
10f20 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 ee that it will
10f30 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 be invoked.** wh
10f40 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b en there is lock
10f50 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 49 66 20 contention. If
10f60 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 SQLite determine
10f70 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 s that invoking
10f80 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 the busy.** hand
10f90 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 ler could result
10fa0 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 in a deadlock,
10fb0 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 it will go ahead
10fc0 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c and return [SQL
10fd0 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 ITE_BUSY].** or
10fe0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c [SQLITE_IOERR_BL
10ff0 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f OCKED] instead o
11000 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 f invoking the b
11010 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 usy handler..**
11020 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 Consider a scena
11030 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 rio where one pr
11040 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 ocess is holding
11050 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 a read lock tha
11060 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e t.** it is tryin
11070 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 g to promote to
11080 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 a reserved lock
11090 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 and.** a second
110a0 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 process is holdi
110b0 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f ng a reserved lo
110c0 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 ck that it is tr
110d0 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f ying.** to promo
110e0 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 te to an exclusi
110f0 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 ve lock. The fi
11100 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e rst process cann
11110 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 ot proceed.** be
11120 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 cause it is bloc
11130 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e ked by the secon
11140 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 d and the second
11150 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a process cannot.
11160 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 ** proceed becau
11170 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 se it is blocked
11180 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 by the first.
11190 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 If both processe
111a0 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 s.** invoke the
111b0 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e busy handlers, n
111c0 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 either will make
111d0 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 any progress.
111e0 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 Therefore,.** SQ
111f0 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 Lite returns [SQ
11200 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 LITE_BUSY] for t
11210 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 he first process
11220 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 , hoping that th
11230 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 is.** will induc
11240 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 e the first proc
11250 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 ess to release i
11260 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 ts read lock and
11270 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 allow.** the se
11280 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 cond process to
11290 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 proceed..**.** T
112a0 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 he default busy
112b0 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c callback is NULL
112c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c ..**.** The [SQL
112d0 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 ITE_BUSY] error
112e0 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 is converted to
112f0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c [SQLITE_IOERR_BL
11300 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 OCKED].** when S
11310 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 QLite is in the
11320 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 middle of a larg
11330 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 e transaction wh
11340 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 ere all the.** c
11350 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 hanges will not
11360 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d fit into the in-
11370 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 memory cache. S
11380 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c QLite will.** al
11390 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 ready hold a RES
113a0 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 ERVED lock on th
113b0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c e database file,
113c0 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a but it needs.**
113d0 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 to promote this
113e0 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 lock to EXCLUSI
113f0 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 VE so that it ca
11400 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a n spill cache.**
11410 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 pages into the
11420 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 database file wi
11430 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f thout harm to co
11440 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 ncurrent.** read
11450 65 72 73 2e 20 20 49 66 20 69 74 20 69 73 20 75 ers. If it is u
11460 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 nable to promote
11470 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 the lock, then
11480 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a the in-memory.**
11490 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c cache will be l
114a0 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 eft in an incons
114b0 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 istent state and
114c0 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a so the error.**
114d0 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 code is promote
114e0 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 d from the relat
114f0 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 ively benign [SQ
11500 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a LITE_BUSY] to.**
11510 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 the more severe
11520 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 [SQLITE_IOERR_B
11530 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69 73 20 65 LOCKED]. This e
11540 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 rror code promot
11550 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e ion.** forces an
11560 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 automatic rollb
11570 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 ack of the chang
11580 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 es. See the.**
11590 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 <a href="/cvstra
115a0 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 c/wiki?p=Corrupt
115b0 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 ionFollowingBusy
115c0 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 Error">.** Corru
115d0 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 ptionFollowingBu
115e0 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 syError</a> wiki
115f0 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 page for a disc
11600 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a ussion of why.**
11610 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 this is importa
11620 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 nt..**.** There
11630 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 can only be a si
11640 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 ngle busy handle
11650 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 r defined for ea
11660 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 ch.** [database
11670 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 connection]. Se
11680 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 tting a new busy
11690 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 handler clears
116a0 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c any.** previousl
116b0 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 20 20 y set handler.
116c0 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e Note that callin
116d0 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f g [sqlite3_busy_
116e0 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 timeout()].** wi
116f0 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 ll also set or c
11700 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61 lear the busy ha
11710 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 ndler..**.** INV
11720 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
11730 48 31 32 33 31 31 7d 20 54 68 65 20 5b 73 71 6c H12311} The [sql
11740 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 ite3_busy_handle
11750 72 28 44 2c 43 2c 41 29 5d 20 66 75 6e 63 74 69 r(D,C,A)] functi
11760 6f 6e 20 73 68 61 6c 6c 20 72 65 70 6c 61 63 65 on shall replace
11770 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 75 73 .** bus
11780 79 20 63 61 6c 6c 62 61 63 6b 20 69 6e 20 74 68 y callback in th
11790 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
117a0 65 63 74 69 6f 6e 5d 20 44 20 77 69 74 68 20 61 ection] D with a
117b0 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 new.**
117c0 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 a new busy hand
117d0 6c 65 72 20 43 20 61 6e 64 20 61 70 70 6c 69 63 ler C and applic
117e0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 ation data point
117f0 65 72 20 41 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 er A..**.** {H12
11800 33 31 32 7d 20 4e 65 77 6c 79 20 63 72 65 61 74 312} Newly creat
11810 65 64 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ed [database con
11820 6e 65 63 74 69 6f 6e 73 5d 20 73 68 61 6c 6c 20 nections] shall
11830 68 61 76 65 20 61 20 62 75 73 79 0a 2a 2a 20 20 have a busy.**
11840 20 20 20 20 20 20 20 20 68 61 6e 64 6c 65 72 20 handler
11850 6f 66 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b of NULL..**.** {
11860 48 31 32 33 31 34 7d 20 57 68 65 6e 20 74 77 6f H12314} When two
11870 20 6f 72 20 6d 6f 72 65 20 5b 64 61 74 61 62 61 or more [databa
11880 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 se connections]
11890 73 68 61 72 65 20 61 0a 2a 2a 20 20 20 20 20 20 share a.**
118a0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 [sqlite3_ena
118b0 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 ble_shared_cache
118c0 20 7c 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 5d | common cache]
118d0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 ,.** th
118e0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 e busy handler f
118f0 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 or the database
11900 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 75 72 72 65 connection curre
11910 6e 74 6c 79 20 75 73 69 6e 67 0a 2a 2a 20 20 20 ntly using.**
11920 20 20 20 20 20 20 20 74 68 65 20 63 61 63 68 65 the cache
11930 20 73 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 shall be invoke
11940 64 20 77 68 65 6e 20 74 68 65 20 63 61 63 68 65 d when the cache
11950 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 6c 6f encounters a lo
11960 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 ck..**.** {H1231
11970 36 7d 20 49 66 20 61 20 62 75 73 79 20 68 61 6e 6} If a busy han
11980 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 dler callback re
11990 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 6e turns zero, then
119a0 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 the SQLite inte
119b0 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 rface.**
119c0 20 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 that provoked
119d0 74 68 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e the locking even
119e0 74 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b t shall return [
119f0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a SQLITE_BUSY]..**
11a00 0a 2a 2a 20 7b 48 31 32 33 31 38 7d 20 53 51 4c .** {H12318} SQL
11a10 69 74 65 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 ite shall invoke
11a20 73 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c s the busy handl
11a30 65 72 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 er with two argu
11a40 6d 65 6e 74 73 20 77 68 69 63 68 0a 2a 2a 20 20 ments which.**
11a50 20 20 20 20 20 20 20 20 61 72 65 20 61 20 63 6f are a co
11a60 70 79 20 6f 66 20 74 68 65 20 70 6f 69 6e 74 65 py of the pointe
11a70 72 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 r supplied by th
11a80 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 e 3rd parameter
11a90 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b to.** [
11aa0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e sqlite3_busy_han
11ab0 64 6c 65 72 28 29 5d 20 61 6e 64 20 61 20 63 6f dler()] and a co
11ac0 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 unt of the numbe
11ad0 72 20 6f 66 20 70 72 69 6f 72 0a 2a 2a 20 20 20 r of prior.**
11ae0 20 20 20 20 20 20 20 69 6e 76 6f 63 61 74 69 6f invocatio
11af0 6e 73 20 6f 66 20 74 68 65 20 62 75 73 79 20 68 ns of the busy h
11b00 61 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20 73 andler for the s
11b10 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e ame locking even
11b20 74 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 t..**.** ASSUMPT
11b30 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 IONS:.**.** {A12
11b40 33 31 39 7d 20 41 20 62 75 73 79 20 68 61 6e 64 319} A busy hand
11b50 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f ler must not clo
11b60 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 se the database
11b70 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 connection.**
11b80 20 20 20 20 20 20 20 6f 72 20 5b 70 72 65 70 61 or [prepa
11b90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 red statement] t
11ba0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 hat invoked the
11bb0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f busy handler..*/
11bc0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 .int sqlite3_bus
11bd0 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 y_handler(sqlite
11be0 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 3*, int(*)(void*
11bf0 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a ,int), void*);..
11c00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
11c10 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f Set A Busy Timeo
11c20 75 74 20 7b 48 31 32 33 34 30 7d 20 3c 53 34 30 ut {H12340} <S40
11c30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 410>.**.** This
11c40 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b routine sets a [
11c50 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e sqlite3_busy_han
11c60 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 dler | busy hand
11c70 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 ler] that sleeps
11c80 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 .** for a specif
11c90 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 ied amount of ti
11ca0 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 me when a table
11cb0 69 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 is locked. The
11cc0 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 handler.** will
11cd0 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 sleep multiple t
11ce0 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 imes until at le
11cf0 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 ast "ms" millise
11d00 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e conds of sleepin
11d10 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 g.** have accumu
11d20 6c 61 74 65 64 2e 20 7b 48 31 32 33 34 33 7d 20 lated. {H12343}
11d30 41 66 74 65 72 20 22 6d 73 22 20 6d 69 6c 6c 69 After "ms" milli
11d40 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 seconds of sleep
11d50 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 ing,.** the hand
11d60 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 ler returns 0 wh
11d70 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 ich causes [sqli
11d80 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 te3_step()] to r
11d90 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 eturn.** [SQLITE
11da0 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 _BUSY] or [SQLIT
11db0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d E_IOERR_BLOCKED]
11dc0 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 ..**.** Calling
11dd0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 this routine wit
11de0 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 h an argument le
11df0 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c ss than or equal
11e00 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e to zero.** turn
11e10 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 s off all busy h
11e20 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 andlers..**.** T
11e30 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 here can only be
11e40 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 a single busy h
11e50 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 andler for a par
11e60 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 ticular.** [data
11e70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
11e80 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d any any given m
11e90 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 oment. If anoth
11ea0 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a er busy handler.
11eb0 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 ** was defined
11ec0 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f (using [sqlite3_
11ed0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 busy_handler()])
11ee0 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e prior to callin
11ef0 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e g.** this routin
11f00 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 e, that other bu
11f10 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c sy handler is cl
11f20 65 61 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 eared..**.** INV
11f30 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
11f40 48 31 32 33 34 31 7d 20 54 68 65 20 5b 73 71 6c H12341} The [sql
11f50 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 ite3_busy_timeou
11f60 74 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 t()] function sh
11f70 61 6c 6c 20 6f 76 65 72 72 69 64 65 20 61 6e 79 all override any
11f80 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 prior.**
11f90 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 [sqlite3_busy
11fa0 5f 74 69 6d 65 6f 75 74 28 29 5d 20 6f 72 20 5b _timeout()] or [
11fb0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e sqlite3_busy_han
11fc0 64 6c 65 72 28 29 5d 20 73 65 74 74 69 6e 67 0a dler()] setting.
11fd0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74 ** on t
11fe0 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 he same [databas
11ff0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a e connection]..*
12000 2a 0a 2a 2a 20 7b 48 31 32 33 34 33 7d 20 49 66 *.** {H12343} If
12010 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
12020 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 er to [sqlite3_b
12030 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 usy_timeout()] i
12040 73 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 s less than.**
12050 20 20 20 20 20 20 20 20 6f 72 20 65 71 75 61 6c or equal
12060 20 74 6f 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 to zero, then t
12070 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 he busy handler
12080 73 68 61 6c 6c 20 62 65 20 63 6c 65 61 72 65 64 shall be cleared
12090 20 73 6f 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 so that.**
120a0 20 20 20 20 20 61 6c 6c 20 73 75 62 73 65 71 75 all subsequ
120b0 65 6e 74 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e ent locking even
120c0 74 73 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 72 ts immediately r
120d0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 eturn [SQLITE_BU
120e0 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 SY]..**.** {H123
120f0 34 34 7d 20 49 66 20 74 68 65 20 32 6e 64 20 70 44} If the 2nd p
12100 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c arameter to [sql
12110 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 ite3_busy_timeou
12120 74 28 29 5d 20 69 73 20 61 20 70 6f 73 69 74 69 t()] is a positi
12130 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e ve.** n
12140 75 6d 62 65 72 20 4e 2c 20 74 68 65 6e 20 61 20 umber N, then a
12150 62 75 73 79 20 68 61 6e 64 6c 65 72 20 73 68 61 busy handler sha
12160 6c 6c 20 62 65 20 73 65 74 20 74 68 61 74 20 72 ll be set that r
12170 65 70 65 61 74 65 64 6c 79 20 63 61 6c 6c 73 0a epeatedly calls.
12180 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
12190 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 xSleep() method
121a0 69 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f in the [sqlite3_
121b0 76 66 73 20 7c 20 56 46 53 20 69 6e 74 65 72 66 vfs | VFS interf
121c0 61 63 65 5d 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 ace] until.**
121d0 20 20 20 20 20 20 20 65 69 74 68 65 72 20 74 68 either th
121e0 65 20 6c 6f 63 6b 20 63 6c 65 61 72 73 20 6f 72 e lock clears or
121f0 20 75 6e 74 69 6c 20 74 68 65 20 63 75 6d 75 6c until the cumul
12200 61 74 69 76 65 20 73 6c 65 65 70 20 74 69 6d 65 ative sleep time
12210 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 70 .** rep
12220 6f 72 74 65 64 20 62 61 63 6b 20 62 79 20 78 53 orted back by xS
12230 6c 65 65 70 28 29 20 65 78 63 65 65 64 73 20 4e leep() exceeds N
12240 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a milliseconds..*
12250 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 /.int sqlite3_bu
12260 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 sy_timeout(sqlit
12270 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f e3*, int ms);../
12280 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
12290 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 onvenience Routi
122a0 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 nes For Running
122b0 51 75 65 72 69 65 73 20 7b 48 31 32 33 37 30 7d Queries {H12370}
122c0 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S10000>.**.**
122d0 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 Definition: A <b
122e0 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 >result table</b
122f0 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 > is memory data
12300 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 structure creat
12310 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 ed by the.** [sq
12320 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
12330 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 )] interface. A
12340 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 result table re
12350 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d cords the.** com
12360 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 plete query resu
12370 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 lts from one or
12380 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a more queries..**
12390 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f .** The table co
123a0 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 nceptually has a
123b0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 number of rows
123c0 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 and columns. Bu
123d0 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 t.** these numbe
123e0 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 rs are not part
123f0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 of the result ta
12400 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 ble itself. The
12410 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 se.** numbers ar
12420 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 e obtained separ
12430 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 ately. Let N be
12440 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 the number of r
12450 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 ows.** and M be
12460 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f the number of co
12470 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 lumns..**.** A r
12480 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 esult table is a
12490 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 n array of point
124a0 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d ers to zero-term
124b0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 inated UTF-8 str
124c0 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 ings..** There a
124d0 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 re (N+1)*M eleme
124e0 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 nts in the array
124f0 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 . The first M p
12500 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a ointers point.**
12510 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 to zero-termina
12520 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 ted strings that
12530 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 contain the na
12540 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d mes of the colum
12550 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 ns..** The remai
12560 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c ning entries all
12570 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 point to query
12580 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 results. NULL v
12590 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 alues result.**
125a0 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 in NULL pointers
125b0 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c . All other val
125c0 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 ues are in their
125d0 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d UTF-8 zero-term
125e0 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 inated.** string
125f0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 representation
12600 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b as returned by [
12610 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
12620 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 ext()]..**.** A
12630 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 result table mig
12640 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e ht consist of on
12650 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 e or more memory
12660 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a allocations..**
12670 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 It is not safe
12680 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 to pass a result
12690 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 table directly
126a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 to [sqlite3_free
126b0 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 ()]..** A result
126c0 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 table should be
126d0 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 deallocated usi
126e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ng [sqlite3_free
126f0 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a _table()]..**.**
12700 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f As an example o
12710 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 f the result tab
12720 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f le format, suppo
12730 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c se a query resul
12740 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f t.** is as follo
12750 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b ws:.**.** <block
12760 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
12770 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 Name
12780 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 | Age.**
12790 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d --------------
127a0 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 ---------.**
127b0 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 Alice
127c0 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 | 43.** B
127d0 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a ob | 28.
127e0 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 ** Cindy
127f0 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f | 21.** </
12800 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
12810 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 >.**.** There ar
12820 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d e two column (M=
12830 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f =2) and three ro
12840 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 ws (N==3). Thus
12850 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 the.** result t
12860 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 able has 8 entri
12870 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 es. Suppose the
12880 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 result table is
12890 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e stored.** in an
128a0 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 array names azR
128b0 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 esult. Then azR
128c0 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 esult holds this
128d0 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 content:.**.**
128e0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
128f0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 >.** azRe
12900 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e sult[0] = "N
12910 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 ame";.**
12920 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 azResult[1]
12930 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 = "Age";.**
12940 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
12950 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 2] = "Alice";.**
12960 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
12970 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a [3] = "43";.
12980 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
12990 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 lt[4] = "Bob
129a0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
129b0 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 esult[5] = "
129c0 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 28";.** a
129d0 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d zResult[6] =
129e0 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 "Cindy";.**
129f0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
12a00 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c ;7] = "21";.** <
12a10 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
12a20 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c e>.**.** The sql
12a30 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
12a40 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 function evalua
12a50 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a tes one or more.
12a60 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 ** semicolon-sep
12a70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 arated SQL state
12a80 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 ments in the zer
12a90 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 o-terminated UTF
12aa0 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 -8.** string of
12ab0 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 its 2nd paramete
12ac0 72 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 61 r. It returns a
12ad0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f result table to
12ae0 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 the.** pointer
12af0 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 given in its 3rd
12b00 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a parameter..**.*
12b10 2a 20 41 66 74 65 72 20 74 68 65 20 63 61 6c 6c * After the call
12b20 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 ing function has
12b30 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 finished using
12b40 74 68 65 20 72 65 73 75 6c 74 2c 20 69 74 20 73 the result, it s
12b50 68 6f 75 6c 64 0a 2a 2a 20 70 61 73 73 20 74 68 hould.** pass th
12b60 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 e pointer to the
12b70 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f result table to
12b80 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 sqlite3_free_ta
12b90 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 ble() in order t
12ba0 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 o.** release the
12bb0 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 memory that was
12bc0 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 malloced. Beca
12bd0 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 use of the way t
12be0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d he.** [sqlite3_m
12bf0 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 alloc()] happens
12c00 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f within sqlite3_
12c10 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 get_table(), the
12c20 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 calling.** func
12c30 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 tion must not tr
12c40 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 y to call [sqlit
12c50 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 e3_free()] direc
12c60 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 tly. Only.** [s
12c70 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c qlite3_free_tabl
12c80 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 e()] is able to
12c90 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f release the memo
12ca0 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 ry properly and
12cb0 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 safely..**.** Th
12cc0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 e sqlite3_get_ta
12cd0 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 ble() interface
12ce0 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 is implemented a
12cf0 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 s a wrapper arou
12d00 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 nd.** [sqlite3_e
12d10 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c xec()]. The sql
12d20 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
12d30 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f routine does no
12d40 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a t have access.**
12d50 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c to any internal
12d60 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 data structures
12d70 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 of SQLite. It
12d80 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 uses only the pu
12d90 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 blic.** interfac
12da0 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 e defined here.
12db0 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 As a consequenc
12dc0 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f e, errors that o
12dd0 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 ccur in the.** w
12de0 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 rapper layer out
12df0 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 side of the inte
12e00 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 rnal [sqlite3_ex
12e10 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e ec()] call are n
12e20 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 ot.** reflected
12e30 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 in subsequent ca
12e40 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
12e50 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 20 5b 73 errcode()] or [s
12e60 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d qlite3_errmsg()]
12e70 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
12e80 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 TS:.**.** {H1237
12e90 31 7d 20 49 66 20 61 20 5b 73 71 6c 69 74 65 33 1} If a [sqlite3
12ea0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 61 _get_table()] fa
12eb0 69 6c 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c ils a memory all
12ec0 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a ocation, then.**
12ed0 20 20 20 20 20 20 20 20 20 20 69 74 20 73 68 61 it sha
12ee0 6c 6c 20 66 72 65 65 20 74 68 65 20 72 65 73 75 ll free the resu
12ef0 6c 74 20 74 61 62 6c 65 20 75 6e 64 65 72 20 63 lt table under c
12f00 6f 6e 73 74 72 75 63 74 69 6f 6e 2c 20 61 62 6f onstruction, abo
12f10 72 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 rt the.**
12f20 20 20 20 71 75 65 72 79 20 69 6e 20 70 72 6f 63 query in proc
12f30 65 73 73 2c 20 73 6b 69 70 20 61 6e 79 20 73 75 ess, skip any su
12f40 62 73 65 71 75 65 6e 74 20 71 75 65 72 69 65 73 bsequent queries
12f50 2c 20 73 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 , set the.**
12f60 20 20 20 20 20 20 2a 70 61 7a 52 65 73 75 6c 74 *pazResult
12f70 20 6f 75 74 70 75 74 20 70 6f 69 6e 74 65 72 20 output pointer
12f80 74 6f 20 4e 55 4c 4c 20 61 6e 64 20 72 65 74 75 to NULL and retu
12f90 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d rn [SQLITE_NOMEM
12fa0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 33 ]..**.** {H12373
12fb0 7d 20 49 66 20 74 68 65 20 70 6e 43 6f 6c 75 6d } If the pnColum
12fc0 6e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b n parameter to [
12fd0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
12fe0 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c e()] is not NULL
12ff0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
13000 6e 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 69 n a successful i
13010 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 nvocation of [sq
13020 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
13030 29 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 )] shall.**
13040 20 20 20 20 20 77 72 69 74 65 20 74 68 65 20 6e write the n
13050 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
13060 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 in the.**
13070 20 20 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f result set o
13080 66 20 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f f the query into
13090 20 2a 70 6e 43 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a *pnColumn..**.*
130a0 2a 20 7b 48 31 32 33 37 34 7d 20 49 66 20 74 68 * {H12374} If th
130b0 65 20 70 6e 52 6f 77 20 70 61 72 61 6d 65 74 65 e pnRow paramete
130c0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 r to [sqlite3_ge
130d0 74 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f t_table()] is no
130e0 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 t NULL.**
130f0 20 20 20 74 68 65 6e 20 61 20 73 75 63 63 65 73 then a succes
13100 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 sful invocation
13110 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f of [sqlite3_get_
13120 74 61 62 6c 65 28 29 5d 20 73 68 61 6c 6c 0a 2a table()] shall.*
13130 2a 20 20 20 20 20 20 20 20 20 20 77 72 69 74 65 * write
13140 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
13150 72 6f 77 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 rows in the.**
13160 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 result s
13170 65 74 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 et of the query
13180 69 6e 74 6f 20 2a 70 6e 52 6f 77 2e 0a 2a 2a 0a into *pnRow..**.
13190 2a 2a 20 7b 48 31 32 33 37 36 7d 20 41 20 73 75 ** {H12376} A su
131a0 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 ccessful invocat
131b0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f ion of [sqlite3_
131c0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 74 68 61 get_table()] tha
131d0 74 20 63 6f 6d 70 75 74 65 73 0a 2a 2a 20 20 20 t computes.**
131e0 20 20 20 20 20 20 20 4e 20 72 6f 77 73 20 6f 66 N rows of
131f0 20 72 65 73 75 6c 74 20 77 69 74 68 20 43 20 63 result with C c
13200 6f 6c 75 6d 6e 73 20 70 65 72 20 72 6f 77 20 73 olumns per row s
13210 68 61 6c 6c 20 6d 61 6b 65 20 2a 70 61 7a 52 65 hall make *pazRe
13220 73 75 6c 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 sult.**
13230 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 72 72 point to an arr
13240 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 ay of pointers t
13250 6f 20 28 4e 2b 31 29 2a 43 20 73 74 72 69 6e 67 o (N+1)*C string
13260 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 s where the firs
13270 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 20 t.** C
13280 73 74 72 69 6e 67 73 20 61 72 65 20 63 6f 6c 75 strings are colu
13290 6d 6e 20 6e 61 6d 65 73 20 61 73 20 6f 62 74 61 mn names as obta
132a0 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 ined from.**
132b0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 [sqlite3_c
132c0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e olumn_name()] an
132d0 64 20 74 68 65 20 72 65 73 74 20 61 72 65 20 63 d the rest are c
132e0 6f 6c 75 6d 6e 20 72 65 73 75 6c 74 20 76 61 6c olumn result val
132f0 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ues.**
13300 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 obtained from [s
13310 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
13320 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 xt()]..**.** {H1
13330 32 33 37 39 7d 20 54 68 65 20 76 61 6c 75 65 73 2379} The values
13340 20 69 6e 20 74 68 65 20 70 61 7a 52 65 73 75 6c in the pazResul
13350 74 20 61 72 72 61 79 20 72 65 74 75 72 6e 65 64 t array returned
13360 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 by [sqlite3_get
13370 5f 74 61 62 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 _table()].**
13380 20 20 20 20 20 20 73 68 61 6c 6c 20 72 65 6d 61 shall rema
13390 69 6e 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 63 in valid until c
133a0 6c 65 61 72 65 64 20 62 79 20 5b 73 71 6c 69 74 leared by [sqlit
133b0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d e3_free_table()]
133c0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 38 32 7d ..**.** {H12382}
133d0 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f When an error o
133e0 63 63 75 72 73 20 64 75 72 69 6e 67 20 65 76 61 ccurs during eva
133f0 6c 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 luation of [sqli
13400 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d te3_get_table()]
13410 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
13420 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 function shall
13430 73 65 74 20 2a 70 61 7a 52 65 73 75 6c 74 20 74 set *pazResult t
13440 6f 20 4e 55 4c 4c 2c 20 77 72 69 74 65 20 61 6e o NULL, write an
13450 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a error message.*
13460 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 6f 20 * into
13470 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
13480 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 from [sqlite3_ma
13490 6c 6c 6f 63 28 29 5d 2c 20 6d 61 6b 65 0a 2a 2a lloc()], make.**
134a0 20 20 20 20 20 20 20 20 20 20 2a 2a 70 7a 45 72 **pzEr
134b0 72 6d 73 67 20 70 6f 69 6e 74 20 74 6f 20 74 68 rmsg point to th
134c0 61 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 at error message
134d0 2c 20 61 6e 64 20 72 65 74 75 72 6e 20 61 0a 2a , and return a.*
134e0 2a 20 20 20 20 20 20 20 20 20 20 61 70 70 72 6f * appro
134f0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f priate [error co
13500 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 de]..*/.int sqli
13510 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 te3_get_table(.
13520 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
13530 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 /* An ope
13540 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 n database */.
13550 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c const char *zSql
13560 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 , /* SQL to
13570 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a be evaluated */.
13580 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 char ***pazRes
13590 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c ult, /* Resul
135a0 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 ts of the query
135b0 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c */. int *pnRow,
135c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 /* Nu
135d0 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 mber of result r
135e0 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 ows written here
135f0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c */. int *pnCol
13600 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e umn, /* N
13610 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 umber of result
13620 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 columns written
13630 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a here */. char *
13640 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 *pzErrmsg
13650 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 /* Error msg wri
13660 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a tten here */.);.
13670 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 void sqlite3_fre
13680 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 e_table(char **r
13690 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 esult);../*.** C
136a0 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 API3REF: Formatt
136b0 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 ed String Printi
136c0 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 ng Functions {H1
136d0 37 34 30 30 7d 20 3c 53 37 30 30 30 30 3e 3c 53 7400} <S70000><S
136e0 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20000>.**.** The
136f0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
13700 77 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 workalikes of th
13710 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d e "printf()" fam
13720 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 ily of functions
13730 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 .** from the sta
13740 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e ndard C library.
13750 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
13760 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 e3_mprintf() and
13770 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 sqlite3_vmprint
13780 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 f() routines wri
13790 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 te their.** resu
137a0 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 lts into memory
137b0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 obtained from [s
137c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
137d0 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 ..** The strings
137e0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 returned by the
137f0 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 se two routines
13800 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c should be.** rel
13810 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 eased by [sqlite
13820 33 5f 66 72 65 65 28 29 5d 2e 20 20 42 6f 74 68 3_free()]. Both
13830 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
13840 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 a.** NULL point
13850 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d er if [sqlite3_m
13860 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 alloc()] is unab
13870 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 le to allocate e
13880 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 nough.** memory
13890 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 to hold the resu
138a0 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a lting string..**
138b0 0a 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 .** In sqlite3_s
138c0 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e nprintf() routin
138d0 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 e is similar to
138e0 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f "snprintf()" fro
138f0 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 m.** the standar
13900 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 d C library. Th
13910 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 e result is writ
13920 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 ten into the.**
13930 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 buffer supplied
13940 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 as the second pa
13950 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 rameter whose si
13960 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a ze is given by.*
13970 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 * the first para
13980 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 meter. Note that
13990 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 the order of th
139a0 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 e.** first two p
139b0 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 arameters is rev
139c0 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 ersed from snpri
139d0 6e 74 66 28 29 2e 20 20 54 68 69 73 20 69 73 20 ntf(). This is
139e0 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c an.** historical
139f0 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 accident that c
13a00 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 annot be fixed w
13a10 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a ithout breaking.
13a20 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d ** backwards com
13a30 70 61 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 patibility. Not
13a40 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 e also that sqli
13a50 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a te3_snprintf().*
13a60 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e * returns a poin
13a70 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 ter to its buffe
13a80 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 r instead of the
13a90 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 number of.** ch
13aa0 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c aracters actuall
13ab0 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 y written into t
13ac0 68 65 20 62 75 66 66 65 72 2e 20 20 57 65 20 61 he buffer. We a
13ad0 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 dmit that.** the
13ae0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 number of chara
13af0 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f cters written wo
13b00 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 uld be a more us
13b10 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 eful return.** v
13b20 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e alue but we cann
13b30 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d ot change the im
13b40 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
13b50 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
13b60 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 ().** now withou
13b70 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 t breaking compa
13b80 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 tibility..**.**
13b90 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 As long as the b
13ba0 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 uffer size is gr
13bb0 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c eater than zero,
13bc0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
13bd0 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 f().** guarantee
13be0 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 s that the buffe
13bf0 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f r is always zero
13c00 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 -terminated. Th
13c10 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d e first.** param
13c20 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 eter "n" is the
13c30 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 total size of th
13c40 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 e buffer, includ
13c50 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a ing space for.**
13c60 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e the zero termin
13c70 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f ator. So the lo
13c80 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 ngest string tha
13c90 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 t can be complet
13ca0 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 ely.** written w
13cb0 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 ill be n-1 chara
13cc0 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 cters..**.** The
13cd0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 se routines all
13ce0 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 implement some a
13cf0 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 dditional format
13d00 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 ting.** options
13d10 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 that are useful
13d20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 for constructing
13d30 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e SQL statements.
13d40 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 .** All of the u
13d50 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f sual printf() fo
13d60 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 rmatting options
13d70 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 apply. In addi
13d80 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 tion, there.** i
13d90 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 s are "%q", "%Q"
13da0 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f , and "%z" optio
13db0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 ns..**.** The %q
13dc0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 option works li
13dd0 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 ke %s in that it
13de0 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e substitutes a n
13df0 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a ull-terminated.*
13e00 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 * string from th
13e10 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e e argument list.
13e20 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f But %q also do
13e30 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 ubles every '\''
13e40 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 character..** %
13e50 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f q is designed fo
13e60 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 r use inside a s
13e70 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 tring literal.
13e80 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 By doubling each
13e90 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 '\''.** charact
13ea0 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 er it escapes th
13eb0 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 at character and
13ec0 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 allows it to be
13ed0 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a inserted into.*
13ee0 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a * the string..**
13ef0 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c .** For example,
13f00 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 assume the stri
13f10 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 ng variable zTex
13f20 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 t contains text
13f30 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a as follows:.**.*
13f40 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
13f50 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 re>.** char *zT
13f60 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 ext = "It's a ha
13f70 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f ppy day!";.** </
13f80 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
13f90 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 >.**.** One can
13fa0 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e use this text in
13fb0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e an SQL statemen
13fc0 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a t as follows:.**
13fd0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
13fe0 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a <pre>.** char *
13ff0 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d zSQL = sqlite3_m
14000 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 printf("INSERT I
14010 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 NTO table VALUES
14020 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b ('%q')", zText);
14030 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 .** sqlite3_exe
14040 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 c(db, zSQL, 0, 0
14050 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 , 0);.** sqlite
14060 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 3_free(zSQL);.**
14070 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
14080 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 ote>.**.** Becau
14090 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 se the %q format
140a0 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c string is used,
140b0 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 the '\'' charac
140c0 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 ter in zText.**
140d0 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 is escaped and t
140e0 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 he SQL generated
140f0 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a is as follows:.
14100 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
14110 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 e><pre>.** INSE
14120 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 RT INTO table1 V
14130 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 ALUES('It''s a h
14140 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c appy day!').** <
14150 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
14160 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 e>.**.** This is
14170 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 correct. Had w
14180 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 e used %s instea
14190 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e d of %q, the gen
141a0 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f erated SQL.** wo
141b0 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 uld have looked
141c0 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a like this:.**.**
141d0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
141e0 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e e>.** INSERT IN
141f0 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 TO table1 VALUES
14200 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 ('It's a happy d
14210 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e ay!');.** </pre>
14220 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
14230 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 .** This second
14240 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 example is an SQ
14250 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 L syntax error.
14260 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 As a general ru
14270 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a le you should.**
14280 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 always use %q i
14290 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 nstead of %s whe
142a0 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 n inserting text
142b0 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c into a string l
142c0 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 iteral..**.** Th
142d0 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b e %Q option work
142e0 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 s like %q except
142f0 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 it also adds si
14300 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 ngle quotes arou
14310 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 nd.** the outsid
14320 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 e of the total s
14330 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e tring. Addition
14340 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 ally, if the par
14350 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a ameter in the.**
14360 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 argument list i
14370 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
14380 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 , %Q substitutes
14390 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 the text "NULL"
143a0 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e (without.** sin
143b0 67 6c 65 20 71 75 6f 74 65 73 29 20 69 6e 20 70 gle quotes) in p
143c0 6c 61 63 65 20 6f 66 20 74 68 65 20 25 51 20 6f lace of the %Q o
143d0 70 74 69 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 ption. So, for
143e0 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 example, one cou
143f0 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ld say:.**.** <b
14400 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
14410 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d ** char *zSQL =
14420 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 sqlite3_mprintf
14430 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 ("INSERT INTO ta
14440 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c ble VALUES(%Q)",
14450 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c zText);.** sql
14460 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 ite3_exec(db, zS
14470 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a QL, 0, 0, 0);.**
14480 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a sqlite3_free(z
14490 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c SQL);.** </pre><
144a0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
144b0 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 ** The code abov
144c0 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 e will render a
144d0 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 correct SQL stat
144e0 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 ement in the zSQ
144f0 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 L.** variable ev
14500 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 en if the zText
14510 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 variable is a NU
14520 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
14530 2a 20 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 * The "%z" forma
14540 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 tting option wor
14550 6b 73 20 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 ks exactly like
14560 22 25 73 22 20 77 69 74 68 20 74 68 65 0a 2a 2a "%s" with the.**
14570 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 addition that a
14580 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 fter the string
14590 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e has been read an
145a0 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a d copied into.**
145b0 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 the result, [sq
145c0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 lite3_free()] is
145d0 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 called on the i
145e0 6e 70 75 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e nput string. {EN
145f0 44 7d 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 D}.**.** INVARIA
14600 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 NTS:.**.** {H174
14610 30 33 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 03} The [sqlite
14620 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 61 6e 64 3_mprintf()] and
14630 20 5b 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e [sqlite3_vmprin
14640 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 tf()] interfaces
14650 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 .** re
14660 74 75 72 6e 20 65 69 74 68 65 72 20 70 6f 69 6e turn either poin
14670 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 ters to zero-ter
14680 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 minated UTF-8 st
14690 72 69 6e 67 73 20 68 65 6c 64 20 69 6e 0a 2a 2a rings held in.**
146a0 20 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 memor
146b0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
146c0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
146d0 29 5d 20 6f 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 )] or NULL point
146e0 65 72 73 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 ers if.**
146f0 20 20 20 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 a call to [s
14700 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
14710 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 fails..**.** {H
14720 31 37 34 30 36 7d 20 20 54 68 65 20 5b 73 71 6c 17406} The [sql
14730 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d ite3_snprintf()]
14740 20 69 6e 74 65 72 66 61 63 65 20 77 72 69 74 65 interface write
14750 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 s a zero-termina
14760 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ted.**
14770 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 69 6e UTF-8 string in
14780 74 6f 20 74 68 65 20 62 75 66 66 65 72 20 70 6f to the buffer po
14790 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 inted to by the
147a0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
147b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 70 72 .** pr
147c0 6f 76 69 64 65 64 20 74 68 61 74 20 74 68 65 20 ovided that the
147d0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
147e0 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 is greater than
147f0 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 zero..**.** {H17
14800 34 30 37 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 407} The [sqlit
14810 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 e3_snprintf()] i
14820 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f nterface does no
14830 74 20 77 72 69 74 65 20 73 6c 6f 74 73 20 6f 66 t write slots of
14840 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 74 .** it
14850 73 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 s output buffer
14860 28 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 (the second para
14870 6d 65 74 65 72 29 20 6f 75 74 73 69 64 65 20 74 meter) outside t
14880 68 65 20 72 61 6e 67 65 0a 2a 2a 20 20 20 20 20 he range.**
14890 20 20 20 20 20 20 6f 66 20 30 20 74 68 72 6f 75 of 0 throu
148a0 67 68 20 4e 2d 31 20 28 77 68 65 72 65 20 4e 20 gh N-1 (where N
148b0 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 is the first par
148c0 61 6d 65 74 65 72 29 0a 2a 2a 20 20 20 20 20 20 ameter).**
148d0 20 20 20 20 20 72 65 67 61 72 64 6c 65 73 73 20 regardless
148e0 6f 66 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 of the length of
148f0 20 74 68 65 20 73 74 72 69 6e 67 0a 2a 2a 20 20 the string.**
14900 20 20 20 20 20 20 20 20 20 72 65 71 75 65 73 74 request
14910 65 64 20 62 79 20 74 68 65 20 66 6f 72 6d 61 74 ed by the format
14920 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a specification..
14930 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 */.char *sqlite3
14940 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 _mprintf(const c
14950 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 har*,...);.char
14960 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 *sqlite3_vmprint
14970 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 f(const char*, v
14980 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 a_list);.char *s
14990 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
149a0 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 int,char*,const
149b0 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a char*, ...);../*
149c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 .** CAPI3REF: Me
149d0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 mory Allocation
149e0 53 75 62 73 79 73 74 65 6d 20 7b 48 31 37 33 30 Subsystem {H1730
149f0 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 0} <S20000>.**.*
14a00 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 * The SQLite cor
14a10 65 20 20 75 73 65 73 20 74 68 65 73 65 20 74 68 e uses these th
14a20 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 ree routines for
14a30 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a all of its own.
14a40 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f ** internal memo
14a50 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 ry allocation ne
14a60 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 eds. "Core" in t
14a70 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 he previous sent
14a80 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 ence.** does not
14a90 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 include operati
14aa0 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 ng-system specif
14ab0 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 ic VFS implement
14ac0 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 ation. The.** W
14ad0 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 indows VFS uses
14ae0 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 native malloc()
14af0 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 and free() for s
14b00 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a ome operations..
14b10 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
14b20 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 3_malloc() routi
14b30 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ne returns a poi
14b40 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a nter to a block.
14b50 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 ** of memory at
14b60 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e least N bytes in
14b70 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e length, where N
14b80 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 is the paramete
14b90 72 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 r..** If sqlite3
14ba0 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 _malloc() is una
14bb0 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 ble to obtain su
14bc0 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a fficient free.**
14bd0 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 memory, it retu
14be0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 rns a NULL point
14bf0 65 72 2e 20 20 49 66 20 74 68 65 20 70 61 72 61 er. If the para
14c00 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 meter N to.** sq
14c10 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 lite3_malloc() i
14c20 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 s zero or negati
14c30 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f ve then sqlite3_
14c40 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 malloc() returns
14c50 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 .** a NULL point
14c60 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e er..**.** Callin
14c70 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 g sqlite3_free()
14c80 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 with a pointer
14c90 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 previously retur
14ca0 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 ned.** by sqlite
14cb0 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 3_malloc() or sq
14cc0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 lite3_realloc()
14cd0 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 releases that me
14ce0 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 mory so.** that
14cf0 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 it might be reus
14d00 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 ed. The sqlite3
14d10 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 _free() routine
14d20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 is.** a no-op if
14d30 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 is called with
14d40 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 a NULL pointer.
14d50 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 Passing a NULL
14d60 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 pointer.** to sq
14d70 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 lite3_free() is
14d80 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 harmless. After
14d90 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 being freed, me
14da0 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e mory.** should n
14db0 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e either be read n
14dc0 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 or written. Eve
14dd0 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f n reading previo
14de0 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 usly freed.** me
14df0 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c mory might resul
14e00 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 t in a segmentat
14e10 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 ion fault or oth
14e20 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e er severe error.
14e30 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 .** Memory corru
14e40 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 ption, a segment
14e50 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 ation fault, or
14e60 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 other severe err
14e70 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 or.** might resu
14e80 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 lt if sqlite3_fr
14e90 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 ee() is called w
14ea0 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 ith a non-NULL p
14eb0 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 ointer that.** w
14ec0 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 as not obtained
14ed0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c from sqlite3_mal
14ee0 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 loc() or sqlite3
14ef0 5f 66 72 65 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 _free()..**.** T
14f00 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c he sqlite3_reall
14f10 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 oc() interface a
14f20 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a ttempts to resiz
14f30 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d e a.** prior mem
14f40 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 ory allocation t
14f50 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 o be at least N
14f60 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 bytes, where N i
14f70 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 s the.** second
14f80 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 parameter. The
14f90 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
14fa0 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 n to be resized
14fb0 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 is the first.**
14fc0 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 20 74 parameter. If t
14fd0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
14fe0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 er to sqlite3_re
14ff0 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 alloc().** is a
15000 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 NULL pointer the
15010 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 n its behavior i
15020 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 s identical to c
15030 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 alling.** sqlite
15040 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 3_malloc(N) wher
15050 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e e N is the secon
15060 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 d parameter to s
15070 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
15080 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 65 63 6f ..** If the seco
15090 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 nd parameter to
150a0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
150b0 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 ) is zero or.**
150c0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 negative then th
150d0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 e behavior is ex
150e0 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 actly the same a
150f0 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c s calling.** sql
15100 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 ite3_free(P) whe
15110 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73 re P is the firs
15120 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 t parameter to s
15130 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
15140 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 ..** sqlite3_rea
15150 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 lloc() returns a
15160 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 pointer to a me
15170 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a mory allocation.
15180 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e ** of at least N
15190 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f bytes in size o
151a0 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 r NULL if suffic
151b0 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 ient memory is u
151c0 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 49 navailable..** I
151d0 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 f M is the size
151e0 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c of the prior all
151f0 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 ocation, then mi
15200 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 n(N,M) bytes.**
15210 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c of the prior all
15220 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 ocation are copi
15230 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 ed into the begi
15240 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 nning of buffer
15250 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 returned.** by s
15260 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
15270 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 and the prior a
15280 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 llocation is fre
15290 65 64 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 ed..** If sqlite
152a0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 3_realloc() retu
152b0 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 rns NULL, then t
152c0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 he prior allocat
152d0 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 ion.** is not fr
152e0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d eed..**.** The m
152f0 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 emory returned b
15300 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 y sqlite3_malloc
15310 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 () and sqlite3_r
15320 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 ealloc().** is a
15330 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f lways aligned to
15340 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 at least an 8 b
15350 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 7b 45 yte boundary. {E
15360 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 ND}.**.** The de
15370 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61 fault implementa
15380 74 69 6f 6e 20 6f 66 20 74 68 65 20 6d 65 6d 6f tion of the memo
15390 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 ry allocation su
153a0 62 73 79 73 74 65 6d 20 75 73 65 73 0a 2a 2a 20 bsystem uses.**
153b0 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 the malloc(), re
153c0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 alloc() and free
153d0 28 29 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 () provided by t
153e0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 he standard C li
153f0 62 72 61 72 79 2e 0a 2a 2a 20 7b 48 31 37 33 38 brary..** {H1738
15400 32 7d 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53 2} However, if S
15410 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
15420 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 d with the.** SQ
15430 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45 LITE_MEMORY_SIZE
15440 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 43 20 70 72 =<i>NNN</i> C pr
15450 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f eprocessor macro
15460 20 28 77 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f (where <i>NNN</
15470 69 3e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 i>.** is an inte
15480 67 65 72 29 2c 20 74 68 65 6e 20 53 51 4c 69 74 ger), then SQLit
15490 65 20 63 72 65 61 74 65 20 61 20 73 74 61 74 69 e create a stati
154a0 63 20 61 72 72 61 79 20 6f 66 20 61 74 20 6c 65 c array of at le
154b0 61 73 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e 3c 2f 69 ast.** <i>NNN</i
154c0 3e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 > bytes in size
154d0 61 6e 64 20 75 73 65 73 20 74 68 61 74 20 61 72 and uses that ar
154e0 72 61 79 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 ray for all of i
154f0 74 73 20 64 79 6e 61 6d 69 63 0a 2a 2a 20 6d 65 ts dynamic.** me
15500 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
15510 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 20 20 41 64 needs. {END} Ad
15520 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 ditional memory
15530 61 6c 6c 6f 63 61 74 6f 72 20 6f 70 74 69 6f 6e allocator option
15540 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61 64 64 65 s.** may be adde
15550 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
15560 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 ases..**.** In S
15570 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e QLite version 3.
15580 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 5.0 and 3.5.1, i
15590 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 t was possible t
155a0 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 o define.** the
155b0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f SQLITE_OMIT_MEMO
155c0 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 RY_ALLOCATION wh
155d0 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 ich would cause
155e0 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 the built-in.**
155f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
15600 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
15610 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 to be omitted.
15620 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 That capability
15630 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 .** is no longer
15640 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 provided. Only
15650 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 built-in memory
15660 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 allocators can
15670 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 be used..**.** T
15680 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e he Windows OS in
15690 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 terface layer ca
156a0 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 lls.** the syste
156b0 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 m malloc() and f
156c0 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 ree() directly w
156d0 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a hen converting.*
156e0 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 * filenames betw
156f0 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e een the UTF-8 en
15700 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 coding used by S
15710 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 QLite.** and wha
15720 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 tever filename e
15730 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 ncoding is used
15740 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 by the particula
15750 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 r Windows.** ins
15760 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f tallation. Memo
15770 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 ry allocation er
15780 72 6f 72 73 20 61 72 65 20 64 65 74 65 63 74 65 rors are detecte
15790 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 d, but.** they a
157a0 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b re reported back
157b0 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 as [SQLITE_CANT
157c0 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c OPEN] or.** [SQL
157d0 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 ITE_IOERR] rathe
157e0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e r than [SQLITE_N
157f0 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 OMEM]..**.** INV
15800 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
15810 48 31 37 33 30 33 7d 20 20 54 68 65 20 5b 73 71 H17303} The [sq
15820 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d lite3_malloc(N)]
15830 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
15840 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f 69 6e ns either a poin
15850 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 ter to.**
15860 20 20 20 20 61 20 6e 65 77 6c 79 20 63 68 65 63 a newly chec
15870 6b 65 64 2d 6f 75 74 20 62 6c 6f 63 6b 20 6f 66 ked-out block of
15880 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 at least N byte
15890 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 s of memory.**
158a0 20 20 20 20 20 20 20 20 20 74 68 61 74 20 69 73 that is
158b0 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 2c 8-byte aligned,
158c0 20 6f 72 20 69 74 20 72 65 74 75 72 6e 73 20 4e or it returns N
158d0 55 4c 4c 20 69 66 20 69 74 20 69 73 20 75 6e 61 ULL if it is una
158e0 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ble.**
158f0 20 74 6f 20 66 75 6c 66 69 6c 6c 20 74 68 65 20 to fulfill the
15900 72 65 71 75 65 73 74 2e 0a 2a 2a 0a 2a 2a 20 7b request..**.** {
15910 48 31 37 33 30 34 7d 20 20 54 68 65 20 5b 73 71 H17304} The [sq
15920 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d lite3_malloc(N)]
15930 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
15940 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ns a NULL pointe
15950 72 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 r if.**
15960 20 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e N is less than
15970 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 or equal to zer
15980 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 35 o..**.** {H17305
15990 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f } The [sqlite3_
159a0 66 72 65 65 28 50 29 5d 20 69 6e 74 65 72 66 61 free(P)] interfa
159b0 63 65 20 72 65 6c 65 61 73 65 73 20 6d 65 6d 6f ce releases memo
159c0 72 79 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a ry previously.**
159d0 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 retur
159e0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ned from [sqlite
159f0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 3_malloc()] or [
15a00 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
15a10 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 )],.**
15a20 20 6d 61 6b 69 6e 67 20 69 74 20 61 76 61 69 6c making it avail
15a30 61 62 6c 65 20 66 6f 72 20 72 65 75 73 65 2e 0a able for reuse..
15a40 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 36 7d 20 20 **.** {H17306}
15a50 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 A call to [sqlit
15a60 65 33 5f 66 72 65 65 28 4e 55 4c 4c 29 5d 20 69 e3_free(NULL)] i
15a70 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d s a harmless no-
15a80 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 op..**.** {H1731
15a90 30 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 0} A call to [s
15aa0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 30 qlite3_realloc(0
15ab0 2c 4e 29 5d 20 69 73 20 65 71 75 69 76 61 6c 65 ,N)] is equivale
15ac0 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 nt to a call.**
15ad0 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71 to [sq
15ae0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d lite3_malloc(N)]
15af0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 32 7d ..**.** {H17312}
15b00 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c A call to [sql
15b10 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 30 ite3_realloc(P,0
15b20 29 5d 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 )] is equivalent
15b30 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20 to a call.**
15b40 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69 to [sqli
15b50 74 65 33 5f 66 72 65 65 28 50 29 5d 2e 0a 2a 2a te3_free(P)]..**
15b60 0a 2a 2a 20 7b 48 31 37 33 31 35 7d 20 20 54 68 .** {H17315} Th
15b70 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 e SQLite core us
15b80 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c es [sqlite3_mall
15b90 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f oc()], [sqlite3_
15ba0 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 realloc()],.**
15bb0 20 20 20 20 20 20 20 20 20 61 6e 64 20 5b 73 71 and [sq
15bc0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 66 6f lite3_free()] fo
15bd0 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6d 65 6d r all of its mem
15be0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 ory allocation a
15bf0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 nd.**
15c00 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 deallocation nee
15c10 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 ds..**.** {H1731
15c20 38 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 8} The [sqlite3
15c30 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 69 _realloc(P,N)] i
15c40 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
15c50 20 65 69 74 68 65 72 20 61 20 70 6f 69 6e 74 65 either a pointe
15c60 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 r.** t
15c70 6f 20 61 20 62 6c 6f 63 6b 20 6f 66 20 63 68 65 o a block of che
15c80 63 6b 65 64 2d 6f 75 74 20 6d 65 6d 6f 72 79 20 cked-out memory
15c90 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 of at least N by
15ca0 74 65 73 20 69 6e 20 73 69 7a 65 0a 2a 2a 20 20 tes in size.**
15cb0 20 20 20 20 20 20 20 20 20 74 68 61 74 20 69 73 that is
15cc0 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 2c 8-byte aligned,
15cd0 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 or a NULL point
15ce0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 er..**.** {H1732
15cf0 31 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 1} When [sqlite
15d00 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 3_realloc(P,N)]
15d10 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 returns a non-NU
15d20 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66 LL pointer, it f
15d30 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 irst.**
15d40 20 20 63 6f 70 69 65 73 20 74 68 65 20 66 69 72 copies the fir
15d50 73 74 20 4b 20 62 79 74 65 73 20 6f 66 20 63 6f st K bytes of co
15d60 6e 74 65 6e 74 20 66 72 6f 6d 20 50 20 69 6e 74 ntent from P int
15d70 6f 20 74 68 65 20 6e 65 77 6c 79 0a 2a 2a 20 20 o the newly.**
15d80 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 allocat
15d90 65 64 20 62 6c 6f 63 6b 2c 20 77 68 65 72 65 20 ed block, where
15da0 4b 20 69 73 20 74 68 65 20 6c 65 73 73 65 72 20 K is the lesser
15db0 6f 66 20 4e 20 61 6e 64 20 74 68 65 20 73 69 7a of N and the siz
15dc0 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 e of.**
15dd0 20 20 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a the buffer P..
15de0 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 32 7d 20 20 **.** {H17322}
15df0 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 When [sqlite3_re
15e00 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 alloc(P,N)] retu
15e10 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 rns a non-NULL p
15e20 6f 69 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74 ointer, it first
15e30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 .** re
15e40 6c 65 61 73 65 73 20 74 68 65 20 62 75 66 66 65 leases the buffe
15e50 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 r P..**.** {H173
15e60 32 33 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 23} When [sqlit
15e70 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d e3_realloc(P,N)]
15e80 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 returns NULL, t
15e90 68 65 20 62 75 66 66 65 72 20 50 20 69 73 0a 2a he buffer P is.*
15ea0 2a 20 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20 * not
15eb0 6d 6f 64 69 66 69 65 64 20 6f 72 20 72 65 6c 65 modified or rele
15ec0 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 ased..**.** ASSU
15ed0 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b MPTIONS:.**.** {
15ee0 41 31 37 33 35 30 7d 20 20 54 68 65 20 70 6f 69 A17350} The poi
15ef0 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 nter arguments t
15f00 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 o [sqlite3_free(
15f10 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
15f20 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 20 20 realloc()].**
15f30 20 20 20 20 20 20 20 20 6d 75 73 74 20 62 65 20 must be
15f40 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 either NULL or e
15f50 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 lse pointers obt
15f60 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 ained from a pri
15f70 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 or.**
15f80 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 invocation of [s
15f90 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
15fa0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 or [sqlite3_rea
15fb0 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 lloc()] that hav
15fc0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e e.** n
15fd0 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 ot yet been rele
15fe0 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 37 ased..**.** {A17
15ff0 33 35 31 7d 20 20 54 68 65 20 61 70 70 6c 69 63 351} The applic
16000 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 ation must not r
16010 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 ead or write any
16020 20 70 61 72 74 20 6f 66 0a 2a 2a 20 20 20 20 20 part of.**
16030 20 20 20 20 20 20 61 20 62 6c 6f 63 6b 20 6f 66 a block of
16040 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 memory after it
16050 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 has been releas
16060 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 ed using.**
16070 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 66 [sqlite3_f
16080 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 ree()] or [sqlit
16090 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a e3_realloc()]..*
160a0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f /.void *sqlite3_
160b0 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 malloc(int);.voi
160c0 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c d *sqlite3_reall
160d0 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a oc(void*, int);.
160e0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 void sqlite3_fre
160f0 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a e(void*);../*.**
16100 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 CAPI3REF: Memor
16110 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 y Allocator Stat
16120 69 73 74 69 63 73 20 7b 48 31 37 33 37 30 7d 20 istics {H17370}
16130 3c 53 33 30 32 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 <S30210>.**.** S
16140 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 QLite provides t
16150 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 hese two interfa
16160 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e ces for reportin
16170 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a g on the status.
16180 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ** of the [sqlit
16190 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 e3_malloc()], [s
161a0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 qlite3_free()],
161b0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 and [sqlite3_rea
161c0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 lloc()].** routi
161d0 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 nes, which form
161e0 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d the built-in mem
161f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 ory allocation s
16200 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 ubsystem..**.**
16210 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
16220 2a 20 7b 48 31 37 33 37 31 7d 20 54 68 65 20 5b * {H17371} The [
16230 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 sqlite3_memory_u
16240 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 sed()] routine r
16250 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
16260 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 20 20 r of bytes.**
16270 20 20 20 20 20 20 20 6f 66 20 6d 65 6d 6f 72 79 of memory
16280 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 currently outst
16290 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 anding (malloced
162a0 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e but not freed).
162b0 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 33 7d 20 .**.** {H17373}
162c0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d The [sqlite3_mem
162d0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d ory_highwater()]
162e0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
162f0 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 the maximum.**
16300 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f value o
16310 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 f [sqlite3_memor
16320 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 y_used()] since
16330 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d the high-water m
16340 61 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ark.**
16350 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 0a was last reset..
16360 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 34 7d 20 54 **.** {H17374} T
16370 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e he values return
16380 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d ed by [sqlite3_m
16390 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e emory_used()] an
163a0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 d.** [s
163b0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
163c0 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 ghwater()] inclu
163d0 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a de any overhead.
163e0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 64 64 65 ** adde
163f0 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 d by SQLite in i
16400 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ts implementatio
16410 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 n of [sqlite3_ma
16420 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 lloc()],.**
16430 20 20 20 20 20 62 75 74 20 6e 6f 74 20 6f 76 65 but not ove
16440 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74 rhead added by t
16450 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e he any underlyin
16460 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 g system library
16470 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75 .** rou
16480 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 tines that [sqli
16490 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 te3_malloc()] ma
164a0 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 y call..**.** {H
164b0 31 37 33 37 35 7d 20 54 68 65 20 6d 65 6d 6f 72 17375} The memor
164c0 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 y high-water mar
164d0 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 k is reset to th
164e0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 e current value
164f0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b of.** [
16500 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 sqlite3_memory_u
16510 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e sed()] if and on
16520 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 ly if the parame
16530 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 ter to.**
16540 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f [sqlite3_memo
16550 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 ry_highwater()]
16560 69 73 20 74 72 75 65 2e 20 20 54 68 65 20 76 61 is true. The va
16570 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 lue returned.**
16580 20 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c by [sql
16590 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 ite3_memory_high
165a0 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 water(1)] is the
165b0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b high-water mark
165c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 69 .** pri
165d0 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e or to the reset.
165e0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 .*/.sqlite3_int6
165f0 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 4 sqlite3_memory
16600 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c _used(void);.sql
16610 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 ite3_int64 sqlit
16620 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
16630 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 ter(int resetFla
16640 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 g);../*.** CAPI3
16650 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 REF: Pseudo-Rand
16660 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 om Number Genera
16670 74 6f 72 20 7b 48 31 37 33 39 30 7d 20 3c 53 32 tor {H17390} <S2
16680 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 0000>.**.** SQLi
16690 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 te contains a hi
166a0 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 gh-quality pseud
166b0 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 o-random number
166c0 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 generator (PRNG)
166d0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 used to.** sele
166e0 63 74 20 72 61 6e 64 6f 6d 20 52 4f 57 49 44 73 ct random ROWIDs
166f0 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 when inserting
16700 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f new records into
16710 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a a table that.**
16720 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 already uses th
16730 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 e largest possib
16740 6c 65 20 52 4f 57 49 44 2e 20 20 54 68 65 20 50 le ROWID. The P
16750 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 RNG is also used
16760 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c for.** the buil
16770 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e d-in random() an
16780 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 d randomblob() S
16790 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 QL functions. T
167a0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c his interface al
167b0 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 lows.** applicat
167c0 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 ions to access t
167d0 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 he same PRNG for
167e0 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e other purposes.
167f0 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f .**.** A call to
16800 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 this routine st
16810 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 ores N bytes of
16820 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 randomness into
16830 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 buffer P..**.**
16840 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 The first time t
16850 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 his routine is i
16860 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 nvoked (either i
16870 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a nternally or by.
16880 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ** the applicati
16890 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 on) the PRNG is
168a0 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e seeded using ran
168b0 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 domness obtained
168c0 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 .** from the xRa
168d0 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 ndomness method
168e0 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b of the default [
168f0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
16900 65 63 74 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 ect..** On all s
16910 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 ubsequent invoca
16920 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 tions, the pseud
16930 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 o-randomness is
16940 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 generated.** int
16950 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 ernally and with
16960 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 out recourse to
16970 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 the [sqlite3_vfs
16980 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a ] xRandomness.**
16990 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 49 method..**.** I
169a0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
169b0 20 7b 48 31 37 33 39 32 7d 20 54 68 65 20 5b 73 {H17392} The [s
169c0 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 qlite3_randomnes
169d0 73 28 4e 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 s(N,P)] interfac
169e0 65 20 77 72 69 74 65 73 20 4e 20 62 79 74 65 73 e writes N bytes
169f0 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 of.**
16a00 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 high-quality pse
16a10 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 udo-randomness i
16a20 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2f nto buffer P..*/
16a30 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 .void sqlite3_ra
16a40 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 ndomness(int N,
16a50 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a void *P);../*.**
16a60 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 CAPI3REF: Compi
16a70 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a le-Time Authoriz
16a80 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 ation Callbacks
16a90 7b 48 31 32 35 30 30 7d 20 3c 53 37 30 31 30 30 {H12500} <S70100
16aa0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 >.**.** This rou
16ab0 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 tine registers a
16ac0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
16ad0 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 back with a part
16ae0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 icular.** [datab
16af0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c ase connection],
16b00 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 supplied in the
16b10 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e first argument.
16b20 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a .** The authoriz
16b30 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 er callback is i
16b40 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 nvoked as SQL st
16b50 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 atements are bei
16b60 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 ng compiled.** b
16b70 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 y [sqlite3_prepa
16b80 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 re()] or its var
16b90 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 iants [sqlite3_p
16ba0 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a repare_v2()],.**
16bb0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
16bc0 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 e16()] and [sqli
16bd0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
16be0 28 29 5d 2e 20 20 41 74 20 76 61 72 69 6f 75 73 ()]. At various
16bf0 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e .** points durin
16c00 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f g the compilatio
16c10 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f n process, as lo
16c20 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 gic is being cre
16c30 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f ated.** to perfo
16c40 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f rm various actio
16c50 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a ns, the authoriz
16c60 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 er callback is i
16c70 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 nvoked to.** see
16c80 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e if those action
16c90 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 s are allowed.
16ca0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 The authorizer c
16cb0 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a allback should.*
16cc0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 * return [SQLITE
16cd0 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 _OK] to allow th
16ce0 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 e action, [SQLIT
16cf0 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 E_IGNORE] to dis
16d00 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 allow the.** spe
16d10 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 cific action but
16d20 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 allow the SQL s
16d30 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 tatement to cont
16d40 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f inue to be.** co
16d50 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 mpiled, or [SQLI
16d60 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 TE_DENY] to caus
16d70 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c e the entire SQL
16d80 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 statement to be
16d90 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 .** rejected wit
16da0 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 49 66 20 h an error. If
16db0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
16dc0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a allback returns.
16dd0 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 ** any value oth
16de0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
16df0 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 IGNORE], [SQLITE
16e00 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 _OK], or [SQLITE
16e10 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 _DENY].** then t
16e20 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 he [sqlite3_prep
16e30 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 are_v2()] or equ
16e40 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 ivalent call tha
16e50 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 t triggered.** t
16e60 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 he authorizer wi
16e70 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 ll fail with an
16e80 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a error message..*
16e90 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 *.** When the ca
16ea0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b llback returns [
16eb0 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 SQLITE_OK], that
16ec0 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 means the opera
16ed0 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 tion.** requeste
16ee0 64 20 69 73 20 6f 6b 2e 20 20 57 68 65 6e 20 74 d is ok. When t
16ef0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 he callback retu
16f00 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 rns [SQLITE_DENY
16f10 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ], the.** [sqlit
16f20 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
16f30 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 or equivalent c
16f40 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 all that trigger
16f50 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 ed the.** author
16f60 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 izer will fail w
16f70 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 ith an error mes
16f80 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 sage explaining
16f90 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 that.** access i
16fa0 73 20 64 65 6e 69 65 64 2e 20 20 49 66 20 74 68 s denied. If th
16fb0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 e authorizer cod
16fc0 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 e is [SQLITE_REA
16fd0 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 D].** and the ca
16fe0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b llback returns [
16ff0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 SQLITE_IGNORE] t
17000 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 hen the.** [prep
17010 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
17020 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e statement is con
17030 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 structed to subs
17040 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c titute.** a NULL
17050 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 value in place
17060 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c of the table col
17070 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 umn that would h
17080 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 ave.** been read
17090 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 if [SQLITE_OK]
170a0 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 had been returne
170b0 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f d. The [SQLITE_
170c0 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 IGNORE].** retur
170d0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f n can be used to
170e0 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 deny an untrust
170f0 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 ed user access t
17100 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 o individual.**
17110 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 columns of a tab
17120 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 le..**.** The fi
17130 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f rst parameter to
17140 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
17150 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f callback is a co
17160 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a py of the third.
17170 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 ** parameter to
17180 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f the sqlite3_set_
17190 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 authorizer() int
171a0 65 72 66 61 63 65 2e 20 54 68 65 20 73 65 63 6f erface. The seco
171b0 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 nd parameter.**
171c0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
171d0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 is an integer [S
171e0 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 QLITE_COPY | act
171f0 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 ion code] that s
17200 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 pecifies.** the
17210 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f particular actio
17220 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a n to be authoriz
17230 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 74 68 ed. The third th
17240 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 rough sixth para
17250 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 meters.** to the
17260 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 callback are ze
17270 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 ro-terminated st
17280 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 rings that conta
17290 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a in additional.**
172a0 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 details about t
172b0 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 he action to be
172c0 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a authorized..**.*
172d0 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 * An authorizer
172e0 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 is used when [sq
172f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 lite3_prepare |
17300 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 preparing].** SQ
17310 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f L statements fro
17320 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 m an untrusted s
17330 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 ource, to ensure
17340 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 that the SQL st
17350 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e atements.** do n
17360 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 ot try to access
17370 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e data they are n
17380 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 ot allowed to se
17390 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 e, or that they
173a0 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f do not.** try to
173b0 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f execute malicio
173c0 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 us statements th
173d0 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 at damage the da
173e0 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 tabase. For.**
173f0 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c example, an appl
17400 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f ication may allo
17410 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 w a user to ente
17420 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 r arbitrary.** S
17430 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 QL queries for e
17440 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 valuation by a d
17450 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 atabase. But th
17460 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f e application do
17470 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 es.** not want t
17480 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 he user to be ab
17490 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 le to make arbit
174a0 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 rary changes to
174b0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e the.** database.
174c0 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 An authorizer
174d0 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 could then be pu
174e0 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 t in place while
174f0 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 the.** user-ent
17500 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e ered SQL is bein
17510 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 g [sqlite3_prepa
17520 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 re | prepared] t
17530 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 hat.** disallows
17540 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 everything exce
17550 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 pt [SELECT] stat
17560 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 ements..**.** Ap
17570 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 plications that
17580 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 need to process
17590 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 SQL from untrust
175a0 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 ed sources.** mi
175b0 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 ght also conside
175c0 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 r lowering resou
175d0 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 rce limits using
175e0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 [sqlite3_limit(
175f0 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 )].** and limiti
17600 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 ng database size
17610 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f using the [max_
17620 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 page_count] [PRA
17630 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 GMA].** in addit
17640 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 ion to using an
17650 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a authorizer..**.*
17660 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 * Only a single
17670 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 authorizer can b
17680 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 e in place on a
17690 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
176a0 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 ion.** at a time
176b0 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 . Each call to
176c0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
176d0 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 orizer overrides
176e0 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 the.** previous
176f0 20 63 61 6c 6c 2e 20 20 44 69 73 61 62 6c 65 20 call. Disable
17700 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 the authorizer b
17710 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e y installing a N
17720 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a ULL callback..**
17730 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 The authorizer
17740 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 is disabled by d
17750 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 4e 6f efault..**.** No
17760 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 te that the auth
17770 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
17780 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 is invoked only
17790 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 during.** [sqlit
177a0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 e3_prepare()] or
177b0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 its variants.
177c0 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 Authorization is
177d0 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 not.** performe
177e0 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 d during stateme
177f0 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e nt evaluation in
17800 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
17810 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 ]..**.** INVARIA
17820 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 NTS:.**.** {H125
17830 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 01} The [sqlite3
17840 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 _set_authorizer(
17850 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 D,...)] interfac
17860 65 20 72 65 67 69 73 74 65 72 73 20 61 0a 2a 2a e registers a.**
17870 20 20 20 20 20 20 20 20 20 20 61 75 74 68 6f 72 author
17880 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 izer callback wi
17890 74 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e th database conn
178a0 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 ection D..**.**
178b0 7b 48 31 32 35 30 32 7d 20 54 68 65 20 61 75 74 {H12502} The aut
178c0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
178d0 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 is invoked as S
178e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 QL statements ar
178f0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 e.** be
17900 69 6e 67 20 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a ing compiled..**
17910 0a 2a 2a 20 7b 48 31 32 35 30 33 7d 20 49 66 20 .** {H12503} If
17920 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
17930 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
17940 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 any value other
17950 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 than.**
17960 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d [SQLITE_IGNORE]
17970 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f , [SQLITE_OK], o
17980 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c r [SQLITE_DENY],
17990 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 then.**
179a0 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 the [sqlite3_p
179b0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
179c0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 equivalent call
179d0 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 20 that caused.**
179e0 20 20 20 20 20 20 20 20 74 68 65 20 61 75 74 68 the auth
179f0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
17a00 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20 66 61 69 to run shall fai
17a10 6c 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 l with an.**
17a20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 [SQLITE_ER
17a30 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 ROR] error code
17a40 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 and an appropria
17a50 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 te error message
17a60 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 34 7d ..**.** {H12504}
17a70 20 57 68 65 6e 20 74 68 65 20 61 75 74 68 6f 72 When the author
17a80 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 izer callback re
17a90 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b turns [SQLITE_OK
17aa0 5d 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e ], the operation
17ab0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 73 .** des
17ac0 63 72 69 62 65 64 20 69 73 20 70 72 6f 63 65 73 cribed is proces
17ad0 73 65 64 20 6e 6f 72 6d 61 6c 6c 79 2e 0a 2a 2a sed normally..**
17ae0 0a 2a 2a 20 7b 48 31 32 35 30 35 7d 20 57 68 65 .** {H12505} Whe
17af0 6e 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 n the authorizer
17b00 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
17b10 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c s [SQLITE_DENY],
17b20 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
17b30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
17b40 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 e_v2()] or equiv
17b50 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 alent call that
17b60 63 61 75 73 65 64 20 74 68 65 0a 2a 2a 20 20 20 caused the.**
17b70 20 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65 authorize
17b80 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75 r callback to ru
17b90 6e 20 73 68 61 6c 6c 20 66 61 69 6c 0a 2a 2a 20 n shall fail.**
17ba0 20 20 20 20 20 20 20 20 20 77 69 74 68 20 61 6e with an
17bb0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
17bc0 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 error code and a
17bd0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a n error message.
17be0 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78 70 6c ** expl
17bf0 61 69 6e 69 6e 67 20 74 68 61 74 20 61 63 63 65 aining that acce
17c00 73 73 20 69 73 20 64 65 6e 69 65 64 2e 0a 2a 2a ss is denied..**
17c10 0a 2a 2a 20 7b 48 31 32 35 30 36 7d 20 49 66 20 .** {H12506} If
17c20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
17c30 6f 64 65 20 28 74 68 65 20 32 6e 64 20 70 61 72 ode (the 2nd par
17c40 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 ameter to the au
17c50 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20 thorizer.**
17c60 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69 callback) i
17c70 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 s [SQLITE_READ]
17c80 61 6e 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a and the authoriz
17c90 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 er callback retu
17ca0 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 rns.**
17cb0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c [SQLITE_IGNORE],
17cc0 20 74 68 65 6e 20 74 68 65 20 70 72 65 70 61 72 then the prepar
17cd0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 ed statement is
17ce0 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 0a 2a constructed to.*
17cf0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 73 65 72 * inser
17d00 74 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 t a NULL value i
17d10 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 n place of the t
17d20 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 able column that
17d30 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 20 would have.**
17d40 20 20 20 20 20 20 20 20 62 65 65 6e 20 72 65 61 been rea
17d50 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d d if [SQLITE_OK]
17d60 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e had been return
17d70 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 ed..**.** {H1250
17d80 37 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 7} If the author
17d90 69 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20 32 izer code (the 2
17da0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 nd parameter to
17db0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a the authorizer.*
17dc0 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 * callb
17dd0 61 63 6b 29 20 69 73 20 61 6e 79 74 68 69 6e 67 ack) is anything
17de0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c other than [SQL
17df0 49 54 45 5f 52 45 41 44 5d 2c 20 74 68 65 6e 0a ITE_READ], then.
17e00 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 72 65 ** a re
17e10 74 75 72 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f turn of [SQLITE_
17e20 49 47 4e 4f 52 45 5d 20 68 61 73 20 74 68 65 20 IGNORE] has the
17e30 73 61 6d 65 20 65 66 66 65 63 74 20 61 73 20 5b same effect as [
17e40 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2e 0a 2a 2a SQLITE_DENY]..**
17e50 0a 2a 2a 20 7b 48 31 32 35 31 30 7d 20 54 68 65 .** {H12510} The
17e60 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
17e70 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a to the authoriz
17e80 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 er callback is a
17e90 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 copy of.**
17ea0 20 20 20 20 20 74 68 65 20 74 68 69 72 64 20 70 the third p
17eb0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
17ec0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 [sqlite3_set_aut
17ed0 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 horizer()] inter
17ee0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 face..**.** {H12
17ef0 35 31 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 511} The second
17f00 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
17f10 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 callback is an
17f20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 integer.**
17f30 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 [SQLITE_COPY
17f40 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 | action code]
17f50 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74 that specifies t
17f60 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 he particular ac
17f70 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 tion.**
17f80 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 to be authorize
17f90 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31 32 d..**.** {H12512
17fa0 7d 20 54 68 65 20 74 68 69 72 64 20 74 68 72 6f } The third thro
17fb0 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 ugh sixth parame
17fc0 74 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c 6c ters to the call
17fd0 62 61 63 6b 20 61 72 65 0a 2a 2a 20 20 20 20 20 back are.**
17fe0 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e zero-termin
17ff0 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 ated strings tha
18000 74 20 63 6f 6e 74 61 69 6e 0a 2a 2a 20 20 20 20 t contain.**
18010 20 20 20 20 20 20 61 64 64 69 74 69 6f 6e 61 6c additional
18020 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 details about t
18030 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 he action to be
18040 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a authorized..**.*
18050 2a 20 7b 48 31 32 35 32 30 7d 20 45 61 63 68 20 * {H12520} Each
18060 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
18070 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 _set_authorizer(
18080 29 5d 20 6f 76 65 72 72 69 64 65 73 0a 2a 2a 20 )] overrides.**
18090 20 20 20 20 20 20 20 20 20 61 6e 79 20 70 72 65 any pre
180a0 76 69 6f 75 73 6c 79 20 69 6e 73 74 61 6c 6c 65 viously installe
180b0 64 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a d authorizer..**
180c0 0a 2a 2a 20 7b 48 31 32 35 32 31 7d 20 41 20 4e .** {H12521} A N
180d0 55 4c 4c 20 61 75 74 68 6f 72 69 7a 65 72 20 6d ULL authorizer m
180e0 65 61 6e 73 20 74 68 61 74 20 6e 6f 20 61 75 74 eans that no aut
180f0 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 20 20 horization.**
18100 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 callback
18110 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a is invoked..**.*
18120 2a 20 7b 48 31 32 35 32 32 7d 20 54 68 65 20 64 * {H12522} The d
18130 65 66 61 75 6c 74 20 61 75 74 68 6f 72 69 7a 65 efault authorize
18140 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e r is NULL..*/.in
18150 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 t sqlite3_set_au
18160 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 thorizer(. sqli
18170 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 te3*,. int (*xA
18180 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 uth)(void*,int,c
18190 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 onst char*,const
181a0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 char*,const cha
181b0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c r*,const char*),
181c0 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 . void *pUserDa
181d0 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ta.);../*.** CAP
181e0 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 I3REF: Authorize
181f0 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 20 7b r Return Codes {
18200 48 31 32 35 39 30 7d 20 3c 48 31 32 35 30 30 3e H12590} <H12500>
18210 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 .**.** The [sqli
18220 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
18230 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 er | authorizer
18240 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
18250 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 n] must.** retur
18260 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 n either [SQLITE
18270 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 _OK] or one of t
18280 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e hese two constan
18290 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 ts in order.** t
182a0 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 o signal SQLite
182b0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 whether or not t
182c0 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 he action is per
182d0 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 mitted. See the
182e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 .** [sqlite3_set
182f0 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 _authorizer | au
18300 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e thorizer documen
18310 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 tation] for addi
18320 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d tional.** inform
18330 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e ation..*/.#defin
18340 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 e SQLITE_DENY
18350 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 1 /* Abort the
18360 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 SQL statement w
18370 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a ith an error */.
18380 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
18390 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e GNORE 2 /* Don
183a0 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 't allow access,
183b0 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 but don't gener
183c0 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a ate an error */.
183d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
183e0 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 Authorizer Acti
183f0 6f 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 35 30 on Codes {H12550
18400 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a } <H12500>.**.**
18410 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 The [sqlite3_se
18420 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 t_authorizer()]
18430 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 interface regist
18440 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 ers a callback f
18450 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 unction.** that
18460 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 is invoked to au
18470 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 thorize certain
18480 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 SQL statement ac
18490 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 tions. The.** s
184a0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
184b0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
184c0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f is an integer co
184d0 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 de that specifie
184e0 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e s.** what action
184f0 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 is being author
18500 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 ized. These are
18510 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 the integer act
18520 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a ion codes that.*
18530 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 * the authorizer
18540 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 callback may be
18550 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 passed..**.** T
18560 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 hese action code
18570 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 values signify
18580 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 what kind of ope
18590 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a ration is to be.
185a0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 ** authorized.
185b0 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 The 3rd and 4th
185c0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 parameters to th
185d0 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a e authorization.
185e0 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 ** callback func
185f0 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 tion will be par
18600 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 ameters or NULL
18610 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 depending on whi
18620 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 ch of these.** c
18630 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 odes is used as
18640 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
18650 65 74 65 72 2e 20 20 54 68 65 20 35 74 68 20 70 eter. The 5th p
18660 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a arameter to the.
18670 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 ** authorizer ca
18680 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 llback is the na
18690 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 me of the databa
186a0 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d se ("main", "tem
186b0 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 p",.** etc.) if
186c0 61 70 70 6c 69 63 61 62 6c 65 2e 20 20 54 68 65 applicable. The
186d0 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6th parameter t
186e0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 o the authorizer
186f0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 callback.** is
18700 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
18710 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 inner-most trigg
18720 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 er or view that
18730 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 is responsible f
18740 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 or.** the access
18750 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c attempt or NULL
18760 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 if this access
18770 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 attempt is direc
18780 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d tly from.** top-
18790 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a level SQL code..
187a0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
187b0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 31 7d :.**.** {H12551}
187c0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 The second para
187d0 6d 65 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 20 meter to an.**
187e0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
187f0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 _set_authorizer
18800 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c | authorizer cal
18810 6c 62 61 63 6b 5d 20 69 73 20 61 6c 77 61 79 73 lback] is always
18820 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 an integer.**
18830 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f [SQLITE_
18840 43 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 COPY | authorize
18850 72 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 r code] that spe
18860 63 69 66 69 65 73 20 77 68 61 74 20 61 63 74 69 cifies what acti
18870 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 on.** i
18880 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a s being authoriz
18890 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 ed..**.** {H1255
188a0 32 7d 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 2} The 3rd and 4
188b0 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f th parameters to
188c0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
188d0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
188e0 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f thorizer | autho
188f0 72 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 rization callbac
18900 6b 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 k].** w
18910 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 ill be parameter
18920 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 s or NULL depend
18930 69 6e 67 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 ing on which.**
18940 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 [SQLITE
18950 5f 43 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a _COPY | authoriz
18960 65 72 20 63 6f 64 65 5d 20 69 73 20 75 73 65 64 er code] is used
18970 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 as the second p
18980 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 arameter..**.**
18990 7b 48 31 32 35 35 33 7d 20 54 68 65 20 35 74 68 {H12553} The 5th
189a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
189b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 e.** [s
189c0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
189d0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a rizer | authoriz
189e0 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20 er callback] is
189f0 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 the name.**
18a00 20 20 20 20 20 6f 66 20 74 68 65 20 64 61 74 61 of the data
18a10 62 61 73 65 20 28 65 78 61 6d 70 6c 65 3a 20 22 base (example: "
18a20 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 65 main", "temp", e
18a30 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 tc.) if applicab
18a40 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 le..**.** {H1255
18a50 34 7d 20 54 68 65 20 36 74 68 20 70 61 72 61 6d 4} The 6th param
18a60 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 eter to the.**
18a70 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
18a80 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 _set_authorizer
18a90 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c | authorizer cal
18aa0 6c 62 61 63 6b 5d 20 69 73 20 74 68 65 20 6e 61 lback] is the na
18ab0 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f me.** o
18ac0 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 f the inner-most
18ad0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 trigger or view
18ae0 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 that is respons
18af0 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 ible for.**
18b00 20 20 20 20 20 74 68 65 20 61 63 63 65 73 73 20 the access
18b10 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 attempt or NULL
18b20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 if this access a
18b30 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 ttempt is direct
18b40 6c 79 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 ly from.**
18b50 20 20 20 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 top-level SQ
18b60 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a L code..*/./****
18b70 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
18b80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
18b90 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a ******* 3rd ****
18ba0 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a ******** 4th ***
18bb0 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e ********/.#defin
18bc0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
18bd0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 INDEX 1
18be0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 /* Index Name
18bf0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 Table Name
18c00 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
18c10 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 SQLITE_CREATE_T
18c20 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 ABLE 2
18c30 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
18c40 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
18c50 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
18c60 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 SQLITE_CREATE_TE
18c70 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 MP_INDEX 3
18c80 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 /* Index Name
18c90 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
18ca0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
18cb0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d QLITE_CREATE_TEM
18cc0 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 P_TABLE 4
18cd0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
18ce0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
18cf0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
18d00 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 LITE_CREATE_TEMP
18d10 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f _TRIGGER 5 /
18d20 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 * Trigger Name
18d30 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
18d40 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
18d50 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f ITE_CREATE_TEMP_
18d60 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a VIEW 6 /*
18d70 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 View Name
18d80 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
18d90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
18da0 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 TE_CREATE_TRIGGE
18db0 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 R 7 /*
18dc0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 Trigger Name
18dd0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
18de0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
18df0 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 E_CREATE_VIEW
18e00 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 8 /* V
18e10 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e iew Name N
18e20 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
18e30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
18e40 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 _DELETE
18e50 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 9 /* Ta
18e60 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
18e70 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
18e80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
18e90 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 DROP_INDEX
18ea0 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 10 /* Ind
18eb0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 ex Name Tab
18ec0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
18ed0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
18ee0 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 ROP_TABLE
18ef0 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 11 /* Tabl
18f00 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
18f10 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
18f20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
18f30 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 OP_TEMP_INDEX
18f40 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 12 /* Index
18f50 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 Name Table
18f60 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
18f70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
18f80 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 P_TEMP_TABLE
18f90 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 13 /* Table
18fa0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
18fb0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
18fc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
18fd0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 _TEMP_TRIGGER
18fe0 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 14 /* Trigger
18ff0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e Name Table N
19000 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
19010 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
19020 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 TEMP_VIEW
19030 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 15 /* View Nam
19040 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 e NULL
19050 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
19060 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
19070 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 RIGGER 1
19080 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 6 /* Trigger N
19090 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d ame Table Nam
190a0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
190b0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 e SQLITE_DROP_VI
190c0 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 EW 17
190d0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 /* View Name
190e0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
190f0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
19100 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 SQLITE_INSERT
19110 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 18
19120 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
19130 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
19140 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
19150 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 SQLITE_PRAGMA
19160 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 19
19170 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 /* Pragma Name
19180 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 1st arg or N
19190 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ULL */.#define S
191a0 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 QLITE_READ
191b0 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 20
191c0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
191d0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 Column Name
191e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
191f0 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 LITE_SELECT
19200 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 21 /
19210 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 * NULL
19220 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
19230 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
19240 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 ITE_TRANSACTION
19250 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 22 /*
19260 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
19270 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
19280 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
19290 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 TE_UPDATE
192a0 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 23 /*
192b0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
192c0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 Column Name
192d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
192e0 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 E_ATTACH
192f0 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 24 /* F
19300 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e ilename N
19310 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
19320 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
19330 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 _DETACH
19340 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 25 /* Da
19350 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 tabase Name NU
19360 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
19370 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
19380 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 ALTER_TABLE
19390 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 26 /* Dat
193a0 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 abase Name Tab
193b0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
193c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
193d0 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 EINDEX
193e0 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 27 /* Inde
193f0 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c x Name NULL
19400 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
19410 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e define SQLITE_AN
19420 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 ALYZE
19430 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 28 /* Table
19440 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
19450 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
19460 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
19470 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 ATE_VTABLE
19480 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 29 /* Table
19490 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 Name Module
194a0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
194b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
194c0 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 _VTABLE
194d0 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 30 /* Table N
194e0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 ame Module
194f0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 Name */.#def
19500 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 ine SQLITE_FUNCT
19510 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 ION
19520 33 31 20 20 20 2f 2a 20 46 75 6e 63 74 69 6f 6e 31 /* Function
19530 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 Name NULL
19540 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
19550 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 ne SQLITE_COPY
19560 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
19570 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 0 /* No longer
19580 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 used */../*.**
19590 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e CAPI3REF: Tracin
195a0 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 g And Profiling
195b0 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 32 32 38 Functions {H1228
195c0 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 20 45 0} <S60400>.** E
195d0 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a XPERIMENTAL.**.*
195e0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
195f0 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 register callba
19600 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 ck functions tha
19610 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f t can be used fo
19620 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 r.** tracing and
19630 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 profiling the e
19640 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 xecution of SQL
19650 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a statements..**.*
19660 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 * The callback f
19670 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 unction register
19680 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 ed by sqlite3_tr
19690 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 ace() is invoked
196a0 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 at.** various t
196b0 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c imes when an SQL
196c0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 statement is be
196d0 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 ing run by [sqli
196e0 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 te3_step()]..**
196f0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 The callback ret
19700 75 72 6e 73 20 61 20 55 54 46 2d 38 20 72 65 6e urns a UTF-8 ren
19710 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 53 51 dering of the SQ
19720 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 L statement text
19730 0a 2a 2a 20 61 73 20 74 68 65 20 73 74 61 74 65 .** as the state
19740 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e ment first begin
19750 73 20 65 78 65 63 75 74 69 6e 67 2e 20 20 41 64 s executing. Ad
19760 64 69 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 ditional callbac
19770 6b 73 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 ks occur.** as e
19780 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 ach triggered su
19790 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 bprogram is ente
197a0 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 red. The callba
197b0 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 cks for triggers
197c0 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 .** contain a UT
197d0 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 F-8 SQL comment
197e0 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 that identifies
197f0 74 68 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a the trigger..**.
19800 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 ** The callback
19810 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 function registe
19820 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 red by sqlite3_p
19830 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f rofile() is invo
19840 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 ked.** as each S
19850 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e QL statement fin
19860 69 73 68 65 73 2e 20 20 54 68 65 20 70 72 6f 66 ishes. The prof
19870 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e ile callback con
19880 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 tains.** the ori
19890 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 ginal statement
198a0 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 text and an esti
198b0 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f mate of wall-clo
198c0 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f ck time.** of ho
198d0 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 w long that stat
198e0 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 ement took to ru
198f0 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 n..**.** INVARIA
19900 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 NTS:.**.** {H122
19910 38 31 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 81} The callback
19920 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 function regist
19930 65 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 ered by [sqlite3
19940 5f 74 72 61 63 65 28 29 5d 20 69 73 0a 2a 2a 20 _trace()] is.**
19950 20 20 20 20 20 20 20 20 20 77 68 65 6e 65 76 65 wheneve
19960 72 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 r an SQL stateme
19970 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 nt first begins
19980 74 6f 20 65 78 65 63 75 74 65 20 61 6e 64 0a 2a to execute and.*
19990 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 65 * whene
199a0 76 65 72 20 61 20 74 72 69 67 67 65 72 20 73 75 ver a trigger su
199b0 62 70 72 6f 67 72 61 6d 20 66 69 72 73 74 20 62 bprogram first b
199c0 65 67 69 6e 73 20 74 6f 20 72 75 6e 2e 0a 2a 2a egins to run..**
199d0 0a 2a 2a 20 7b 48 31 32 32 38 32 7d 20 45 61 63 .** {H12282} Eac
199e0 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 h call to [sqlit
199f0 65 33 5f 74 72 61 63 65 28 29 5d 20 6f 76 65 72 e3_trace()] over
19a00 72 69 64 65 73 20 74 68 65 20 70 72 65 76 69 6f rides the previo
19a10 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 usly.**
19a20 20 72 65 67 69 73 74 65 72 65 64 20 74 72 61 63 registered trac
19a30 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a e callback..**.*
19a40 2a 20 7b 48 31 32 32 38 33 7d 20 41 20 4e 55 4c * {H12283} A NUL
19a50 4c 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b L trace callback
19a60 20 64 69 73 61 62 6c 65 73 20 74 72 61 63 69 6e disables tracin
19a70 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 34 g..**.** {H12284
19a80 7d 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 } The first argu
19a90 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 ment to the trac
19aa0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 e callback is a
19ab0 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 copy of.**
19ac0 20 20 20 20 74 68 65 20 70 6f 69 6e 74 65 72 20 the pointer
19ad0 77 68 69 63 68 20 77 61 73 20 74 68 65 20 33 72 which was the 3r
19ae0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 d argument to [s
19af0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 2e qlite3_trace()].
19b00 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 35 7d 20 .**.** {H12285}
19b10 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d The second argum
19b20 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 ent to the trace
19b30 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a callback is a.*
19b40 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d * zero-
19b50 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 terminated UTF-8
19b60 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 string containi
19b70 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 ng the original
19b80 74 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 text.**
19b90 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 of the SQL stat
19ba0 65 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73 20 ement as it was
19bb0 70 61 73 73 65 64 20 69 6e 74 6f 20 5b 73 71 6c passed into [sql
19bc0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
19bd0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f )].** o
19be0 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 r the equivalent
19bf0 2c 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d , or an SQL comm
19c00 65 6e 74 20 69 6e 64 69 63 61 74 69 6e 67 20 74 ent indicating t
19c10 68 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 he beginning.**
19c20 20 20 20 20 20 20 20 20 20 6f 66 20 61 20 74 72 of a tr
19c30 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d igger subprogram
19c40 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 37 7d ..**.** {H12287}
19c50 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 The callback fu
19c60 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 nction registere
19c70 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 d by [sqlite3_pr
19c80 6f 66 69 6c 65 28 29 5d 20 69 73 20 69 6e 76 6f ofile()] is invo
19c90 6b 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ked.**
19ca0 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 as each SQL stat
19cb0 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a ement finishes..
19cc0 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 38 7d 20 54 **.** {H12288} T
19cd0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
19ce0 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c er to the profil
19cf0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 e callback is a
19d00 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 copy of.**
19d10 20 20 20 20 74 68 65 20 33 72 64 20 70 61 72 61 the 3rd para
19d20 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 meter to [sqlite
19d30 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2e 0a 2a 2a 3_profile()]..**
19d40 0a 2a 2a 20 7b 48 31 32 32 38 39 7d 20 54 68 65 .** {H12289} The
19d50 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
19d60 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 r to the profile
19d70 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a callback is a.*
19d80 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d * zero-
19d90 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 terminated UTF-8
19da0 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 6f 6e string that con
19db0 74 61 69 6e 73 20 74 68 65 20 63 6f 6d 70 6c 65 tains the comple
19dc0 74 65 20 74 65 78 74 20 6f 66 0a 2a 2a 20 20 20 te text of.**
19dd0 20 20 20 20 20 20 20 74 68 65 20 53 51 4c 20 73 the SQL s
19de0 74 61 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77 tatement as it w
19df0 61 73 20 70 72 6f 63 65 73 73 65 64 20 62 79 20 as processed by
19e00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
19e10 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 _v2()].**
19e20 20 20 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 or the equiva
19e30 6c 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 lent..**.** {H12
19e40 32 39 30 7d 20 54 68 65 20 74 68 69 72 64 20 70 290} The third p
19e50 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
19e60 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b profile callback
19e70 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 0a is an estimate.
19e80 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 ** of t
19e90 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e he number of nan
19ea0 6f 73 65 63 6f 6e 64 73 20 6f 66 20 77 61 6c 6c oseconds of wall
19eb0 2d 63 6c 6f 63 6b 20 74 69 6d 65 20 72 65 71 75 -clock time requ
19ec0 69 72 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 ired to.**
19ed0 20 20 20 20 72 75 6e 20 74 68 65 20 53 51 4c 20 run the SQL
19ee0 73 74 61 74 65 6d 65 6e 74 20 66 72 6f 6d 20 73 statement from s
19ef0 74 61 72 74 20 74 6f 20 66 69 6e 69 73 68 2e 0a tart to finish..
19f00 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 */.void *sqlite3
19f10 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c _trace(sqlite3*,
19f20 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 void(*xTrace)(v
19f30 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a oid*,const char*
19f40 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 ), void*);.void
19f50 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 *sqlite3_profile
19f60 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f (sqlite3*,. vo
19f70 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f id(*xProfile)(vo
19f80 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c id*,const char*,
19f90 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c sqlite3_uint64),
19fa0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 void*);../*.**
19fb0 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 CAPI3REF: Query
19fc0 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 Progress Callbac
19fd0 6b 73 20 7b 48 31 32 39 31 30 7d 20 3c 53 36 30 ks {H12910} <S60
19fe0 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 400>.**.** This
19ff0 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 routine configur
1a000 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 es a callback fu
1a010 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 nction - the.**
1a020 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 progress callbac
1a030 6b 20 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f k - that is invo
1a040 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 ked periodically
1a050 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 during long.**
1a060 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f running calls to
1a070 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 [sqlite3_exec()
1a080 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ], [sqlite3_step
1a090 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 ()] and.** [sqli
1a0a0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d te3_get_table()]
1a0b0 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 . An example us
1a0c0 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e e for this.** in
1a0d0 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 terface is to ke
1a0e0 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 ep a GUI updated
1a0f0 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 during a large
1a100 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 query..**.** If
1a110 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c the progress cal
1a120 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f lback returns no
1a130 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 n-zero, the oper
1a140 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 ation is.** inte
1a150 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 rrupted. This f
1a160 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 eature can be us
1a170 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 ed to implement
1a180 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 a.** "Cancel" bu
1a190 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 64 69 tton on a GUI di
1a1a0 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 alog box..**.**
1a1b0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
1a1c0 2a 20 7b 48 31 32 39 31 31 7d 20 54 68 65 20 63 * {H12911} The c
1a1d0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
1a1e0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 registered by s
1a1f0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f qlite3_progress_
1a200 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 20 20 20 handler().**
1a210 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 is invoked
1a220 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 periodically du
1a230 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e ring long runnin
1a240 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20 g calls to.**
1a250 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
1a260 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b step()]..**.** {
1a270 48 31 32 39 31 32 7d 20 54 68 65 20 70 72 6f 67 H12912} The prog
1a280 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 ress callback is
1a290 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f invoked once fo
1a2a0 72 20 65 76 65 72 79 20 4e 20 76 69 72 74 75 61 r every N virtua
1a2b0 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 61 l.** ma
1a2c0 63 68 69 6e 65 20 6f 70 63 6f 64 65 73 2c 20 77 chine opcodes, w
1a2d0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 here N is the se
1a2e0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
1a2f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
1a300 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 [sqlite3_progre
1a310 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 20 63 61 ss_handler()] ca
1a320 6c 6c 20 74 68 61 74 20 72 65 67 69 73 74 65 72 ll that register
1a330 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 ed.** t
1a340 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66 he callback. If
1a350 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 N is less than
1a360 31 2c 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 1, sqlite3_progr
1a370 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a ess_handler().**
1a380 20 20 20 20 20 20 20 20 20 20 61 63 74 73 20 61 acts a
1a390 73 20 69 66 20 61 20 4e 55 4c 4c 20 70 72 6f 67 s if a NULL prog
1a3a0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 68 61 64 ress handler had
1a3b0 20 62 65 65 6e 20 73 70 65 63 69 66 69 65 64 2e been specified.
1a3c0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 33 7d 20 .**.** {H12913}
1a3d0 54 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c The progress cal
1a3e0 6c 62 61 63 6b 20 69 74 73 65 6c 66 20 69 73 20 lback itself is
1a3f0 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 identified by th
1a400 65 20 74 68 69 72 64 0a 2a 2a 20 20 20 20 20 20 e third.**
1a410 20 20 20 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 argument to
1a420 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 sqlite3_progress
1a430 5f 68 61 6e 64 6c 65 72 28 29 2e 0a 2a 2a 0a 2a _handler()..**.*
1a440 2a 20 7b 48 31 32 39 31 34 7d 20 54 68 65 20 66 * {H12914} The f
1a450 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 ourth argument t
1a460 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 o sqlite3_progre
1a470 73 73 5f 68 61 6e 64 6c 65 72 28 29 20 69 73 20 ss_handler() is
1a480 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 6f a.** vo
1a490 69 64 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 id pointer passe
1a4a0 64 20 74 6f 20 74 68 65 20 70 72 6f 67 72 65 73 d to the progres
1a4b0 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 s callback.**
1a4c0 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 function
1a4d0 65 61 63 68 20 74 69 6d 65 20 69 74 20 69 73 20 each time it is
1a4e0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b invoked..**.** {
1a4f0 48 31 32 39 31 35 7d 20 49 66 20 61 20 63 61 6c H12915} If a cal
1a500 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 l to [sqlite3_st
1a510 65 70 28 29 5d 20 72 65 73 75 6c 74 73 20 69 6e ep()] results in
1a520 20 66 65 77 65 72 20 74 68 61 6e 20 4e 20 6f 70 fewer than N op
1a530 63 6f 64 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 codes.**
1a540 20 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 being executed
1a550 2c 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 , then the progr
1a560 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ess callback is
1a570 6e 65 76 65 72 20 69 6e 76 6f 6b 65 64 2e 0a 2a never invoked..*
1a580 2a 0a 2a 2a 20 7b 48 31 32 39 31 36 7d 20 45 76 *.** {H12916} Ev
1a590 65 72 79 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ery call to [sql
1a5a0 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 ite3_progress_ha
1a5b0 6e 64 6c 65 72 28 29 5d 0a 2a 2a 20 20 20 20 20 ndler()].**
1a5c0 20 20 20 20 20 6f 76 65 72 77 72 69 74 65 73 20 overwrites
1a5d0 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 72 any previously r
1a5e0 65 67 69 73 74 65 72 65 64 20 70 72 6f 67 72 65 egistered progre
1a5f0 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a ss handler..**.*
1a600 2a 20 7b 48 31 32 39 31 37 7d 20 49 66 20 74 68 * {H12917} If th
1a610 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c e progress handl
1a620 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e er callback is N
1a630 55 4c 4c 20 74 68 65 6e 20 6e 6f 20 70 72 6f 67 ULL then no prog
1a640 72 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 ress.**
1a650 20 68 61 6e 64 6c 65 72 20 69 73 20 69 6e 76 6f handler is invo
1a660 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 ked..**.** {H129
1a670 31 38 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72 18} If the progr
1a680 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 ess callback ret
1a690 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 6f 74 urns a result ot
1a6a0 68 65 72 20 74 68 61 6e 20 30 2c 20 74 68 65 6e her than 0, then
1a6b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
1a6c0 20 62 65 68 61 76 69 6f 72 20 69 73 20 61 20 69 behavior is a i
1a6d0 66 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 f [sqlite3_inter
1a6e0 72 75 70 74 28 29 5d 20 68 61 64 20 62 65 65 6e rupt()] had been
1a6f0 20 63 61 6c 6c 65 64 2e 0a 2a 2a 20 20 20 20 20 called..**
1a700 20 20 20 20 20 3c 53 33 30 35 30 30 3e 0a 2a 2f <S30500>.*/
1a710 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 .void sqlite3_pr
1a720 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 ogress_handler(s
1a730 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e qlite3*, int, in
1a740 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 t(*)(void*), voi
1a750 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d*);../*.** CAPI
1a760 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 3REF: Opening A
1a770 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e New Database Con
1a780 6e 65 63 74 69 6f 6e 20 7b 48 31 32 37 30 30 7d nection {H12700}
1a790 20 3c 53 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S40200>.**.**
1a7a0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f These routines o
1a7b0 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 pen an SQLite da
1a7c0 74 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73 tabase file whos
1a7d0 65 20 6e 61 6d 65 20 69 73 20 67 69 76 65 6e 20 e name is given
1a7e0 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 by the.** filena
1a7f0 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 65 me argument. The
1a800 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 filename argume
1a810 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 nt is interprete
1a820 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a d as UTF-8 for.*
1a830 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 * sqlite3_open()
1a840 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 and sqlite3_ope
1a850 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 n_v2() and as UT
1a860 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 F-16 in the nati
1a870 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 ve byte.** order
1a880 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 for sqlite3_ope
1a890 6e 31 36 28 29 2e 20 41 20 5b 64 61 74 61 62 61 n16(). A [databa
1a8a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 se connection] h
1a8b0 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 andle is usually
1a8c0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 .** returned in
1a8d0 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 *ppDb, even if a
1a8e0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 n error occurs.
1a8f0 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 The only except
1a900 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 ion is that.** i
1a910 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 f SQLite is unab
1a920 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d le to allocate m
1a930 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 emory to hold th
1a940 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 e [sqlite3] obje
1a950 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 ct,.** a NULL wi
1a960 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e ll be written in
1a970 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 to *ppDb instead
1a980 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f of a pointer to
1a990 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a the [sqlite3].*
1a9a0 2a 20 6f 62 6a 65 63 74 2e 20 49 66 20 74 68 65 * object. If the
1a9b0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
1a9c0 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 ned (and/or crea
1a9d0 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c ted) successfull
1a9e0 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 y, then.** [SQLI
1a9f0 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e TE_OK] is return
1aa00 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 ed. Otherwise a
1aa10 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 n [error code] i
1aa20 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 s returned. The
1aa30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 .** [sqlite3_err
1aa40 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 msg()] or [sqlit
1aa50 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 e3_errmsg16()] r
1aa60 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 outines can be u
1aa70 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a sed to obtain.**
1aa80 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 an English lang
1aa90 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e uage description
1aaa0 20 6f 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a of the error..*
1aab0 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 *.** The default
1aac0 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 encoding for th
1aad0 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 e database will
1aae0 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 be UTF-8 if.** s
1aaf0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 qlite3_open() or
1ab00 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
1ab10 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 () is called and
1ab20 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 .** UTF-16 in th
1ab30 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 e native byte or
1ab40 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f der if sqlite3_o
1ab50 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e pen16() is used.
1ab60 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f .**.** Whether o
1ab70 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f r not an error o
1ab80 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 ccurs when it is
1ab90 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 opened, resourc
1aba0 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 es.** associated
1abb0 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 with the [datab
1abc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
1abd0 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 handle should be
1abe0 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 released by.**
1abf0 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 passing it to [s
1ac00 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 qlite3_close()]
1ac10 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f when it is no lo
1ac20 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a nger required..*
1ac30 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
1ac40 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 _open_v2() inter
1ac50 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 face works like
1ac60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a sqlite3_open().*
1ac70 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 * except that it
1ac80 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 accepts two add
1ac90 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 itional paramete
1aca0 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 rs for additiona
1acb0 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 l control.** ove
1acc0 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 r the new databa
1acd0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 se connection.
1ace0 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 The flags parame
1acf0 74 65 72 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 ter can take one
1ad00 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f of.** the follo
1ad10 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 wing three value
1ad20 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f s, optionally co
1ad30 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 mbined with the
1ad40 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e .** [SQLITE_OPEN
1ad50 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 3a 0a _NOMUTEX] flag:.
1ad60 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 **.** <dl>.** <d
1ad70 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 t>[SQLITE_OPEN_R
1ad80 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a EADONLY]</dt>.**
1ad90 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 <dd>The databas
1ada0 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 e is opened in r
1adb0 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 ead-only mode.
1adc0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 If the database
1add0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 does not.** alre
1ade0 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 ady exist, an er
1adf0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e ror is returned.
1ae00 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
1ae10 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 [SQLITE_OPEN_REA
1ae20 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 DWRITE]</dt>.**
1ae30 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 <dd>The database
1ae40 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 is opened for r
1ae50 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 eading and writi
1ae60 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 ng if possible,
1ae70 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e or reading.** on
1ae80 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 ly if the file i
1ae90 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 s write protecte
1aea0 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 d by the operati
1aeb0 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 ng system. In e
1aec0 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 ither.** case th
1aed0 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 e database must
1aee0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f already exist, o
1aef0 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f therwise an erro
1af00 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f r is returned.</
1af10 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 dd>.**.** <dt>[S
1af20 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
1af30 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f RITE] | [SQLITE_
1af40 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 OPEN_CREATE]</dt
1af50 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 >.** <dd>The dat
1af60 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 abase is opened
1af70 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 for reading and
1af80 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 writing, and is
1af90 63 72 65 61 74 65 73 20 69 74 20 69 66 0a 2a 2a creates it if.**
1afa0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 it does not alr
1afb0 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 eady exist. This
1afc0 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 is the behavior
1afd0 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 that is always
1afe0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 used for.** sqli
1aff0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 te3_open() and s
1b000 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e qlite3_open16().
1b010 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a </dd>.** </dl>.*
1b020 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 *.** If the 3rd
1b030 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
1b040 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 ite3_open_v2() i
1b050 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 s not one of the
1b060 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 .** combinations
1b070 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20 shown above or
1b080 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69 one of the combi
1b090 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 nations shown ab
1b0a0 6f 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 ove combined.**
1b0b0 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 with the [SQLITE
1b0c0 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 _OPEN_NOMUTEX] f
1b0d0 6c 61 67 2c 20 74 68 65 6e 20 74 68 65 20 62 65 lag, then the be
1b0e0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 havior is undefi
1b0f0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ned..**.** If th
1b100 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e e [SQLITE_OPEN_N
1b110 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 OMUTEX] flag is
1b120 73 65 74 2c 20 74 68 65 6e 20 6d 75 74 65 78 65 set, then mutexe
1b130 73 20 6f 6e 20 74 68 65 0a 2a 2a 20 6f 70 65 6e s on the.** open
1b140 65 64 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ed [database con
1b150 6e 65 63 74 69 6f 6e 5d 20 61 72 65 20 64 69 73 nection] are dis
1b160 61 62 6c 65 64 20 61 6e 64 20 74 68 65 20 61 70 abled and the ap
1b170 70 6c 69 61 74 69 6f 6e 20 6d 75 73 74 0a 2a 2a pliation must.**
1b180 20 69 6e 73 75 72 65 20 74 68 61 74 20 61 63 63 insure that acc
1b190 65 73 73 20 74 6f 20 74 68 65 20 5b 64 61 74 61 ess to the [data
1b1a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
1b1b0 20 61 6e 64 20 69 74 73 20 61 73 73 6f 63 69 61 and its associa
1b1c0 74 65 64 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 ted.** [prepared
1b1d0 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 69 73 20 statements] is
1b1e0 73 65 72 69 61 6c 69 7a 65 64 2e 20 20 54 68 65 serialized. The
1b1f0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f [SQLITE_OPEN_NO
1b200 4d 55 54 45 58 5d 20 66 6c 61 67 0a 2a 2a 20 69 MUTEX] flag.** i
1b210 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 62 65 s the default be
1b220 68 61 76 69 6f 72 20 69 73 20 53 51 4c 69 74 65 havior is SQLite
1b230 20 69 73 20 63 6f 6e 66 69 67 75 72 65 64 20 75 is configured u
1b240 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c sing the.** [SQL
1b250 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 ITE_CONFIG_MULTI
1b260 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 THREAD] or [SQLI
1b270 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 TE_CONFIG_SINGLE
1b280 54 48 52 45 41 44 5d 20 6f 70 74 69 6f 6e 73 0a THREAD] options.
1b290 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ** to [sqlite3_c
1b2a0 6f 6e 66 69 67 28 29 5d 2e 20 20 54 68 65 20 5b onfig()]. The [
1b2b0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 SQLITE_OPEN_NOMU
1b2c0 54 45 58 5d 20 66 6c 61 67 20 6f 6e 6c 79 20 6d TEX] flag only m
1b2d0 61 6b 65 73 20 61 0a 2a 2a 20 64 69 66 66 65 72 akes a.** differ
1b2e0 65 6e 63 65 20 77 68 65 6e 20 53 51 4c 69 74 65 ence when SQLite
1b2f0 20 69 73 20 69 6e 20 69 74 73 20 64 65 66 61 75 is in its defau
1b300 6c 74 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 lt [SQLITE_CONFI
1b310 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 20 6d 6f G_SERIALIZED] mo
1b320 64 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 de..**.** If the
1b330 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d filename is ":m
1b340 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 emory:", then a
1b350 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 private, tempora
1b360 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 ry in-memory dat
1b370 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 abase.** is crea
1b380 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e ted for the conn
1b390 65 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 6e ection. This in
1b3a0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 -memory database
1b3b0 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 will vanish whe
1b3c0 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 n.** the databas
1b3d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
1b3e0 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 closed. Future
1b3f0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
1b400 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 te might.** make
1b410 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e use of addition
1b420 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e al special filen
1b430 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 ames that begin
1b440 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 with the ":" cha
1b450 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 racter..** It is
1b460 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 recommended tha
1b470 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 t when a databas
1b480 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 e filename actua
1b490 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 lly does begin w
1b4a0 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 ith.** a ":" cha
1b4b0 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c racter you shoul
1b4c0 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c d prefix the fil
1b4d0 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 ename with a pat
1b4e0 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a hname such as.**
1b4f0 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 "./" to avoid a
1b500 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 mbiguity..**.**
1b510 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 If the filename
1b520 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 is an empty stri
1b530 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 ng, then a priva
1b540 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a te, temporary.**
1b550 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 on-disk databas
1b560 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 e will be create
1b570 64 2e 20 20 54 68 69 73 20 70 72 69 76 61 74 65 d. This private
1b580 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 database will b
1b590 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c e.** automatical
1b5a0 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f ly deleted as so
1b5b0 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 on as the databa
1b5c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
1b5d0 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 closed..**.** T
1b5e0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
1b5f0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f ter to sqlite3_o
1b600 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 pen_v2() is the
1b610 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b name of the.** [
1b620 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
1b630 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 ect that defines
1b640 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 the operating s
1b650 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 ystem interface
1b660 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 that.** the new
1b670 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1b680 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 ion should use.
1b690 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 If the fourth p
1b6a0 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 arameter is.** a
1b6b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 NULL pointer th
1b6c0 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b en the default [
1b6d0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
1b6e0 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a ect is used..**.
1b6f0 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 ** <b>Note to Wi
1b700 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e ndows users:</b>
1b710 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 The encoding u
1b720 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 sed for the file
1b730 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a name argument.**
1b740 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e of sqlite3_open
1b750 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f () and sqlite3_o
1b760 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 pen_v2() must be
1b770 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 UTF-8, not what
1b780 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 ever.** codepage
1b790 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 is currently de
1b7a0 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 fined. Filename
1b7b0 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 s containing int
1b7c0 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 ernational.** ch
1b7d0 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 aracters must be
1b7e0 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 converted to UT
1b7f0 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 F-8 prior to pas
1b800 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a sing them into.*
1b810 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 * sqlite3_open()
1b820 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e or sqlite3_open
1b830 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 _v2()..**.** INV
1b840 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
1b850 48 31 32 37 30 31 7d 20 54 68 65 20 5b 73 71 6c H12701} The [sql
1b860 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 ite3_open()], [s
1b870 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
1b880 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 , and.**
1b890 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f [sqlite3_open_
1b8a0 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 v2()] interfaces
1b8b0 20 63 72 65 61 74 65 20 61 20 6e 65 77 0a 2a 2a create a new.**
1b8c0 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 [datab
1b8d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
1b8e0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a associated with.
1b8f0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
1b900 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 67 69 database file gi
1b910 76 65 6e 20 69 6e 20 74 68 65 69 72 20 66 69 72 ven in their fir
1b920 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a st parameter..**
1b930 0a 2a 2a 20 7b 48 31 32 37 30 32 7d 20 54 68 65 .** {H12702} The
1b940 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 filename argume
1b950 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 nt is interprete
1b960 64 20 61 73 20 55 54 46 2d 38 0a 2a 2a 20 20 20 d as UTF-8.**
1b970 20 20 20 20 20 20 20 66 6f 72 20 5b 73 71 6c 69 for [sqli
1b980 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 te3_open()] and
1b990 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
1b9a0 28 29 5d 20 61 6e 64 20 61 73 20 55 54 46 2d 31 ()] and as UTF-1
1b9b0 36 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 6.** in
1b9c0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 the native byte
1b9d0 20 6f 72 64 65 72 20 66 6f 72 20 5b 73 71 6c 69 order for [sqli
1b9e0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a te3_open16()]..*
1b9f0 2a 0a 2a 2a 20 7b 48 31 32 37 30 33 7d 20 41 20 *.** {H12703} A
1ba00 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 successful invoc
1ba10 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 ation of [sqlite
1ba20 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 3_open()], [sqli
1ba30 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a te3_open16()],.*
1ba40 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 * or [s
1ba50 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
1ba60 5d 20 77 72 69 74 65 73 20 61 20 70 6f 69 6e 74 ] writes a point
1ba70 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 er to a new.**
1ba80 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 [databas
1ba90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e e connection] in
1baa0 74 6f 20 2a 70 70 44 62 2e 0a 2a 2a 0a 2a 2a 20 to *ppDb..**.**
1bab0 7b 48 31 32 37 30 34 7d 20 54 68 65 20 5b 73 71 {H12704} The [sq
1bac0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b lite3_open()], [
1bad0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
1bae0 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 ], and.**
1baf0 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e [sqlite3_open
1bb00 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 _v2()] interface
1bb10 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 s return [SQLITE
1bb20 5f 4f 4b 5d 20 75 70 6f 6e 20 73 75 63 63 65 73 _OK] upon succes
1bb30 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f s,.** o
1bb40 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 r an appropriate
1bb50 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e [error code] on
1bb60 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 failure..**.**
1bb70 7b 48 31 32 37 30 36 7d 20 54 68 65 20 64 65 66 {H12706} The def
1bb80 61 75 6c 74 20 74 65 78 74 20 65 6e 63 6f 64 69 ault text encodi
1bb90 6e 67 20 66 6f 72 20 61 20 6e 65 77 20 64 61 74 ng for a new dat
1bba0 61 62 61 73 65 20 63 72 65 61 74 65 64 20 75 73 abase created us
1bbb0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ing.**
1bbc0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
1bbd0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 or [sqlite3_ope
1bbe0 6e 5f 76 32 28 29 5d 20 77 69 6c 6c 20 62 65 20 n_v2()] will be
1bbf0 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 UTF-8..**.** {H1
1bc00 32 37 30 37 7d 20 54 68 65 20 64 65 66 61 75 6c 2707} The defaul
1bc10 74 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 t text encoding
1bc20 66 6f 72 20 61 20 6e 65 77 20 64 61 74 61 62 61 for a new databa
1bc30 73 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 se created using
1bc40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
1bc50 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 lite3_open16()]
1bc60 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 2e 0a will be UTF-16..
1bc70 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 39 7d 20 54 **.** {H12709} T
1bc80 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e he [sqlite3_open
1bc90 28 46 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 (F,D)] interface
1bca0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 is equivalent t
1bcb0 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 o.** [s
1bcc0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 qlite3_open_v2(F
1bcd0 2c 44 2c 47 2c 30 29 5d 20 77 68 65 72 65 20 74 ,D,G,0)] where t
1bce0 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 69 he G parameter i
1bcf0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 s.** [S
1bd00 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
1bd10 52 49 54 45 5d 7c 5b 53 51 4c 49 54 45 5f 4f 50 RITE]|[SQLITE_OP
1bd20 45 4e 5f 43 52 45 41 54 45 5d 2e 0a 2a 2a 0a 2a EN_CREATE]..**.*
1bd30 2a 20 7b 48 31 32 37 31 31 7d 20 49 66 20 74 68 * {H12711} If th
1bd40 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f e G parameter to
1bd50 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
1bd60 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 2(F,D,G,V)] cont
1bd70 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 ains the.**
1bd80 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b bit value [
1bd90 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
1bda0 4f 4e 4c 59 5d 20 74 68 65 6e 20 74 68 65 20 64 ONLY] then the d
1bdb0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 atabase is opene
1bdc0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f d.** fo
1bdd0 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 2e 0a r reading only..
1bde0 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 32 7d 20 49 **.** {H12712} I
1bdf0 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 f the G paramete
1be00 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 r to [sqlite3_op
1be10 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 en_v2(F,D,G,V)]
1be20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 contains the.**
1be30 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c bit val
1be40 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ue [SQLITE_OPEN_
1be50 52 45 41 44 57 52 49 54 45 5d 20 74 68 65 6e 20 READWRITE] then
1be60 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 the database is
1be70 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 opened.**
1be80 20 20 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 reading and w
1be90 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 riting if possib
1bea0 6c 65 2c 20 6f 72 20 66 6f 72 20 72 65 61 64 69 le, or for readi
1beb0 6e 67 20 6f 6e 6c 79 20 69 66 20 74 68 65 0a 2a ng only if the.*
1bec0 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 20 * file
1bed0 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 is write protect
1bee0 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 ed by the operat
1bef0 69 6e 67 20 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a ing system..**.*
1bf00 2a 20 7b 48 31 32 37 31 33 7d 20 49 66 20 74 68 * {H12713} If th
1bf10 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f e G parameter to
1bf20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 76 [sqlite3_open(v
1bf30 32 28 46 2c 44 2c 47 2c 56 29 5d 20 6f 6d 69 74 2(F,D,G,V)] omit
1bf40 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 s the.**
1bf50 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c bit value [SQL
1bf60 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d ITE_OPEN_CREATE]
1bf70 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 and the databas
1bf80 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 e does not.**
1bf90 20 20 20 20 20 20 20 70 72 65 76 69 6f 75 73 6c previousl
1bfa0 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f y exist, an erro
1bfb0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a r is returned..*
1bfc0 2a 0a 2a 2a 20 7b 48 31 32 37 31 34 7d 20 49 66 *.** {H12714} If
1bfd0 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 the G parameter
1bfe0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 to [sqlite3_ope
1bff0 6e 28 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 n(v2(F,D,G,V)] c
1c000 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 ontains the.**
1c010 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 bit valu
1c020 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 e [SQLITE_OPEN_C
1c030 52 45 41 54 45 5d 20 61 6e 64 20 74 68 65 20 64 REATE] and the d
1c040 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 atabase does not
1c050 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 65 .** pre
1c060 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 74 viously exist, t
1c070 68 65 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 69 hen an attempt i
1c080 73 20 6d 61 64 65 20 74 6f 20 63 72 65 61 74 65 s made to create
1c090 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 and.**
1c0a0 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 initialize the
1c0b0 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 database..**.**
1c0c0 7b 48 31 32 37 31 37 7d 20 49 66 20 74 68 65 20 {H12717} If the
1c0d0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e filename argumen
1c0e0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 t to [sqlite3_op
1c0f0 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f en()], [sqlite3_
1c100 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 open16()],.**
1c110 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 or [sqlit
1c120 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73 e3_open_v2()] is
1c130 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 ":memory:", the
1c140 6e 20 61 6e 20 70 72 69 76 61 74 65 2c 0a 2a 2a n an private,.**
1c150 20 20 20 20 20 20 20 20 20 20 65 70 68 65 6d 65 epheme
1c160 72 61 6c 2c 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 ral, in-memory d
1c170 61 74 61 62 61 73 65 20 69 73 20 63 72 65 61 74 atabase is creat
1c180 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 ed for the conne
1c190 63 74 69 6f 6e 2e 0a 2a 2a 20 20 20 20 20 20 20 ction..**
1c1a0 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 <todo>Is SQLI
1c1b0 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 TE_OPEN_CREATE|S
1c1c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
1c1d0 52 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a RITE required.**
1c1e0 20 20 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c in sql
1c1f0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c ite3_open_v2()?<
1c200 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 /todo>.**.** {H1
1c210 32 37 31 39 7d 20 49 66 20 74 68 65 20 66 69 6c 2719} If the fil
1c220 65 6e 61 6d 65 20 69 73 20 4e 55 4c 4c 20 6f 72 ename is NULL or
1c230 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
1c240 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 , then a private
1c250 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 70 ,.** ep
1c260 68 65 6d 65 72 61 6c 20 6f 6e 2d 64 69 73 6b 20 hemeral on-disk
1c270 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 database will be
1c280 20 63 72 65 61 74 65 64 2e 0a 2a 2a 20 20 20 20 created..**
1c290 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53 <todo>Is S
1c2a0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
1c2b0 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 E|SQLITE_OPEN_RE
1c2c0 41 44 57 52 49 54 45 20 72 65 71 75 69 72 65 64 ADWRITE required
1c2d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 .** in
1c2e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
1c2f0 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 )?</todo>.**.**
1c300 7b 48 31 32 37 32 31 7d 20 54 68 65 20 5b 64 61 {H12721} The [da
1c310 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1c320 6e 5d 20 63 72 65 61 74 65 64 20 62 79 20 5b 73 n] created by [s
1c330 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 qlite3_open_v2(F
1c340 2c 44 2c 47 2c 56 29 5d 0a 2a 2a 20 20 20 20 20 ,D,G,V)].**
1c350 20 20 20 20 20 77 69 6c 6c 20 75 73 65 20 74 68 will use th
1c360 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 e [sqlite3_vfs]
1c370 6f 62 6a 65 63 74 20 69 64 65 6e 74 69 66 69 65 object identifie
1c380 64 20 62 79 20 74 68 65 20 56 20 70 61 72 61 6d d by the V param
1c390 65 74 65 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 eter,.**
1c3a0 20 20 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 or the default
1c3b0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f [sqlite3_vfs] o
1c3c0 62 6a 65 63 74 20 69 66 20 56 20 69 73 20 61 20 bject if V is a
1c3d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
1c3e0 0a 2a 2a 20 7b 48 31 32 37 32 33 7d 20 54 77 6f .** {H12723} Two
1c3f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
1c400 63 74 69 6f 6e 73 5d 20 77 69 6c 6c 20 73 68 61 ctions] will sha
1c410 72 65 20 61 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 re a common cach
1c420 65 20 69 66 20 62 6f 74 68 20 77 65 72 65 0a 2a e if both were.*
1c430 2a 20 20 20 20 20 20 20 20 20 20 6f 70 65 6e 65 * opene
1c440 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 d with the same
1c450 56 46 53 20 77 68 69 6c 65 20 5b 73 68 61 72 65 VFS while [share
1c460 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 77 61 d cache mode] wa
1c470 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 0a 2a 2a s enabled and.**
1c480 20 20 20 20 20 20 20 20 20 20 69 66 20 62 6f 74 if bot
1c490 68 20 66 69 6c 65 6e 61 6d 65 73 20 63 6f 6d 70 h filenames comp
1c4a0 61 72 65 20 65 71 75 61 6c 20 75 73 69 6e 67 20 are equal using
1c4b0 6d 65 6d 63 6d 70 28 29 20 61 66 74 65 72 20 68 memcmp() after h
1c4c0 61 76 69 6e 67 20 62 65 65 6e 0a 2a 2a 20 20 20 aving been.**
1c4d0 20 20 20 20 20 20 20 70 72 6f 63 65 73 73 65 64 processed
1c4e0 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 by the [sqlite3
1c4f0 5f 76 66 73 20 7c 20 78 46 75 6c 6c 50 61 74 68 _vfs | xFullPath
1c500 6e 61 6d 65 5d 20 6d 65 74 68 6f 64 20 6f 66 20 name] method of
1c510 74 68 65 20 56 46 53 2e 0a 2a 2f 0a 69 6e 74 20 the VFS..*/.int
1c520 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 sqlite3_open(.
1c530 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 const char *file
1c540 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 name, /* Datab
1c550 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 ase filename (UT
1c560 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 F-8) */. sqlite
1c570 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 3 **ppDb
1c580 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 /* OUT: SQLite
1c590 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b db handle */.);
1c5a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 .int sqlite3_ope
1c5b0 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 n16(. const voi
1c5c0 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f d *filename, /
1c5d0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e * Database filen
1c5e0 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a ame (UTF-16) */.
1c5f0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 sqlite3 **ppDb
1c600 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 /* OUT
1c610 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 : SQLite db hand
1c620 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c le */.);.int sql
1c630 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 ite3_open_v2(.
1c640 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 const char *file
1c650 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 name, /* Datab
1c660 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 ase filename (UT
1c670 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 F-8) */. sqlite
1c680 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 3 **ppDb,
1c690 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 /* OUT: SQLite
1c6a0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 db handle */.
1c6b0 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 int flags,
1c6c0 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 /* Flags
1c6d0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
1c6e0 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a *zVfs /*
1c6f0 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 Name of VFS mod
1c700 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b ule to use */.);
1c710 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1c720 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e : Error Codes An
1c730 64 20 4d 65 73 73 61 67 65 73 20 7b 48 31 32 38 d Messages {H128
1c740 30 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 0a 00} <S60200>.**.
1c750 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 ** The sqlite3_e
1c760 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 rrcode() interfa
1c770 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e ce returns the n
1c780 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 umeric [result c
1c790 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 ode] or.** [exte
1c7a0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
1c7b0 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 ] for the most r
1c7c0 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c ecent failed sql
1c7d0 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a ite3_* API call.
1c7e0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ** associated wi
1c7f0 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 th a [database c
1c800 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 onnection]. If a
1c810 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 prior API call
1c820 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 failed.** but th
1c830 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 e most recent AP
1c840 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 I call succeeded
1c850 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c , the return val
1c860 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 ue from.** sqlit
1c870 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 e3_errcode() is
1c880 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
1c890 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 The sqlite3_err
1c8a0 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 msg() and sqlite
1c8b0 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 3_errmsg16() ret
1c8c0 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 urn English-lang
1c8d0 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 uage.** text tha
1c8e0 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 t describes the
1c8f0 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 error, as either
1c900 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 UTF-8 or UTF-16
1c910 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a respectively..*
1c920 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 * Memory to hold
1c930 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
1c940 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e ge string is man
1c950 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e aged internally.
1c960 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
1c970 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 ion does not nee
1c980 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 d to worry about
1c990 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 freeing the res
1c9a0 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c ult..** However,
1c9b0 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e the error strin
1c9c0 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 g might be overw
1c9d0 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f ritten or deallo
1c9e0 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 cated by.** subs
1c9f0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 equent calls to
1ca00 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 other SQLite int
1ca10 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 erface functions
1ca20 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e ..**.** If an in
1ca30 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 terface fails wi
1ca40 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 th SQLITE_MISUSE
1ca50 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 , that means the
1ca60 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 interface.** wa
1ca70 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 s invoked incorr
1ca80 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 ectly by the app
1ca90 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 lication. In th
1caa0 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 at case, the.**
1cab0 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d error code and m
1cac0 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 essage may or ma
1cad0 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2a y not be set..**
1cae0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
1caf0 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 31 7d 20 54 **.** {H12801} T
1cb00 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 he [sqlite3_errc
1cb10 6f 64 65 28 44 29 5d 20 69 6e 74 65 72 66 61 63 ode(D)] interfac
1cb20 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 e returns the nu
1cb30 6d 65 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 meric.**
1cb40 20 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 [result code]
1cb50 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 or [extended res
1cb60 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 ult code] for th
1cb70 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 0a e most recently.
1cb80 2a 2a 20 20 20 20 20 20 20 20 20 20 66 61 69 6c ** fail
1cb90 65 64 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c ed interface cal
1cba0 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 l associated wit
1cbb0 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 h the [database
1cbc0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a connection] D..*
1cbd0 2a 0a 2a 2a 20 7b 48 31 32 38 30 33 7d 20 54 68 *.** {H12803} Th
1cbe0 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 e [sqlite3_errms
1cbf0 67 28 44 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 g(D)] and [sqlit
1cc00 65 33 5f 65 72 72 6d 73 67 31 36 28 44 29 5d 0a e3_errmsg16(D)].
1cc10 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 ** inte
1cc20 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 45 6e rfaces return En
1cc30 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 glish-language t
1cc40 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 ext that describ
1cc50 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 es.** t
1cc60 68 65 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20 he error in the
1cc70 6d 6f 73 74 6c 79 20 72 65 63 65 6e 74 6c 79 20 mostly recently
1cc80 66 61 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65 failed interface
1cc90 20 63 61 6c 6c 2c 0a 2a 2a 20 20 20 20 20 20 20 call,.**
1cca0 20 20 20 65 6e 63 6f 64 65 64 20 61 73 20 65 69 encoded as ei
1ccb0 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 ther UTF-8 or UT
1ccc0 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c F-16 respectivel
1ccd0 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 37 y..**.** {H12807
1cce0 7d 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 } The strings re
1ccf0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
1cd00 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 e3_errmsg()] and
1cd10 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
1cd20 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 16()].**
1cd30 20 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 are valid unti
1cd40 6c 20 74 68 65 20 6e 65 78 74 20 53 51 4c 69 74 l the next SQLit
1cd50 65 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c e interface call
1cd60 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 38 7d ..**.** {H12808}
1cd70 20 43 61 6c 6c 73 20 74 6f 20 41 50 49 20 72 6f Calls to API ro
1cd80 75 74 69 6e 65 73 20 74 68 61 74 20 64 6f 20 6e utines that do n
1cd90 6f 74 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 ot return an err
1cda0 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 or code.**
1cdb0 20 20 20 20 28 65 78 61 6d 70 6c 65 3a 20 5b 73 (example: [s
1cdc0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
1cdd0 74 28 29 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20 t()]) do not.**
1cde0 20 20 20 20 20 20 20 20 20 63 68 61 6e 67 65 20 change
1cdf0 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 6f the error code o
1ce00 72 20 6d 65 73 73 61 67 65 20 72 65 74 75 72 6e r message return
1ce10 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 ed by.**
1ce20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f [sqlite3_errco
1ce30 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f de()], [sqlite3_
1ce40 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73 errmsg()], or [s
1ce50 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 qlite3_errmsg16(
1ce60 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 )]..**.** {H1280
1ce70 39 7d 20 49 6e 74 65 72 66 61 63 65 73 20 74 68 9} Interfaces th
1ce80 61 74 20 61 72 65 20 6e 6f 74 20 61 73 73 6f 63 at are not assoc
1ce90 69 61 74 65 64 20 77 69 74 68 20 61 20 73 70 65 iated with a spe
1cea0 63 69 66 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 cific.**
1ceb0 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e [database conn
1cec0 65 63 74 69 6f 6e 5d 20 28 65 78 61 6d 70 6c 65 ection] (example
1ced0 73 3a 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b s:.** [
1cee0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
1cef0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 )] or [sqlite3_e
1cf00 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 nable_shared_cac
1cf10 68 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 he()].**
1cf20 20 20 64 6f 20 6e 6f 74 20 63 68 61 6e 67 65 20 do not change
1cf30 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 the values retur
1cf40 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 ned by.**
1cf50 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 [sqlite3_errc
1cf60 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 ode()], [sqlite3
1cf70 5f 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b _errmsg()], or [
1cf80 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 sqlite3_errmsg16
1cf90 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ()]..*/.int sqli
1cfa0 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 te3_errcode(sqli
1cfb0 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 te3 *db);.const
1cfc0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 char *sqlite3_er
1cfd0 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a rmsg(sqlite3*);.
1cfe0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
1cff0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c te3_errmsg16(sql
1d000 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ite3*);../*.** C
1d010 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 API3REF: SQL Sta
1d020 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 tement Object {H
1d030 31 33 30 30 30 7d 20 3c 48 31 33 30 31 30 3e 0a 13000} <H13010>.
1d040 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 ** KEYWORDS: {pr
1d050 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1d060 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 } {prepared stat
1d070 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e ements}.**.** An
1d080 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 instance of thi
1d090 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 s object represe
1d0a0 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c nts a single SQL
1d0b0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 statement..** T
1d0c0 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 his object is va
1d0d0 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 riously known as
1d0e0 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 a "prepared sta
1d0f0 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 tement" or a.**
1d100 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 "compiled SQL st
1d110 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 atement" or simp
1d120 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 ly as a "stateme
1d130 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c nt"..**.** The l
1d140 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 ife of a stateme
1d150 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 nt object goes s
1d160 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 omething like th
1d170 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a is:.**.** <ol>.*
1d180 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 * <li> Create th
1d190 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b e object using [
1d1a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1d1b0 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 v2()] or a relat
1d1c0 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 ed.** funct
1d1d0 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e ion..** <li> Bin
1d1e0 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 d values to [hos
1d1f0 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 t parameters] us
1d200 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f ing the sqlite3_
1d210 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 bind_*().**
1d220 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 interfaces..**
1d230 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c <li> Run the SQL
1d240 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c by calling [sql
1d250 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 ite3_step()] one
1d260 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a or more times..
1d270 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 ** <li> Reset th
1d280 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e e statement usin
1d290 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 g [sqlite3_reset
1d2a0 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b ()] then go back
1d2b0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 .** to step
1d2c0 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 2. Do this zer
1d2d0 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e o or more times.
1d2e0 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 .** <li> Destroy
1d2f0 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e the object usin
1d300 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c g [sqlite3_final
1d310 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e ize()]..** </ol>
1d320 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 .**.** Refer to
1d330 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e documentation on
1d340 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 individual meth
1d350 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 ods above for ad
1d360 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f ditional.** info
1d370 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 rmation..*/.type
1d380 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
1d390 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f e3_stmt sqlite3_
1d3a0 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 stmt;../*.** CAP
1d3b0 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 I3REF: Run-time
1d3c0 4c 69 6d 69 74 73 20 7b 48 31 32 37 36 30 7d 20 Limits {H12760}
1d3d0 3c 53 32 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S20600>.**.** T
1d3e0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c his interface al
1d3f0 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 lows the size of
1d400 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 various constru
1d410 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 cts to be limite
1d420 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 d.** on a connec
1d430 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 tion by connecti
1d440 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 on basis. The f
1d450 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 irst parameter i
1d460 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 s the.** [databa
1d470 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 se connection] w
1d480 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f hose limit is to
1d490 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 be set or queri
1d4a0 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f ed. The.** seco
1d4b0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
1d4c0 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 one of the [limi
1d4d0 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 t categories] th
1d4e0 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 at define a.** c
1d4f0 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 lass of construc
1d500 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 ts to be size li
1d510 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 mited. The thir
1d520 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 d parameter is t
1d530 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 he.** new limit
1d540 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 for that constru
1d550 63 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f ct. The functio
1d560 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6f 6c n returns the ol
1d570 64 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 d limit..**.** I
1d580 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 f the new limit
1d590 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 is a negative nu
1d5a0 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 mber, the limit
1d5b0 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a is unchanged..**
1d5c0 20 46 6f 72 20 74 68 65 20 6c 69 6d 69 74 20 63 For the limit c
1d5d0 61 74 65 67 6f 72 79 20 6f 66 20 53 51 4c 49 54 ategory of SQLIT
1d5e0 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65 72 E_LIMIT_XYZ ther
1d5f0 65 20 69 73 20 61 20 68 61 72 64 20 75 70 70 65 e is a hard uppe
1d600 72 0a 2a 2a 20 62 6f 75 6e 64 20 73 65 74 20 62 r.** bound set b
1d610 79 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 y a compile-time
1d620 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 C preprocessor
1d630 6d 61 63 72 6f 20 6e 61 6d 65 64 20 53 51 4c 49 macro named SQLI
1d640 54 45 5f 4d 41 58 5f 58 59 5a 2e 0a 2a 2a 20 28 TE_MAX_XYZ..** (
1d650 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e The "_LIMIT_" in
1d660 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 the name is cha
1d670 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e nged to "_MAX_".
1d680 29 0a 2a 2a 20 41 74 74 65 6d 70 74 73 20 74 6f ).** Attempts to
1d690 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 increase a limi
1d6a0 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 t above its hard
1d6b0 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 upper bound are
1d6c0 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 .** silently tru
1d6d0 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 ncated to the ha
1d6e0 72 64 20 75 70 70 65 72 20 6c 69 6d 69 74 2e 0a rd upper limit..
1d6f0 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d 65 20 6c **.** Run time l
1d700 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 imits are intend
1d710 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 ed for use in ap
1d720 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 plications that
1d730 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 manage.** both t
1d740 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 heir own interna
1d750 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 l database and a
1d760 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 lso databases th
1d770 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 at are controlle
1d780 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 d.** by untruste
1d790 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 d external sourc
1d7a0 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 es. An example
1d7b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 application migh
1d7c0 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 62 72 6f t be a.** webbro
1d7d0 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74 wser that has it
1d7e0 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 s own databases
1d7f0 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 for storing hist
1d800 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 ory and.** separ
1d810 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f ate databases co
1d820 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 ntrolled by Java
1d830 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 Script applicati
1d840 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a ons downloaded.*
1d850 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e * off the Intern
1d860 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 et. The interna
1d870 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 l databases can
1d880 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 be given the.**
1d890 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c large, default l
1d8a0 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 imits. Database
1d8b0 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 s managed by ext
1d8c0 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 ernal sources ca
1d8d0 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 n.** be given mu
1d8e0 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 ch smaller limit
1d8f0 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 s designed to pr
1d900 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f event a denial o
1d910 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 f service.** att
1d920 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 ack. Developers
1d930 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 might also want
1d940 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c to use the [sql
1d950 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
1d960 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 zer()].** interf
1d970 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 ace to further c
1d980 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 ontrol untrusted
1d990 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 SQL. The size
1d9a0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a of the database.
1d9b0 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e ** created by an
1d9c0 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 untrusted scrip
1d9d0 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e t can be contain
1d9e0 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 ed using the.**
1d9f0 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d [max_page_count]
1da00 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a [PRAGMA]..**.**
1da10 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 New run-time li
1da20 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d mit categories m
1da30 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 ay be added in f
1da40 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a uture releases..
1da50 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
1da60 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 32 7d :.**.** {H12762}
1da70 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 A successful ca
1da80 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c ll to [sqlite3_l
1da90 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20 77 68 65 imit(D,C,V)] whe
1daa0 72 65 20 56 20 69 73 0a 2a 2a 20 20 20 20 20 20 re V is.**
1dab0 20 20 20 20 70 6f 73 69 74 69 76 65 20 63 68 61 positive cha
1dac0 6e 67 65 73 20 74 68 65 20 6c 69 6d 69 74 20 6f nges the limit o
1dad0 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 63 6f n the size of co
1dae0 6e 73 74 72 75 63 74 20 43 20 69 6e 20 74 68 65 nstruct C in the
1daf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 .** [da
1db00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1db10 6e 5d 20 44 20 74 6f 20 74 68 65 20 6c 65 73 73 n] D to the less
1db20 65 72 20 6f 66 20 56 20 61 6e 64 20 74 68 65 20 er of V and the
1db30 68 61 72 64 20 75 70 70 65 72 0a 2a 2a 20 20 20 hard upper.**
1db40 20 20 20 20 20 20 20 62 6f 75 6e 64 20 6f 6e 20 bound on
1db50 74 68 65 20 73 69 7a 65 20 6f 66 20 43 20 74 68 the size of C th
1db60 61 74 20 69 73 20 73 65 74 20 61 74 20 63 6f 6d at is set at com
1db70 70 69 6c 65 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a pile-time..**.**
1db80 20 7b 48 31 32 37 36 36 7d 20 41 20 73 75 63 63 {H12766} A succ
1db90 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b essful call to [
1dba0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c sqlite3_limit(D,
1dbb0 43 2c 56 29 5d 20 77 68 65 72 65 20 56 20 69 73 C,V)] where V is
1dbc0 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 negative.**
1dbd0 20 20 20 20 20 20 6c 65 61 76 65 73 20 74 68 65 leaves the
1dbe0 20 73 74 61 74 65 20 6f 66 20 74 68 65 20 5b 64 state of the [d
1dbf0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1dc00 6f 6e 5d 20 44 20 75 6e 63 68 61 6e 67 65 64 2e on] D unchanged.
1dc10 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 39 7d 20 .**.** {H12769}
1dc20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c A successful cal
1dc30 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 l to [sqlite3_li
1dc40 6d 69 74 28 44 2c 43 2c 56 29 5d 20 72 65 74 75 mit(D,C,V)] retu
1dc50 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 rns the.**
1dc60 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 value of the
1dc70 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 73 69 limit on the si
1dc80 7a 65 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 20 ze of construct
1dc90 43 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 C in the.**
1dca0 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 [database c
1dcb0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 61 73 20 onnection] D as
1dcc0 69 74 20 77 61 73 20 70 72 69 6f 72 20 74 6f 20 it was prior to
1dcd0 74 68 65 20 63 61 6c 6c 2e 0a 2a 2f 0a 69 6e 74 the call..*/.int
1dce0 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 sqlite3_limit(s
1dcf0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c qlite3*, int id,
1dd00 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f int newVal);../
1dd10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
1dd20 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 un-Time Limit Ca
1dd30 74 65 67 6f 72 69 65 73 20 7b 48 31 32 37 39 30 tegories {H12790
1dd40 7d 20 3c 48 31 32 37 36 30 3e 0a 2a 2a 20 4b 45 } <H12760>.** KE
1dd50 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 YWORDS: {limit c
1dd60 61 74 65 67 6f 72 79 7d 20 7b 6c 69 6d 69 74 20 ategory} {limit
1dd70 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a categories}.**.*
1dd80 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 * These constant
1dd90 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 s define various
1dda0 20 61 73 70 65 63 74 73 20 6f 66 20 61 20 5b 64 aspects of a [d
1ddb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1ddc0 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 on].** that can
1ddd0 62 65 20 6c 69 6d 69 74 65 64 20 69 6e 20 73 69 be limited in si
1dde0 7a 65 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 5b ze by calls to [
1ddf0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d sqlite3_limit()]
1de00 2e 0a 2a 2a 20 54 68 65 20 6d 65 61 6e 69 6e 67 ..** The meaning
1de10 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 s of the various
1de20 20 6c 69 6d 69 74 73 20 61 72 65 20 61 73 20 66 limits are as f
1de30 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 ollows:.**.** <d
1de40 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 l>.** <dt>SQLITE
1de50 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 _LIMIT_LENGTH</d
1de60 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
1de70 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e ximum size of an
1de80 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 y string or BLOB
1de90 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64 or table row.<d
1dea0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
1deb0 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 ITE_LIMIT_SQL_LE
1dec0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 NGTH</dt>.** <dd
1ded0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e >The maximum len
1dee0 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 gth of an SQL st
1def0 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a atement.</dd>.**
1df00 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c .** <dt>SQLITE_L
1df10 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e IMIT_COLUMN</dt>
1df20 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
1df30 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f mum number of co
1df40 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 lumns in a table
1df50 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 definition or i
1df60 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 n the.** result
1df70 73 65 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 set of a SELECT
1df80 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e or the maximum n
1df90 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
1dfa0 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 in an index.**
1dfb0 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 or in an ORDER B
1dfc0 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c Y or GROUP BY cl
1dfd0 61 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ause.</dd>.**.**
1dfe0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 <dt>SQLITE_LIMI
1dff0 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 T_EXPR_DEPTH</dt
1e000 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
1e010 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 imum depth of th
1e020 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 e parse tree on
1e030 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c any expression.<
1e040 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
1e050 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 QLITE_LIMIT_COMP
1e060 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e OUND_SELECT</dt>
1e070 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
1e080 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 mum number of te
1e090 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e rms in a compoun
1e0a0 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 d SELECT stateme
1e0b0 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c nt.</dd>.**.** <
1e0c0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
1e0d0 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 VDBE_OP</dt>.**
1e0e0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
1e0f0 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 number of instru
1e100 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 ctions in a virt
1e110 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 ual machine prog
1e120 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 ram.** used to i
1e130 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 mplement an SQL
1e140 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a statement.</dd>.
1e150 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
1e160 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f _LIMIT_FUNCTION_
1e170 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ARG</dt>.** <dd>
1e180 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
1e190 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 er of arguments
1e1a0 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f on a function.</
1e1b0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
1e1c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 LITE_LIMIT_ATTAC
1e1d0 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e HED</dt>.** <dd>
1e1e0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
1e1f0 65 72 20 6f 66 20 61 74 74 61 63 68 65 64 20 64 er of attached d
1e200 61 74 61 62 61 73 65 73 2e 3c 2f 64 64 3e 0a 2a atabases.</dd>.*
1e210 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
1e220 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 LIMIT_LIKE_PATTE
1e230 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a RN_LENGTH</dt>.*
1e240 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
1e250 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 m length of the
1e260 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 pattern argument
1e270 20 74 6f 20 74 68 65 20 4c 49 4b 45 20 6f 72 0a to the LIKE or.
1e280 2a 2a 20 47 4c 4f 42 20 6f 70 65 72 61 74 6f 72 ** GLOB operator
1e290 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 s.</dd>.**.** <d
1e2a0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 t>SQLITE_LIMIT_V
1e2b0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f ARIABLE_NUMBER</
1e2c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
1e2d0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
1e2e0 20 76 61 72 69 61 62 6c 65 73 20 69 6e 20 61 6e variables in an
1e2f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
1e300 68 61 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f hat can.** be bo
1e310 75 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 und.</dd>.** </d
1e320 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 l>.*/.#define SQ
1e330 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 LITE_LIMIT_LENGT
1e340 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 H
1e350 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 0.#define S
1e360 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f QLITE_LIMIT_SQL_
1e370 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 LENGTH
1e380 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 1.#define
1e390 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c SQLITE_LIMIT_COL
1e3a0 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 UMN
1e3b0 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 2.#define
1e3c0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 SQLITE_LIMIT_EX
1e3d0 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 PR_DEPTH
1e3e0 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 3.#defin
1e3f0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 e SQLITE_LIMIT_C
1e400 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 OMPOUND_SELECT
1e410 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 4.#defi
1e420 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
1e430 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 VDBE_OP
1e440 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 5.#def
1e450 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
1e460 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 _FUNCTION_ARG
1e470 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 6.#de
1e480 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
1e490 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 T_ATTACHED
1e4a0 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 7.#d
1e4b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
1e4c0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f IT_LIKE_PATTERN_
1e4d0 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 LENGTH 8.#
1e4e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
1e4f0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d MIT_VARIABLE_NUM
1e500 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a BER 9.
1e510 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1e520 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 Compiling An SQ
1e530 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 L Statement {H13
1e540 30 31 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 010} <S10000>.**
1e550 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 KEYWORDS: {SQL
1e560 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c statement compil
1e570 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 er}.**.** To exe
1e580 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 cute an SQL quer
1e590 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 y, it must first
1e5a0 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 be compiled int
1e5b0 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a o a byte-code.**
1e5c0 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f program using o
1e5d0 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ne of these rout
1e5e0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ines..**.** The
1e5f0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 first argument,
1e600 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 "db", is a [data
1e610 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
1e620 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 obtained from a
1e630 0a 2a 2a 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 .** prior call t
1e640 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 o [sqlite3_open(
1e650 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
1e660 6e 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 n_v2()] or [sqli
1e670 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a te3_open16()]..*
1e680 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 *.** The second
1e690 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 argument, "zSql"
1e6a0 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 , is the stateme
1e6b0 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 nt to be compile
1e6c0 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 d, encoded.** as
1e6d0 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 either UTF-8 or
1e6e0 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 UTF-16. The sq
1e6f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 lite3_prepare()
1e700 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 and sqlite3_prep
1e710 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 are_v2().** inte
1e720 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 rfaces use UTF-8
1e730 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 , and sqlite3_pr
1e740 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 epare16() and sq
1e750 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
1e760 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d v2().** use UTF-
1e770 31 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 16..**.** If the
1e780 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 nByte argument
1e790 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 is less than zer
1e7a0 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 o, then zSql is
1e7b0 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a read up to the.*
1e7c0 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 * first zero ter
1e7d0 6d 69 6e 61 74 6f 72 2e 20 49 66 20 6e 42 79 74 minator. If nByt
1e7e0 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 e is non-negativ
1e7f0 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 e, then it is th
1e800 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d e maximum.** num
1e810 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 ber of bytes re
1e820 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 ad from zSql. W
1e830 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e hen nByte is non
1e840 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a -negative, the.*
1e850 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e * zSql string en
1e860 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 ds at either the
1e870 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 first '\000' or
1e880 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 '\u0000' charac
1e890 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 ter or.** the nB
1e8a0 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 yte-th byte, whi
1e8b0 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 chever comes fir
1e8c0 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 st. If the calle
1e8d0 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 r knows.** that
1e8e0 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 the supplied str
1e8f0 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 ing is nul-termi
1e900 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 nated, then ther
1e910 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 e is a small.**
1e920 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 performance adva
1e930 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e ntage to be gain
1e940 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e ed by passing an
1e950 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 nByte parameter
1e960 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 that.** is equa
1e970 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 l to the number
1e980 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 of bytes in the
1e990 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e input string <i>
1e9a0 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a including</i>.**
1e9b0 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 the nul-termina
1e9c0 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a tor bytes..**.**
1e9d0 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 *pzTail is made
1e9e0 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 to point to the
1e9f0 20 66 69 72 73 74 20 62 79 74 65 20 70 61 73 74 first byte past
1ea00 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 0a the end of the.
1ea10 2a 2a 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 ** first SQL sta
1ea20 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 tement in zSql.
1ea30 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
1ea40 6f 6e 6c 79 20 63 6f 6d 70 69 6c 65 20 74 68 65 only compile the
1ea50 20 66 69 72 73 74 0a 2a 2a 20 73 74 61 74 65 6d first.** statem
1ea60 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 ent in zSql, so
1ea70 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 *pzTail is left
1ea80 70 6f 69 6e 74 69 6e 67 20 74 6f 20 77 68 61 74 pointing to what
1ea90 20 72 65 6d 61 69 6e 73 0a 2a 2a 20 75 6e 63 6f remains.** unco
1eaa0 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 mpiled..**.** *p
1eab0 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f pStmt is left po
1eac0 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 inting to a comp
1ead0 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 iled [prepared s
1eae0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 tatement] that c
1eaf0 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 an be.** execute
1eb00 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
1eb10 5f 73 74 65 70 28 29 5d 2e 20 20 49 66 20 74 68 _step()]. If th
1eb20 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c ere is an error,
1eb30 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a *ppStmt is set.
1eb40 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 ** to NULL. If
1eb50 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 the input text c
1eb60 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 ontains no SQL (
1eb70 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 if the input is
1eb80 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 an empty.** stri
1eb90 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 ng or a comment)
1eba0 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 then *ppStmt is
1ebb0 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a set to NULL..**
1ebc0 20 7b 41 31 33 30 31 38 7d 20 54 68 65 20 63 61 {A13018} The ca
1ebd0 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 lling procedure
1ebe0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 is responsible f
1ebf0 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 or deleting the
1ec00 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 compiled.** SQL
1ec10 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 statement using
1ec20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
1ec30 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 e()] after it ha
1ec40 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 s finished with
1ec50 69 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 it..**.** On suc
1ec60 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b cess, [SQLITE_OK
1ec70 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2c 20 6f ] is returned, o
1ec80 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 therwise an [err
1ec90 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 or code] is retu
1eca0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 rned..**.** The
1ecb0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1ecc0 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 v2() and sqlite3
1ecd0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 _prepare16_v2()
1ece0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a interfaces are.*
1ecf0 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f * recommended fo
1ed00 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 r all new progra
1ed10 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 ms. The two olde
1ed20 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 r interfaces are
1ed30 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 retained.** for
1ed40 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 backwards compa
1ed50 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 tibility, but th
1ed60 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f eir use is disco
1ed70 75 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 uraged..** In th
1ed80 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 e "v2" interface
1ed90 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 s, the prepared
1eda0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 statement.** tha
1edb0 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 t is returned (t
1edc0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 he [sqlite3_stmt
1edd0 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 ] object) contai
1ede0 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 ns a copy of the
1edf0 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c .** original SQL
1ee00 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 text. This caus
1ee10 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f es the [sqlite3_
1ee20 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 step()] interfac
1ee30 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 e to.** behave a
1ee40 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 differently in
1ee50 74 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 two ways:.**.**
1ee60 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 <ol>.** <li>.**
1ee70 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 If the database
1ee80 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 schema changes,
1ee90 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 instead of retur
1eea0 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 ning [SQLITE_SCH
1eeb0 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c EMA] as it.** al
1eec0 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c ways used to do,
1eed0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
1eee0 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 ] will automatic
1eef0 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 ally recompile t
1ef00 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d he SQL.** statem
1ef10 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 ent and try to r
1ef20 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 49 66 un it again. If
1ef30 20 74 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 the schema has
1ef40 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 changed in.** a
1ef50 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74 way that makes t
1ef60 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 he statement no
1ef70 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 longer valid, [s
1ef80 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 qlite3_step()] w
1ef90 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 ill still.** ret
1efa0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 urn [SQLITE_SCHE
1efb0 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 MA]. But unlike
1efc0 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 the legacy beha
1efd0 76 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 vior, [SQLITE_SC
1efe0 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 HEMA] is.** now
1eff0 61 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 a fatal error.
1f000 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 Calling [sqlite3
1f010 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 _prepare_v2()] a
1f020 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 gain will not ma
1f030 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 ke the.** error
1f040 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 go away. Note:
1f050 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 use [sqlite3_err
1f060 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 msg()] to find t
1f070 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 he text.** of th
1f080 65 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72 20 e parsing error
1f090 74 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 that results in
1f0a0 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d an [SQLITE_SCHEM
1f0b0 41 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f A] return..** </
1f0c0 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a li>.**.** <li>.*
1f0d0 2a 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 * When an error
1f0e0 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 occurs, [sqlite3
1f0f0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 _step()] will re
1f100 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 turn one of the
1f110 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 detailed.** [err
1f120 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 or codes] or [ex
1f130 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 tended error cod
1f140 65 73 5d 2e 20 20 54 68 65 20 6c 65 67 61 63 79 es]. The legacy
1f150 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 behavior was th
1f160 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 at.** [sqlite3_s
1f170 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c tep()] would onl
1f180 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 y return a gener
1f190 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ic [SQLITE_ERROR
1f1a0 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a ] result code.**
1f1b0 20 61 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 and you would h
1f1c0 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 ave to make a se
1f1d0 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 cond call to [sq
1f1e0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69 lite3_reset()] i
1f1f0 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 66 69 n order.** to fi
1f200 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e nd the underlyin
1f210 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 g cause of the p
1f220 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 roblem. With the
1f230 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a "v2" prepare.**
1f240 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 interfaces, the
1f250 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 underlying reas
1f260 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 on for the error
1f270 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d is returned imm
1f280 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c ediately..** </l
1f290 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a i>.** </ol>.**.*
1f2a0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
1f2b0 0a 2a 2a 20 7b 48 31 33 30 31 31 7d 20 54 68 65 .** {H13011} The
1f2c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1f2d0 65 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 e(db,zSql,...)]
1f2e0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 and.**
1f2f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1f300 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 _v2(db,zSql,...)
1f310 5d 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74 ] interfaces int
1f320 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20 erpret the.**
1f330 20 20 20 20 20 20 20 74 65 78 74 20 69 6e 20 74 text in t
1f340 68 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 heir zSql parame
1f350 74 65 72 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a ter as UTF-8..**
1f360 0a 2a 2a 20 7b 48 31 33 30 31 32 7d 20 54 68 65 .** {H13012} The
1f370 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1f380 65 31 36 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 e16(db,zSql,...)
1f390 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 ] and.**
1f3a0 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 [sqlite3_prepa
1f3b0 72 65 31 36 5f 76 32 28 64 62 2c 7a 53 71 6c 2c re16_v2(db,zSql,
1f3c0 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 73 ...)] interfaces
1f3d0 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a interpret the.*
1f3e0 2a 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20 * text
1f3f0 69 6e 20 74 68 65 69 72 20 7a 53 71 6c 20 70 61 in their zSql pa
1f400 72 61 6d 65 74 65 72 20 61 73 20 55 54 46 2d 31 rameter as UTF-1
1f410 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 6 in the native
1f420 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a byte order..**.*
1f430 2a 20 7b 48 31 33 30 31 33 7d 20 49 66 20 74 68 * {H13013} If th
1f440 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 e nByte argument
1f450 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 to [sqlite3_pre
1f460 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c pare_v2(db,zSql,
1f470 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 nByte,...)].**
1f480 20 20 20 20 20 20 20 20 61 6e 64 20 69 74 73 20 and its
1f490 76 61 72 69 61 6e 74 73 20 69 73 20 6c 65 73 73 variants is less
1f4a0 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 20 than zero, the
1f4b0 53 51 4c 20 74 65 78 74 20 69 73 0a 2a 2a 20 20 SQL text is.**
1f4c0 20 20 20 20 20 20 20 20 72 65 61 64 20 66 72 6f read fro
1f4d0 6d 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 m zSql is read u
1f4e0 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a p to the first z
1f4f0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a ero terminator..
1f500 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 34 7d 20 49 **.** {H13014} I
1f510 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 f the nByte argu
1f520 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 ment to [sqlite3
1f530 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a _prepare_v2(db,z
1f540 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a Sql,nByte,...)].
1f550 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 ** and
1f560 69 74 73 20 76 61 72 69 61 6e 74 73 20 69 73 20 its variants is
1f570 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 non-negative, th
1f580 65 6e 20 61 74 20 6d 6f 73 74 20 6e 42 79 74 65 en at most nByte
1f590 73 20 62 79 74 65 73 20 6f 66 0a 2a 2a 20 20 20 s bytes of.**
1f5a0 20 20 20 20 20 20 20 53 51 4c 20 74 65 78 74 20 SQL text
1f5b0 69 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 is read from zSq
1f5c0 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 35 l..**.** {H13015
1f5d0 7d 20 49 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 } In [sqlite3_pr
1f5e0 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c epare_v2(db,zSql
1f5f0 2c 4e 2c 50 2c 70 7a 54 61 69 6c 29 5d 20 61 6e ,N,P,pzTail)] an
1f600 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 0a 2a d its variants.*
1f610 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 74 68 * if th
1f620 65 20 7a 53 71 6c 20 69 6e 70 75 74 20 74 65 78 e zSql input tex
1f630 74 20 63 6f 6e 74 61 69 6e 73 20 6d 6f 72 65 20 t contains more
1f640 74 68 61 6e 20 6f 6e 65 20 53 51 4c 20 73 74 61 than one SQL sta
1f650 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 tement.**
1f660 20 20 20 61 6e 64 20 70 7a 54 61 69 6c 20 69 73 and pzTail is
1f670 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 not NULL, then
1f680 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 *pzTail is made
1f690 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 0a to point to the.
1f6a0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 72 73 ** firs
1f6b0 74 20 62 79 74 65 20 70 61 73 74 20 74 68 65 20 t byte past the
1f6c0 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 end of the first
1f6d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 SQL statement i
1f6e0 6e 20 7a 53 71 6c 2e 0a 2a 2a 20 20 20 20 20 20 n zSql..**
1f6f0 20 20 20 20 3c 74 6f 64 6f 3e 57 68 61 74 20 64 <todo>What d
1f700 6f 65 73 20 2a 70 7a 54 61 69 6c 20 70 6f 69 6e oes *pzTail poin
1f710 74 20 74 6f 20 69 66 20 74 68 65 72 65 20 69 73 t to if there is
1f720 20 6f 6e 65 20 73 74 61 74 65 6d 65 6e 74 3f 3c one statement?<
1f730 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 /todo>.**.** {H1
1f740 33 30 31 36 7d 20 41 20 73 75 63 63 65 73 73 66 3016} A successf
1f750 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 ul call to [sqli
1f760 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 te3_prepare_v2(d
1f770 62 2c 7a 53 71 6c 2c 4e 2c 70 70 53 74 6d 74 2c b,zSql,N,ppStmt,
1f780 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 ...)].**
1f790 20 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 or one of its
1f7a0 76 61 72 69 61 6e 74 73 20 77 72 69 74 65 73 20 variants writes
1f7b0 69 6e 74 6f 20 2a 70 70 53 74 6d 74 20 61 20 70 into *ppStmt a p
1f7c0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 77 0a ointer to a new.
1f7d0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 ** [pre
1f7e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
1f7f0 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f or a pointer to
1f800 20 4e 55 4c 4c 20 69 66 20 7a 53 71 6c 20 63 6f NULL if zSql co
1f810 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 ntains.**
1f820 20 20 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65 72 nothing other
1f830 20 74 68 61 6e 20 77 68 69 74 65 73 70 61 63 65 than whitespace
1f840 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 2e 0a 2a 2a or comments..**
1f850 0a 2a 2a 20 7b 48 31 33 30 31 39 7d 20 54 68 65 .** {H13019} The
1f860 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1f870 65 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 e_v2()] interfac
1f880 65 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e e and its varian
1f890 74 73 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 ts return.**
1f8a0 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b [SQLITE_OK
1f8b0 5d 20 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 ] or an appropri
1f8c0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d ate [error code]
1f8d0 20 75 70 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a upon failure..*
1f8e0 2a 0a 2a 2a 20 7b 48 31 33 30 32 31 7d 20 42 65 *.** {H13021} Be
1f8f0 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 fore [sqlite3_pr
1f900 65 70 61 72 65 28 64 62 2c 7a 53 71 6c 2c 6e 42 epare(db,zSql,nB
1f910 79 74 65 2c 70 70 53 74 6d 74 2c 70 7a 54 61 69 yte,ppStmt,pzTai
1f920 6c 29 5d 20 6f 72 20 69 74 73 0a 2a 2a 20 20 20 l)] or its.**
1f930 20 20 20 20 20 20 20 76 61 72 69 61 6e 74 73 20 variants
1f940 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 returns an error
1f950 20 28 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 (any value othe
1f960 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f r than [SQLITE_O
1f970 4b 5d 29 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 K]),.**
1f980 20 74 68 65 79 20 66 69 72 73 74 20 73 65 74 20 they first set
1f990 2a 70 70 53 74 6d 74 20 74 6f 20 4e 55 4c 4c 2e *ppStmt to NULL.
1f9a0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
1f9b0 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 prepare(. sqlit
1f9c0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
1f9d0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 /* Database h
1f9e0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
1f9f0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 char *zSql,
1fa00 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d /* SQL statem
1fa10 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 ent, UTF-8 encod
1fa20 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 ed */. int nByt
1fa30 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 e,
1fa40 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 /* Maximum lengt
1fa50 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 h of zSql in byt
1fa60 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 es. */. sqlite3
1fa70 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 _stmt **ppStmt,
1fa80 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 /* OUT: Stateme
1fa90 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 nt handle */. c
1faa0 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 onst char **pzTa
1fab0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 il /* OUT: P
1fac0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 ointer to unused
1fad0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c portion of zSql
1fae0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 */.);.int sqlit
1faf0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 e3_prepare_v2(.
1fb00 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
1fb10 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
1fb20 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 base handle */.
1fb30 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 const char *zSq
1fb40 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 l, /* SQL
1fb50 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 statement, UTF-8
1fb60 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e encoded */. in
1fb70 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 t nByte,
1fb80 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d /* Maximum
1fb90 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 length of zSql
1fba0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 in bytes. */. s
1fbb0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 qlite3_stmt **pp
1fbc0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 Stmt, /* OUT: S
1fbd0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 tatement handle
1fbe0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
1fbf0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 **pzTail /*
1fc00 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 OUT: Pointer to
1fc10 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f unused portion o
1fc20 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 f zSql */.);.int
1fc30 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
1fc40 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 16(. sqlite3 *d
1fc50 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a b, /*
1fc60 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 Database handle
1fc70 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 */. const void
1fc80 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a *zSql, /*
1fc90 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 SQL statement,
1fca0 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a UTF-16 encoded *
1fcb0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 /. int nByte,
1fcc0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d /* M
1fcd0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
1fce0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 zSql in bytes.
1fcf0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d */. sqlite3_stm
1fd00 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 t **ppStmt, /*
1fd10 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 OUT: Statement h
1fd20 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
1fd30 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 void **pzTail
1fd40 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 /* OUT: Point
1fd50 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 er to unused por
1fd60 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a tion of zSql */.
1fd70 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 );.int sqlite3_p
1fd80 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 repare16_v2(. s
1fd90 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
1fda0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
1fdb0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 se handle */. c
1fdc0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c onst void *zSql,
1fdd0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 /* SQL st
1fde0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 atement, UTF-16
1fdf0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 encoded */. int
1fe00 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 nByte,
1fe10 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 /* Maximum
1fe20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 length of zSql i
1fe30 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 n bytes. */. sq
1fe40 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 lite3_stmt **ppS
1fe50 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 tmt, /* OUT: St
1fe60 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a atement handle *
1fe70 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a /. const void *
1fe80 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f *pzTail /* O
1fe90 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 UT: Pointer to u
1fea0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 nused portion of
1feb0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a zSql */.);../*.
1fec0 2a 2a 20 43 41 50 49 52 45 46 3a 20 52 65 74 72 ** CAPIREF: Retr
1fed0 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 ieving Statement
1fee0 20 53 51 4c 20 7b 48 31 33 31 30 30 7d 20 3c 48 SQL {H13100} <H
1fef0 31 33 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 13000>.**.** Thi
1ff00 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 s interface can
1ff10 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 be used to retri
1ff20 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 eve a saved copy
1ff30 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c of the original
1ff40 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 .** SQL text use
1ff50 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 d to create a [p
1ff60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
1ff70 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65 t] if that state
1ff80 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 ment was.** comp
1ff90 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 iled using eithe
1ffa0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
1ffb0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c re_v2()] or [sql
1ffc0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
1ffd0 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 2()]..**.** INVA
1ffe0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
1fff0 31 33 31 30 31 7d 20 49 66 20 74 68 65 20 5b 70 13101} If the [p
20000 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
20010 74 5d 20 70 61 73 73 65 64 20 61 73 20 74 68 65 t] passed as the
20020 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 argument to.**
20030 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
20040 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 3_sql()] was com
20050 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 piled using eith
20060 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 er [sqlite3_prep
20070 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 are_v2()] or.**
20080 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
20090 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
200a0 5d 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 ], then [sqlite3
200b0 5f 73 71 6c 28 29 5d 20 72 65 74 75 72 6e 73 0a _sql()] returns.
200c0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 6f ** a po
200d0 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d inter to a zero-
200e0 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e terminated strin
200f0 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 20 55 g containing a U
20100 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 0a 2a TF-8 rendering.*
20110 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 * of th
20120 65 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 73 e original SQL s
20130 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 tatement..**.**
20140 7b 48 31 33 31 30 32 7d 20 49 66 20 74 68 65 20 {H13102} If the
20150 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
20160 65 6e 74 5d 20 70 61 73 73 65 64 20 61 73 20 74 ent] passed as t
20170 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a he argument to.*
20180 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
20190 74 65 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 te3_sql()] was c
201a0 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 ompiled using ei
201b0 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 ther [sqlite3_pr
201c0 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 epare()] or.**
201d0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
201e0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 _prepare16()], t
201f0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c hen [sqlite3_sql
20200 28 29 5d 20 72 65 74 75 72 6e 73 20 61 20 4e 55 ()] returns a NU
20210 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
20220 2a 20 7b 48 31 33 31 30 33 7d 20 54 68 65 20 73 * {H13103} The s
20230 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 tring returned b
20240 79 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 53 y [sqlite3_sql(S
20250 29 5d 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 )] is valid unti
20260 6c 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 l the.**
20270 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 [prepared stat
20280 65 6d 65 6e 74 5d 20 53 20 69 73 20 64 65 6c 65 ement] S is dele
20290 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ted using [sqlit
202a0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 2e e3_finalize(S)].
202b0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a .*/.const char *
202c0 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 sqlite3_sql(sqli
202d0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
202e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
202f0 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 F: Dynamically T
20300 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 yped Value Objec
20310 74 20 7b 48 31 35 30 30 30 7d 20 3c 53 32 30 32 t {H15000} <S202
20320 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 00>.** KEYWORDS:
20330 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 {protected sqli
20340 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 te3_value} {unpr
20350 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
20360 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c value}.**.** SQL
20370 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c ite uses the sql
20380 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
20390 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 t to represent a
203a0 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 ll values.** tha
203b0 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 t can be stored
203c0 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 in a database ta
203d0 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 ble. SQLite uses
203e0 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a dynamic typing.
203f0 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 ** for the value
20400 73 20 69 74 20 73 74 6f 72 65 73 2e 20 56 61 6c s it stores. Val
20410 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 ues stored in sq
20420 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
20430 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e cts.** can be in
20440 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 tegers, floating
20450 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 point values, s
20460 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f trings, BLOBs, o
20470 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e r NULL..**.** An
20480 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
20490 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 bject may be eit
204a0 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 her "protected"
204b0 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 or "unprotected"
204c0 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 ..** Some interf
204d0 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 aces require a p
204e0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
204f0 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 _value. Other i
20500 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c nterfaces.** wil
20510 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 l accept either
20520 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 a protected or a
20530 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 n unprotected sq
20540 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 lite3_value..**
20550 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 Every interface
20560 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c that accepts sql
20570 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d ite3_value argum
20580 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a ents specifies.*
20590 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 * whether or not
205a0 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 it requires a p
205b0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
205c0 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 _value..**.** Th
205d0 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 e terms "protect
205e0 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 ed" and "unprote
205f0 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 cted" refer to w
20600 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a hether or not.**
20610 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 a mutex is held
20620 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75 . A internal mu
20630 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 tex is held for
20640 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 a protected.** s
20650 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
20660 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 ect but no mutex
20670 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 is held for an
20680 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 unprotected.** s
20690 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
206a0 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 ect. If SQLite
206b0 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 is compiled to b
206c0 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 e single-threade
206d0 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 d.** (with [SQLI
206e0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d TE_THREADSAFE=0]
206f0 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 and with [sqlit
20700 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d e3_threadsafe()]
20710 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a returning 0).**
20720 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 or if SQLite is
20730 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 run in one of r
20740 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 educed mutex mod
20750 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 es .** [SQLITE_C
20760 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
20770 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 AD] or [SQLITE_C
20780 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 ONFIG_MULTITHREA
20790 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 D].** then there
207a0 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 is no distincti
207b0 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 on between prote
207c0 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 cted and unprote
207d0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f cted.** sqlite3_
207e0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e value objects an
207f0 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 d they can be us
20800 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 ed interchangeab
20810 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a ly. However,.**
20820 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 for maximum cod
20830 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 e portability it
20840 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
20850 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e that application
20860 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 s.** still make
20870 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 the distinction
20880 62 65 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20 between between
20890 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e protected and un
208a0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c protected.** sql
208b0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
208c0 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 ts even when not
208d0 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 strictly requir
208e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ed..**.** The sq
208f0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
20900 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 cts that are pas
20910 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 sed as parameter
20920 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d s into the.** im
20930 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
20940 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 [application-def
20950 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f ined SQL functio
20960 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 ns] are protecte
20970 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 d..** The sqlite
20980 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 3_value object r
20990 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 eturned by.** [s
209a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 qlite3_column_va
209b0 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 lue()] is unprot
209c0 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 ected..** Unprot
209d0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
209e0 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 lue objects may
209f0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 only be used wit
20a00 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 h.** [sqlite3_re
20a10 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e sult_value()] an
20a20 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f d [sqlite3_bind_
20a30 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 value()]..** The
20a40 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
20a50 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 blob | sqlite3_v
20a60 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d alue_type()] fam
20a70 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 ily of.** interf
20a80 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f aces require pro
20a90 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
20aa0 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f alue objects..*/
20ab0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
20ac0 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 Mem sqlite3_valu
20ad0 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 e;../*.** CAPI3R
20ae0 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e EF: SQL Function
20af0 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 20 Context Object
20b00 7b 48 31 36 30 30 31 7d 20 3c 53 32 30 32 30 30 {H16001} <S20200
20b10 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 >.**.** The cont
20b20 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 ext in which an
20b30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 SQL function exe
20b40 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 cutes is stored
20b50 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 in an.** sqlite3
20b60 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e _context object.
20b70 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 A pointer to a
20b80 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 n sqlite3_contex
20b90 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 t object.** is a
20ba0 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 lways first para
20bb0 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 meter to [applic
20bc0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
20bd0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a L functions]..**
20be0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
20bf0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
20c00 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 ction implementa
20c10 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 tion will pass t
20c20 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 his.** pointer t
20c30 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c hrough into call
20c40 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 s to [sqlite3_re
20c50 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 sult_int | sqlit
20c60 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a e3_result()],.**
20c70 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 [sqlite3_aggreg
20c80 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 ate_context()],
20c90 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 [sqlite3_user_da
20ca0 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 ta()],.** [sqlit
20cb0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 e3_context_db_ha
20cc0 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 ndle()], [sqlite
20cd0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 3_get_auxdata()]
20ce0 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c ,.** and/or [sql
20cf0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 ite3_set_auxdata
20d00 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ()]..*/.typedef
20d10 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 struct sqlite3_c
20d20 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 ontext sqlite3_c
20d30 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ontext;../*.** C
20d40 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 API3REF: Binding
20d50 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 Values To Prepa
20d60 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 20 7b red Statements {
20d70 48 31 33 35 30 30 7d 20 3c 53 37 30 33 30 30 3e H13500} <S70300>
20d80 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 .** KEYWORDS: {h
20d90 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b ost parameter} {
20da0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d host parameters}
20db0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 {host parameter
20dc0 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 name}.** KEYWOR
20dd0 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 DS: {SQL paramet
20de0 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 er} {SQL paramet
20df0 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 ers} {parameter
20e00 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49 binding}.**.** I
20e10 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67 n the SQL string
20e20 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 s input to [sqli
20e30 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
20e40 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e ] and its varian
20e50 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 ts,.** literals
20e60 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 may be replaced
20e70 62 79 20 61 20 70 61 72 61 6d 65 74 65 72 20 69 by a parameter i
20e80 6e 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 66 n one of these f
20e90 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e orms:.**.** <ul>
20ea0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c .** <li> ?.** <
20eb0 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 li> ?NNN.** <li
20ec0 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 > :VVV.** <li>
20ed0 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 @VVV.** <li> $
20ee0 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a VVV.** </ul>.**.
20ef0 2a 2a 20 49 6e 20 74 68 65 20 70 61 72 61 6d 65 ** In the parame
20f00 74 65 72 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20 ter forms shown
20f10 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20 above NNN is an
20f20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c integer literal,
20f30 0a 2a 2a 20 61 6e 64 20 56 56 56 20 69 73 20 61 .** and VVV is a
20f40 6e 20 61 6c 70 68 61 2d 6e 75 6d 65 72 69 63 20 n alpha-numeric
20f50 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 2e 20 parameter name.
20f60 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 The values of th
20f70 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ese.** parameter
20f80 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 s (also called "
20f90 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e host parameter n
20fa0 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 ames" or "SQL pa
20fb0 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 rameters").** ca
20fc0 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 n be set using t
20fd0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
20fe0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 *() routines def
20ff0 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a ined here..**.**
21000 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
21010 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ent to the sqlit
21020 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 e3_bind_*() rout
21030 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a ines is always.*
21040 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 * a pointer to t
21050 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 he [sqlite3_stmt
21060 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 ] object returne
21070 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 d from.** [sqlit
21080 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
21090 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 or its variants
210a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f ..**.** The seco
210b0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 nd argument is t
210c0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 he index of the
210d0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f SQL parameter to
210e0 20 62 65 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20 be set..** The
210f0 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 leftmost SQL par
21100 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e ameter has an in
21110 64 65 78 20 6f 66 20 31 2e 20 20 57 68 65 6e 20 dex of 1. When
21120 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a the same named.*
21130 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 * SQL parameter
21140 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 is used more tha
21150 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 n once, second a
21160 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a nd subsequent.**
21170 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 occurrences hav
21180 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 e the same index
21190 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 as the first oc
211a0 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 54 68 65 currence..** The
211b0 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 index for named
211c0 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 parameters can
211d0 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 be looked up usi
211e0 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ng the.** [sqlit
211f0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
21200 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 r_index()] API i
21210 66 20 64 65 73 69 72 65 64 2e 20 20 54 68 65 20 f desired. The
21220 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e index.** for "?N
21230 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 NN" parameters i
21240 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e s the value of N
21250 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 NN..** The NNN v
21260 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 alue must be bet
21270 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b ween 1 and the [
21280 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d sqlite3_limit()]
21290 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 .** parameter [S
212a0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 QLITE_LIMIT_VARI
212b0 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 ABLE_NUMBER] (de
212c0 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 fault value: 999
212d0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 )..**.** The thi
212e0 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 rd argument is t
212f0 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 he value to bind
21300 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 to the paramete
21310 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 r..**.** In thos
21320 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 e routines that
21330 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 have a fourth ar
21340 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 gument, its valu
21350 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 e is the.** numb
21360 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
21370 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 he parameter. T
21380 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 o be clear: the
21390 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 value is the.**
213a0 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 number of <u>byt
213b0 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 es</u> in the va
213c0 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d lue, not the num
213d0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 ber of character
213e0 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 s..** If the fou
213f0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 rth parameter is
21400 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c negative, the l
21410 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 ength of the str
21420 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 ing is.** the nu
21430 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 mber of bytes up
21440 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 to the first ze
21450 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a ro terminator..*
21460 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 61 *.** The fifth a
21470 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
21480 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 e3_bind_blob(),
21490 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
214a0 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 t(), and.** sqli
214b0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 te3_bind_text16(
214c0 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f ) is a destructo
214d0 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 r used to dispos
214e0 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 e of the BLOB or
214f0 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 .** string after
21500 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 SQLite has fini
21510 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 49 66 shed with it. If
21520 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d the fifth argum
21530 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 ent is.** the sp
21540 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c ecial value [SQL
21550 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 ITE_STATIC], the
21560 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 n SQLite assumes
21570 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 that the.** inf
21580 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 ormation is in s
21590 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 tatic, unmanaged
215a0 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 space and does
215b0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 not need to be f
215c0 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 reed..** If the
215d0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 fifth argument h
215e0 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 as the value [SQ
215f0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c LITE_TRANSIENT],
21600 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 then.** SQLite
21610 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 makes its own pr
21620 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 ivate copy of th
21630 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 e data immediate
21640 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 ly, before.** th
21650 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
21660 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 () routine retur
21670 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ns..**.** The sq
21680 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 lite3_bind_zerob
21690 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 lob() routine bi
216a0 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 nds a BLOB of le
216b0 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 ngth N that.** i
216c0 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 s filled with ze
216d0 72 6f 65 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f roes. A zeroblo
216e0 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 b uses a fixed a
216f0 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a mount of memory.
21700 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 ** (just an inte
21710 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 ger to hold its
21720 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 size) while it i
21730 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 s being processe
21740 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 d..** Zeroblobs
21750 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 are intended to
21760 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f serve as placeho
21770 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 lders for BLOBs
21780 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 whose.** content
21790 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 is later writte
217a0 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 n using.** [sqli
217b0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 te3_blob_open |
217c0 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 incremental BLOB
217d0 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a I/O] routines..
217e0 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20 76 61 ** A negative va
217f0 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f lue for the zero
21800 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 blob results in
21810 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c a zero-length BL
21820 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 OB..**.** The sq
21830 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 lite3_bind_*() r
21840 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 outines must be
21850 63 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 called after.**
21860 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
21870 5f 76 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20 _v2()] (and its
21880 76 61 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 variants) or [sq
21890 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 lite3_reset()] a
218a0 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 nd.** before [sq
218b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a lite3_step()]..*
218c0 2a 20 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e * Bindings are n
218d0 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 ot cleared by th
218e0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 e [sqlite3_reset
218f0 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 ()] routine..**
21900 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 Unbound paramete
21910 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 rs are interpret
21920 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a ed as NULL..**.*
21930 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
21940 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
21950 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f OK] on success o
21960 72 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 r an error code
21970 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 if.** anything g
21980 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c oes wrong. [SQL
21990 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 ITE_RANGE] is re
219a0 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 turned if the pa
219b0 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 rameter.** index
219c0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 is out of range
219d0 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d . [SQLITE_NOMEM
219e0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 ] is returned if
219f0 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e malloc() fails.
21a00 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 .** [SQLITE_MISU
21a10 53 45 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 SE] might be ret
21a20 75 72 6e 65 64 20 69 66 20 74 68 65 73 65 20 72 urned if these r
21a30 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c outines are call
21a40 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75 ed on a.** virtu
21a50 61 6c 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20 al machine that
21a60 69 73 20 74 68 65 20 77 72 6f 6e 67 20 73 74 61 is the wrong sta
21a70 74 65 20 6f 72 20 77 68 69 63 68 20 68 61 73 20 te or which has
21a80 61 6c 72 65 61 64 79 20 62 65 65 6e 20 66 69 6e already been fin
21a90 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63 alized..** Detec
21aa0 74 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65 20 69 tion of misuse i
21ab0 73 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41 s unreliable. A
21ac0 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 pplications shou
21ad0 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a ld not depend.**
21ae0 20 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 on SQLITE_MISUS
21af0 45 20 72 65 74 75 72 6e 73 2e 20 20 53 51 4c 49 E returns. SQLI
21b00 54 45 5f 4d 49 53 55 53 45 20 69 73 20 69 6e 74 TE_MISUSE is int
21b10 65 6e 64 65 64 20 74 6f 20 69 6e 64 69 63 61 74 ended to indicat
21b20 65 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65 e a.** a logic e
21b30 72 72 6f 72 20 69 6e 20 74 68 65 20 61 70 70 6c rror in the appl
21b40 69 63 61 74 69 6f 6e 2e 20 20 46 75 74 75 72 65 ication. Future
21b50 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
21b60 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e ite might.** pan
21b70 69 63 20 72 61 74 68 65 72 20 74 68 61 6e 20 72 ic rather than r
21b80 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 eturn SQLITE_MIS
21b90 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 USE..**.** See a
21ba0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 lso: [sqlite3_bi
21bb0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 nd_parameter_cou
21bc0 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 nt()],.** [sqlit
21bd0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
21be0 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b r_name()], and [
21bf0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
21c00 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e ameter_index()].
21c10 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
21c20 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 30 36 S:.**.** {H13506
21c30 7d 20 54 68 65 20 5b 53 51 4c 20 73 74 61 74 65 } The [SQL state
21c40 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 72 ment compiler] r
21c50 65 63 6f 67 6e 69 7a 65 73 20 74 6f 6b 65 6e 73 ecognizes tokens
21c60 20 6f 66 20 74 68 65 20 66 6f 72 6d 73 0a 2a 2a of the forms.**
21c70 20 20 20 20 20 20 20 20 20 20 22 3f 22 2c 20 22 "?", "
21c80 3f 4e 4e 4e 22 2c 20 22 24 56 56 56 22 2c 20 22 ?NNN", "$VVV", "
21c90 3a 56 56 56 22 2c 20 61 6e 64 20 22 40 56 56 56 :VVV", and "@VVV
21ca0 22 20 61 73 20 53 51 4c 20 70 61 72 61 6d 65 74 " as SQL paramet
21cb0 65 72 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ers,.**
21cc0 20 77 68 65 72 65 20 4e 4e 4e 20 69 73 20 61 6e where NNN is an
21cd0 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e y sequence of on
21ce0 65 20 6f 72 20 6d 6f 72 65 20 64 69 67 69 74 73 e or more digits
21cf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 .** and
21d00 20 77 68 65 72 65 20 56 56 56 20 69 73 20 61 6e where VVV is an
21d10 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e y sequence of on
21d20 65 20 6f 72 20 6d 6f 72 65 20 61 6c 70 68 61 6e e or more alphan
21d30 75 6d 65 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 umeric.**
21d40 20 20 20 63 68 61 72 61 63 74 65 72 73 20 6f 72 characters or
21d50 20 22 3a 3a 22 20 6f 70 74 69 6f 6e 61 6c 6c 79 "::" optionally
21d60 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61 20 73 followed by a s
21d70 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 tring containing
21d80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 20 .** no
21d90 73 70 61 63 65 73 20 61 6e 64 20 63 6f 6e 74 61 spaces and conta
21da0 69 6e 65 64 20 77 69 74 68 69 6e 20 70 61 72 65 ined within pare
21db0 6e 74 68 65 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b ntheses..**.** {
21dc0 48 31 33 35 30 39 7d 20 54 68 65 20 69 6e 69 74 H13509} The init
21dd0 69 61 6c 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 ial value of an
21de0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 SQL parameter is
21df0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 NULL..**.** {H1
21e00 33 35 31 32 7d 20 54 68 65 20 69 6e 64 65 78 20 3512} The index
21e10 6f 66 20 61 6e 20 22 3f 22 20 53 51 4c 20 70 61 of an "?" SQL pa
21e20 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6c rameter is one l
21e30 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 0a 2a arger than the.*
21e40 2a 20 20 20 20 20 20 20 20 20 20 6c 61 72 67 65 * large
21e50 73 74 20 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 st index of SQL
21e60 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
21e70 20 6c 65 66 74 2c 20 6f 72 20 31 20 69 66 0a 2a left, or 1 if.*
21e80 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 22 * the "
21e90 3f 22 20 69 73 20 74 68 65 20 6c 65 66 74 6d 6f ?" is the leftmo
21ea0 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 st SQL parameter
21eb0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 35 7d ..**.** {H13515}
21ec0 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e The index of an
21ed0 20 22 3f 4e 4e 4e 22 20 53 51 4c 20 70 61 72 61 "?NNN" SQL para
21ee0 6d 65 74 65 72 20 69 73 20 74 68 65 20 69 6e 74 meter is the int
21ef0 65 67 65 72 20 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 eger NNN..**.**
21f00 7b 48 31 33 35 31 38 7d 20 54 68 65 20 69 6e 64 {H13518} The ind
21f10 65 78 20 6f 66 20 61 6e 20 22 3a 56 56 56 22 2c ex of an ":VVV",
21f20 20 22 24 56 56 56 22 2c 20 6f 72 20 22 40 56 56 "$VVV", or "@VV
21f30 56 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 V" SQL parameter
21f40 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 is.**
21f50 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 the same as the
21f60 69 6e 64 65 78 20 6f 66 20 6c 65 66 74 6d 6f 73 index of leftmos
21f70 74 20 6f 63 63 75 72 72 65 6e 63 65 73 20 6f 66 t occurrences of
21f80 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 the same.**
21f90 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 2c parameter,
21fa0 20 6f 72 20 6f 6e 65 20 6d 6f 72 65 20 74 68 61 or one more tha
21fb0 6e 20 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e n the largest in
21fc0 64 65 78 20 6f 76 65 72 20 61 6c 6c 0a 2a 2a 20 dex over all.**
21fd0 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 paramet
21fe0 65 72 73 20 74 6f 20 74 68 65 20 6c 65 66 74 20 ers to the left
21ff0 69 66 20 74 68 69 73 20 69 73 20 74 68 65 20 66 if this is the f
22000 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 0a irst occurrence.
22010 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 ** of t
22020 68 69 73 20 70 61 72 61 6d 65 74 65 72 2c 20 6f his parameter, o
22030 72 20 31 20 69 66 20 74 68 69 73 20 69 73 20 74 r 1 if this is t
22040 68 65 20 6c 65 66 74 6d 6f 73 74 20 70 61 72 61 he leftmost para
22050 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 meter..**.** {H1
22060 33 35 32 31 7d 20 54 68 65 20 5b 53 51 4c 20 73 3521} The [SQL s
22070 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 tatement compile
22080 72 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e r] fails with an
22090 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 0a [SQLITE_RANGE].
220a0 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72 72 6f ** erro
220b0 72 20 69 66 20 74 68 65 20 69 6e 64 65 78 20 6f r if the index o
220c0 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 f an SQL paramet
220d0 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 er is less than
220e0 31 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 1.** or
220f0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 greater than th
22100 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 53 e compile-time S
22110 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49 41 42 QLITE_MAX_VARIAB
22120 4c 45 5f 4e 55 4d 42 45 52 0a 2a 2a 20 20 20 20 LE_NUMBER.**
22130 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 2e parameter.
22140 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 34 7d 20 .**.** {H13524}
22150 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 Calls to [sqlite
22160 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 3_bind_text | sq
22170 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 56 lite3_bind(S,N,V
22180 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 ,...)].**
22190 20 20 20 61 73 73 6f 63 69 61 74 65 20 74 68 65 associate the
221a0 20 76 61 6c 75 65 20 56 20 77 69 74 68 20 61 6c value V with al
221b0 6c 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 l SQL parameters
221c0 20 68 61 76 69 6e 67 20 61 6e 0a 2a 2a 20 20 20 having an.**
221d0 20 20 20 20 20 20 20 69 6e 64 65 78 20 6f 66 20 index of
221e0 4e 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 N in the [prepar
221f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e ed statement] S.
22200 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 37 7d 20 .**.** {H13527}
22210 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 Calls to [sqlite
22220 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 3_bind_text | sq
22230 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e lite3_bind(S,N,.
22240 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 ..)].**
22250 20 6f 76 65 72 72 69 64 65 20 70 72 69 6f 72 20 override prior
22260 63 61 6c 6c 73 20 77 69 74 68 20 74 68 65 20 73 calls with the s
22270 61 6d 65 20 76 61 6c 75 65 73 20 6f 66 20 53 20 ame values of S
22280 61 6e 64 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 and N..**.** {H1
22290 33 35 33 30 7d 20 42 69 6e 64 69 6e 67 73 20 65 3530} Bindings e
222a0 73 74 61 62 6c 69 73 68 65 64 20 62 79 20 5b 73 stablished by [s
222b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
222c0 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 | sqlite3_bind(
222d0 53 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 S,...)].**
222e0 20 20 20 20 70 65 72 73 69 73 74 20 61 63 72 6f persist acro
222f0 73 73 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c ss calls to [sql
22300 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 0a ite3_reset(S)]..
22310 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 33 7d 20 49 **.** {H13533} I
22320 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 n calls to [sqli
22330 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c te3_bind_blob(S,
22340 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 N,V,L,D)],.**
22350 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
22360 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c bind_text(S,N,V,
22370 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 L,D)], or.**
22380 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 [sqlite3_b
22390 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 ind_text16(S,N,V
223a0 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69 ,L,D)] SQLite bi
223b0 6e 64 73 20 74 68 65 20 66 69 72 73 74 20 4c 0a nds the first L.
223c0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 74 65 ** byte
223d0 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 s of the BLOB or
223e0 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 string pointed
223f0 74 6f 20 62 79 20 56 2c 20 77 68 65 6e 20 4c 0a to by V, when L.
22400 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e ** is n
22410 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a on-negative..**.
22420 2a 2a 20 7b 48 31 33 35 33 36 7d 20 49 6e 20 63 ** {H13536} In c
22430 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
22440 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 _bind_text(S,N,V
22450 2c 4c 2c 44 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 ,L,D)] or.**
22460 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 [sqlite3_b
22470 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 ind_text16(S,N,V
22480 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69 ,L,D)] SQLite bi
22490 6e 64 73 20 63 68 61 72 61 63 74 65 72 73 0a 2a nds characters.*
224a0 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 * from
224b0 56 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 V through the fi
224c0 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 rst zero charact
224d0 65 72 20 77 68 65 6e 20 4c 20 69 73 20 6e 65 67 er when L is neg
224e0 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ative..**.** {H1
224f0 33 35 33 39 7d 20 49 6e 20 63 61 6c 6c 73 20 74 3539} In calls t
22500 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f o [sqlite3_bind_
22510 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d blob(S,N,V,L,D)]
22520 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 ,.** [s
22530 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
22540 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 (S,N,V,L,D)], or
22550 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
22560 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 lite3_bind_text1
22570 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 6(S,N,V,L,D)] wh
22580 65 6e 20 44 20 69 73 20 74 68 65 20 73 70 65 63 en D is the spec
22590 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ial.**
225a0 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 constant [SQLITE
225b0 5f 53 54 41 54 49 43 5d 2c 20 53 51 4c 69 74 65 _STATIC], SQLite
225c0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 assumes that th
225d0 65 20 76 61 6c 75 65 20 56 0a 2a 2a 20 20 20 20 e value V.**
225e0 20 20 20 20 20 20 69 73 20 68 65 6c 64 20 69 6e is held in
225f0 20 73 74 61 74 69 63 20 75 6e 6d 61 6e 61 67 65 static unmanage
22600 64 20 73 70 61 63 65 20 74 68 61 74 20 77 69 6c d space that wil
22610 6c 20 6e 6f 74 20 63 68 61 6e 67 65 0a 2a 2a 20 l not change.**
22620 20 20 20 20 20 20 20 20 20 64 75 72 69 6e 67 20 during
22630 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 the lifetime of
22640 74 68 65 20 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a the binding..**.
22650 2a 2a 20 7b 48 31 33 35 34 32 7d 20 49 6e 20 63 ** {H13542} In c
22660 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
22670 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 _bind_blob(S,N,V
22680 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 ,L,D)],.**
22690 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e [sqlite3_bin
226a0 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 d_text(S,N,V,L,D
226b0 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 )], or.**
226c0 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 [sqlite3_bind
226d0 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c _text16(S,N,V,L,
226e0 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74 68 D)] when D is th
226f0 65 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 e special.**
22700 20 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b constant [
22710 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 SQLITE_TRANSIENT
22720 5d 2c 20 74 68 65 20 72 6f 75 74 69 6e 65 20 6d ], the routine m
22730 61 6b 65 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 akes a.**
22740 20 20 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 private copy
22750 6f 66 20 74 68 65 20 76 61 6c 75 65 20 56 20 62 of the value V b
22760 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 efore it returns
22770 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34 35 7d ..**.** {H13545}
22780 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 In calls to [sq
22790 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 lite3_bind_blob(
227a0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 S,N,V,L,D)],.**
227b0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
227c0 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 3_bind_text(S,N,
227d0 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 V,L,D)], or.**
227e0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
227f0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e _bind_text16(S,N
22800 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 ,V,L,D)] when D
22810 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a is a pointer to.
22820 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 66 75 ** a fu
22830 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 69 nction, SQLite i
22840 6e 76 6f 6b 65 73 20 74 68 61 74 20 66 75 6e 63 nvokes that func
22850 74 69 6f 6e 20 74 6f 20 64 65 73 74 72 6f 79 20 tion to destroy
22860 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
22870 76 61 6c 75 65 20 56 20 61 66 74 65 72 20 69 74 value V after it
22880 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 has finished us
22890 69 6e 67 20 74 68 65 20 76 61 6c 75 65 20 56 2e ing the value V.
228a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34 38 7d 20 .**.** {H13548}
228b0 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c In calls to [sql
228c0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c ite3_bind_zerobl
228d0 6f 62 28 53 2c 4e 2c 56 2c 4c 29 5d 20 74 68 65 ob(S,N,V,L)] the
228e0 20 76 61 6c 75 65 20 62 6f 75 6e 64 0a 2a 2a 20 value bound.**
228f0 20 20 20 20 20 20 20 20 20 69 73 20 61 20 42 4c is a BL
22900 4f 42 20 6f 66 20 4c 20 62 79 74 65 73 2c 20 6f OB of L bytes, o
22910 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 r a zero-length
22920 42 4c 4f 42 20 69 66 20 4c 20 69 73 20 6e 65 67 BLOB if L is neg
22930 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ative..**.** {H1
22940 33 35 35 31 7d 20 49 6e 20 63 61 6c 6c 73 20 74 3551} In calls t
22950 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f o [sqlite3_bind_
22960 76 61 6c 75 65 28 53 2c 4e 2c 56 29 5d 20 74 68 value(S,N,V)] th
22970 65 20 56 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 e V argument may
22980 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 20 .** be
22990 65 69 74 68 65 72 20 61 20 5b 70 72 6f 74 65 63 either a [protec
229a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
229b0 65 5d 20 6f 62 6a 65 63 74 20 6f 72 20 61 6e 0a e] object or an.
229c0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 75 6e 70 ** [unp
229d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
229e0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a _value] object..
229f0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 */.int sqlite3_b
22a00 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 ind_blob(sqlite3
22a10 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e _stmt*, int, con
22a20 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c st void*, int n,
22a30 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 void(*)(void*))
22a40 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 ;.int sqlite3_bi
22a50 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 nd_double(sqlite
22a60 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 3_stmt*, int, do
22a70 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 uble);.int sqlit
22a80 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 e3_bind_int(sqli
22a90 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
22aa0 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 int);.int sqlite
22ab0 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 3_bind_int64(sql
22ac0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
22ad0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b sqlite3_int64);
22ae0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
22af0 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 d_null(sqlite3_s
22b00 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 tmt*, int);.int
22b10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
22b20 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c t(sqlite3_stmt*,
22b30 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 int, const char
22b40 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a *, int n, void(*
22b50 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 )(void*));.int s
22b60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
22b70 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
22b80 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 , int, const voi
22b90 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 d*, int, void(*)
22ba0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 (void*));.int sq
22bb0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 lite3_bind_value
22bc0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
22bd0 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 int, const sqlit
22be0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 e3_value*);.int
22bf0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 sqlite3_bind_zer
22c00 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 oblob(sqlite3_st
22c10 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 mt*, int, int n)
22c20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
22c30 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c F: Number Of SQL
22c40 20 50 61 72 61 6d 65 74 65 72 73 20 7b 48 31 33 Parameters {H13
22c50 36 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 600} <S70300>.**
22c60 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
22c70 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
22c80 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 find the number
22c90 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 of [SQL paramete
22ca0 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 rs].** in a [pre
22cb0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
22cc0 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 . SQL parameter
22cd0 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 s are tokens of
22ce0 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c the.** form "?",
22cf0 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c "?NNN", ":AAA",
22d00 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 "$AAA", or "@AA
22d10 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 A" that serve as
22d20 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 .** placeholders
22d30 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 for values that
22d40 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 are [sqlite3_bi
22d50 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d nd_blob | bound]
22d60 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d .** to the param
22d70 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 eters at a later
22d80 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 time..**.** Thi
22d90 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c s routine actual
22da0 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 ly returns the i
22db0 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 ndex of the larg
22dc0 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a est (rightmost).
22dd0 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f ** parameter. Fo
22de0 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 r all forms exce
22df0 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 pt ?NNN, this wi
22e00 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f ll correspond to
22e10 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f the.** number o
22e20 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 f unique paramet
22e30 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 ers. If paramet
22e40 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 ers of the ?NNN
22e50 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 are used,.** the
22e60 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 re may be gaps i
22e70 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a n the list..**.*
22e80 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
22e90 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 ite3_bind_blob|s
22ea0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a qlite3_bind()],.
22eb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
22ec0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 _parameter_name(
22ed0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 )], and.** [sqli
22ee0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
22ef0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a er_index()]..**.
22f00 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
22f10 2a 0a 2a 2a 20 7b 48 31 33 36 30 31 7d 20 54 68 *.** {H13601} Th
22f20 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f e [sqlite3_bind_
22f30 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 parameter_count(
22f40 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 S)] interface re
22f50 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 turns.**
22f60 20 20 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e the largest in
22f70 64 65 78 20 6f 66 20 61 6c 6c 20 53 51 4c 20 70 dex of all SQL p
22f80 61 72 61 6d 65 74 65 72 73 20 69 6e 20 74 68 65 arameters in the
22f90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 .** [pr
22fa0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
22fb0 5d 20 53 2c 20 6f 72 20 30 20 69 66 20 53 20 63 ] S, or 0 if S c
22fc0 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 70 ontains no SQL p
22fd0 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e arameters..*/.in
22fe0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 t sqlite3_bind_p
22ff0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 arameter_count(s
23000 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a qlite3_stmt*);..
23010 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
23020 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 Name Of A Host P
23030 61 72 61 6d 65 74 65 72 20 7b 48 31 33 36 32 30 arameter {H13620
23040 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a } <S70300>.**.**
23050 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 This routine re
23060 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
23070 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 to the name of t
23080 68 65 20 6e 2d 74 68 0a 2a 2a 20 5b 53 51 4c 20 he n-th.** [SQL
23090 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 20 parameter] in a
230a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
230b0 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70 61 72 ent]..** SQL par
230c0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 ameters of the f
230d0 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a orm "?NNN" or ":
230e0 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f AAA" or "@AAA" o
230f0 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 r "$AAA".** have
23100 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 a name which is
23110 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e the string "?NN
23120 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 N" or ":AAA" or
23130 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 "@AAA" or "$AAA"
23140 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 .** respectively
23150 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f ..** In other wo
23160 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c rds, the initial
23170 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 ":" or "$" or "
23180 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 @" or "?".** is
23190 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 included as part
231a0 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a of the name..**
231b0 20 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 Parameters of t
231c0 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 he form "?" with
231d0 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 out a following
231e0 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 integer have no
231f0 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 name.** and are
23200 61 6c 73 6f 20 72 65 66 65 72 72 65 64 20 74 6f also referred to
23210 20 61 73 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 as "anonymous p
23220 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a arameters"..**.*
23230 2a 20 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 * The first host
23240 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 parameter has a
23250 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f n index of 1, no
23260 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 t 0..**.** If th
23270 65 20 76 61 6c 75 65 20 6e 20 69 73 20 6f 75 74 e value n is out
23280 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 of range or if
23290 74 68 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 the n-th paramet
232a0 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 er is.** nameles
232b0 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 s, then NULL is
232c0 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 72 returned. The r
232d0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 eturned string i
232e0 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 s.** always in U
232f0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 TF-8 encoding ev
23300 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 en if the named
23310 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a parameter was.**
23320 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 originally spec
23330 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 ified as UTF-16
23340 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 in [sqlite3_prep
23350 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b are16()] or.** [
23360 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
23370 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 6_v2()]..**.** S
23380 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
23390 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 3_bind_blob|sqli
233a0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 te3_bind()],.**
233b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
233c0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d rameter_count()]
233d0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 , and.** [sqlite
233e0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
233f0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a _index()]..**.**
23400 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
23410 2a 2a 20 7b 48 31 33 36 32 31 7d 20 54 68 65 20 ** {H13621} The
23420 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
23430 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 53 2c 4e rameter_name(S,N
23440 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
23450 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 urns.**
23460 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 a UTF-8 renderi
23470 6e 67 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 6f ng of the name o
23480 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 f the SQL parame
23490 74 65 72 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 ter in.**
234a0 20 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 the [prepared
234b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 statement] S ha
234c0 76 69 6e 67 20 69 6e 64 65 78 20 4e 2c 20 6f 72 ving index N, or
234d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 55 4c .** NUL
234e0 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f L if there is no
234f0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 77 SQL parameter w
23500 69 74 68 20 69 6e 64 65 78 20 4e 20 6f 72 20 69 ith index N or i
23510 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 f the.**
23520 20 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 parameter with
23530 20 69 6e 64 65 78 20 4e 20 69 73 20 61 6e 20 61 index N is an a
23540 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 nonymous paramet
23550 65 72 20 22 3f 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 er "?"..*/.const
23560 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 char *sqlite3_b
23570 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 ind_parameter_na
23580 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
23590 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 , int);../*.** C
235a0 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f API3REF: Index O
235b0 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 f A Parameter Wi
235c0 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 20 th A Given Name
235d0 7b 48 31 33 36 34 30 7d 20 3c 53 37 30 33 30 30 {H13640} <S70300
235e0 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 >.**.** Return t
235f0 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 he index of an S
23600 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 QL parameter giv
23610 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 54 68 en its name. Th
23620 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 e.** index value
23630 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 returned is sui
23640 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 table for use as
23650 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 the second.** p
23660 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c arameter to [sql
23670 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 ite3_bind_blob|s
23680 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 qlite3_bind()].
23690 20 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 A zero.** is re
236a0 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 turned if no mat
236b0 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 ching parameter
236c0 69 73 20 66 6f 75 6e 64 2e 20 20 54 68 65 20 70 is found. The p
236d0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 arameter.** name
236e0 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 must be given i
236f0 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 n UTF-8 even if
23700 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 the original sta
23710 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 tement.** was pr
23720 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d epared from UTF-
23730 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 16 text using [s
23740 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
23750 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 _v2()]..**.** Se
23760 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
23770 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 _bind_blob|sqlit
23780 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b e3_bind()],.** [
23790 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
237a0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c ameter_count()],
237b0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
237c0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
237d0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 index()]..**.**
237e0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
237f0 2a 20 7b 48 31 33 36 34 31 7d 20 54 68 65 20 5b * {H13641} The [
23800 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
23810 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 53 2c 4e ameter_index(S,N
23820 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
23830 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 urns.**
23840 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 53 51 the index of SQ
23850 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 L parameter in t
23860 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
23870 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 tement].**
23880 20 20 20 20 53 20 77 68 6f 73 65 20 6e 61 6d 65 S whose name
23890 20 6d 61 74 63 68 65 73 20 74 68 65 20 55 54 46 matches the UTF
238a0 2d 38 20 73 74 72 69 6e 67 20 4e 2c 20 6f 72 20 -8 string N, or
238b0 30 20 69 66 20 74 68 65 72 65 20 69 73 0a 2a 2a 0 if there is.**
238c0 20 20 20 20 20 20 20 20 20 20 6e 6f 20 6d 61 74 no mat
238d0 63 68 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ch..*/.int sqlit
238e0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
238f0 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f r_index(sqlite3_
23900 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 stmt*, const cha
23910 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a r *zName);../*.*
23920 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 * CAPI3REF: Rese
23930 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f t All Bindings O
23940 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 n A Prepared Sta
23950 74 65 6d 65 6e 74 20 7b 48 31 33 36 36 30 7d 20 tement {H13660}
23960 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 <S70300>.**.** C
23970 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 ontrary to the i
23980 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 ntuition of many
23990 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 , [sqlite3_reset
239a0 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 ()] does not res
239b0 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 et.** the [sqlit
239c0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 e3_bind_blob | b
239d0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 indings] on a [p
239e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
239f0 74 5d 2e 0a 2a 2a 20 55 73 65 20 74 68 69 73 20 t]..** Use this
23a00 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 routine to reset
23a10 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 all host parame
23a20 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a ters to NULL..**
23a30 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
23a40 2a 2a 0a 2a 2a 20 7b 48 31 33 36 36 31 7d 20 54 **.** {H13661} T
23a50 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 he [sqlite3_clea
23a60 72 5f 62 69 6e 64 69 6e 67 73 28 53 29 5d 20 69 r_bindings(S)] i
23a70 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 nterface resets
23a80 61 6c 6c 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20 all SQL.**
23a90 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 62 69 parameter bi
23aa0 6e 64 69 6e 67 73 20 69 6e 20 74 68 65 20 5b 70 ndings in the [p
23ab0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
23ac0 74 5d 20 53 20 62 61 63 6b 20 74 6f 20 4e 55 4c t] S back to NUL
23ad0 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 L..*/.int sqlite
23ae0 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 3_clear_bindings
23af0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b (sqlite3_stmt*);
23b00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
23b10 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 : Number Of Colu
23b20 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 mns In A Result
23b30 53 65 74 20 7b 48 31 33 37 31 30 7d 20 3c 53 31 Set {H13710} <S1
23b40 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 0700>.**.** Retu
23b50 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 rn the number of
23b60 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 columns in the
23b70 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 result set retur
23b80 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 ned by the.** [p
23b90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
23ba0 74 5d 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 t]. This routine
23bb0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 returns 0 if pS
23bc0 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a tmt is an SQL.**
23bd0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 statement that
23be0 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 does not return
23bf0 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c data (for exampl
23c00 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a e an [UPDATE])..
23c10 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
23c20 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 31 31 7d :.**.** {H13711}
23c30 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f The [sqlite3_co
23c40 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 69 lumn_count(S)] i
23c50 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
23c60 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a the number of.*
23c70 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 75 6d * colum
23c80 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 ns in the result
23c90 20 73 65 74 20 67 65 6e 65 72 61 74 65 64 20 62 set generated b
23ca0 79 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 y the [prepared
23cb0 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a statement] S,.**
23cc0 20 20 20 20 20 20 20 20 20 20 6f 72 20 30 20 69 or 0 i
23cd0 66 20 53 20 64 6f 65 73 20 6e 6f 74 20 67 65 6e f S does not gen
23ce0 65 72 61 74 65 20 61 20 72 65 73 75 6c 74 20 73 erate a result s
23cf0 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 et..*/.int sqlit
23d00 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 e3_column_count(
23d10 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
23d20 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tmt);../*.** CAP
23d30 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 I3REF: Column Na
23d40 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 mes In A Result
23d50 53 65 74 20 7b 48 31 33 37 32 30 7d 20 3c 53 31 Set {H13720} <S1
23d60 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 0700>.**.** Thes
23d70 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 e routines retur
23d80 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 n the name assig
23d90 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 ned to a particu
23da0 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e lar column.** in
23db0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 the result set
23dc0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 of a [SELECT] st
23dd0 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 20 73 71 atement. The sq
23de0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
23df0 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 e().** interface
23e00 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
23e10 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 er to a zero-ter
23e20 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 minated UTF-8 st
23e30 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 ring.** and sqli
23e40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 te3_column_name1
23e50 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 6() returns a po
23e60 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d inter to a zero-
23e70 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 terminated.** UT
23e80 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 F-16 string. Th
23e90 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
23ea0 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 r is the [prepar
23eb0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a ed statement].**
23ec0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 that implements
23ed0 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 the [SELECT] st
23ee0 61 74 65 6d 65 6e 74 2e 20 54 68 65 20 73 65 63 atement. The sec
23ef0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ond parameter is
23f00 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e the.** column n
23f10 75 6d 62 65 72 2e 20 20 54 68 65 20 6c 65 66 74 umber. The left
23f20 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e most column is n
23f30 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 umber 0..**.** T
23f40 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 he returned stri
23f50 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 ng pointer is va
23f60 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 lid until either
23f70 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
23f80 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 tatement].** is
23f90 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 destroyed by [sq
23fa0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
23fb0 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e ] or until the n
23fc0 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 ext call to.** s
23fd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
23fe0 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f me() or sqlite3_
23ff0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 column_name16()
24000 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 on the same colu
24010 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c mn..**.** If sql
24020 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 ite3_malloc() fa
24030 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 ils during the p
24040 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 rocessing of eit
24050 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 her routine.** (
24060 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 for example duri
24070 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 ng a conversion
24080 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 from UTF-8 to UT
24090 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 F-16) then a.**
240a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 NULL pointer is
240b0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
240c0 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 The name of a re
240d0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 sult column is t
240e0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 he value of the
240f0 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a "AS" clause for.
24100 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 ** that column,
24110 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 if there is an A
24120 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 S clause. If th
24130 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 ere is no AS cla
24140 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 use.** then the
24150 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 name of the colu
24160 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 mn is unspecifie
24170 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 d and may change
24180 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c from.** one rel
24190 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 ease of SQLite t
241a0 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a o the next..**.*
241b0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
241c0 0a 2a 2a 20 7b 48 31 33 37 32 31 7d 20 41 20 73 .** {H13721} A s
241d0 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 uccessful invoca
241e0 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c tion of the [sql
241f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
24200 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 (S,N)].**
24210 20 20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 interface ret
24220 75 72 6e 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 urns the name of
24230 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
24240 28 77 68 65 72 65 20 30 20 69 73 0a 2a 2a 20 20 (where 0 is.**
24250 20 20 20 20 20 20 20 20 74 68 65 20 6c 65 66 74 the left
24260 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 most column) for
24270 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 the result set
24280 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 of the.**
24290 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 [prepared sta
242a0 74 65 6d 65 6e 74 5d 20 53 20 61 73 20 61 20 7a tement] S as a z
242b0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 ero-terminated U
242c0 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a TF-8 string..**.
242d0 2a 2a 20 7b 48 31 33 37 32 33 7d 20 41 20 73 75 ** {H13723} A su
242e0 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 ccessful invocat
242f0 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 ion of the [sqli
24300 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 te3_column_name1
24310 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 6(S,N)].**
24320 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 72 65 interface re
24330 74 75 72 6e 73 20 74 68 65 20 6e 61 6d 65 20 6f turns the name o
24340 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e f the Nth column
24350 20 28 77 68 65 72 65 20 30 20 69 73 0a 2a 2a 20 (where 0 is.**
24360 20 20 20 20 20 20 20 20 20 74 68 65 20 6c 65 66 the lef
24370 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f tmost column) fo
24380 72 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 r the result set
24390 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 of the.**
243a0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 [prepared st
243b0 61 74 65 6d 65 6e 74 5d 20 53 20 61 73 20 61 20 atement] S as a
243c0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
243d0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a UTF-16 string.**
243e0 20 20 20 20 20 20 20 20 20 20 69 6e 20 74 68 65 in the
243f0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
24400 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 er..**.** {H1372
24410 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 4} The [sqlite3_
24420 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 column_name()] a
24430 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 nd [sqlite3_colu
24440 6d 6e 5f 6e 61 6d 65 31 36 28 29 5d 0a 2a 2a 20 mn_name16()].**
24450 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 interfa
24460 63 65 73 20 72 65 74 75 72 6e 20 61 20 4e 55 4c ces return a NUL
24470 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 74 68 65 L pointer if the
24480 79 20 61 72 65 20 75 6e 61 62 6c 65 20 74 6f 0a y are unable to.
24490 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f ** allo
244a0 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 cate memory to h
244b0 6f 6c 64 20 74 68 65 69 72 20 6e 6f 72 6d 61 6c old their normal
244c0 20 72 65 74 75 72 6e 20 73 74 72 69 6e 67 73 2e return strings.
244d0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 35 7d 20 .**.** {H13725}
244e0 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 If the N paramet
244f0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 er to [sqlite3_c
24500 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d olumn_name(S,N)]
24510 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 or.**
24520 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
24530 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 73 20 name16(S,N)] is
24540 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 out of range, th
24550 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 en the.**
24560 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 interfaces re
24570 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e turn a NULL poin
24580 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 ter..**.** {H137
24590 32 36 7d 20 54 68 65 20 73 74 72 69 6e 67 73 20 26} The strings
245a0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
245b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
245c0 28 53 2c 4e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 (S,N)] and.**
245d0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
245e0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c column_name16(S,
245f0 4e 29 5d 20 61 72 65 20 76 61 6c 69 64 20 75 6e N)] are valid un
24600 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 til the next.**
24610 20 20 20 20 20 20 20 20 20 63 61 6c 6c 20 74 6f call to
24620 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 20 either routine
24630 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 53 20 with the same S
24640 61 6e 64 20 4e 20 70 61 72 61 6d 65 74 65 72 73 and N parameters
24650 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 .** or
24660 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 66 until [sqlite3_f
24670 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 inalize(S)] is c
24680 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 alled..**.** {H1
24690 33 37 32 37 7d 20 57 68 65 6e 20 61 20 72 65 73 3727} When a res
246a0 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 ult column of a
246b0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 [SELECT] stateme
246c0 6e 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 nt contains.**
246d0 20 20 20 20 20 20 20 20 61 6e 20 41 53 20 63 6c an AS cl
246e0 61 75 73 65 2c 20 74 68 65 20 6e 61 6d 65 20 6f ause, the name o
246f0 66 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 f that column is
24700 20 74 68 65 20 69 64 65 6e 74 69 66 69 65 72 0a the identifier.
24710 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 ** to t
24720 68 65 20 72 69 67 68 74 20 6f 66 20 74 68 65 20 he right of the
24730 41 53 20 6b 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63 AS keyword..*/.c
24740 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
24750 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 e3_column_name(s
24760 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
24770 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 t N);.const void
24780 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
24790 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f _name16(sqlite3_
247a0 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a stmt*, int N);..
247b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
247c0 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 Source Of Data I
247d0 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 n A Query Result
247e0 20 7b 48 31 33 37 34 30 7d 20 3c 53 31 30 37 30 {H13740} <S1070
247f0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 0>.**.** These r
24800 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 outines provide
24810 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 a means to deter
24820 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e mine what column
24830 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c of what.** tabl
24840 65 20 69 6e 20 77 68 69 63 68 20 64 61 74 61 62 e in which datab
24850 61 73 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20 ase a result of
24860 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 a [SELECT] state
24870 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e ment comes from.
24880 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 .** The name of
24890 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 the database or
248a0 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 table or column
248b0 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 can be returned
248c0 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 as.** either a U
248d0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 TF-8 or UTF-16 s
248e0 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 74 tring. The _dat
248f0 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 abase_ routines
24900 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 return.** the da
24910 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 tabase name, the
24920 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 _table_ routine
24930 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 s return the tab
24940 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 le name, and.**
24950 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 the origin_ rout
24960 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 ines return the
24970 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 column name..**
24980 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 The returned str
24990 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 ing is valid unt
249a0 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 il the [prepared
249b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 statement] is d
249c0 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e estroyed.** usin
249d0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c g [sqlite3_final
249e0 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 ize()] or until
249f0 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 the same informa
24a00 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 tion is requeste
24a10 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 d.** again in a
24a20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 different encodi
24a30 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 ng..**.** The na
24a40 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 mes returned are
24a50 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e the original un
24a60 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f -aliased names o
24a70 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 f the.** databas
24a80 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f e, table, and co
24a90 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 lumn..**.** The
24aa0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
24ab0 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 o the following
24ac0 63 61 6c 6c 73 20 69 73 20 61 20 5b 70 72 65 70 calls is a [prep
24ad0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
24ae0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 .** These functi
24af0 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 ons return infor
24b00 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 mation about the
24b10 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 Nth column retu
24b20 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 rned by.** the s
24b30 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 tatement, where
24b40 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 N is the second
24b50 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e function argumen
24b60 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 t..**.** If the
24b70 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 Nth column retur
24b80 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 ned by the state
24b90 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 ment is an expre
24ba0 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 ssion or.** subq
24bb0 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 uery and is not
24bc0 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 a column value,
24bd0 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 then all of thes
24be0 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 e functions retu
24bf0 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68 65 rn.** NULL. The
24c00 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 se routine might
24c10 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c also return NUL
24c20 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c L if a memory al
24c30 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a location error.*
24c40 2a 20 6f 63 63 75 72 73 2e 20 20 4f 74 68 65 72 * occurs. Other
24c50 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 wise, they retur
24c60 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 n the name of th
24c70 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 e attached datab
24c80 61 73 65 2c 20 74 61 62 6c 65 0a 2a 2a 20 61 6e ase, table.** an
24c90 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 d column that qu
24ca0 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d ery result colum
24cb0 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 n was extracted
24cc0 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 from..**.** As w
24cd0 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 ith all other SQ
24ce0 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 Lite APIs, those
24cf0 20 70 6f 73 74 66 69 78 65 64 20 77 69 74 68 20 postfixed with
24d00 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 "16" return.** U
24d10 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 TF-16 encoded st
24d20 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72 rings, the other
24d30 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 functions retur
24d40 6e 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a n UTF-8. {END}.*
24d50 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20 *.** These APIs
24d60 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 are only availab
24d70 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 le if the librar
24d80 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 y was compiled w
24d90 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ith the.** [SQLI
24da0 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e TE_ENABLE_COLUMN
24db0 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 _METADATA] C-pre
24dc0 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c processor symbol
24dd0 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 defined..**.**
24de0 7b 41 31 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74 {A13751}.** If t
24df0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 wo or more threa
24e00 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d ds call one or m
24e10 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 ore of these rou
24e20 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 tines against th
24e30 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 e same.** prepar
24e40 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 ed statement and
24e50 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 column at the s
24e60 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 ame time then th
24e70 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a e results are.**
24e80 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
24e90 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
24ea0 0a 2a 2a 20 7b 48 31 33 37 34 31 7d 20 54 68 65 .** {H13741} The
24eb0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
24ec0 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 53 _database_name(S
24ed0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 ,N)] interface r
24ee0 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a eturns either.**
24ef0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 the UT
24f00 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 F-8 zero-termina
24f10 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 ted name of the
24f20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 77 68 database from wh
24f30 69 63 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 ich the.**
24f40 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 Nth result c
24f50 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 olumn of the [pr
24f60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
24f70 5d 20 53 20 69 73 20 65 78 74 72 61 63 74 65 64 ] S is extracted
24f80 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 ,.** or
24f90 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 NULL if the Nth
24fa0 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 column of S is
24fb0 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 a general expres
24fc0 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 sion.**
24fd0 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f or if unable to
24fe0 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 allocate memory
24ff0 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 to store the na
25000 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 me..**.** {H1374
25010 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 2} The [sqlite3_
25020 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f column_database_
25030 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 name16(S,N)] int
25040 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 erface returns e
25050 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 ither.**
25060 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 the UTF-16 nat
25070 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 7a ive byte order z
25080 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e ero-terminated n
25090 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 ame of the datab
250a0 61 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ase.**
250b0 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 4e from which the N
250c0 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e th result column
250d0 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 of the [prepare
250e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 d statement] S i
250f0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78 s.** ex
25100 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c tracted, or NULL
25110 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 if the Nth colu
25120 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e mn of S is a gen
25130 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a eral expression.
25140 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 ** or i
25150 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f f unable to allo
25160 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 cate memory to s
25170 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a tore the name..*
25180 2a 0a 2a 2a 20 7b 48 31 33 37 34 33 7d 20 54 68 *.** {H13743} Th
25190 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d e [sqlite3_colum
251a0 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 53 2c 4e n_table_name(S,N
251b0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
251c0 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 urns either.**
251d0 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d the UTF-
251e0 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 8 zero-terminate
251f0 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 d name of the ta
25200 62 6c 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74 ble from which t
25210 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e he.** N
25220 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e th result column
25230 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 of the [prepare
25240 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 d statement] S i
25250 73 20 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20 s extracted,.**
25260 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c or NULL
25270 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 if the Nth colu
25280 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e mn of S is a gen
25290 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a eral expression.
252a0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 ** or i
252b0 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f f unable to allo
252c0 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 cate memory to s
252d0 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a tore the name..*
252e0 2a 0a 2a 2a 20 7b 48 31 33 37 34 34 7d 20 54 68 *.** {H13744} Th
252f0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d e [sqlite3_colum
25300 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 53 n_table_name16(S
25310 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 ,N)] interface r
25320 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a eturns either.**
25330 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 the UT
25340 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 F-16 native byte
25350 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d order zero-term
25360 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 inated name of t
25370 68 65 20 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 he table.**
25380 20 20 20 20 20 66 72 6f 6d 20 77 68 69 63 68 20 from which
25390 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 the Nth result c
253a0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 olumn of the [pr
253b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
253c0 5d 20 53 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 ] S is.**
253d0 20 20 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72 extracted, or
253e0 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 NULL if the Nth
253f0 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 column of S is
25400 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 a general expres
25410 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 sion.**
25420 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f or if unable to
25430 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 allocate memory
25440 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 to store the na
25450 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 me..**.** {H1374
25460 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 5} The [sqlite3_
25470 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 column_origin_na
25480 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 me(S,N)] interfa
25490 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 ce returns eithe
254a0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 r.** th
254b0 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 e UTF-8 zero-ter
254c0 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 minated name of
254d0 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e the table column
254e0 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a from which the.
254f0 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 ** Nth
25500 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 result column of
25510 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
25520 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 tatement] S is e
25530 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 xtracted,.**
25540 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 or NULL if
25550 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
25560 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 of S is a genera
25570 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 l expression.**
25580 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 or if u
25590 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 nable to allocat
255a0 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 e memory to stor
255b0 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a e the name..**.*
255c0 2a 20 7b 48 31 33 37 34 36 7d 20 54 68 65 20 5b * {H13746} The [
255d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f sqlite3_column_o
255e0 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e rigin_name16(S,N
255f0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
25600 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 urns either.**
25610 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d the UTF-
25620 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 16 native byte o
25630 72 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e rder zero-termin
25640 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 ated name of the
25650 20 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 table.**
25660 20 20 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 column from w
25670 68 69 63 68 20 74 68 65 20 4e 74 68 20 72 65 73 hich the Nth res
25680 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 ult column of th
25690 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 e.** [p
256a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
256b0 74 5d 20 53 20 69 73 20 65 78 74 72 61 63 74 65 t] S is extracte
256c0 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 d, or NULL if th
256d0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 e Nth column.**
256e0 20 20 20 20 20 20 20 20 20 6f 66 20 53 20 69 73 of S is
256f0 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 a general expre
25700 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62 ssion or if unab
25710 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d le to allocate m
25720 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 emory.**
25730 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e to store the n
25740 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 ame..**.** {H137
25750 34 38 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 48} The return v
25760 61 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 20 20 alues from.**
25770 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
25780 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f column_database_
25790 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 name | column me
257a0 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 tadata interface
257b0 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 s].** a
257c0 72 65 20 76 61 6c 69 64 20 66 6f 72 20 74 68 65 re valid for the
257d0 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 lifetime of the
257e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
257f0 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 ment].**
25800 20 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 65 or until the e
25810 6e 63 6f 64 69 6e 67 20 69 73 20 63 68 61 6e 67 ncoding is chang
25820 65 64 20 62 79 20 61 6e 6f 74 68 65 72 20 6d 65 ed by another me
25830 74 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 tadata.**
25840 20 20 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c interface cal
25850 6c 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 70 l for the same p
25860 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
25870 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a t and column..**
25880 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a .** ASSUMPTIONS:
25890 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 20 .**.** {A13751}
258a0 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 If two or more t
258b0 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 hreads call one
258c0 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 or more.**
258d0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c [sqlite3_col
258e0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d umn_database_nam
258f0 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 e | column metad
25900 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a ata interfaces].
25910 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 ** for
25920 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 the same [prepar
25930 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e ed statement] an
25940 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a d result column.
25950 2a 2a 20 20 20 20 20 20 20 20 20 20 61 74 20 74 ** at t
25960 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 he same time the
25970 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 n the results ar
25980 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a e undefined..*/.
25990 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 const char *sqli
259a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 te3_column_datab
259b0 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 ase_name(sqlite3
259c0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e _stmt*,int);.con
259d0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
259e0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 _column_database
259f0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f _name16(sqlite3_
25a00 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 stmt*,int);.cons
25a10 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
25a20 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d column_table_nam
25a30 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
25a40 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 int);.const void
25a50 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
25a60 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 _table_name16(sq
25a70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
25a80 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 ;.const char *sq
25a90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 lite3_column_ori
25aa0 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 gin_name(sqlite3
25ab0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e _stmt*,int);.con
25ac0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
25ad0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e _column_origin_n
25ae0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ame16(sqlite3_st
25af0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a mt*,int);../*.**
25b00 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 CAPI3REF: Decla
25b10 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 red Datatype Of
25b20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b A Query Result {
25b30 48 31 33 37 36 30 7d 20 3c 53 31 30 37 30 30 3e H13760} <S10700>
25b40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
25b50 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 parameter is a
25b60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
25b70 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 ent]..** If this
25b80 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 statement is a
25b90 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 [SELECT] stateme
25ba0 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 nt and the Nth c
25bb0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 olumn of the.**
25bc0 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 returned result
25bd0 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c set of that [SEL
25be0 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 ECT] is a table
25bf0 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a column (not an.*
25c00 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 * expression or
25c10 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 subquery) then t
25c20 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 he declared type
25c30 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a of the table.**
25c40 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 column is retur
25c50 6e 65 64 2e 20 20 49 66 20 74 68 65 20 4e 74 68 ned. If the Nth
25c60 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 column of the r
25c70 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a esult set is an.
25c80 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 ** expression or
25c90 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 subquery, then
25ca0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 a NULL pointer i
25cb0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 s returned..** T
25cc0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 he returned stri
25cd0 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 ng is always UTF
25ce0 2d 38 20 65 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 -8 encoded. {END
25cf0 7d 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d }.**.** For exam
25d00 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 ple, given the d
25d10 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a atabase schema:.
25d20 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 **.** CREATE TAB
25d30 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 LE t1(c1 VARIANT
25d40 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 );.**.** and the
25d50 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 following state
25d60 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 ment to be compi
25d70 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 led:.**.** SELEC
25d80 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f T c1 + 1, c1 FRO
25d90 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 M t1;.**.** this
25da0 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 routine would r
25db0 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 eturn the string
25dc0 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 "VARIANT" for t
25dd0 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 he second result
25de0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 .** column (i==1
25df0 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f ), and a NULL po
25e00 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 inter for the fi
25e10 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d rst result colum
25e20 6e 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 n (i==0)..**.**
25e30 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 SQLite uses dyna
25e40 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 mic run-time typ
25e50 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 ing. So just be
25e60 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a cause a column.*
25e70 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f * is declared to
25e80 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 contain a parti
25e90 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 cular type does
25ea0 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 not mean that th
25eb0 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 e.** data stored
25ec0 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 in that column
25ed0 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 is of the declar
25ee0 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 ed type. SQLite
25ef0 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 is.** strongly
25f00 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 typed, but the t
25f10 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 yping is dynamic
25f20 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 54 79 not static. Ty
25f30 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 pe.** is associa
25f40 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 ted with individ
25f50 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 ual values, not
25f60 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e with the contain
25f70 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 ers.** used to h
25f80 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 old those values
25f90 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
25fa0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36 TS:.**.** {H1376
25fb0 31 7d 20 20 41 20 73 75 63 63 65 73 73 66 75 6c 1} A successful
25fc0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
25fd0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 3_column_decltyp
25fe0 65 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 e(S,N)] returns
25ff0 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 7a a.** z
26000 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 ero-terminated U
26010 54 46 2d 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 TF-8 string cont
26020 61 69 6e 69 6e 67 20 74 68 65 20 64 65 63 6c 61 aining the decla
26030 72 65 64 20 64 61 74 61 74 79 70 65 0a 2a 2a 20 red datatype.**
26040 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 of the
26050 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 table column th
26060 61 74 20 61 70 70 65 61 72 73 20 61 73 20 74 68 at appears as th
26070 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 e Nth column (nu
26080 6d 62 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 mbered.**
26090 20 20 20 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 from 0) of t
260a0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 74 6f he result set to
260b0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
260c0 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a tatement] S..**.
260d0 2a 2a 20 7b 48 31 33 37 36 32 7d 20 20 41 20 73 ** {H13762} A s
260e0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
260f0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d o [sqlite3_colum
26100 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 53 2c 4e n_decltype16(S,N
26110 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 )].**
26120 72 65 74 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74 returns a zero-t
26130 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36 erminated UTF-16
26140 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
26150 65 72 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 er string.**
26160 20 20 20 20 20 20 20 63 6f 6e 74 61 69 6e 69 6e containin
26170 67 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 64 g the declared d
26180 61 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 74 atatype of the t
26190 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 able column that
261a0 20 61 70 70 65 61 72 73 0a 2a 2a 20 20 20 20 20 appears.**
261b0 20 20 20 20 20 20 61 73 20 74 68 65 20 4e 74 68 as the Nth
261c0 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65 column (numbere
261d0 64 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 d from 0) of the
261e0 20 72 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74 result set to t
261f0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 he.**
26200 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
26210 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ent] S..**.** {H
26220 31 33 37 36 33 7d 20 20 49 66 20 4e 20 69 73 20 13763} If N is
26230 6c 65 73 73 20 74 68 61 6e 20 30 20 6f 72 20 4e less than 0 or N
26240 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e is greater than
26250 20 6f 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 or equal to.**
26260 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6e 75 the nu
26270 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 mber of columns
26280 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 in the [prepared
26290 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a statement] S,.*
262a0 2a 20 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 * or i
262b0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e f the Nth column
262c0 20 6f 66 20 53 20 69 73 20 61 6e 20 65 78 70 72 of S is an expr
262d0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 ession or subque
262e0 72 79 20 72 61 74 68 65 72 0a 2a 2a 20 20 20 20 ry rather.**
262f0 20 20 20 20 20 20 20 74 68 61 6e 20 61 20 74 61 than a ta
26300 62 6c 65 20 63 6f 6c 75 6d 6e 2c 20 6f 72 20 69 ble column, or i
26310 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 f a memory alloc
26320 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 0a 2a 2a ation failure.**
26330 20 20 20 20 20 20 20 20 20 20 20 6f 63 63 75 72 occur
26340 73 20 64 75 72 69 6e 67 20 65 6e 63 6f 64 69 6e s during encodin
26350 67 20 63 6f 6e 76 65 72 73 69 6f 6e 73 2c 20 74 g conversions, t
26360 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 hen.**
26370 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
26380 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 e3_column_declty
26390 70 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 pe(S,N)] or.**
263a0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
263b0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 3_column_decltyp
263c0 65 31 36 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e e16(S,N)] return
263d0 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 NULL..*/.const
263e0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
263f0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 lumn_decltype(sq
26400 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
26410 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 ;.const void *sq
26420 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 lite3_column_dec
26430 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f ltype16(sqlite3_
26440 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a stmt*,int);../*.
26450 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 ** CAPI3REF: Eva
26460 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 luate An SQL Sta
26470 74 65 6d 65 6e 74 20 7b 48 31 33 32 30 30 7d 20 tement {H13200}
26480 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 <S10000>.**.** A
26490 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 fter a [prepared
264a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 statement] has
264b0 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 been prepared us
264c0 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 ing either.** [s
264d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
264e0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 2()] or [sqlite3
264f0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
26500 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c or one of the l
26510 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 egacy.** interfa
26520 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 ces [sqlite3_pre
26530 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 pare()] or [sqli
26540 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d te3_prepare16()]
26550 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a , this function.
26560 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 ** must be calle
26570 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 d one or more ti
26580 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 mes to evaluate
26590 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a the statement..*
265a0 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 *.** The details
265b0 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 of the behavior
265c0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f of the sqlite3_
265d0 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 step() interface
265e0 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 depend.** on wh
265f0 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d ether the statem
26600 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 ent was prepared
26610 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 using the newer
26620 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a "v2" interface.
26630 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
26640 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 are_v2()] and [s
26650 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
26660 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c _v2()] or the ol
26670 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e der legacy.** in
26680 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 terface [sqlite3
26690 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 _prepare()] and
266a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
266b0 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 16()]. The use
266c0 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 of the.** new "v
266d0 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 2" interface is
266e0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 recommended for
266f0 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 new applications
26700 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a but the legacy.
26710 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c ** interface wil
26720 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 l continue to be
26730 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a supported..**.*
26740 2a 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 * In the legacy
26750 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 interface, the r
26760 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c eturn value will
26770 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 be either [SQLI
26780 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 TE_BUSY],.** [SQ
26790 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c LITE_DONE], [SQL
267a0 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 ITE_ROW], [SQLIT
267b0 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 E_ERROR], or [SQ
267c0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a LITE_MISUSE]..**
267d0 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 With the "v2" i
267e0 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 nterface, any of
267f0 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 the other [resu
26800 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 lt codes] or.**
26810 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
26820 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 codes] might be
26830 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c returned as wel
26840 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 l..**.** [SQLITE
26850 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 _BUSY] means tha
26860 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 t the database e
26870 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 ngine was unable
26880 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a to acquire the.
26890 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b ** database lock
268a0 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f s it needs to do
268b0 20 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68 its job. If th
268c0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 e statement is a
268d0 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 [COMMIT].** or
268e0 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f occurs outside o
268f0 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 f an explicit tr
26900 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 ansaction, then
26910 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 you can retry th
26920 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 e.** statement.
26930 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e If the statemen
26940 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d t is not a [COMM
26950 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 IT] and occurs w
26960 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 ithin a.** expli
26970 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 cit transaction
26980 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 then you should
26990 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 rollback the tra
269a0 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a nsaction before.
269b0 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a ** continuing..*
269c0 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e *.** [SQLITE_DON
269d0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 E] means that th
269e0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 e statement has
269f0 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 finished executi
26a00 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c ng.** successful
26a10 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 ly. sqlite3_ste
26a20 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 p() should not b
26a30 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f e called again o
26a40 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a n this virtual.*
26a50 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 * machine withou
26a60 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 t first calling
26a70 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
26a80 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 ] to reset the v
26a90 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e irtual.** machin
26aa0 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e e back to its in
26ab0 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a itial state..**.
26ac0 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 ** If the SQL st
26ad0 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 atement being ex
26ae0 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 ecuted returns a
26af0 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 ny data, then [S
26b00 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 QLITE_ROW].** is
26b10 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 returned each t
26b20 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 ime a new row of
26b30 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 data is ready f
26b40 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 or processing by
26b50 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 the.** caller.
26b60 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 The values may b
26b70 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 e accessed using
26b80 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 the [column acc
26b90 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a ess functions]..
26ba0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 ** sqlite3_step(
26bb0 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 ) is called agai
26bc0 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 n to retrieve th
26bd0 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 e next row of da
26be0 74 61 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 ta..**.** [SQLIT
26bf0 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 E_ERROR] means t
26c00 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 hat a run-time e
26c10 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 rror (such as a
26c20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 constraint.** vi
26c30 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 olation) has occ
26c40 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f urred. sqlite3_
26c50 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f step() should no
26c60 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 t be called agai
26c70 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 n on.** the VM.
26c80 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e More information
26c90 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 may be found by
26ca0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
26cb0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 3_errmsg()]..**
26cc0 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 With the legacy
26cd0 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 interface, a mor
26ce0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 e specific error
26cf0 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 code (for examp
26d00 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 le,.** [SQLITE_I
26d10 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 NTERRUPT], [SQLI
26d20 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c TE_SCHEMA], [SQL
26d30 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e ITE_CORRUPT], an
26d40 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 d so forth).** c
26d50 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 an be obtained b
26d60 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 y calling [sqlit
26d70 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 e3_reset()] on t
26d80 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 he.** [prepared
26d90 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 statement]. In
26da0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
26db0 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 ce,.** the more
26dc0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 specific error c
26dd0 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 ode is returned
26de0 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 directly by sqli
26df0 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a te3_step()..**.*
26e00 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 * [SQLITE_MISUSE
26e10 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 ] means that the
26e20 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 this routine wa
26e30 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f s called inappro
26e40 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 priately..** Per
26e50 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c haps it was call
26e60 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 ed on a [prepare
26e70 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 d statement] tha
26e80 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 t has.** already
26e90 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 been [sqlite3_f
26ea0 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 inalize | finali
26eb0 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 zed] or on one t
26ec0 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 hat had.** previ
26ed0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b ously returned [
26ee0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 SQLITE_ERROR] or
26ef0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 [SQLITE_DONE].
26f00 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 Or it could.**
26f10 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 be the case that
26f20 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
26f30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
26f40 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 being used by t
26f50 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 wo or.** more th
26f60 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d reads at the sam
26f70 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 e moment in time
26f80 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 ..**.** <b>Goofy
26f90 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 Interface Alert
26fa0 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 :</b> In the leg
26fb0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 acy interface, t
26fc0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 he sqlite3_step(
26fd0 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 ).** API always
26fe0 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 returns a generi
26ff0 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 c error code, [S
27000 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f QLITE_ERROR], fo
27010 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 llowing any.** e
27020 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 rror other than
27030 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e [SQLITE_BUSY] an
27040 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 d [SQLITE_MISUSE
27050 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c ]. You must cal
27060 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 l.** [sqlite3_re
27070 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 set()] or [sqlit
27080 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 e3_finalize()] i
27090 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 n order to find
270a0 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 one of the.** sp
270b0 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f ecific [error co
270c0 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 des] that better
270d0 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 describes the e
270e0 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 rror..** We admi
270f0 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 t that this is a
27100 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 goofy design.
27110 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 The problem has
27120 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 been fixed.** wi
27130 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 th the "v2" inte
27140 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 rface. If you p
27150 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f repare all of yo
27160 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ur SQL statement
27170 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 s.** using eithe
27180 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
27190 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c re_v2()] or [sql
271a0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
271b0 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 2()] instead.**
271c0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 of the legacy [s
271d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
271e0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 ] and [sqlite3_p
271f0 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 repare16()] inte
27200 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 rfaces,.** then
27210 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 the more specifi
27220 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 c [error codes]
27230 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 are returned dir
27240 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 ectly.** by sqli
27250 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 te3_step(). The
27260 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 use of the "v2"
27270 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 interface is re
27280 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a commended..**.**
27290 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
272a0 2a 2a 20 7b 48 31 33 32 30 32 7d 20 20 49 66 20 ** {H13202} If
272b0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
272c0 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 72 65 atement] S is re
272d0 61 64 79 20 74 6f 20 62 65 20 72 75 6e 2c 20 74 ady to be run, t
272e0 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 hen.**
272f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 [sqlite3_step(S
27300 29 5d 20 61 64 76 61 6e 63 65 73 20 74 68 61 74 )] advances that
27310 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
27320 65 6e 74 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20 ent until.**
27330 20 20 20 20 20 20 20 63 6f 6d 70 6c 65 74 69 6f completio
27340 6e 20 6f 72 20 75 6e 74 69 6c 20 69 74 20 69 73 n or until it is
27350 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e ready to return
27360 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66 20 another row of
27370 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
27380 20 72 65 73 75 6c 74 20 73 65 74 2c 20 6f 72 20 result set, or
27390 75 6e 74 69 6c 20 61 6e 20 5b 73 71 6c 69 74 65 until an [sqlite
273a0 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 3_interrupt | in
273b0 74 65 72 72 75 70 74 5d 0a 2a 2a 20 20 20 20 20 terrupt].**
273c0 20 20 20 20 20 20 6f 72 20 61 20 72 75 6e 2d 74 or a run-t
273d0 69 6d 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 ime error occurs
273e0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 34 7d ..**.** {H15304}
273f0 20 20 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f When a call to
27400 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 [sqlite3_step(S
27410 29 5d 20 63 61 75 73 65 73 20 74 68 65 20 5b 70 )] causes the [p
27420 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
27430 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 t].**
27440 53 20 74 6f 20 72 75 6e 20 74 6f 20 63 6f 6d 70 S to run to comp
27450 6c 65 74 69 6f 6e 2c 20 74 68 65 20 66 75 6e 63 letion, the func
27460 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 tion returns [SQ
27470 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a LITE_DONE]..**.*
27480 2a 20 7b 48 31 35 33 30 36 7d 20 20 57 68 65 6e * {H15306} When
27490 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 a call to [sqli
274a0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 73 74 6f te3_step(S)] sto
274b0 70 73 20 62 65 63 61 75 73 65 20 69 74 20 69 73 ps because it is
274c0 20 72 65 61 64 79 20 74 6f 0a 2a 2a 20 20 20 20 ready to.**
274d0 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 61 6e return an
274e0 6f 74 68 65 72 20 72 6f 77 20 6f 66 20 74 68 65 other row of the
274f0 20 72 65 73 75 6c 74 20 73 65 74 2c 20 69 74 20 result set, it
27500 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
27510 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 ROW]..**.** {H15
27520 33 30 38 7d 20 20 49 66 20 61 20 63 61 6c 6c 20 308} If a call
27530 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 to [sqlite3_step
27540 28 53 29 5d 20 65 6e 63 6f 75 6e 74 65 72 73 20 (S)] encounters
27550 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 an.**
27560 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 [sqlite3_interru
27570 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 20 pt | interrupt]
27580 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 or a run-time er
27590 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ror,.**
275a0 20 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 it returns an
275b0 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f appropriate erro
275c0 72 20 63 6f 64 65 20 74 68 61 74 20 69 73 20 6e r code that is n
275d0 6f 74 20 6f 6e 65 20 6f 66 0a 2a 2a 20 20 20 20 ot one of.**
275e0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f [SQLITE_O
275f0 4b 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d K], [SQLITE_ROW]
27600 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e , or [SQLITE_DON
27610 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 31 E]..**.** {H1531
27620 30 7d 20 20 49 66 20 61 6e 20 5b 73 71 6c 69 74 0} If an [sqlit
27630 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 e3_interrupt | i
27640 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 61 20 72 nterrupt] or a r
27650 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 0a 2a 2a un-time error.**
27660 20 20 20 20 20 20 20 20 20 20 20 6f 63 63 75 72 occur
27670 73 20 64 75 72 69 6e 67 20 61 20 63 61 6c 6c 20 s during a call
27680 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 to [sqlite3_step
27690 28 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 (S)].**
276a0 20 20 66 6f 72 20 61 20 5b 70 72 65 70 61 72 65 for a [prepare
276b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 63 d statement] S c
276c0 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 reated using.**
276d0 20 20 20 20 20 20 20 20 20 20 6c 65 67 61 63 79 legacy
276e0 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c interfaces [sql
276f0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
27700 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 or.**
27710 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
27720 31 36 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 16()], then the
27730 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
27740 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 either.**
27750 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 [SQLITE_ERR
27760 4f 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 OR], [SQLITE_BUS
27770 59 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d Y], or [SQLITE_M
27780 49 53 55 53 45 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 ISUSE]..*/.int s
27790 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 qlite3_step(sqli
277a0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a te3_stmt*);../*.
277b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d ** CAPI3REF: Num
277c0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 ber of columns i
277d0 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 20 7b n a result set {
277e0 48 31 33 37 37 30 7d 20 3c 53 31 30 37 30 30 3e H13770} <S10700>
277f0 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74 .**.** Returns t
27800 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c he number of val
27810 75 65 73 20 69 6e 20 74 68 65 20 63 75 72 72 65 ues in the curre
27820 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 nt row of the re
27830 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 sult set..**.**
27840 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
27850 2a 20 7b 48 31 33 37 37 31 7d 20 20 41 66 74 65 * {H13771} Afte
27860 72 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c r a call to [sql
27870 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 74 68 ite3_step(S)] th
27880 61 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 at returns [SQLI
27890 54 45 5f 52 4f 57 5d 2c 0a 2a 2a 20 20 20 20 20 TE_ROW],.**
278a0 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 the [sqlit
278b0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 e3_data_count(S)
278c0 5d 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 ] routine will r
278d0 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 76 eturn the same v
278e0 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 alue.**
278f0 20 20 61 73 20 74 68 65 20 5b 73 71 6c 69 74 65 as the [sqlite
27900 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 3_column_count(S
27910 29 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a )] function..**.
27920 2a 2a 20 7b 48 31 33 37 37 32 7d 20 20 41 66 74 ** {H13772} Aft
27930 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 er [sqlite3_step
27940 28 53 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 (S)] has returne
27950 64 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 d any value othe
27960 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 r than.**
27970 20 20 20 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d [SQLITE_ROW]
27980 20 6f 72 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 or before [sqli
27990 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 te3_step(S)] has
279a0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 been called on
279b0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
279c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
279d0 6d 65 6e 74 5d 20 66 6f 72 20 74 68 65 20 66 69 ment] for the fi
279e0 72 73 74 20 74 69 6d 65 20 73 69 6e 63 65 20 69 rst time since i
279f0 74 20 77 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 t was.**
27a00 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 [sqlite3_prep
27a10 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 are | prepared]
27a20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 or [sqlite3_rese
27a30 74 20 7c 20 72 65 73 65 74 5d 2c 0a 2a 2a 20 20 t | reset],.**
27a40 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 the [sq
27a50 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 lite3_data_count
27a60 28 53 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 (S)] routine ret
27a70 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e urns zero..*/.in
27a80 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 t sqlite3_data_c
27a90 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d ount(sqlite3_stm
27aa0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
27ab0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 * CAPI3REF: Fund
27ac0 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 amental Datatype
27ad0 73 20 7b 48 31 30 32 36 35 7d 20 3c 53 31 30 31 s {H10265} <S101
27ae0 31 30 3e 3c 53 31 30 31 32 30 3e 0a 2a 2a 20 4b 10><S10120>.** K
27af0 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f EYWORDS: SQLITE_
27b00 54 45 58 54 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 TEXT.**.** {H102
27b10 36 36 7d 20 45 76 65 72 79 20 76 61 6c 75 65 20 66} Every value
27b20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e in SQLite has on
27b30 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d e of five fundam
27b40 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a ental datatypes:
27b50 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
27b60 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 li> 64-bit signe
27b70 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 d integer.** <li
27b80 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c > 64-bit IEEE fl
27b90 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d oating point num
27ba0 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 ber.** <li> stri
27bb0 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a ng.** <li> BLOB.
27bc0 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 ** <li> NULL.**
27bd0 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a </ul> {END}.**.*
27be0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 * These constant
27bf0 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 s are codes for
27c00 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 each of those ty
27c10 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 pes..**.** Note
27c20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f that the SQLITE_
27c30 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 TEXT constant wa
27c40 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 s also used in S
27c50 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a QLite version 2.
27c60 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 ** for a complet
27c70 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 ely different me
27c80 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 aning. Software
27c90 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 that links agai
27ca0 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 nst both.** SQLi
27cb0 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 te version 2 and
27cc0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
27cd0 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 3 should use SQL
27ce0 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a ITE3_TEXT, not.*
27cf0 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a * SQLITE_TEXT..*
27d00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
27d10 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 _INTEGER 1.#def
27d20 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 ine SQLITE_FLOAT
27d30 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 2.#define SQ
27d40 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a LITE_BLOB 4.
27d50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e #define SQLITE_N
27d60 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 ULL 5.#ifdef
27d70 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 SQLITE_TEXT.# u
27d80 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 ndef SQLITE_TEXT
27d90 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 .#else.# define
27da0 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 SQLITE_TEXT
27db0 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 3.#endif.#define
27dc0 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 SQLITE3_TEXT
27dd0 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 3../*.** CAPI3
27de0 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 REF: Result Valu
27df0 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 20 es From A Query
27e00 7b 48 31 33 38 30 30 7d 20 3c 53 31 30 37 30 30 {H13800} <S10700
27e10 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b >.** KEYWORDS: {
27e20 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 column access fu
27e30 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 nctions}.**.** T
27e40 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f hese routines fo
27e50 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 rm the "result s
27e60 65 74 20 71 75 65 72 79 22 20 69 6e 74 65 72 66 et query" interf
27e70 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ace..**.** These
27e80 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
27e90 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f information abo
27ea0 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 ut a single colu
27eb0 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e mn of the curren
27ec0 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 t.** result row
27ed0 6f 66 20 61 20 71 75 65 72 79 2e 20 20 49 6e 20 of a query. In
27ee0 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 every case the f
27ef0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 irst argument is
27f00 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f a pointer.** to
27f10 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
27f20 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 tatement] that i
27f30 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 s being evaluate
27f40 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f d (the [sqlite3_
27f50 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 stmt*].** that w
27f60 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d as returned from
27f70 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
27f80 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f e_v2()] or one o
27f90 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a f its variants).
27fa0 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e ** and the secon
27fb0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
27fc0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 e index of the c
27fd0 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 olumn for which
27fe0 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 information.** s
27ff0 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 hould be returne
28000 64 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 d. The leftmost
28010 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 column of the r
28020 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 esult set has th
28030 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 0a 2a 2a e index 0..**.**
28040 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 If the SQL stat
28050 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 ement does not c
28060 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 urrently point t
28070 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f o a valid row, o
28080 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 r if the.** colu
28090 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 mn index is out
280a0 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 of range, the re
280b0 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 sult is undefine
280c0 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 d..** These rout
280d0 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 ines may only be
280e0 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 called when the
280f0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c most recent cal
28100 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 l to.** [sqlite3
28110 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 _step()] has ret
28120 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f urned [SQLITE_RO
28130 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a W] and neither.*
28140 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 * [sqlite3_reset
28150 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 ()] nor [sqlite3
28160 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 _finalize()] hav
28170 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 e been called su
28180 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 bsequently..** I
28190 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 f any of these r
281a0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c outines are call
281b0 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 ed after [sqlite
281c0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 3_reset()] or.**
281d0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
281e0 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b ze()] or after [
281f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
28200 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 has returned.**
28210 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 something other
28220 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 than [SQLITE_ROW
28230 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 ], the results a
28240 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a re undefined..**
28250 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 If [sqlite3_ste
28260 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 p()] or [sqlite3
28270 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 _reset()] or [sq
28280 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
28290 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 ].** are called
282a0 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 from a different
282b0 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e thread while an
282c0 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 y of these routi
282d0 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 nes.** are pendi
282e0 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 ng, then the res
282f0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e ults are undefin
28300 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ed..**.** The sq
28310 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 lite3_column_typ
28320 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 e() routine retu
28330 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 rns the.** [SQLI
28340 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 TE_INTEGER | dat
28350 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 atype code] for
28360 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 the initial data
28370 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 type.** of the
28380 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 result column.
28390 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c The returned val
283a0 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 ue is one of [SQ
283b0 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a LITE_INTEGER],.*
283c0 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d * [SQLITE_FLOAT]
283d0 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c , [SQLITE_TEXT],
283e0 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 [SQLITE_BLOB],
283f0 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d or [SQLITE_NULL]
28400 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 . The value.**
28410 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
28420 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
28430 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e ) is only meanin
28440 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a gful if no type.
28450 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 ** conversions h
28460 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 ave occurred as
28470 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e described below.
28480 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 After a type c
28490 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 onversion,.** th
284a0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
284b0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by sqlite3_colu
284c0 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 mn_type() is und
284d0 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a efined. Future.
284e0 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 ** versions of S
284f0 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 QLite may change
28500 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 the behavior of
28510 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
28520 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 type().** follow
28530 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 ing a type conve
28540 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 rsion..**.** If
28550 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 the result is a
28560 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 BLOB or UTF-8 st
28570 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 ring then the sq
28580 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
28590 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 es().** routine
285a0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
285b0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
285c0 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 hat BLOB or stri
285d0 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 ng..** If the re
285e0 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 sult is a UTF-16
285f0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 string, then sq
28600 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
28610 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a es() converts.**
28620 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 the string to U
28630 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 TF-8 and then re
28640 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
28650 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 49 66 of bytes..** If
28660 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 the result is a
28670 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 numeric value t
28680 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 hen sqlite3_colu
28690 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a mn_bytes() uses.
286a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 ** [sqlite3_snpr
286b0 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 intf()] to conve
286c0 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f rt that value to
286d0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 a UTF-8 string
286e0 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 and returns.** t
286f0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
28700 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e es in that strin
28710 67 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 g..** The value
28720 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f returned does no
28730 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 t include the ze
28740 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 ro terminator at
28750 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 the end.** of t
28760 68 65 20 73 74 72 69 6e 67 2e 20 20 46 6f 72 20 he string. For
28770 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c clarity: the val
28780 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 74 ue returned is t
28790 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 he number of.**
287a0 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 bytes in the str
287b0 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d ing, not the num
287c0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 ber of character
287d0 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 s..**.** Strings
287e0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
287f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
28800 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 () and sqlite3_c
28810 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a olumn_text16(),.
28820 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 ** even empty st
28830 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 rings, are alway
28840 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 s zero terminate
28850 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 0a 2a d. The return.*
28860 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c * value from sql
28870 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 ite3_column_blob
28880 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 () for a zero-le
28890 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 6e 20 ngth BLOB is an
288a0 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 arbitrary.** poi
288b0 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 nter, possibly e
288c0 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 ven a NULL point
288d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 er..**.** The sq
288e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
288f0 65 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20 69 es16() routine i
28900 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c s similar to sql
28910 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
28920 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 s().** but leave
28930 73 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20 s the result in
28940 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 UTF-16 in native
28950 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74 byte order inst
28960 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a ead of UTF-8..**
28970 20 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e The zero termin
28980 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c ator is not incl
28990 75 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75 uded in this cou
289a0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62 nt..**.** The ob
289b0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 ject returned by
289c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
289d0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a _value()] is an.
289e0 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 ** [unprotected
289f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
28a00 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f bject. An unpro
28a10 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
28a20 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d alue object.** m
28a30 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 ay only be used
28a40 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 with [sqlite3_bi
28a50 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 nd_value()] and
28a60 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
28a70 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 value()]..** If
28a80 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 the [unprotected
28a90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
28aa0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 object returned
28ab0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 by.** [sqlite3_c
28ac0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 olumn_value()] i
28ad0 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 s used in any ot
28ae0 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 her way, includi
28af0 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 ng calls.** to r
28b00 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 outines like [sq
28b10 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 lite3_value_int(
28b20 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c )], [sqlite3_val
28b30 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f ue_text()],.** o
28b40 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 r [sqlite3_value
28b50 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 _bytes()], then
28b60 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 the behavior is
28b70 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
28b80 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
28b90 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 attempt to conve
28ba0 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 rt the value whe
28bb0 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 re appropriate.
28bc0 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c For.** example,
28bd0 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c if the internal
28be0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 representation
28bf0 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 is FLOAT and a t
28c00 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 ext result.** is
28c10 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c requested, [sql
28c20 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d ite3_snprintf()]
28c30 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 is used interna
28c40 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 lly to perform t
28c50 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e he.** conversion
28c60 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 automatically.
28c70 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 The following t
28c80 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 able details the
28c90 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 conversions.**
28ca0 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 that are applied
28cb0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
28cc0 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 ote>.** <table b
28cd0 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 order="1">.** <t
28ce0 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c r><th> Internal<
28cf0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 br>Type <th> Req
28d00 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c uested<br>Type <
28d10 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a th> Conversion.
28d20 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 **.** <tr><td>
28d30 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 NULL <td> INT
28d40 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 EGER <td> Resu
28d50 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c lt is 0.** <tr><
28d60 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 td> NULL <td
28d70 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e > FLOAT <td>
28d80 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a Result is 0.0.*
28d90 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c * <tr><td> NULL
28da0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 <td> TEXT
28db0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 <td> Result i
28dc0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a s NULL pointer.*
28dd0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c * <tr><td> NULL
28de0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 <td> BLOB
28df0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 <td> Result i
28e00 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a s NULL pointer.*
28e10 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 * <tr><td> INTEG
28e20 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 ER <td> FLOAT
28e30 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 <td> Convert
28e40 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 from integer to
28e50 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 float.** <tr><td
28e60 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 > INTEGER <td>
28e70 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 TEXT <td> A
28e80 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f SCII rendering o
28e90 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a f the integer.**
28ea0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 <tr><td> INTEGE
28eb0 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 R <td> BLOB
28ec0 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 <td> Same as I
28ed0 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 NTEGER->TEXT.**
28ee0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <tr><td> FLOAT
28ef0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 <td> INTEGER
28f00 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 <td> Convert fr
28f10 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 om float to inte
28f20 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 ger.** <tr><td>
28f30 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 FLOAT <td>
28f40 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 TEXT <td> ASC
28f50 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 II rendering of
28f60 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 the float.** <tr
28f70 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c ><td> FLOAT <
28f80 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 td> BLOB <t
28f90 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 d> Same as FLOAT
28fa0 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 ->TEXT.** <tr><t
28fb0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e d> TEXT <td>
28fc0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 INTEGER <td>
28fd0 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 Use atoi().** <t
28fe0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 r><td> TEXT
28ff0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c <td> FLOAT <
29000 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a td> Use atof().*
29010 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 * <tr><td> TEXT
29020 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 <td> BLOB
29030 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 <td> No chang
29040 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 e.** <tr><td> B
29050 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 LOB <td> INTE
29060 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 GER <td> Conve
29070 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 rt to TEXT then
29080 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 use atoi().** <t
29090 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 r><td> BLOB
290a0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c <td> FLOAT <
290b0 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 td> Convert to T
290c0 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f EXT then use ato
290d0 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 f().** <tr><td>
290e0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 BLOB <td>
290f0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 TEXT <td> Add
29100 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 a zero terminat
29110 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 or if needed.**
29120 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c </table>.** </bl
29130 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
29140 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 The table above
29150 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 makes reference
29160 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 to standard C li
29170 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 brary functions
29180 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 atoi().** and at
29190 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f of(). SQLite do
291a0 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 es not really us
291b0 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e e these function
291c0 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a s. It has its.*
291d0 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 * own equivalent
291e0 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e internal routin
291f0 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 es. The atoi()
29200 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 and atof() names
29210 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 are.** used in
29220 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 the table for br
29230 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 evity and becaus
29240 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c e they are famil
29250 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 iar to most.** C
29260 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a programmers..**
29270 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 .** Note that wh
29280 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 en type conversi
29290 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 ons occur, point
292a0 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 ers returned by
292b0 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 prior.** calls t
292c0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e o sqlite3_column
292d0 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 _blob(), sqlite3
292e0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 _column_text(),
292f0 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 and/or.** sqlite
29300 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
29310 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 ) may be invalid
29320 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f ated..** Type co
29330 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f nversions and po
29340 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 inter invalidati
29350 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a ons might occur.
29360 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 ** in the follow
29370 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a ing cases:.**.**
29380 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 <ul>.** <li> Th
29390 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e e initial conten
293a0 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 t is a BLOB and
293b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
293c0 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 ext() or.**
293d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
293e0 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c text16() is call
293f0 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d ed. A zero-term
29400 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 inator might.**
29410 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 need to be
29420 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 added to the str
29430 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 ing.</li>.** <li
29440 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f > The initial co
29450 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 ntent is UTF-8 t
29460 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f ext and sqlite3_
29470 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
29480 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 or.** sqli
29490 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
294a0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 6() is called.
294b0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 The content must
294c0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a be converted.**
294d0 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e to UTF-16.
294e0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 </li>.** <li> Th
294f0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e e initial conten
29500 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 t is UTF-16 text
29510 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
29520 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a umn_bytes() or.*
29530 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 * sqlite3_c
29540 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 olumn_text() is
29550 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e called. The con
29560 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e tent must be con
29570 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 verted.** t
29580 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a o UTF-8.</li>.**
29590 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e </ul>.**.** Con
295a0 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e versions between
295b0 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 UTF-16be and UT
295c0 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 F-16le are alway
295d0 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 s done in place
295e0 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e and do.** not in
295f0 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 validate a prior
29600 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 pointer, though
29610 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 of course the c
29620 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 ontent of the bu
29630 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 ffer.** that the
29640 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 prior pointer p
29650 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 oints to will ha
29660 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 ve been modified
29670 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a . Other kinds.*
29680 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 * of conversion
29690 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 are done in plac
296a0 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 e when it is pos
296b0 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 sible, but somet
296c0 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 imes they.** are
296d0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e not possible an
296e0 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 d in those cases
296f0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 prior pointers
29700 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e are invalidated.
29710 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 .**.** The safes
29720 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f t and easiest to
29730 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 remember policy
29740 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 is to invoke th
29750 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 ese routines.**
29760 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f in one of the fo
29770 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a llowing ways:.**
29780 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 .** <ul>.** <li
29790 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f >sqlite3_column_
297a0 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 text() followed
297b0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d by sqlite3_colum
297c0 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a n_bytes()</li>.*
297d0 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 * <li>sqlite3_c
297e0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c olumn_blob() fol
297f0 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 lowed by sqlite3
29800 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c _column_bytes()<
29810 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c /li>.** <li>sql
29820 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
29830 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 16() followed by
29840 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
29850 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a bytes16()</li>.*
29860 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e * </ul>.**.** In
29870 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f other words, yo
29880 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 u should call sq
29890 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
298a0 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f t(),.** sqlite3_
298b0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f column_blob(), o
298c0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e r sqlite3_column
298d0 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 _text16() first
298e0 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 to force the res
298f0 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 ult.** into the
29900 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 desired format,
29910 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 then invoke sqli
29920 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
29930 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 () or.** sqlite3
29940 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
29950 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 ) to find the si
29960 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 ze of the result
29970 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 . Do not mix ca
29980 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 lls.** to sqlite
29990 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 3_column_text()
299a0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d or sqlite3_colum
299b0 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 n_blob() with ca
299c0 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 lls to.** sqlite
299d0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
299e0 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d (), and do not m
299f0 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 ix calls to sqli
29a00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
29a10 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 6().** with call
29a20 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c s to sqlite3_col
29a30 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a umn_bytes()..**.
29a40 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 73 20 ** The pointers
29a50 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c returned are val
29a60 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 id until a type
29a70 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 conversion occur
29a80 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 s as.** describe
29a90 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 d above, or unti
29aa0 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 l [sqlite3_step(
29ab0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 )] or [sqlite3_r
29ac0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 eset()] or.** [s
29ad0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
29ae0 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 )] is called. T
29af0 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 he memory space
29b00 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 used to hold str
29b10 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 ings.** and BLOB
29b20 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d s is freed autom
29b30 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 atically. Do <b
29b40 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 >not</b> pass th
29b50 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 e pointers retur
29b60 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ned.** [sqlite3_
29b70 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 column_blob()],
29b80 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
29b90 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e text()], etc. in
29ba0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 to.** [sqlite3_f
29bb0 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 ree()]..**.** If
29bc0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
29bd0 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 tion error occur
29be0 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 s during the eva
29bf0 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a luation of any.*
29c00 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 * of these routi
29c10 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 nes, a default v
29c20 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 alue is returned
29c30 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 . The default v
29c40 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 alue.** is eithe
29c50 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c r the integer 0,
29c60 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f the floating po
29c70 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 int number 0.0,
29c80 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 or a NULL.** poi
29c90 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e nter. Subsequen
29ca0 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 t calls to [sqli
29cb0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 te3_errcode()] w
29cc0 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 ill return.** [S
29cd0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a QLITE_NOMEM]..**
29ce0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
29cf0 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 33 7d 20 54 **.** {H13803} T
29d00 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 he [sqlite3_colu
29d10 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e mn_blob(S,N)] in
29d20 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 terface converts
29d30 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
29d40 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 Nth column in t
29d50 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f he current row o
29d60 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 f the result set
29d70 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 for.**
29d80 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
29d90 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f tatement] S into
29da0 20 61 20 42 4c 4f 42 20 61 6e 64 20 74 68 65 6e a BLOB and then
29db0 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 returns a.**
29dc0 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74 pointer t
29dd0 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 65 64 20 o the converted
29de0 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 value..**.** {H1
29df0 33 38 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 3806} The [sqlit
29e00 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
29e10 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 S,N)] interface
29e20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 returns the.**
29e30 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f number o
29e40 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 42 f bytes in the B
29e50 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 28 65 LOB or string (e
29e60 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a xclusive of the.
29e70 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f ** zero
29e80 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 terminator on t
29e90 68 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 he string) that
29ea0 77 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 was returned by
29eb0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
29ec0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c most recent call
29ed0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c to [sqlite3_col
29ee0 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f umn_blob(S,N)] o
29ef0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 r.** [s
29f00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
29f10 78 74 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 xt(S,N)]..**.**
29f20 7b 48 31 33 38 30 39 7d 20 54 68 65 20 5b 73 71 {H13809} The [sq
29f30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
29f40 65 73 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 es16(S,N)] inter
29f50 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 face returns the
29f60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d .** num
29f70 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 ber of bytes in
29f80 74 68 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c the string (excl
29f90 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 usive of the.**
29fa0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 zero te
29fb0 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 rminator on the
29fc0 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 string) that was
29fd0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 returned by the
29fe0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 .** mos
29ff0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f t recent call to
2a000 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
2a010 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a _text16(S,N)]..*
2a020 2a 0a 2a 2a 20 7b 48 31 33 38 31 32 7d 20 54 68 *.** {H13812} Th
2a030 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d e [sqlite3_colum
2a040 6e 5f 64 6f 75 62 6c 65 28 53 2c 4e 29 5d 20 69 n_double(S,N)] i
2a050 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 nterface convert
2a060 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 s the.**
2a070 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 Nth column in
2a080 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 the current row
2a090 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 of the result se
2a0a0 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 t for the.**
2a0b0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 [prepared
2a0c0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 statement] S int
2a0d0 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 o a floating poi
2a0e0 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 nt value and.**
2a0f0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 returns
2a100 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 a copy of that
2a110 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 value..**.** {H1
2a120 33 38 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 3815} The [sqlit
2a130 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 53 2c e3_column_int(S,
2a140 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f N)] interface co
2a150 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 nverts the.**
2a160 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d Nth colum
2a170 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 n in the current
2a180 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 row of the resu
2a190 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a lt set for the.*
2a1a0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 * [prep
2a1b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2a1c0 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 S into a 64-bit
2a1d0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 signed integer a
2a1e0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 nd.** r
2a1f0 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 eturns the lower
2a200 20 33 32 20 62 69 74 73 20 6f 66 20 74 68 61 74 32 bits of that
2a210 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 integer..**.**
2a220 7b 48 31 33 38 31 38 7d 20 54 68 65 20 5b 73 71 {H13818} The [sq
2a230 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 lite3_column_int
2a240 36 34 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 64(S,N)] interfa
2a250 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a ce converts the.
2a260 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 ** Nth
2a270 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 column in the cu
2a280 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 rrent row of the
2a290 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 20 result set for
2a2a0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
2a2b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2a2c0 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 36 34 ent] S into a 64
2a2d0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 -bit signed inte
2a2e0 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 ger and.**
2a2f0 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f returns a co
2a300 70 79 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 py of that integ
2a310 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 er..**.** {H1382
2a320 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 1} The [sqlite3_
2a330 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 column_text(S,N)
2a340 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 ] interface conv
2a350 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 erts the.**
2a360 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 Nth column
2a370 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 in the current r
2a380 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 ow of the result
2a390 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 set for.**
2a3a0 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61 72 the [prepar
2a3b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 ed statement] S
2a3c0 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d into a zero-term
2a3d0 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 inated UTF-8.**
2a3e0 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 string
2a3f0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f and returns a po
2a400 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 inter to that st
2a410 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 ring..**.** {H13
2a420 38 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 824} The [sqlite
2a430 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
2a440 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 S,N)] interface
2a450 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 converts the.**
2a460 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c Nth col
2a470 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 umn in the curre
2a480 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 nt row of the re
2a490 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 sult set for the
2a4a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 .** [pr
2a4b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2a4c0 5d 20 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d ] S into a zero-
2a4d0 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 terminated 2-byt
2a4e0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c e.** al
2a4f0 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74 igned UTF-16 nat
2a500 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 73 ive byte order s
2a510 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e tring and return
2a520 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 s.** a
2a530 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 pointer to that
2a540 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 string..**.** {H
2a550 31 33 38 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 13827} The [sqli
2a560 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
2a570 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 S,N)] interface
2a580 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 returns.**
2a590 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 one of [SQLI
2a5a0 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 TE_NULL], [SQLIT
2a5b0 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c E_INTEGER], [SQL
2a5c0 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 ITE_FLOAT],.**
2a5d0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f [SQLITE_
2a5e0 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 TEXT], or [SQLIT
2a5f0 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f E_BLOB] as appro
2a600 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 priate for.**
2a610 20 20 20 20 20 20 20 74 68 65 20 4e 74 68 20 63 the Nth c
2a620 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 olumn in the cur
2a630 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 rent row of the
2a640 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a result set for.*
2a650 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b * the [
2a660 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2a670 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 nt] S..**.** {H1
2a680 33 38 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 3830} The [sqlit
2a690 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 e3_column_value(
2a6a0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 S,N)] interface
2a6b0 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 returns a.**
2a6c0 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f pointer to
2a6d0 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 an [unprotected
2a6e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
2a6f0 6f 62 6a 65 63 74 20 66 6f 72 20 74 68 65 0a 2a object for the.*
2a700 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 * Nth c
2a710 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 olumn in the cur
2a720 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 rent row of the
2a730 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a result set for.*
2a740 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b * the [
2a750 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2a760 6e 74 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 nt] S..*/.const
2a770 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
2a780 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 lumn_blob(sqlite
2a790 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
2a7a0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f l);.int sqlite3_
2a7b0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c column_bytes(sql
2a7c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
2a7d0 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 iCol);.int sqlit
2a7e0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
2a7f0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
2a800 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 int iCol);.doub
2a810 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d le sqlite3_colum
2a820 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 n_double(sqlite3
2a830 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
2a840 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 );.int sqlite3_c
2a850 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 olumn_int(sqlite
2a860 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
2a870 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 l);.sqlite3_int6
2a880 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 4 sqlite3_column
2a890 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 _int64(sqlite3_s
2a8a0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
2a8b0 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 .const unsigned
2a8c0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
2a8d0 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 lumn_text(sqlite
2a8e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
2a8f0 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a l);.const void *
2a900 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2a910 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ext16(sqlite3_st
2a920 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
2a930 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 int sqlite3_colu
2a940 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f mn_type(sqlite3_
2a950 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
2a960 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 ;.sqlite3_value
2a970 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
2a980 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 value(sqlite3_st
2a990 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
2a9a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2a9b0 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 Destroy A Prepa
2a9c0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 red Statement Ob
2a9d0 6a 65 63 74 20 7b 48 31 33 33 30 30 7d 20 3c 53 ject {H13300} <S
2a9e0 37 30 33 30 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 70300><S30100>.*
2a9f0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
2aa00 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 _finalize() func
2aa10 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 tion is called t
2aa20 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 o delete a [prep
2aa30 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
2aa40 0a 2a 2a 20 49 66 20 74 68 65 20 73 74 61 74 65 .** If the state
2aa50 6d 65 6e 74 20 77 61 73 20 65 78 65 63 75 74 65 ment was execute
2aa60 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f d successfully o
2aa70 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20 61 r not executed a
2aa80 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53 t all, then.** S
2aa90 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 QLITE_OK is retu
2aaa0 72 6e 65 64 2e 20 49 66 20 65 78 65 63 75 74 69 rned. If executi
2aab0 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d on of the statem
2aac0 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65 6e 20 ent failed then
2aad0 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 an.** [error cod
2aae0 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 e] or [extended
2aaf0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 error code] is r
2ab00 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 eturned..**.** T
2ab10 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 his routine can
2ab20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 be called at any
2ab30 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68 point during th
2ab40 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 e execution of t
2ab50 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 he.** [prepared
2ab60 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 66 20 statement]. If
2ab70 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68 the virtual mach
2ab80 69 6e 65 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 ine has not.** c
2ab90 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 ompleted executi
2aba0 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75 on when this rou
2abb0 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 tine is called,
2abc0 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 that is like.**
2abd0 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 encountering an
2abe0 65 72 72 6f 72 20 6f 72 20 61 6e 20 5b 73 71 6c error or an [sql
2abf0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c ite3_interrupt |
2ac00 20 69 6e 74 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 interrupt]..**
2ac10 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 Incomplete updat
2ac20 65 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 es may be rolled
2ac30 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 back and transa
2ac40 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c ctions canceled,
2ac50 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e .** depending on
2ac60 20 74 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 the circumstanc
2ac70 65 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b es, and the.** [
2ac80 65 72 72 6f 72 20 63 6f 64 65 5d 20 72 65 74 75 error code] retu
2ac90 72 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 rned will be [SQ
2aca0 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a LITE_ABORT]..**.
2acb0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
2acc0 2a 0a 2a 2a 20 7b 48 31 31 33 30 32 7d 20 54 68 *.** {H11302} Th
2acd0 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c e [sqlite3_final
2ace0 69 7a 65 28 53 29 5d 20 69 6e 74 65 72 66 61 63 ize(S)] interfac
2acf0 65 20 64 65 73 74 72 6f 79 73 20 74 68 65 0a 2a e destroys the.*
2ad00 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 * [prep
2ad10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2ad20 53 20 61 6e 64 20 72 65 6c 65 61 73 65 73 20 61 S and releases a
2ad30 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d ll.** m
2ad40 65 6d 6f 72 79 20 61 6e 64 20 66 69 6c 65 20 72 emory and file r
2ad50 65 73 6f 75 72 63 65 73 20 68 65 6c 64 20 62 79 esources held by
2ad60 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 0a 2a 2a that object..**
2ad70 0a 2a 2a 20 7b 48 31 31 33 30 34 7d 20 49 66 20 .** {H11304} If
2ad80 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
2ad90 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
2ada0 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 _step(S)] for th
2adb0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 e.** [p
2adc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2add0 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 61 6e t] S returned an
2ade0 20 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 error,.**
2adf0 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 then [sqlite
2ae00 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 72 3_finalize(S)] r
2ae10 65 74 75 72 6e 73 20 74 68 61 74 20 73 61 6d 65 eturns that same
2ae20 20 65 72 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 error..*/.int s
2ae30 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2ae40 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
2ae50 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tmt);../*.** CAP
2ae60 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 I3REF: Reset A P
2ae70 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e repared Statemen
2ae80 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 33 30 t Object {H13330
2ae90 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a } <S70300>.**.**
2aea0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 The sqlite3_res
2aeb0 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 et() function is
2aec0 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 called to reset
2aed0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
2aee0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 tement].** objec
2aef0 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e t back to its in
2af00 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 itial state, rea
2af10 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 dy to be re-exec
2af20 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c uted..** Any SQL
2af30 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 statement varia
2af40 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 bles that had va
2af50 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 lues bound to th
2af60 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 em using.** the
2af70 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
2af80 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e ob | sqlite3_bin
2af90 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 d_*() API] retai
2afa0 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a n their values..
2afb0 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f ** Use [sqlite3_
2afc0 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 clear_bindings()
2afd0 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 ] to reset the b
2afe0 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b indings..**.** {
2aff0 48 31 31 33 33 32 7d 20 54 68 65 20 5b 73 71 6c H11332} The [sql
2b000 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 ite3_reset(S)] i
2b010 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 nterface resets
2b020 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
2b030 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 atement] S.**
2b040 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f 20 74 back to t
2b050 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 he beginning of
2b060 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a its program..**.
2b070 2a 2a 20 7b 48 31 31 33 33 34 7d 20 49 66 20 74 ** {H11334} If t
2b080 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 he most recent c
2b090 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
2b0a0 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 step(S)] for the
2b0b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 .** [pr
2b0c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2b0d0 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 ] S returned [SQ
2b0e0 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 LITE_ROW] or [SQ
2b0f0 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 LITE_DONE],.**
2b100 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 5b 73 or if [s
2b110 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 qlite3_step(S)]
2b120 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 has never before
2b130 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 been called on
2b140 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 S,.** t
2b150 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 hen [sqlite3_res
2b160 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b et(S)] returns [
2b170 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a SQLITE_OK]..**.*
2b180 2a 20 7b 48 31 31 33 33 36 7d 20 49 66 20 74 68 * {H11336} If th
2b190 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 e most recent ca
2b1a0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ll to [sqlite3_s
2b1b0 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a tep(S)] for the.
2b1c0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 ** [pre
2b1d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2b1e0 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 S indicated an
2b1f0 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 error, then.**
2b200 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
2b210 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 _reset(S)] retur
2b220 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 ns an appropriat
2b230 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a e [error code]..
2b240 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 38 7d 20 54 **.** {H11338} T
2b250 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 he [sqlite3_rese
2b260 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 t(S)] interface
2b270 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 does not change
2b280 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 the values.**
2b290 20 20 20 20 20 20 20 6f 66 20 61 6e 79 20 5b 73 of any [s
2b2a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
2b2b0 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 |bindings] on th
2b2c0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
2b2d0 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 ement] S..*/.int
2b2e0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 sqlite3_reset(s
2b2f0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
2b300 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
2b310 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 3REF: Create Or
2b320 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e Redefine SQL Fun
2b330 63 74 69 6f 6e 73 20 7b 48 31 36 31 30 30 7d 20 ctions {H16100}
2b340 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 <S20200>.** KEYW
2b350 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 ORDS: {function
2b360 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 creation routine
2b370 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 s}.** KEYWORDS:
2b380 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 {application-def
2b390 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f ined SQL functio
2b3a0 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 n}.** KEYWORDS:
2b3b0 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 {application-def
2b3c0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f ined SQL functio
2b3d0 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ns}.**.** These
2b3e0 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 two functions (c
2b3f0 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 ollectively know
2b400 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 n as "function c
2b410 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 reation routines
2b420 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 ").** are used t
2b430 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 o add SQL functi
2b440 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 ons or aggregate
2b450 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 s or to redefine
2b460 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a the behavior.**
2b470 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c of existing SQL
2b480 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 functions or ag
2b490 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f gregates. The o
2b4a0 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20 62 nly difference b
2b4b0 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77 etween the.** tw
2b4c0 6f 20 69 73 20 74 68 61 74 20 74 68 65 20 73 65 o is that the se
2b4d0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20 cond parameter,
2b4e0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
2b4f0 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f (scalar) functio
2b500 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 n or.** aggregat
2b510 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e e, is encoded in
2b520 20 55 54 46 2d 38 20 66 6f 72 20 73 71 6c 69 74 UTF-8 for sqlit
2b530 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
2b540 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36 0a on() and UTF-16.
2b550 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 ** for sqlite3_c
2b560 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
2b570 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 ()..**.** The fi
2b580 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 rst parameter is
2b590 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
2b5a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 onnection] to wh
2b5b0 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 ich the SQL.** f
2b5c0 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 unction is to be
2b5d0 20 61 64 64 65 64 2e 20 20 49 66 20 61 20 73 69 added. If a si
2b5e0 6e 67 6c 65 20 70 72 6f 67 72 61 6d 20 75 73 65 ngle program use
2b5f0 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 s more than one
2b600 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
2b610 65 63 74 69 6f 6e 20 69 6e 74 65 72 6e 61 6c 6c ection internall
2b620 79 2c 20 74 68 65 6e 20 53 51 4c 20 66 75 6e 63 y, then SQL func
2b630 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 tions must be ad
2b640 64 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 ded individually
2b650 20 74 6f 0a 2a 2a 20 65 61 63 68 20 64 61 74 61 to.** each data
2b660 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e base connection.
2b670 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e .**.** The secon
2b680 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 d parameter is t
2b690 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 he name of the S
2b6a0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 QL function to b
2b6b0 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 e created or.**
2b6c0 72 65 64 65 66 69 6e 65 64 2e 20 20 54 68 65 20 redefined. The
2b6d0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 length of the na
2b6e0 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f me is limited to
2b6f0 20 32 35 35 20 62 79 74 65 73 2c 20 65 78 63 6c 255 bytes, excl
2b700 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74 68 65 20 usive of.** the
2b710 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e zero-terminator.
2b720 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 Note that the
2b730 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69 name length limi
2b740 74 20 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e t is in bytes, n
2b750 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 ot.** characters
2b760 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 . Any attempt t
2b770 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 o create a funct
2b780 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 ion with a longe
2b790 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 r name.** will r
2b7a0 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 esult in [SQLITE
2b7b0 5f 45 52 52 4f 52 5d 20 62 65 69 6e 67 20 72 65 _ERROR] being re
2b7c0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 turned..**.** Th
2b7d0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
2b7e0 72 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 r is the number
2b7f0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 of arguments tha
2b800 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 t the SQL functi
2b810 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 on or.** aggrega
2b820 74 65 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69 te takes. If thi
2b830 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e s parameter is n
2b840 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 egative, then th
2b850 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f e SQL function o
2b860 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d r.** aggregate m
2b870 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 ay take any numb
2b880 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e er of arguments.
2b890 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 .**.** The fourt
2b8a0 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 h parameter, eTe
2b8b0 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 xtRep, specifies
2b8c0 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 what.** [SQLITE
2b8d0 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 _UTF8 | text enc
2b8e0 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 oding] this SQL
2b8f0 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 function prefers
2b900 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 for.** its para
2b910 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c meters. Any SQL
2b920 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d function implem
2b930 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 entation should
2b940 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a be able to work.
2b950 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46 ** work with UTF
2b960 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 -8, UTF-16le, or
2b970 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 UTF-16be. But
2b980 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 some implementat
2b990 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d ions may be.** m
2b9a0 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 ore efficient wi
2b9b0 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 th one encoding
2b9c0 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49 than another. I
2b9d0 74 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a t is allowed to.
2b9e0 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 ** invoke sqlite
2b9f0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
2ba00 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 n() or sqlite3_c
2ba10 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
2ba20 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 () multiple.** t
2ba30 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 imes with the sa
2ba40 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 me function but
2ba50 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 with different v
2ba60 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 alues of eTextRe
2ba70 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 p..** When multi
2ba80 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ple implementati
2ba90 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 ons of the same
2baa0 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 function are ava
2bab0 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a ilable, SQLite.*
2bac0 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 * will pick the
2bad0 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 one that involve
2bae0 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 s the least amou
2baf0 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 nt of data conve
2bb00 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 rsion..** If the
2bb10 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e re is only a sin
2bb20 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 gle implementati
2bb30 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f on which does no
2bb40 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74 t care what text
2bb50 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 .** encoding is
2bb60 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 used, then the f
2bb70 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 ourth argument s
2bb80 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 hould be [SQLITE
2bb90 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 _ANY]..**.** The
2bba0 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 fifth parameter
2bbb0 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 is an arbitrary
2bbc0 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 pointer. The i
2bbd0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
2bbe0 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e the.** function
2bbf0 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 can gain access
2bc00 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 to this pointer
2bc10 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
2bc20 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a user_data()]..**
2bc30 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e 74 68 2c .** The seventh,
2bc40 20 65 69 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 eighth and nint
2bc50 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 h parameters, xF
2bc60 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 unc, xStep and x
2bc70 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f Final, are.** po
2bc80 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 inters to C-lang
2bc90 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 uage functions t
2bca0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 hat implement th
2bcb0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f e SQL function o
2bcc0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 r.** aggregate.
2bcd0 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e A scalar SQL fun
2bce0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 ction requires a
2bcf0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
2bd00 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a of the xFunc.**
2bd10 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 callback only,
2bd20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73 68 NULL pointers sh
2bd30 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 61 ould be passed a
2bd40 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 s the xStep and
2bd50 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 xFinal.** parame
2bd60 74 65 72 73 2e 20 41 6e 20 61 67 67 72 65 67 61 ters. An aggrega
2bd70 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 te SQL function
2bd80 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c requires an impl
2bd90 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 ementation of xS
2bda0 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 tep.** and xFina
2bdb0 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c l and NULL shoul
2bdc0 64 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 d be passed for
2bdd0 78 46 75 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65 xFunc. To delete
2bde0 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 an existing.**
2bdf0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 SQL function or
2be00 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 aggregate, pass
2be10 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 NULL for all thr
2be20 65 65 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c ee function call
2be30 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 backs..**.** It
2be40 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 is permitted to
2be50 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c register multipl
2be60 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
2be70 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a s of the same.**
2be80 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 functions with
2be90 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 the same name bu
2bea0 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 t with either di
2beb0 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 ffering numbers
2bec0 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 of.** arguments
2bed0 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 or differing pre
2bee0 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f ferred text enco
2bef0 64 69 6e 67 73 2e 20 20 53 51 4c 69 74 65 20 77 dings. SQLite w
2bf00 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 ill use.** the i
2bf10 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f mplementation mo
2bf20 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 st closely match
2bf30 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 es the way in wh
2bf40 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 ich the.** SQL f
2bf50 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e unction is used.
2bf60 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
2bf70 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 33 S:.**.** {H16103
2bf80 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 } The [sqlite3_c
2bf90 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
2bfa0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 ()] interface be
2bfb0 68 61 76 65 73 20 65 78 61 63 74 6c 79 0a 2a 2a haves exactly.**
2bfc0 20 20 20 20 20 20 20 20 20 20 6c 69 6b 65 20 5b like [
2bfd0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
2bfe0 75 6e 63 74 69 6f 6e 28 29 5d 20 69 6e 20 65 76 unction()] in ev
2bff0 65 72 79 20 77 61 79 20 65 78 63 65 70 74 20 74 ery way except t
2c000 68 61 74 20 69 74 0a 2a 2a 20 20 20 20 20 20 20 hat it.**
2c010 20 20 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 interprets th
2c020 65 20 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 20 e zFunctionName
2c030 61 72 67 75 6d 65 6e 74 20 61 73 20 7a 65 72 6f argument as zero
2c040 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d -terminated UTF-
2c050 31 36 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 16.** n
2c060 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
2c070 20 69 6e 73 74 65 61 64 20 6f 66 20 61 73 20 7a instead of as z
2c080 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 ero-terminated U
2c090 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 TF-8..**.** {H16
2c0a0 31 30 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 106} A successfu
2c0b0 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a l invocation of.
2c0c0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
2c0d0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
2c0e0 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 function(D,X,N,E
2c0f0 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 ,...)] interface
2c100 20 72 65 67 69 73 74 65 72 73 0a 2a 2a 20 20 20 registers.**
2c110 20 20 20 20 20 20 20 6f 72 20 72 65 70 6c 61 63 or replac
2c120 65 73 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 es callback func
2c130 74 69 6f 6e 73 20 69 6e 20 74 68 65 20 5b 64 61 tions in the [da
2c140 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2c150 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 n] D.**
2c160 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 used to impleme
2c170 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 nt the SQL funct
2c180 69 6f 6e 20 6e 61 6d 65 64 20 58 20 77 69 74 68 ion named X with
2c190 20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a N parameters.**
2c1a0 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 68 61 and ha
2c1b0 76 69 6e 67 20 61 20 70 72 65 66 65 72 72 65 64 ving a preferred
2c1c0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f text encoding o
2c1d0 66 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 f E..**.** {H161
2c1e0 30 39 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 09} A successful
2c1f0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
2c200 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
2c210 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c n(D,X,N,E,P,F,S,
2c220 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 L)].**
2c230 72 65 70 6c 61 63 65 73 20 74 68 65 20 50 2c 20 replaces the P,
2c240 46 2c 20 53 2c 20 61 6e 64 20 4c 20 76 61 6c 75 F, S, and L valu
2c250 65 73 20 66 72 6f 6d 20 61 6e 79 20 70 72 69 6f es from any prio
2c260 72 20 63 61 6c 6c 73 20 77 69 74 68 0a 2a 2a 20 r calls with.**
2c270 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d the sam
2c280 65 20 44 2c 20 58 2c 20 4e 2c 20 61 6e 64 20 45 e D, X, N, and E
2c290 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b values..**.** {
2c2a0 48 31 36 31 31 32 7d 20 54 68 65 20 5b 73 71 6c H16112} The [sql
2c2b0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
2c2c0 74 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 tion(D,X,...)] i
2c2d0 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 nterface fails w
2c2e0 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ith.**
2c2f0 61 20 72 65 74 75 72 6e 20 63 6f 64 65 20 6f 66 a return code of
2c300 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
2c310 69 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 if the SQL funct
2c320 69 6f 6e 20 6e 61 6d 65 20 58 20 69 73 0a 2a 2a ion name X is.**
2c330 20 20 20 20 20 20 20 20 20 20 6c 6f 6e 67 65 72 longer
2c340 20 74 68 61 6e 20 32 35 35 20 62 79 74 65 73 20 than 255 bytes
2c350 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 exclusive of the
2c360 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 zero terminator
2c370 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 31 38 7d ..**.** {H16118}
2c380 20 45 69 74 68 65 72 20 46 20 6d 75 73 74 20 62 Either F must b
2c390 65 20 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 e NULL and S and
2c3a0 20 4c 20 61 72 65 20 6e 6f 6e 2d 4e 55 4c 4c 20 L are non-NULL
2c3b0 6f 72 20 65 6c 73 65 20 46 0a 2a 2a 20 20 20 20 or else F.**
2c3c0 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d 4e 55 4c is non-NUL
2c3d0 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72 L and S and L ar
2c3e0 65 20 4e 55 4c 4c 2c 20 6f 74 68 65 72 77 69 73 e NULL, otherwis
2c3f0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 e.** [s
2c400 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
2c410 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 nction(D,X,N,E,P
2c420 2c 46 2c 53 2c 4c 29 5d 20 72 65 74 75 72 6e 73 ,F,S,L)] returns
2c430 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e [SQLITE_ERROR].
2c440 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 31 7d 20 .**.** {H16121}
2c450 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 The [sqlite3_cre
2c460 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 2e ate_function(D,.
2c470 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66 ..)] interface f
2c480 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 ails with an.**
2c490 20 20 20 20 20 20 20 20 20 65 72 72 6f 72 20 63 error c
2c4a0 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 42 ode of [SQLITE_B
2c4b0 55 53 59 5d 20 69 66 20 74 68 65 72 65 20 65 78 USY] if there ex
2c4c0 69 73 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 ist [prepared st
2c4d0 61 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20 20 20 20 atements].**
2c4e0 20 20 20 20 20 20 61 73 73 6f 63 69 61 74 65 64 associated
2c4f0 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 with the [datab
2c500 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
2c510 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 34 D..**.** {H16124
2c520 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 } The [sqlite3_c
2c530 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 reate_function(D
2c540 2c 58 2c 4e 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 ,X,N,...)] inter
2c550 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 face fails with
2c560 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 an.** e
2c570 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 rror code of [SQ
2c580 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 70 LITE_ERROR] if p
2c590 61 72 61 6d 65 74 65 72 20 4e 20 28 73 70 65 63 arameter N (spec
2c5a0 69 66 79 69 6e 67 20 74 68 65 20 6e 75 6d 62 65 ifying the numbe
2c5b0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 r.** of
2c5c0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 arguments to th
2c5d0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 62 e SQL function b
2c5e0 65 69 6e 67 20 72 65 67 69 73 74 65 72 65 64 29 eing registered)
2c5f0 20 69 73 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20 is less.**
2c600 20 20 20 20 20 74 68 61 6e 20 2d 31 20 6f 72 20 than -1 or
2c610 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 greater than 127
2c620 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 37 7d ..**.** {H16127}
2c630 20 57 68 65 6e 20 4e 20 69 73 20 6e 6f 6e 2d 6e When N is non-n
2c640 65 67 61 74 69 76 65 2c 20 74 68 65 20 5b 73 71 egative, the [sq
2c650 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
2c660 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 ction(D,X,N,...)
2c670 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e ].** in
2c680 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 63 terface causes c
2c690 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69 allbacks to be i
2c6a0 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 53 nvoked for the S
2c6b0 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 QL function.**
2c6c0 20 20 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20 named X
2c6d0 77 68 65 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 when the number
2c6e0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 of arguments to
2c6f0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
2c700 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 is.**
2c710 65 78 61 63 74 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a exactly N..**.**
2c720 20 7b 48 31 36 31 33 30 7d 20 57 68 65 6e 20 4e {H16130} When N
2c730 20 69 73 20 2d 31 2c 20 74 68 65 20 5b 73 71 6c is -1, the [sql
2c740 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
2c750 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d tion(D,X,N,...)]
2c760 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 .** int
2c770 65 72 66 61 63 65 20 63 61 75 73 65 73 20 63 61 erface causes ca
2c780 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e llbacks to be in
2c790 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 53 51 voked for the SQ
2c7a0 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 L function.**
2c7b0 20 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77 named X w
2c7c0 69 74 68 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f ith any number o
2c7d0 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a f arguments..**.
2c7e0 2a 2a 20 7b 48 31 36 31 33 33 7d 20 57 68 65 6e ** {H16133} When
2c7f0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
2c800 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
2c810 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a on(D,X,N,...)].*
2c820 2a 20 20 20 20 20 20 20 20 20 20 73 70 65 63 69 * speci
2c830 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c fy multiple impl
2c840 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 ementations of t
2c850 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e he same function
2c860 20 58 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 X.** a
2c870 6e 64 20 77 68 65 6e 20 6f 6e 65 20 69 6d 70 6c nd when one impl
2c880 65 6d 65 6e 74 61 74 69 6f 6e 20 68 61 73 20 4e ementation has N
2c890 3e 3d 30 20 61 6e 64 20 74 68 65 20 6f 74 68 65 >=0 and the othe
2c8a0 72 20 68 61 73 20 4e 3d 28 2d 31 29 0a 2a 2a 20 r has N=(-1).**
2c8b0 20 20 20 20 20 20 20 20 20 74 68 65 20 69 6d 70 the imp
2c8c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 lementation with
2c8d0 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 4e 20 69 73 a non-zero N is
2c8e0 20 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a preferred..**.*
2c8f0 2a 20 7b 48 31 36 31 33 36 7d 20 57 68 65 6e 20 * {H16136} When
2c900 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
2c910 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
2c920 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 0a n(D,X,N,E,...)].
2c930 2a 2a 20 20 20 20 20 20 20 20 20 20 73 70 65 63 ** spec
2c940 69 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 ify multiple imp
2c950 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 lementations of
2c960 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f the same functio
2c970 6e 20 58 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 n X with.**
2c980 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 6e 75 the same nu
2c990 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 mber of argument
2c9a0 73 20 4e 20 62 75 74 20 77 69 74 68 20 64 69 66 s N but with dif
2c9b0 66 65 72 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 ferent.**
2c9c0 20 20 20 65 6e 63 6f 64 69 6e 67 73 20 45 2c 20 encodings E,
2c9d0 74 68 65 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65 then the impleme
2c9e0 6e 74 61 74 69 6f 6e 20 77 68 65 72 65 20 45 20 ntation where E
2c9f0 6d 61 74 63 68 65 73 20 74 68 65 0a 2a 2a 20 20 matches the.**
2ca00 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65 database
2ca10 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 70 72 65 encoding is pre
2ca20 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ferred..**.** {H
2ca30 31 36 31 33 39 7d 20 46 6f 72 20 61 6e 20 61 67 16139} For an ag
2ca40 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 gregate SQL func
2ca50 74 69 6f 6e 20 63 72 65 61 74 65 64 20 75 73 69 tion created usi
2ca60 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b ng.** [
2ca70 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
2ca80 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c unction(D,X,N,E,
2ca90 50 2c 30 2c 53 2c 4c 29 5d 20 74 68 65 20 66 69 P,0,S,L)] the fi
2caa0 6e 61 6c 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 nalizer.**
2cab0 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 4c 20 77 function L w
2cac0 69 6c 6c 20 61 6c 77 61 79 73 20 62 65 20 69 6e ill always be in
2cad0 76 6f 6b 65 64 20 65 78 61 63 74 6c 79 20 6f 6e voked exactly on
2cae0 63 65 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 ce if the.**
2caf0 20 20 20 20 20 20 73 74 65 70 20 66 75 6e 63 74 step funct
2cb00 69 6f 6e 20 53 20 69 73 20 63 61 6c 6c 65 64 20 ion S is called
2cb10 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 one or more time
2cb20 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 34 32 s..**.** {H16142
2cb30 7d 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e } When SQLite in
2cb40 76 6f 6b 65 73 20 65 69 74 68 65 72 20 74 68 65 vokes either the
2cb50 20 78 46 75 6e 63 20 6f 72 20 78 53 74 65 70 20 xFunc or xStep
2cb60 66 75 6e 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20 function of.**
2cb70 20 20 20 20 20 20 20 20 61 6e 20 61 70 70 6c 69 an appli
2cb80 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 cation-defined S
2cb90 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 QL function or a
2cba0 67 67 72 65 67 61 74 65 20 63 72 65 61 74 65 64 ggregate created
2cbb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20 .** by
2cbc0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
2cbd0 66 75 6e 63 74 69 6f 6e 28 29 5d 20 6f 72 20 5b function()] or [
2cbe0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
2cbf0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 0a 2a 2a unction16()],.**
2cc00 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 then t
2cc10 68 65 20 61 72 72 61 79 20 6f 66 20 5b 73 71 6c he array of [sql
2cc20 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
2cc30 63 74 73 20 70 61 73 73 65 64 20 61 73 20 74 68 cts passed as th
2cc40 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 e.** th
2cc50 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 ird parameter ar
2cc60 65 20 61 6c 77 61 79 73 20 5b 70 72 6f 74 65 63 e always [protec
2cc70 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
2cc80 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 69 e] objects..*/.i
2cc90 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 nt sqlite3_creat
2cca0 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 e_function(. sq
2ccb0 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e lite3 *db,. con
2ccc0 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 st char *zFuncti
2ccd0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 onName,. int nA
2cce0 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 rg,. int eTextR
2ccf0 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 ep,. void *pApp
2cd00 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 ,. void (*xFunc
2cd10 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 )(sqlite3_contex
2cd20 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 t*,int,sqlite3_v
2cd30 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 alue**),. void
2cd40 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 (*xStep)(sqlite3
2cd50 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 _context*,int,sq
2cd60 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a lite3_value**),.
2cd70 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 void (*xFinal)
2cd80 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
2cd90 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 *).);.int sqlite
2cda0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
2cdb0 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a n16(. sqlite3 *
2cdc0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 db,. const void
2cdd0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c *zFunctionName,
2cde0 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 . int nArg,. i
2cdf0 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 nt eTextRep,. v
2ce00 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 oid *pApp,. voi
2ce10 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 d (*xFunc)(sqlit
2ce20 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c e3_context*,int,
2ce30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 sqlite3_value**)
2ce40 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 ,. void (*xStep
2ce50 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 )(sqlite3_contex
2ce60 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 t*,int,sqlite3_v
2ce70 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 alue**),. void
2ce80 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 (*xFinal)(sqlite
2ce90 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 3_context*).);..
2cea0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2ceb0 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b Text Encodings {
2cec0 48 31 30 32 36 37 7d 20 3c 53 35 30 32 30 30 3e H10267} <S50200>
2ced0 20 3c 48 31 36 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 <H16100>.**.**
2cee0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 These constant d
2cef0 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f efine integer co
2cf00 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 des that represe
2cf10 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a nt the various.*
2cf20 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 * text encodings
2cf30 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 supported by SQ
2cf40 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 Lite..*/.#define
2cf50 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 SQLITE_UTF8
2cf60 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 1.#define
2cf70 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 SQLITE_UTF16LE
2cf80 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 2.#define
2cf90 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 SQLITE_UTF16BE
2cfa0 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 3.#define
2cfb0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 SQLITE_UTF16
2cfc0 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 4 /* U
2cfd0 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f se native byte o
2cfe0 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rder */.#define
2cff0 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 SQLITE_ANY
2d000 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 5 /* sq
2d010 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
2d020 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 ction only */.#d
2d030 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 efine SQLITE_UTF
2d040 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 16_ALIGNED 8
2d050 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 /* sqlite3_crea
2d060 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c te_collation onl
2d070 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 y */../*.** CAPI
2d080 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 3REF: Deprecated
2d090 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 Functions.** DE
2d0a0 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 PRECATED.**.** T
2d0b0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 hese functions a
2d0c0 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e re [deprecated].
2d0d0 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 In order to ma
2d0e0 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 intain.** backwa
2d0f0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 rds compatibilit
2d100 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 y with older cod
2d110 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f e, these functio
2d120 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 ns continue .**
2d130 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e to be supported.
2d140 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 However, new a
2d150 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 pplications shou
2d160 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 ld avoid.** the
2d170 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e use of these fun
2d180 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 ctions. To help
2d190 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c encourage peopl
2d1a0 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 e to avoid.** us
2d1b0 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 ing these functi
2d1c0 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 ons, we are not
2d1d0 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f going to tell yo
2d1e0 75 20 77 61 6e 74 20 74 68 65 79 20 64 6f 2e 0a u want they do..
2d1f0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 */.int sqlite3_a
2d200 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 ggregate_count(s
2d210 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
2d220 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 ;.int sqlite3_ex
2d230 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 pired(sqlite3_st
2d240 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 mt*);.int sqlite
2d250 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 3_transfer_bindi
2d260 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ngs(sqlite3_stmt
2d270 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a *, sqlite3_stmt*
2d280 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 );.int sqlite3_g
2d290 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f lobal_recover(vo
2d2a0 69 64 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 id);.void sqlite
2d2b0 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 3_thread_cleanup
2d2c0 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 (void);.int sqli
2d2d0 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d te3_memory_alarm
2d2e0 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 (void(*)(void*,s
2d2f0 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 qlite3_int64,int
2d300 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f ),void*,sqlite3_
2d310 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 int64);../*.** C
2d320 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 API3REF: Obtaini
2d330 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 ng SQL Function
2d340 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 Parameter Values
2d350 20 7b 48 31 35 31 30 30 7d 20 3c 53 32 30 32 30 {H15100} <S2020
2d360 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 0>.**.** The C-l
2d370 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e anguage implemen
2d380 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 tation of SQL fu
2d390 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 nctions and aggr
2d3a0 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 egates uses.** t
2d3b0 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 his set of inter
2d3c0 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f face routines to
2d3d0 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 access the para
2d3e0 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a meter values on.
2d3f0 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 ** the function
2d400 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a or aggregate..**
2d410 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 .** The xFunc (f
2d420 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 or scalar functi
2d430 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 ons) or xStep (f
2d440 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70 or aggregates) p
2d450 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 arameters.** to
2d460 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
2d470 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 function()] and
2d480 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
2d490 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a function16()].**
2d4a0 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b define callback
2d4b0 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 s that implement
2d4c0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
2d4d0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 ns and aggregate
2d4e0 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61 s..** The 4th pa
2d4f0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 rameter to these
2d500 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e callbacks is an
2d510 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 array of pointe
2d520 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 rs to.** [protec
2d530 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
2d540 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 e] objects. The
2d550 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 re is one [sqlit
2d560 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
2d570 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 for.** each par
2d580 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 ameter to the SQ
2d590 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 L function. The
2d5a0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
2d5b0 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 used to.** extra
2d5c0 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 ct values from t
2d5d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 he [sqlite3_valu
2d5e0 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a e] objects..**.*
2d5f0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
2d600 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 work only with
2d610 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 [protected sqlit
2d620 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
2d630 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 s..** Any attemp
2d640 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 t to use these r
2d650 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 outines on an [u
2d660 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
2d670 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a e3_value].** obj
2d680 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 ect results in u
2d690 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f ndefined behavio
2d6a0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 r..**.** These r
2d6b0 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 outines work jus
2d6c0 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 t like the corre
2d6d0 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e sponding [column
2d6e0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e access function
2d6f0 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 s].** except tha
2d700 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 t these routine
2d710 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 s take a single
2d720 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 [protected sqlit
2d730 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
2d740 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 .** pointer inst
2d750 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 ead of a [sqlite
2d760 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 3_stmt*] pointer
2d770 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 and an integer
2d780 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a column number..*
2d790 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
2d7a0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 _value_text16()
2d7b0 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63 interface extrac
2d7c0 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 ts a UTF-16 stri
2d7d0 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 ng.** in the nat
2d7e0 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f ive byte-order o
2d7f0 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 f the host machi
2d800 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 ne. The.** sqli
2d810 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
2d820 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 be() and sqlite3
2d830 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 _value_text16le(
2d840 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 ) interfaces.**
2d850 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 extract UTF-16 s
2d860 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e trings as big-en
2d870 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d dian and little-
2d880 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 endian respectiv
2d890 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ely..**.** The s
2d8a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d qlite3_value_num
2d8b0 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 eric_type() inte
2d8c0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 rface attempts t
2d8d0 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 o apply.** numer
2d8e0 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 ic affinity to t
2d8f0 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 he value. This
2d900 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 means that an at
2d910 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 tempt is.** made
2d920 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 to convert the
2d930 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 value to an inte
2d940 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 ger or floating
2d950 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 point. If.** su
2d960 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 ch a conversion
2d970 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 is possible with
2d980 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f out loss of info
2d990 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 rmation (in othe
2d9a0 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 r.** words, if t
2d9b0 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 he value is a st
2d9c0 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 ring that looks
2d9d0 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a like a number).*
2d9e0 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 * then the conve
2d9f0 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d rsion is perform
2da00 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e ed. Otherwise n
2da10 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 o conversion occ
2da20 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c urs..** The [SQL
2da30 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 ITE_INTEGER | da
2da40 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f tatype] after co
2da50 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 nversion is retu
2da60 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 rned..**.** Plea
2da70 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 se pay particula
2da80 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 r attention to t
2da90 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65 he fact that the
2daa0 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 pointer returne
2dab0 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 d.** from [sqlit
2dac0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d e3_value_blob()]
2dad0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 , [sqlite3_value
2dae0 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 _text()], or.**
2daf0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 [sqlite3_value_t
2db00 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 ext16()] can be
2db10 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 invalidated by a
2db20 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
2db30 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
2db40 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 value_bytes()],
2db50 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 [sqlite3_value_b
2db60 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 ytes16()], [sqli
2db70 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 te3_value_text()
2db80 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 ],.** or [sqlite
2db90 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 3_value_text16()
2dba0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 ]..**.** These r
2dbb0 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 outines must be
2dbc0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 called from the
2dbd0 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a same thread as.*
2dbe0 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 * the SQL functi
2dbf0 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 on that supplied
2dc00 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 the [sqlite3_va
2dc10 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 lue*] parameters
2dc20 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
2dc30 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 TS:.**.** {H1510
2dc40 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 3} The [sqlite3_
2dc50 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20 69 value_blob(V)] i
2dc60 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 nterface convert
2dc70 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 s the.**
2dc80 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c [protected sql
2dc90 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
2dca0 63 74 20 56 20 69 6e 74 6f 20 61 20 42 4c 4f 42 ct V into a BLOB
2dcb0 20 61 6e 64 20 74 68 65 6e 0a 2a 2a 20 20 20 20 and then.**
2dcc0 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 returns a
2dcd0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 pointer to the c
2dce0 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65 2e 0a onverted value..
2dcf0 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 36 7d 20 54 **.** {H15106} T
2dd00 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 he [sqlite3_valu
2dd10 65 5f 62 79 74 65 73 28 56 29 5d 20 69 6e 74 65 e_bytes(V)] inte
2dd20 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 rface returns th
2dd30 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 e.** nu
2dd40 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e mber of bytes in
2dd50 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 the BLOB or str
2dd60 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f ing (exclusive o
2dd70 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 f the.**
2dd80 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f zero terminato
2dd90 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29 r on the string)
2dda0 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e that was return
2ddb0 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 ed by the.**
2ddc0 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e most recen
2ddd0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 t call to [sqlit
2dde0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29 e3_value_blob(V)
2ddf0 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 ] or.**
2de00 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
2de10 74 65 78 74 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 text(V)]..**.**
2de20 7b 48 31 35 31 30 39 7d 20 54 68 65 20 5b 73 71 {H15109} The [sq
2de30 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 lite3_value_byte
2de40 73 31 36 28 56 29 5d 20 69 6e 74 65 72 66 61 63 s16(V)] interfac
2de50 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a e returns the.**
2de60 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 number
2de70 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 of bytes in the
2de80 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 string (exclusi
2de90 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 ve of the.**
2dea0 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 zero termi
2deb0 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 nator on the str
2dec0 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65 ing) that was re
2ded0 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a turned by the.**
2dee0 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 most r
2def0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 ecent call to [s
2df00 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
2df10 74 31 36 28 56 29 5d 2c 0a 2a 2a 20 20 20 20 20 t16(V)],.**
2df20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61 [sqlite3_va
2df30 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56 29 5d lue_text16be(V)]
2df40 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 , or [sqlite3_va
2df50 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56 29 5d lue_text16le(V)]
2df60 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31 32 7d ..**.** {H15112}
2df70 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 The [sqlite3_va
2df80 6c 75 65 5f 64 6f 75 62 6c 65 28 56 29 5d 20 69 lue_double(V)] i
2df90 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 nterface convert
2dfa0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 s the.**
2dfb0 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c [protected sql
2dfc0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
2dfd0 63 74 20 56 20 69 6e 74 6f 20 61 20 66 6c 6f 61 ct V into a floa
2dfe0 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 ting point value
2dff0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 and.**
2e000 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 returns a copy
2e010 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a of that value..*
2e020 2a 0a 2a 2a 20 7b 48 31 35 31 31 35 7d 20 54 68 *.** {H15115} Th
2e030 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
2e040 5f 69 6e 74 28 56 29 5d 20 69 6e 74 65 72 66 61 _int(V)] interfa
2e050 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a ce converts the.
2e060 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f ** [pro
2e070 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
2e080 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 alue] object V i
2e090 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 nto a 64-bit sig
2e0a0 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a ned integer and.
2e0b0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 ** retu
2e0c0 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20 33 32 rns the lower 32
2e0d0 20 62 69 74 73 20 6f 66 20 74 68 61 74 20 69 6e bits of that in
2e0e0 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 teger..**.** {H1
2e0f0 35 31 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 5118} The [sqlit
2e100 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 56 e3_value_int64(V
2e110 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e )] interface con
2e120 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 verts the.**
2e130 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 [protected
2e140 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
2e150 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 object V into a
2e160 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 64-bit signed in
2e170 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 teger and.**
2e180 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 returns a
2e190 63 6f 70 79 20 6f 66 20 74 68 61 74 20 69 6e 74 copy of that int
2e1a0 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 eger..**.** {H15
2e1b0 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 121} The [sqlite
2e1c0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 56 29 5d 3_value_text(V)]
2e1d0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 interface conve
2e1e0 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 rts the.**
2e1f0 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 [protected s
2e200 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
2e210 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 ject V into a ze
2e220 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 ro-terminated UT
2e230 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 F-8.**
2e240 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 string and retur
2e250 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
2e260 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a that string..**.
2e270 2a 2a 20 7b 48 31 35 31 32 34 7d 20 54 68 65 20 ** {H15124} The
2e280 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 [sqlite3_value_t
2e290 65 78 74 31 36 28 56 29 5d 20 69 6e 74 65 72 66 ext16(V)] interf
2e2a0 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 ace converts the
2e2b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 .** [pr
2e2c0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
2e2d0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 value] object V
2e2e0 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d into a zero-term
2e2f0 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a inated 2-byte.**
2e300 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 aligne
2e310 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 d UTF-16 native
2e320 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 byte order.**
2e330 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e string an
2e340 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e d returns a poin
2e350 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 ter to that stri
2e360 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32 ng..**.** {H1512
2e370 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 7} The [sqlite3_
2e380 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56 value_text16be(V
2e390 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e )] interface con
2e3a0 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 verts the.**
2e3b0 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 [protected
2e3c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
2e3d0 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 object V into a
2e3e0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
2e3f0 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 2-byte.**
2e400 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 aligned UTF-1
2e410 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 6 big-endian.**
2e420 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 string
2e430 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f and returns a po
2e440 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 inter to that st
2e450 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 ring..**.** {H15
2e460 31 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 130} The [sqlite
2e470 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 3_value_text16le
2e480 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 (V)] interface c
2e490 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 onverts the.**
2e4a0 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 [protect
2e4b0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
2e4c0 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 ] object V into
2e4d0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
2e4e0 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 d 2-byte.**
2e4f0 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 aligned UTF
2e500 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 -16 little-endia
2e510 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 n.** st
2e520 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 ring and returns
2e530 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
2e540 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a at string..**.**
2e550 20 7b 48 31 35 31 33 33 7d 20 54 68 65 20 5b 73 {H15133} The [s
2e560 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 qlite3_value_typ
2e570 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 e(V)] interface
2e580 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 returns.**
2e590 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 one of [SQLI
2e5a0 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 TE_NULL], [SQLIT
2e5b0 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c E_INTEGER], [SQL
2e5c0 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 ITE_FLOAT],.**
2e5d0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f [SQLITE_
2e5e0 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 TEXT], or [SQLIT
2e5f0 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f E_BLOB] as appro
2e600 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 priate for.**
2e610 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 the [sqli
2e620 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
2e630 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 t V..**.** {H151
2e640 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 36} The [sqlite3
2e650 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 _value_numeric_t
2e660 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 ype(V)] interfac
2e670 65 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 20 20 e converts.**
2e680 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 6f 74 the [prot
2e690 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
2e6a0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e lue] object V in
2e6b0 74 6f 20 65 69 74 68 65 72 20 61 6e 20 69 6e 74 to either an int
2e6c0 65 67 65 72 20 6f 72 0a 2a 2a 20 20 20 20 20 20 eger or.**
2e6d0 20 20 20 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 a floating p
2e6e0 6f 69 6e 74 20 76 61 6c 75 65 20 69 66 20 69 74 oint value if it
2e6f0 20 63 61 6e 20 64 6f 20 73 6f 20 77 69 74 68 6f can do so witho
2e700 75 74 20 6c 6f 73 73 20 6f 66 0a 2a 2a 20 20 20 ut loss of.**
2e710 20 20 20 20 20 20 20 69 6e 66 6f 72 6d 61 74 69 informati
2e720 6f 6e 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 on, and returns
2e730 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e one of [SQLITE_N
2e740 55 4c 4c 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 ULL],.**
2e750 20 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 [SQLITE_INTEGE
2e760 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 R], [SQLITE_FLOA
2e770 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 T], [SQLITE_TEXT
2e780 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 ], or.**
2e790 20 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 [SQLITE_BLOB]
2e7a0 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 as appropriate f
2e7b0 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 or the.**
2e7c0 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 [protected sq
2e7d0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
2e7e0 65 63 74 20 56 20 61 66 74 65 72 20 74 68 65 20 ect V after the
2e7f0 63 6f 6e 76 65 72 73 69 6f 6e 20 61 74 74 65 6d conversion attem
2e800 70 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 pt..*/.const voi
2e810 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 d *sqlite3_value
2e820 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 _blob(sqlite3_va
2e830 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 lue*);.int sqlit
2e840 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 e3_value_bytes(s
2e850 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
2e860 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 int sqlite3_valu
2e870 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 e_bytes16(sqlite
2e880 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 3_value*);.doubl
2e890 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f e sqlite3_value_
2e8a0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 double(sqlite3_v
2e8b0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 alue*);.int sqli
2e8c0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 te3_value_int(sq
2e8d0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 lite3_value*);.s
2e8e0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c qlite3_int64 sql
2e8f0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 ite3_value_int64
2e900 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
2e910 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 ;.const unsigned
2e920 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 char *sqlite3_v
2e930 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 alue_text(sqlite
2e940 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 3_value*);.const
2e950 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 void *sqlite3_v
2e960 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 alue_text16(sqli
2e970 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e te3_value*);.con
2e980 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
2e990 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 _value_text16le(
2e9a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
2e9b0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
2e9c0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
2e9d0 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 6be(sqlite3_valu
2e9e0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 e*);.int sqlite3
2e9f0 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 _value_type(sqli
2ea00 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 te3_value*);.int
2ea10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e sqlite3_value_n
2ea20 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 umeric_type(sqli
2ea30 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a te3_value*);../*
2ea40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 .** CAPI3REF: Ob
2ea50 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 tain Aggregate F
2ea60 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 unction Context
2ea70 7b 48 31 36 32 31 30 7d 20 3c 53 32 30 32 30 30 {H16210} <S20200
2ea80 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c >.**.** The impl
2ea90 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67 ementation of ag
2eaa0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 gregate SQL func
2eab0 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72 tions use this r
2eac0 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 outine to alloca
2ead0 74 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72 te.** a structur
2eae0 65 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 e for storing th
2eaf0 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a eir state..**.**
2eb00 20 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 The first time
2eb10 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 the sqlite3_aggr
2eb20 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 egate_context()
2eb30 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 routine is calle
2eb40 64 20 66 6f 72 20 61 0a 2a 2a 20 70 61 72 74 69 d for a.** parti
2eb50 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c cular aggregate,
2eb60 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65 SQLite allocate
2eb70 73 20 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f s nBytes of memo
2eb80 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 ry, zeroes out t
2eb90 68 61 74 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61 hat.** memory, a
2eba0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 nd returns a poi
2ebb0 6e 74 65 72 20 74 6f 20 69 74 2e 20 4f 6e 20 73 nter to it. On s
2ebc0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 econd and subseq
2ebd0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a uent calls to.**
2ebe0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 sqlite3_aggrega
2ebf0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 te_context() for
2ec00 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 the same aggreg
2ec10 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64 ate function ind
2ec20 65 78 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 ex,.** the same
2ec30 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e buffer is return
2ec40 65 64 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e ed. The implemen
2ec50 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 61 67 tation of the ag
2ec60 67 72 65 67 61 74 65 20 63 61 6e 20 75 73 65 0a gregate can use.
2ec70 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 65 64 20 ** the returned
2ec80 62 75 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75 buffer to accumu
2ec90 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a late data..**.**
2eca0 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 SQLite automati
2ecb0 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 cally frees the
2ecc0 61 6c 6c 6f 63 61 74 65 64 20 62 75 66 66 65 72 allocated buffer
2ecd0 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 when the aggreg
2ece0 61 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e ate.** query con
2ecf0 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 cludes..**.** Th
2ed00 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
2ed10 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 6f r should be a co
2ed20 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 py of the.** [sq
2ed30 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 lite3_context |
2ed40 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e SQL function con
2ed50 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 text] that is th
2ed60 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
2ed70 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c r.** to the call
2ed80 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 back routine tha
2ed90 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 t implements the
2eda0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 aggregate funct
2edb0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ion..**.** This
2edc0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 routine must be
2edd0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 called from the
2ede0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 same thread in w
2edf0 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 hich.** the aggr
2ee00 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 egate SQL functi
2ee10 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a on is running..*
2ee20 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
2ee30 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 31 7d 20 .**.** {H16211}
2ee40 54 68 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61 The first invoca
2ee50 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 tion of [sqlite3
2ee60 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
2ee70 78 74 28 43 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20 xt(C,N)] for.**
2ee80 20 20 20 20 20 20 20 20 20 61 20 70 61 72 74 69 a parti
2ee90 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 20 6f cular instance o
2eea0 66 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 66 f an aggregate f
2eeb0 75 6e 63 74 69 6f 6e 20 28 66 6f 72 20 61 20 70 unction (for a p
2eec0 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 20 20 20 articular.**
2eed0 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 29 context C)
2eee0 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 causes SQLite t
2eef0 6f 20 61 6c 6c 6f 63 61 74 65 20 4e 20 62 79 74 o allocate N byt
2ef00 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a 2a 2a es of memory,.**
2ef10 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 zero t
2ef20 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 hat memory, and
2ef30 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 return a pointer
2ef40 20 74 6f 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 to the allocate
2ef50 64 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 d memory..**.**
2ef60 7b 48 31 36 32 31 33 7d 20 49 66 20 61 20 6d 65 {H16213} If a me
2ef70 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
2ef80 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 error occurs dur
2ef90 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ing.**
2efa0 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 [sqlite3_aggrega
2efb0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d te_context(C,N)]
2efc0 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 then the functi
2efd0 6f 6e 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a on returns 0..**
2efe0 0a 2a 2a 20 7b 48 31 36 32 31 35 7d 20 53 65 63 .** {H16215} Sec
2eff0 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 ond and subseque
2f000 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f nt invocations o
2f010 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 f.** [s
2f020 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
2f030 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 _context(C,N)] f
2f040 6f 72 20 74 68 65 20 73 61 6d 65 20 63 6f 6e 74 or the same cont
2f050 65 78 74 20 70 6f 69 6e 74 65 72 20 43 0a 2a 2a ext pointer C.**
2f060 20 20 20 20 20 20 20 20 20 20 69 67 6e 6f 72 65 ignore
2f070 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 the N parameter
2f080 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f and return a po
2f090 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 61 6d inter to the sam
2f0a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 6c e.** bl
2f0b0 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 72 65 ock of memory re
2f0c0 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 66 69 turned by the fi
2f0d0 72 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a rst invocation..
2f0e0 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 37 7d 20 54 **.** {H16217} T
2f0f0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
2f100 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ted by [sqlite3_
2f110 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
2f120 74 28 43 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20 20 t(C,N)] is.**
2f130 20 20 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63 automatic
2f140 61 6c 6c 79 20 66 72 65 65 64 20 6f 6e 20 74 68 ally freed on th
2f150 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 20 5b e next call to [
2f160 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
2f170 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 .** or
2f180 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
2f190 65 28 29 5d 20 66 6f 72 20 74 68 65 20 5b 70 72 e()] for the [pr
2f1a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2f1b0 5d 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 ] containing.**
2f1c0 20 20 20 20 20 20 20 20 20 74 68 65 20 61 67 67 the agg
2f1d0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 regate function
2f1e0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
2f1f0 63 6f 6e 74 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f context C..*/.vo
2f200 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 id *sqlite3_aggr
2f210 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 egate_context(sq
2f220 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
2f230 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a int nBytes);../*
2f240 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 .** CAPI3REF: Us
2f250 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 er Data For Func
2f260 74 69 6f 6e 73 20 7b 48 31 36 32 34 30 7d 20 3c tions {H16240} <
2f270 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S20200>.**.** Th
2f280 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 e sqlite3_user_d
2f290 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 ata() interface
2f2a0 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f returns a copy o
2f2b0 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 f.** the pointer
2f2c0 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55 that was the pU
2f2d0 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 serData paramete
2f2e0 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d r (the 5th param
2f2f0 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 eter).** of the
2f300 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
2f310 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 function()].** a
2f320 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 nd [sqlite3_crea
2f330 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d te_function16()]
2f340 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f routines that o
2f350 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 riginally.** reg
2f360 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c istered the appl
2f370 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 ication defined
2f380 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a function. {END}.
2f390 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
2f3a0 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 ne must be calle
2f3b0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 d from the same
2f3c0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a thread in which.
2f3d0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ** the applicati
2f3e0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
2f3f0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a ion is running..
2f400 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
2f410 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 34 33 7d :.**.** {H16243}
2f420 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 73 The [sqlite3_us
2f430 65 72 5f 64 61 74 61 28 43 29 5d 20 69 6e 74 65 er_data(C)] inte
2f440 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
2f450 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 copy of the.**
2f460 20 20 20 20 20 20 20 20 50 20 70 6f 69 6e 74 65 P pointe
2f470 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 r from the [sqli
2f480 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
2f490 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c ion(D,X,N,E,P,F,
2f4a0 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 S,L)].**
2f4b0 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 or [sqlite3_cr
2f4c0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
2f4d0 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 D,X,N,E,P,F,S,L)
2f4e0 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 ] call that.**
2f4f0 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 register
2f500 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 ed the SQL funct
2f510 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77 ion associated w
2f520 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e ith [sqlite3_con
2f530 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 76 6f 69 64 text] C..*/.void
2f540 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 *sqlite3_user_d
2f550 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ata(sqlite3_cont
2f560 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ext*);../*.** CA
2f570 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 PI3REF: Database
2f580 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 Connection For
2f590 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 35 Functions {H1625
2f5a0 30 7d 20 3c 53 36 30 36 30 30 3e 3c 53 32 30 32 0} <S60600><S202
2f5b0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 00>.**.** The sq
2f5c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 lite3_context_db
2f5d0 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 _handle() interf
2f5e0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f ace returns a co
2f5f0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 py of.** the poi
2f600 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 nter to the [dat
2f610 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2f620 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d ] (the 1st param
2f630 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 eter).** of the
2f640 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
2f650 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 function()].** a
2f660 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 nd [sqlite3_crea
2f670 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d te_function16()]
2f680 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f routines that o
2f690 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 riginally.** reg
2f6a0 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c istered the appl
2f6b0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 ication defined
2f6c0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 function..**.**
2f6d0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
2f6e0 2a 20 7b 48 31 36 32 35 33 7d 20 54 68 65 20 5b * {H16253} The [
2f6f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f sqlite3_context_
2f700 64 62 5f 68 61 6e 64 6c 65 28 43 29 5d 20 69 6e db_handle(C)] in
2f710 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
2f720 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a a copy of the.**
2f730 20 20 20 20 20 20 20 20 20 20 44 20 70 6f 69 6e D poin
2f740 74 65 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 ter from the [sq
2f750 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
2f760 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c ction(D,X,N,E,P,
2f770 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 F,S,L)].**
2f780 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f or [sqlite3_
2f790 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
2f7a0 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 6(D,X,N,E,P,F,S,
2f7b0 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a L)] call that.**
2f7c0 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74 regist
2f7d0 65 72 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e ered the SQL fun
2f7e0 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 ction associated
2f7f0 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 63 with [sqlite3_c
2f800 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 73 71 ontext] C..*/.sq
2f810 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 lite3 *sqlite3_c
2f820 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 ontext_db_handle
2f830 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
2f840 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
2f850 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 REF: Function Au
2f860 78 69 6c 69 61 72 79 20 44 61 74 61 20 7b 48 31 xiliary Data {H1
2f870 36 32 37 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 6270} <S20200>.*
2f880 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 *.** The followi
2f890 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 ng two functions
2f8a0 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20 may be used by
2f8b0 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 scalar SQL funct
2f8c0 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 ions to.** assoc
2f8d0 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 iate metadata wi
2f8e0 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 th argument valu
2f8f0 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 es. If the same
2f900 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 value is passed
2f910 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 to.** multiple i
2f920 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 nvocations of th
2f930 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 e same SQL funct
2f940 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 ion during query
2f950 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 execution, unde
2f960 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d r.** some circum
2f970 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f stances the asso
2f980 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 ciated metadata
2f990 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 may be preserved
2f9a0 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 . This may.** be
2f9b0 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 used, for examp
2f9c0 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 le, to add a reg
2f9d0 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 ular-expression
2f9e0 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a matching scalar.
2f9f0 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 ** function. The
2fa00 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f compiled versio
2fa10 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 n of the regular
2fa20 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 expression is s
2fa30 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 tored as.** meta
2fa40 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 data associated
2fa50 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c with the SQL val
2fa60 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 ue passed as the
2fa70 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 regular express
2fa80 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 ion.** pattern.
2fa90 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 The compiled re
2faa0 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e gular expression
2fab0 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f can be reused o
2fac0 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e n multiple.** in
2fad0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 vocations of the
2fae0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 same function s
2faf0 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 o that the origi
2fb00 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 nal pattern stri
2fb10 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e ng.** does not n
2fb20 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 eed to be recomp
2fb30 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 iled on each inv
2fb40 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 ocation..**.** T
2fb50 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 he sqlite3_get_a
2fb60 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 uxdata() interfa
2fb70 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ce returns a poi
2fb80 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 nter to the meta
2fb90 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 data.** associat
2fba0 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 ed by the sqlite
2fbb0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 3_set_auxdata()
2fbc0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 function with th
2fbd0 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a e Nth argument.*
2fbe0 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 * value to the a
2fbf0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
2fc00 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 49 66 20 ed function. If
2fc10 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 no metadata has
2fc20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 been ever.** bee
2fc30 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 n set for the Nt
2fc40 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 h argument of th
2fc50 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 e function, or i
2fc60 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 f the correspond
2fc70 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ing.** function
2fc80 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 parameter has ch
2fc90 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 anged since the
2fca0 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 meta-data was se
2fcb0 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 t,.** then sqlit
2fcc0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 e3_get_auxdata()
2fcd0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 returns a NULL
2fce0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 pointer..**.** T
2fcf0 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 he sqlite3_set_a
2fd00 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 uxdata() interfa
2fd10 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 ce saves the met
2fd20 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 adata.** pointed
2fd30 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 to by its 3rd p
2fd40 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 arameter as the
2fd50 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 metadata for the
2fd60 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e N-th.** argumen
2fd70 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 t of the applica
2fd80 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
2fd90 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 ction. Subseque
2fda0 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 nt.** calls to s
2fdb0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 qlite3_get_auxda
2fdc0 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 ta() might retur
2fdd0 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 n this data, if
2fde0 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 it has.** not be
2fdf0 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a en destroyed..**
2fe00 20 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 If it is not NU
2fe10 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 LL, SQLite will
2fe20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 invoke the destr
2fe30 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f uctor.** functio
2fe40 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 n given by the 4
2fe50 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
2fe60 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 sqlite3_set_auxd
2fe70 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 ata() on.** the
2fe80 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68 metadata when th
2fe90 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 e corresponding
2fea0 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 function paramet
2feb0 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 er changes.** or
2fec0 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 when the SQL st
2fed0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 atement complete
2fee0 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d s, whichever com
2fef0 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 es first..**.**
2ff00 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 SQLite is free t
2ff10 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 o call the destr
2ff20 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d uctor and drop m
2ff30 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a etadata on any.*
2ff40 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 * parameter of a
2ff50 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 ny function at a
2ff60 6e 79 20 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e ny time. The on
2ff70 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20 ly guarantee is
2ff80 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 that.** the dest
2ff90 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 ructor will be c
2ffa0 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 alled before the
2ffb0 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f metadata is dro
2ffc0 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 pped..**.** In p
2ffd0 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 ractice, metadat
2ffe0 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62 a is preserved b
2fff0 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 etween function
30000 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 calls for.** exp
30010 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 ressions that ar
30020 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f e constant at co
30030 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 mpile time. This
30040 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 includes litera
30050 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 l.** values and
30060 53 51 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a SQL variables..*
30070 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
30080 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c nes must be call
30090 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 ed from the same
300a0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 thread in which
300b0 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 .** the SQL func
300c0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e tion is running.
300d0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
300e0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 32 S:.**.** {H16272
300f0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 } The [sqlite3_g
30100 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 5d et_auxdata(C,N)]
30110 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
30120 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 ns a pointer.**
30130 20 20 20 20 20 20 20 20 20 74 6f 20 6d 65 74 61 to meta
30140 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 data associated
30150 77 69 74 68 20 74 68 65 20 4e 74 68 20 70 61 72 with the Nth par
30160 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 53 51 ameter of the SQ
30170 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 L function.**
30180 20 20 20 20 20 20 20 77 68 6f 73 65 20 63 6f 6e whose con
30190 74 65 78 74 20 69 73 20 43 2c 20 6f 72 20 4e 55 text is C, or NU
301a0 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 6e LL if there is n
301b0 6f 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 o metadata assoc
301c0 69 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 iated.**
301d0 20 20 77 69 74 68 20 74 68 61 74 20 70 61 72 61 with that para
301e0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 meter..**.** {H1
301f0 36 32 37 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 6274} The [sqlit
30200 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 e3_set_auxdata(C
30210 2c 4e 2c 50 2c 44 29 5d 20 69 6e 74 65 72 66 61 ,N,P,D)] interfa
30220 63 65 20 61 73 73 69 67 6e 73 20 61 20 6d 65 74 ce assigns a met
30230 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 adata.**
30240 20 20 70 6f 69 6e 74 65 72 20 50 20 74 6f 20 74 pointer P to t
30250 68 65 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72 he Nth parameter
30260 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 of the SQL func
30270 74 69 6f 6e 20 77 69 74 68 20 63 6f 6e 74 65 78 tion with contex
30280 74 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 t C..**.** {H162
30290 37 36 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 76} SQLite will
302a0 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 invoke the destr
302b0 75 63 74 6f 72 20 44 20 77 69 74 68 20 61 20 73 uctor D with a s
302c0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a ingle argument.*
302d0 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 63 68 * which
302e0 20 69 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 is the metadata
302f0 20 70 6f 69 6e 74 65 72 20 50 20 66 6f 6c 6c 6f pointer P follo
30300 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 0a 2a wing a call to.*
30310 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
30320 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 te3_set_auxdata(
30330 43 2c 4e 2c 50 2c 44 29 5d 20 77 68 65 6e 20 53 C,N,P,D)] when S
30340 51 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f 20 QLite ceases to
30350 68 6f 6c 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 hold.**
30360 20 74 68 65 20 6d 65 74 61 64 61 74 61 2e 0a 2a the metadata..*
30370 2a 0a 2a 2a 20 7b 48 31 36 32 37 37 7d 20 53 51 *.** {H16277} SQ
30380 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f 20 68 Lite ceases to h
30390 6f 6c 64 20 6d 65 74 61 64 61 74 61 20 66 6f 72 old metadata for
303a0 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e an SQL function
303b0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 parameter.**
303c0 20 20 20 20 20 20 20 77 68 65 6e 20 74 68 65 20 when the
303d0 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 70 61 value of that pa
303e0 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2e rameter changes.
303f0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 38 7d 20 .**.** {H16278}
30400 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 65 When [sqlite3_se
30410 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c t_auxdata(C,N,P,
30420 44 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 D)] is invoked,
30430 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a the destructor.*
30440 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 63 61 * is ca
30450 6c 6c 65 64 20 66 6f 72 20 61 6e 79 20 70 72 69 lled for any pri
30460 6f 72 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f or metadata asso
30470 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 ciated with the
30480 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a same function.**
30490 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78 contex
304a0 74 20 43 20 61 6e 64 20 70 61 72 61 6d 65 74 65 t C and paramete
304b0 72 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 r N..**.** {H162
304c0 37 39 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 79} SQLite will
304d0 63 61 6c 6c 20 64 65 73 74 72 75 63 74 6f 72 73 call destructors
304e0 20 66 6f 72 20 61 6e 79 20 6d 65 74 61 64 61 74 for any metadat
304f0 61 20 69 74 20 69 73 20 68 6f 6c 64 69 6e 67 0a a it is holding.
30500 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 61 ** in a
30510 20 70 61 72 74 69 63 75 6c 61 72 20 5b 70 72 65 particular [pre
30520 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
30530 20 53 20 77 68 65 6e 20 65 69 74 68 65 72 0a 2a S when either.*
30540 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
30550 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 6f 72 te3_reset(S)] or
30560 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
30570 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64 ze(S)] is called
30580 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 ..*/.void *sqlit
30590 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 e3_get_auxdata(s
305a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
305b0 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 int N);.void sq
305c0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 lite3_set_auxdat
305d0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 a(sqlite3_contex
305e0 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a t*, int N, void*
305f0 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a , void (*)(void*
30600 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ));.../*.** CAPI
30610 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 3REF: Constants
30620 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c Defining Special
30630 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 Destructor Beha
30640 76 69 6f 72 20 7b 48 31 30 32 38 30 7d 20 3c 53 vior {H10280} <S
30650 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 30100>.**.** The
30660 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 se are special v
30670 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 alues for the de
30680 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 structor that is
30690 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 passed in as th
306a0 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d e.** final argum
306b0 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 ent to routines
306c0 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 like [sqlite3_re
306d0 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49 sult_blob()]. I
306e0 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 f the destructor
306f0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 .** argument is
30700 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 SQLITE_STATIC, i
30710 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 t means that the
30720 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 content pointer
30730 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 is constant.**
30740 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 and will never c
30750 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 hange. It does
30760 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 not need to be d
30770 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65 0a 2a estroyed. The.*
30780 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 * SQLITE_TRANSIE
30790 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 NT value means t
307a0 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 hat the content
307b0 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e will likely chan
307c0 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 ge in.** the nea
307d0 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 r future and tha
307e0 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 t SQLite should
307f0 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 make its own pri
30800 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 vate copy of.**
30810 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f the content befo
30820 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a re returning..**
30830 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 .** The typedef
30840 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 is necessary to
30850 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 work around prob
30860 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a lems in certain.
30870 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 ** C++ compilers
30880 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 . See ticket #2
30890 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 191..*/.typedef
308a0 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 void (*sqlite3_d
308b0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 estructor_type)(
308c0 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 void*);.#define
308d0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 SQLITE_STATIC
308e0 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 ((sqlite3_des
308f0 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a tructor_type)0).
30900 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
30910 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c RANSIENT ((sql
30920 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f ite3_destructor_
30930 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 type)-1)../*.**
30940 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e CAPI3REF: Settin
30950 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 g The Result Of
30960 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 An SQL Function
30970 7b 48 31 36 34 30 30 7d 20 3c 53 32 30 32 30 30 {H16400} <S20200
30980 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f >.**.** These ro
30990 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 utines are used
309a0 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 by the xFunc or
309b0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 xFinal callbacks
309c0 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 that.** impleme
309d0 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 nt SQL functions
309e0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e and aggregates.
309f0 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 See.** [sqlite
30a00 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
30a10 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 n()] and [sqlite
30a20 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
30a30 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 n16()].** for ad
30a40 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 ditional informa
30a50 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 tion..**.** Thes
30a60 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b e functions work
30a70 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 very much like
30a80 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 the [parameter b
30a90 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f inding] family o
30aa0 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 f.** functions u
30ab0 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 sed to bind valu
30ac0 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d es to host param
30ad0 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 eters in prepare
30ae0 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a d statements..**
30af0 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 Refer to the [S
30b00 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f QL parameter] do
30b10 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 cumentation for
30b20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 additional infor
30b30 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 mation..**.** Th
30b40 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
30b50 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 _blob() interfac
30b60 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c e sets the resul
30b70 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 t from.** an app
30b80 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
30b90 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
30ba0 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 the BLOB whose c
30bb0 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 ontent is pointe
30bc0 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 d.** to by the s
30bd0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
30be0 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 and which is N b
30bf0 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 ytes long where
30c00 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 N is the.** thir
30c10 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a d parameter..**.
30c20 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 ** The sqlite3_r
30c30 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 esult_zeroblob()
30c40 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 interfaces set
30c50 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a the result of.**
30c60 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
30c70 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
30c80 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 n to be a BLOB c
30c90 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 ontaining all ze
30ca0 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 ro.** bytes and
30cb0 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c N bytes in size,
30cc0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 where N is the
30cd0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 value of the 2nd
30ce0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a parameter..**.*
30cf0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 * The sqlite3_re
30d00 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e sult_double() in
30d10 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 terface sets the
30d20 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 result from.**
30d30 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 an application-d
30d40 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
30d50 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 to be a floating
30d60 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 point value spe
30d70 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 cified.** by its
30d80 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2nd argument..*
30d90 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
30da0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 _result_error()
30db0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 and sqlite3_resu
30dc0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e lt_error16() fun
30dd0 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 ctions.** cause
30de0 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 the implemented
30df0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 SQL function to
30e00 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 throw an excepti
30e10 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 on..** SQLite us
30e20 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f es the string po
30e30 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a inted to by the.
30e40 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 ** 2nd parameter
30e50 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 of sqlite3_resu
30e60 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 lt_error() or sq
30e70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
30e80 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 or16().** as the
30e90 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f text of an erro
30ea0 72 20 6d 65 73 73 61 67 65 2e 20 20 53 51 4c 69 r message. SQLi
30eb0 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 te interprets th
30ec0 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 e error.** messa
30ed0 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 ge string from s
30ee0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
30ef0 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 ror() as UTF-8.
30f00 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 SQLite.** interp
30f10 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 rets the string
30f20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 from sqlite3_res
30f30 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 ult_error16() as
30f40 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 UTF-16 in nativ
30f50 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e e.** byte order.
30f60 20 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70 If the third p
30f70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
30f80 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
30f90 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 ().** or sqlite3
30fa0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
30fb0 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 ) is negative th
30fc0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 en SQLite takes
30fd0 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 as the error.**
30fe0 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 message all text
30ff0 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 up through the
31000 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 first zero chara
31010 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 cter..** If the
31020 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
31030 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c to sqlite3_resul
31040 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 t_error() or.**
31050 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
31060 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d rror16() is non-
31070 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 negative then SQ
31080 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 Lite takes that
31090 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e many.** bytes (n
310a0 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 ot characters) f
310b0 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 rom the 2nd para
310c0 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 meter as the err
310d0 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 54 or message..** T
310e0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
310f0 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 t_error() and sq
31100 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
31110 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e or16().** routin
31120 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 es make a privat
31130 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 e copy of the er
31140 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 ror message text
31150 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 before.** they
31160 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 return. Hence,
31170 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 the calling func
31180 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 tion can dealloc
31190 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 ate or.** modify
311a0 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20 the text after
311b0 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 they return with
311c0 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 54 68 65 out harm..** The
311d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
311e0 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e error_code() fun
311f0 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 ction changes th
31200 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 e error code.**
31210 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 returned by SQLi
31220 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f te as a result o
31230 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 f an error in a
31240 66 75 6e 63 74 69 6f 6e 2e 20 20 42 79 20 64 65 function. By de
31250 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 fault,.** the er
31260 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 ror code is SQLI
31270 54 45 5f 45 52 52 4f 52 2e 20 20 41 20 73 75 62 TE_ERROR. A sub
31280 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 sequent call to
31290 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
312a0 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c rror().** or sql
312b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
312c0 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65 r16() resets the
312d0 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 error code to S
312e0 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a QLITE_ERROR..**.
312f0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 ** The sqlite3_r
31300 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 esult_toobig() i
31310 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 nterface causes
31320 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 SQLite to throw
31330 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 an error.** indi
31340 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 cating that a st
31350 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 ring or BLOB is
31360 74 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 to long to repre
31370 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 sent..**.** The
31380 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e sqlite3_result_n
31390 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 omem() interface
313a0 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 causes SQLite t
313b0 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 o throw an error
313c0 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 .** indicating t
313d0 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c hat a memory all
313e0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a ocation failed..
313f0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
31400 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 3_result_int() i
31410 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 nterface sets th
31420 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a e return value.*
31430 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 * of the applica
31440 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
31450 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 ction to be the
31460 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 32-bit signed in
31470 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 teger.** value g
31480 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 iven in the 2nd
31490 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 argument..** The
314a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
314b0 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 int64() interfac
314c0 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 e sets the retur
314d0 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 n value.** of th
314e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
314f0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 fined function t
31500 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 o be the 64-bit
31510 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a signed integer.*
31520 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e * value given in
31530 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e the 2nd argumen
31540 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c t..**.** The sql
31550 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c ite3_result_null
31560 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 () interface set
31570 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c s the return val
31580 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 ue.** of the app
31590 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
315a0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
315b0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 NULL..**.** The
315c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
315d0 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 ext(), sqlite3_r
315e0 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a esult_text16(),.
315f0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c ** sqlite3_resul
31600 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e t_text16le(), an
31610 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
31620 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 _text16be() inte
31630 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 rfaces.** set th
31640 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f e return value o
31650 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
31660 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
31670 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 on to be.** a te
31680 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 xt string which
31690 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 is represented a
316a0 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 s UTF-8, UTF-16
316b0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
316c0 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 r,.** UTF-16 lit
316d0 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 tle endian, or U
316e0 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e TF-16 big endian
316f0 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a , respectively..
31700 2a 2a 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 ** SQLite takes
31710 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 the text result
31720 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 from the applica
31730 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 tion from.** the
31740 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 2nd parameter o
31750 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 f the sqlite3_re
31760 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 sult_text* inter
31770 66 61 63 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 faces..** If the
31780 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 3rd parameter t
31790 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 o the sqlite3_re
317a0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 sult_text* inter
317b0 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 faces.** is nega
317c0 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 tive, then SQLit
317d0 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 e takes result t
317e0 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 ext from the 2nd
317f0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 parameter.** th
31800 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 rough the first
31810 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a zero character..
31820 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 ** If the 3rd pa
31830 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 rameter to the s
31840 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
31850 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a xt* interfaces.*
31860 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 * is non-negativ
31870 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 e, then as many
31880 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 bytes (not chara
31890 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 cters) of the te
318a0 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f xt.** pointed to
318b0 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 by the 2nd para
318c0 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 meter are taken
318d0 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 as the applicati
318e0 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 on-defined.** fu
318f0 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a nction result..*
31900 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72 * If the 4th par
31910 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
31920 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
31930 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a t* interfaces.**
31940 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 or sqlite3_resu
31950 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e lt_blob is a non
31960 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 -NULL pointer, t
31970 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 hen SQLite calls
31980 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f that.** functio
31990 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63 n as the destruc
319a0 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 tor on the text
319b0 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 or BLOB result w
319c0 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 hen it has.** fi
319d0 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 nished using tha
319e0 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 t result..** If
319f0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 the 4th paramete
31a00 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 r to the sqlite3
31a10 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e _result_text* in
31a20 74 65 72 66 61 63 65 73 20 6f 72 0a 2a 2a 20 73 terfaces or.** s
31a30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
31a40 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 ob is the specia
31a50 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 l constant SQLIT
31a60 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 E_STATIC, then S
31a70 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 QLite.** assumes
31a80 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f that the text o
31a90 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 r BLOB result is
31aa0 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 in constant spa
31ab0 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a ce and does not.
31ac0 2a 2a 20 63 6f 70 79 20 74 68 65 20 69 74 20 6f ** copy the it o
31ad0 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 r call a destruc
31ae0 74 6f 72 20 77 68 65 6e 20 69 74 20 68 61 73 20 tor when it has
31af0 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 finished using t
31b00 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 hat result..** I
31b10 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 f the 4th parame
31b20 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ter to the sqlit
31b30 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 e3_result_text*
31b40 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 interfaces.** or
31b50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
31b60 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 blob is the spec
31b70 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c ial constant SQL
31b80 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a ITE_TRANSIENT.**
31b90 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b then SQLite mak
31ba0 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 es a copy of the
31bb0 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 result into spa
31bc0 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ce obtained from
31bd0 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 .** from [sqlite
31be0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 3_malloc()] befo
31bf0 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a re it returns..*
31c00 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
31c10 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 _result_value()
31c20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 interface sets t
31c30 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 he result of.**
31c40 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
31c50 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
31c60 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 to be a copy th
31c70 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 e.** [unprotecte
31c80 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
31c90 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 object specifie
31ca0 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 d by the 2nd par
31cb0 61 6d 65 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20 ameter. The.**
31cc0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
31cd0 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 alue() interface
31ce0 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 makes a copy of
31cf0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 the [sqlite3_va
31d00 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 lue].** so that
31d10 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c the [sqlite3_val
31d20 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e ue] specified in
31d30 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d the parameter m
31d40 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 ay change or.**
31d50 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 be deallocated a
31d60 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 fter sqlite3_res
31d70 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 ult_value() retu
31d80 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d rns without harm
31d90 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74 65 63 74 65 ..** A [protecte
31da0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
31db0 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 object may alwa
31dc0 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65 ys be used where
31dd0 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 an.** [unprotec
31de0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
31df0 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 e] object is req
31e00 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 uired, so either
31e10 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c .** kind of [sql
31e20 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
31e30 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 ct can be used w
31e40 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 ith this interfa
31e50 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 ce..**.** If the
31e60 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
31e70 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 called from with
31e80 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 in the different
31e90 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 thread.** than
31ea0 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 the one containi
31eb0 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ng the applicati
31ec0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
31ed0 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 ion that receive
31ee0 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 d.** the [sqlite
31ef0 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 3_context] point
31f00 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 er, the results
31f10 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a are undefined..*
31f20 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
31f30 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 33 7d 20 .**.** {H16403}
31f40 54 68 65 20 64 65 66 61 75 6c 74 20 72 65 74 75 The default retu
31f50 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e rn value from an
31f60 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 y SQL function i
31f70 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 s NULL..**.** {H
31f80 31 36 34 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 16406} The [sqli
31f90 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 te3_result_blob(
31fa0 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 C,V,N,D)] interf
31fb0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a ace changes the.
31fc0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 ** retu
31fd0 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 rn value of func
31fe0 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 20 42 tion C to be a B
31ff0 4c 4f 42 20 74 68 61 74 20 69 73 20 4e 20 62 79 LOB that is N by
32000 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 tes.**
32010 69 6e 20 6c 65 6e 67 74 68 20 61 6e 64 20 77 69 in length and wi
32020 74 68 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 th content point
32030 65 64 20 74 6f 20 62 79 20 56 2e 0a 2a 2a 0a 2a ed to by V..**.*
32040 2a 20 7b 48 31 36 34 30 39 7d 20 54 68 65 20 5b * {H16409} The [
32050 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 sqlite3_result_d
32060 6f 75 62 6c 65 28 43 2c 56 29 5d 20 69 6e 74 65 ouble(C,V)] inte
32070 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 rface changes th
32080 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 e.** re
32090 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 turn value of fu
320a0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 nction C to be t
320b0 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e he floating poin
320c0 74 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a t value V..**.**
320d0 20 7b 48 31 36 34 31 32 7d 20 54 68 65 20 5b 73 {H16412} The [s
320e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
320f0 72 6f 72 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 ror(C,V,N)] inte
32100 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 rface changes th
32110 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 e return.**
32120 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 66 75 value of fu
32130 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 nction C to be a
32140 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 n exception with
32150 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 error code.**
32160 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f [SQLITE_
32170 45 52 52 4f 52 5d 20 61 6e 64 20 61 20 55 54 46 ERROR] and a UTF
32180 2d 38 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 -8 error message
32190 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 56 20 75 copied from V u
321a0 70 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 p to the.**
321b0 20 20 20 20 20 66 69 72 73 74 20 7a 65 72 6f 20 first zero
321c0 62 79 74 65 20 6f 72 20 75 6e 74 69 6c 20 4e 20 byte or until N
321d0 62 79 74 65 73 20 61 72 65 20 72 65 61 64 20 69 bytes are read i
321e0 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2e f N is positive.
321f0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 35 7d 20 .**.** {H16415}
32200 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 The [sqlite3_res
32210 75 6c 74 5f 65 72 72 6f 72 31 36 28 43 2c 56 2c ult_error16(C,V,
32220 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 N)] interface ch
32230 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e anges the return
32240 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c .** val
32250 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 ue of function C
32260 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 to be an except
32270 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 ion with error c
32280 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ode.**
32290 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61 [SQLITE_ERROR] a
322a0 6e 64 20 61 20 55 54 46 2d 31 36 20 6e 61 74 69 nd a UTF-16 nati
322b0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 65 72 ve byte order er
322c0 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 ror message.**
322d0 20 20 20 20 20 20 20 20 63 6f 70 69 65 64 20 66 copied f
322e0 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 68 65 20 rom V up to the
322f0 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 first zero termi
32300 6e 61 74 6f 72 20 6f 72 20 75 6e 74 69 6c 20 4e nator or until N
32310 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 bytes.**
32320 20 20 20 61 72 65 20 72 65 61 64 20 69 66 20 4e are read if N
32330 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a is positive..**
32340 0a 2a 2a 20 7b 48 31 36 34 31 38 7d 20 54 68 65 .** {H16418} The
32350 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
32360 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 43 29 _error_toobig(C)
32370 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e ] interface chan
32380 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a ges the return.*
32390 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 * value
323a0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e of the function
323b0 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 C to be an exce
323c0 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 ption with error
323d0 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 code.**
323e0 20 20 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 [SQLITE_TOOBIG
323f0 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 ] and an appropr
32400 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 iate error messa
32410 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32 ge..**.** {H1642
32420 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 1} The [sqlite3_
32430 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d result_error_nom
32440 65 6d 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 em(C)] interface
32450 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 changes the ret
32460 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 urn.**
32470 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e value of the fun
32480 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e ction C to be an
32490 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 exception with
324a0 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 error code.**
324b0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4e [SQLITE_N
324c0 4f 4d 45 4d 5d 20 61 6e 64 20 61 6e 20 61 70 70 OMEM] and an app
324d0 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d ropriate error m
324e0 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 essage..**.** {H
324f0 31 36 34 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 16424} The [sqli
32500 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
32510 5f 63 6f 64 65 28 43 2c 45 29 5d 20 69 6e 74 65 _code(C,E)] inte
32520 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 rface changes th
32530 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 e return.**
32540 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 value of th
32550 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 e function C to
32560 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 be an exception
32570 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 20 with error code
32580 45 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 54 E..** T
32590 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 he error message
325a0 20 74 65 78 74 20 69 73 20 75 6e 63 68 61 6e 67 text is unchang
325b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32 ed..**.** {H1642
325c0 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 7} The [sqlite3_
325d0 72 65 73 75 6c 74 5f 69 6e 74 28 43 2c 56 29 5d result_int(C,V)]
325e0 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 interface chang
325f0 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 es the.**
32600 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 return value
32610 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f of function C to
32620 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 69 be the 32-bit i
32630 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a nteger value V..
32640 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 30 7d 20 54 **.** {H16430} T
32650 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 he [sqlite3_resu
32660 6c 74 5f 69 6e 74 36 34 28 43 2c 56 29 5d 20 69 lt_int64(C,V)] i
32670 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 nterface changes
32680 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
32690 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 return value of
326a0 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 function C to b
326b0 65 20 74 68 65 20 36 34 2d 62 69 74 20 69 6e 74 e the 64-bit int
326c0 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a eger value V..**
326d0 0a 2a 2a 20 7b 48 31 36 34 33 33 7d 20 54 68 65 .** {H16433} The
326e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
326f0 5f 6e 75 6c 6c 28 43 29 5d 20 69 6e 74 65 72 66 _null(C)] interf
32700 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a ace changes the.
32710 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 ** retu
32720 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 rn value of func
32730 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 4e 55 4c tion C to be NUL
32740 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 36 L..**.** {H16436
32750 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 } The [sqlite3_r
32760 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e esult_text(C,V,N
32770 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 ,D)] interface c
32780 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 hanges the.**
32790 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 return va
327a0 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 lue of function
327b0 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d C to be the UTF-
327c0 38 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 8 string.**
327d0 20 20 20 20 20 56 20 75 70 20 74 6f 20 74 68 65 V up to the
327e0 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e first zero if N
327f0 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 is negative.**
32800 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 or the
32810 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66 first N bytes of
32820 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e V if N is non-n
32830 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b egative..**.** {
32840 48 31 36 34 33 39 7d 20 54 68 65 20 5b 73 71 6c H16439} The [sql
32850 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
32860 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 16(C,V,N,D)] int
32870 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 erface changes t
32880 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 he.** r
32890 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 eturn value of f
328a0 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 unction C to be
328b0 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 the UTF-16 nativ
328c0 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 e byte order.**
328d0 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 string
328e0 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 V up to the firs
328f0 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e t zero if N is n
32900 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 egative.**
32910 20 20 20 20 6f 72 20 74 68 65 20 66 69 72 73 74 or the first
32920 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66 N bytes of V if
32930 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 N is non-negati
32940 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 ve..**.** {H1644
32950 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 2} The [sqlite3_
32960 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 result_text16be(
32970 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 C,V,N,D)] interf
32980 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a ace changes the.
32990 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 ** retu
329a0 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 rn value of func
329b0 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 tion C to be the
329c0 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 UTF-16 big-endi
329d0 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 an.** s
329e0 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 tring V up to th
329f0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 e first zero if
32a00 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a N is negative.**
32a10 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 or the
32a20 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f first N bytes o
32a30 72 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d r V if N is non-
32a40 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 negative..**.**
32a50 7b 48 31 36 34 34 35 7d 20 54 68 65 20 5b 73 71 {H16445} The [sq
32a60 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
32a70 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 t16le(C,V,N,D)]
32a80 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 interface change
32a90 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 s the.**
32aa0 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f return value o
32ab0 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 f function C to
32ac0 62 65 20 74 68 65 20 55 54 46 2d 31 36 20 6c 69 be the UTF-16 li
32ad0 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 ttle-endian.**
32ae0 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 56 string V
32af0 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 up to the first
32b00 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 zero if N is ne
32b10 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 gative.**
32b20 20 20 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 or the first
32b30 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66 20 N bytes of V if
32b40 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 N is non-negativ
32b50 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 38 e..**.** {H16448
32b60 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 } The [sqlite3_r
32b70 65 73 75 6c 74 5f 76 61 6c 75 65 28 43 2c 56 29 esult_value(C,V)
32b80 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e ] interface chan
32b90 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 ges the.**
32ba0 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 return value
32bb0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 of function C t
32bc0 6f 20 62 65 20 74 68 65 20 5b 75 6e 70 72 6f 74 o be the [unprot
32bd0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
32be0 6c 75 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 lue].**
32bf0 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a object V..**.**
32c00 20 7b 48 31 36 34 35 31 7d 20 54 68 65 20 5b 73 {H16451} The [s
32c10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 qlite3_result_ze
32c20 72 6f 62 6c 6f 62 28 43 2c 4e 29 5d 20 69 6e 74 roblob(C,N)] int
32c30 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 erface changes t
32c40 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 he.** r
32c50 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 eturn value of f
32c60 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 unction C to be
32c70 61 6e 20 4e 2d 62 79 74 65 20 42 4c 4f 42 20 6f an N-byte BLOB o
32c80 66 20 61 6c 6c 20 7a 65 72 6f 73 2e 0a 2a 2a 0a f all zeros..**.
32c90 2a 2a 20 7b 48 31 36 34 35 34 7d 20 54 68 65 20 ** {H16454} The
32ca0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
32cb0 65 72 72 6f 72 28 29 5d 20 61 6e 64 20 5b 73 71 error()] and [sq
32cc0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
32cd0 6f 72 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 or16()].**
32ce0 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 6d interfaces m
32cf0 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 ake a copy of th
32d00 65 69 72 20 65 72 72 6f 72 20 6d 65 73 73 61 67 eir error messag
32d10 65 20 73 74 72 69 6e 67 73 20 62 65 66 6f 72 65 e strings before
32d20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 .** ret
32d30 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 urning..**.** {H
32d40 31 36 34 35 37 7d 20 49 66 20 74 68 65 20 44 20 16457} If the D
32d50 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d destructor param
32d60 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 eter to [sqlite3
32d70 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 _result_blob(C,V
32d80 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 ,N,D)],.**
32d90 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 [sqlite3_res
32da0 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 ult_text(C,V,N,D
32db0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 )], [sqlite3_res
32dc0 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e ult_text16(C,V,N
32dd0 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 ,D)],.**
32de0 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c [sqlite3_resul
32df0 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e t_text16be(C,V,N
32e00 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 ,D)], or.**
32e10 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 [sqlite3_re
32e20 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c sult_text16le(C,
32e30 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63 V,N,D)] is the c
32e40 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f onstant [SQLITE_
32e50 53 54 41 54 49 43 5d 0a 2a 2a 20 20 20 20 20 20 STATIC].**
32e60 20 20 20 20 74 68 65 6e 20 6e 6f 20 64 65 73 74 then no dest
32e70 72 75 63 74 6f 72 20 69 73 20 65 76 65 72 20 63 ructor is ever c
32e80 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 70 6f 69 alled on the poi
32e90 6e 74 65 72 20 56 20 61 6e 64 20 53 51 4c 69 74 nter V and SQLit
32ea0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 e.** as
32eb0 73 75 6d 65 73 20 74 68 61 74 20 56 20 69 73 20 sumes that V is
32ec0 69 6d 6d 75 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a immutable..**.**
32ed0 20 7b 48 31 36 34 36 30 7d 20 49 66 20 74 68 65 {H16460} If the
32ee0 20 44 20 64 65 73 74 72 75 63 74 6f 72 20 70 61 D destructor pa
32ef0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
32f00 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 te3_result_blob(
32f10 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 C,V,N,D)],.**
32f20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
32f30 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c result_text(C,V,
32f40 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f N,D)], [sqlite3_
32f50 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c result_text16(C,
32f60 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 V,N,D)],.**
32f70 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 [sqlite3_re
32f80 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c sult_text16be(C,
32f90 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 V,N,D)], or.**
32fa0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
32fb0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 _result_text16le
32fc0 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 (C,V,N,D)] is th
32fd0 65 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 20 20 e constant.**
32fe0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 [SQLITE_T
32ff0 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e 20 74 RANSIENT] then t
33000 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 he interfaces ma
33010 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 kes a copy of th
33020 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f e.** co
33030 6e 74 65 6e 74 20 6f 66 20 56 20 61 6e 64 20 72 ntent of V and r
33040 65 74 61 69 6e 73 20 74 68 65 20 63 6f 70 79 2e etains the copy.
33050 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 36 33 7d 20 .**.** {H16463}
33060 49 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63 If the D destruc
33070 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f tor parameter to
33080 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
33090 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c _blob(C,V,N,D)],
330a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
330b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
330c0 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 t(C,V,N,D)], [sq
330d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
330e0 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a t16(C,V,N,D)],.*
330f0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
33100 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
33110 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 6be(C,V,N,D)], o
33120 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 r.** [s
33130 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
33140 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d xt16le(C,V,N,D)]
33150 20 69 73 20 73 6f 6d 65 20 76 61 6c 75 65 20 6f is some value o
33160 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 ther than.**
33170 20 20 20 20 20 20 74 68 65 20 63 6f 6e 73 74 61 the consta
33180 6e 74 73 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 nts [SQLITE_STAT
33190 49 43 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f IC] and [SQLITE_
331a0 54 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e 0a TRANSIENT] then.
331b0 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 69 ** SQLi
331c0 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 te will invoke t
331d0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 he destructor D
331e0 77 69 74 68 20 56 20 61 73 20 69 74 73 20 6f 6e with V as its on
331f0 6c 79 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 ly argument.**
33200 20 20 20 20 20 20 20 20 77 68 65 6e 20 69 74 20 when it
33210 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 has finished wit
33220 68 20 74 68 65 20 56 20 76 61 6c 75 65 2e 0a 2a h the V value..*
33230 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 /.void sqlite3_r
33240 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 esult_blob(sqlit
33250 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
33260 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 st void*, int, v
33270 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
33280 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
33290 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 ult_double(sqlit
332a0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 e3_context*, dou
332b0 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 ble);.void sqlit
332c0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
332d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
332e0 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 , const char*, i
332f0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 nt);.void sqlite
33300 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
33310 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
33320 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 *, const void*,
33330 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 int);.void sqlit
33340 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f e3_result_error_
33350 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 toobig(sqlite3_c
33360 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 ontext*);.void s
33370 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
33380 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 ror_nomem(sqlite
33390 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 3_context*);.voi
333a0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
333b0 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 _error_code(sqli
333c0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
333d0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 t);.void sqlite3
333e0 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 _result_int(sqli
333f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
33400 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 t);.void sqlite3
33410 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 _result_int64(sq
33420 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
33430 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a sqlite3_int64);.
33440 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
33450 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 ult_null(sqlite3
33460 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 _context*);.void
33470 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
33480 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e text(sqlite3_con
33490 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 text*, const cha
334a0 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 r*, int, void(*)
334b0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 (void*));.void s
334c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
334d0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e xt16(sqlite3_con
334e0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 text*, const voi
334f0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 d*, int, void(*)
33500 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 (void*));.void s
33510 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
33520 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 xt16le(sqlite3_c
33530 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 ontext*, const v
33540 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a oid*, int,void(*
33550 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 )(void*));.void
33560 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
33570 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f ext16be(sqlite3_
33580 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
33590 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 void*, int,void(
335a0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 *)(void*));.void
335b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
335c0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f value(sqlite3_co
335d0 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f ntext*, sqlite3_
335e0 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 value*);.void sq
335f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 lite3_result_zer
33600 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f oblob(sqlite3_co
33610 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a ntext*, int n);.
33620 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
33630 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c Define New Coll
33640 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 20 ating Sequences
33650 7b 48 31 36 36 30 30 7d 20 3c 53 32 30 33 30 30 {H16600} <S20300
33660 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 >.**.** These fu
33670 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64 nctions are used
33680 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c to add new coll
33690 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 ation sequences
336a0 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 to the.** [datab
336b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
336c0 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65 specified as the
336d0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e first argument.
336e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 .**.** The name
336f0 6f 66 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61 of the new colla
33700 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 tion sequence is
33710 20 73 70 65 63 69 66 69 65 64 20 61 73 20 61 20 specified as a
33720 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 UTF-8 string.**
33730 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 for sqlite3_crea
33740 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 te_collation() a
33750 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 nd sqlite3_creat
33760 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 e_collation_v2()
33770 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 .** and a UTF-16
33780 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 string for sqli
33790 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
337a0 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20 61 6c 6c tion16(). In all
337b0 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61 cases.** the na
337c0 6d 65 20 69 73 20 70 61 73 73 65 64 20 61 73 20 me is passed as
337d0 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 the second funct
337e0 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a ion argument..**
337f0 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 72 .** The third ar
33800 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e gument may be on
33810 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e e of the constan
33820 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d ts [SQLITE_UTF8]
33830 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 ,.** [SQLITE_UTF
33840 31 36 4c 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 16LE] or [SQLITE
33850 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 _UTF16BE], indic
33860 61 74 69 6e 67 20 74 68 61 74 20 74 68 65 20 75 ating that the u
33870 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 ser-supplied.**
33880 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 routine expects
33890 74 6f 20 62 65 20 70 61 73 73 65 64 20 70 6f 69 to be passed poi
338a0 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 nters to strings
338b0 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 encoded using U
338c0 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 TF-8,.** UTF-16
338d0 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f little-endian, o
338e0 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 r UTF-16 big-end
338f0 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c ian, respectivel
33900 79 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 y. The.** third
33910 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20 61 argument might a
33920 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 lso be [SQLITE_U
33930 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 74 6f TF16_ALIGNED] to
33940 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 0a 2a indicate that.*
33950 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78 * the routine ex
33960 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74 pects pointers t
33970 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c o 16-bit word al
33980 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a igned strings.**
33990 20 6f 66 20 55 54 46 2d 31 36 20 69 6e 20 74 68 of UTF-16 in th
339a0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 e native byte or
339b0 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 der of the host
339c0 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 computer..**.**
339d0 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 A pointer to the
339e0 20 75 73 65 72 20 73 75 70 70 6c 69 65 64 20 72 user supplied r
339f0 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70 outine must be p
33a00 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 66 assed as the fif
33a10 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 th.** argument.
33a20 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 If it is NULL,
33a30 74 68 69 73 20 69 73 20 74 68 65 20 73 61 6d 65 this is the same
33a40 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65 as deleting the
33a50 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 collation.** se
33a60 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20 quence (so that
33a70 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 SQLite cannot ca
33a80 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a ll it anymore)..
33a90 2a 2a 20 45 61 63 68 20 74 69 6d 65 20 74 68 65 ** Each time the
33aa0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 75 70 application sup
33ab0 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 plied function i
33ac0 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 s invoked, it is
33ad0 20 70 61 73 73 65 64 0a 2a 2a 20 61 73 20 69 74 passed.** as it
33ae0 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 s first paramete
33af0 72 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 r a copy of the
33b00 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73 20 void* passed as
33b10 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d the fourth argum
33b20 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 ent.** to sqlite
33b30 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
33b40 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f on() or sqlite3_
33b50 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
33b60 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 16()..**.** The
33b70 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 remaining argume
33b80 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69 nts to the appli
33b90 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 cation-supplied
33ba0 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 routine are two
33bb0 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 strings,.** each
33bc0 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 represented by
33bd0 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 a (length, data)
33be0 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 pair and encode
33bf0 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e d in the encodin
33c00 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 g.** that was pa
33c10 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 ssed as the thir
33c20 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 d argument when
33c30 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 the collation se
33c40 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 quence was.** re
33c50 67 69 73 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20 gistered. {END}
33c60 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
33c70 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 defined collati
33c80 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c on routine shoul
33c90 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61 d.** return nega
33ca0 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f tive, zero or po
33cb0 73 69 74 69 76 65 20 69 66 20 74 68 65 20 66 69 sitive if the fi
33cc0 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 rst string is le
33cd0 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61 ss than,.** equa
33ce0 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 l to, or greater
33cf0 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 than the second
33d00 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 string. i.e. (S
33d10 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 TRING1 - STRING2
33d20 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c )..**.** The sql
33d30 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
33d40 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 ation_v2() works
33d50 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 like sqlite3_cr
33d60 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 eate_collation()
33d70 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 .** except that
33d80 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72 it takes an extr
33d90 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 a argument which
33da0 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 is a destructor
33db0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c for.** the coll
33dc0 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 ation. The dest
33dd0 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 ructor is called
33de0 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 when the collat
33df0 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f ion is.** destro
33e00 79 65 64 20 61 6e 64 20 69 73 20 70 61 73 73 65 yed and is passe
33e10 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 d a copy of the
33e20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
33e30 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a void* pointer.*
33e40 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 * of the sqlite3
33e50 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
33e60 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 n_v2()..** Colla
33e70 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f tions are destro
33e80 79 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 yed when they ar
33e90 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 e overridden by
33ea0 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 later calls to t
33eb0 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 he.** collation
33ec0 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f creation functio
33ed0 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b ns or when the [
33ee0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
33ef0 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a ion] is closed.*
33f00 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 * using [sqlite3
33f10 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a _close()]..**.**
33f20 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
33f30 2a 2a 20 7b 48 31 36 36 30 33 7d 20 41 20 73 75 ** {H16603} A su
33f40 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f ccessful call to
33f50 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
33f60 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
33f70 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c _collation_v2(B,
33f80 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 69 6e 74 65 X,E,P,F,D)] inte
33f90 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 rface.**
33fa0 20 20 72 65 67 69 73 74 65 72 73 20 66 75 6e 63 registers func
33fb0 74 69 6f 6e 20 46 20 61 73 20 74 68 65 20 63 6f tion F as the co
33fc0 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f mparison functio
33fd0 6e 20 75 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 n used to.**
33fe0 20 20 20 20 20 20 69 6d 70 6c 65 6d 65 6e 74 20 implement
33ff0 63 6f 6c 6c 61 74 69 6f 6e 20 58 20 6f 6e 20 74 collation X on t
34000 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
34010 6e 65 63 74 69 6f 6e 5d 20 42 20 66 6f 72 0a 2a nection] B for.*
34020 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62 * datab
34030 61 73 65 73 20 68 61 76 69 6e 67 20 65 6e 63 6f ases having enco
34040 64 69 6e 67 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ding E..**.** {H
34050 31 36 36 30 34 7d 20 53 51 4c 69 74 65 20 75 6e 16604} SQLite un
34060 64 65 72 73 74 61 6e 64 73 20 74 68 65 20 58 20 derstands the X
34070 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 parameter to.**
34080 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
34090 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
340a0 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c on_v2(B,X,E,P,F,
340b0 44 29 5d 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 D)] as a zero-te
340c0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 rminated.**
340d0 20 20 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e UTF-8 strin
340e0 67 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 g in which case
340f0 69 73 20 69 67 6e 6f 72 65 64 20 66 6f 72 20 41 is ignored for A
34100 53 43 49 49 20 63 68 61 72 61 63 74 65 72 73 20 SCII characters
34110 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 and.**
34120 69 73 20 73 69 67 6e 69 66 69 63 61 6e 74 20 66 is significant f
34130 6f 72 20 6e 6f 6e 2d 41 53 43 49 49 20 63 68 61 or non-ASCII cha
34140 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b racters..**.** {
34150 48 31 36 36 30 36 7d 20 53 75 63 63 65 73 73 69 H16606} Successi
34160 76 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c ve calls to [sql
34170 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
34180 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 ation_v2(B,X,E,P
34190 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 ,F,D)].**
341a0 20 20 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 with the same
341b0 20 76 61 6c 75 65 73 20 66 6f 72 20 42 2c 20 58 values for B, X
341c0 2c 20 61 6e 64 20 45 2c 20 6f 76 65 72 72 69 64 , and E, overrid
341d0 65 20 70 72 69 6f 72 20 76 61 6c 75 65 73 0a 2a e prior values.*
341e0 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 50 2c * of P,
341f0 20 46 2c 20 61 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a F, and D..**.**
34200 20 7b 48 31 36 36 30 39 7d 20 49 66 20 74 68 65 {H16609} If the
34210 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 69 6e destructor D in
34220 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
34230 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c _collation_v2(B,
34240 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 X,E,P,F,D)].**
34250 20 20 20 20 20 20 20 20 69 73 20 6e 6f 74 20 4e is not N
34260 55 4c 4c 20 74 68 65 6e 20 69 74 20 69 73 20 63 ULL then it is c
34270 61 6c 6c 65 64 20 77 69 74 68 20 61 72 67 75 6d alled with argum
34280 65 6e 74 20 50 20 77 68 65 6e 20 74 68 65 0a 2a ent P when the.*
34290 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 * colla
342a0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 ting function is
342b0 20 64 72 6f 70 70 65 64 20 62 79 20 53 51 4c 69 dropped by SQLi
342c0 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 te..**.** {H1661
342d0 32 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 2} A collating f
342e0 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 unction is dropp
342f0 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 6f 76 ed when it is ov
34300 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 erloaded..**.**
34310 7b 48 31 36 36 31 35 7d 20 41 20 63 6f 6c 6c 61 {H16615} A colla
34320 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 ting function is
34330 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20 74 68 dropped when th
34340 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
34350 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 ction.**
34360 20 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e is closed usin
34370 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 g [sqlite3_close
34380 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 ()]..**.** {H166
34390 31 38 7d 20 54 68 65 20 70 6f 69 6e 74 65 72 20 18} The pointer
343a0 50 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72 P in [sqlite3_cr
343b0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 eate_collation_v
343c0 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2(B,X,E,P,F,D)].
343d0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 70 ** is p
343e0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 assed through as
343f0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
34400 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6d 70 eter to the comp
34410 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 arison.**
34420 20 20 20 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f function F fo
34430 72 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 r all subsequent
34440 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 invocations of
34450 46 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 31 F..**.** {H16621
34460 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c } A call to [sql
34470 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
34480 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29 ation(B,X,E,P,F)
34490 5d 20 69 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20 ] is exactly.**
344a0 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d the sam
344b0 65 20 61 73 20 61 20 63 61 6c 6c 20 74 6f 20 5b e as a call to [
344c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
344d0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 20 77 ollation_v2()] w
344e0 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ith.**
344f0 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74 the same paramet
34500 65 72 73 20 61 6e 64 20 61 20 4e 55 4c 4c 20 64 ers and a NULL d
34510 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2a 0a 2a 2a estructor..**.**
34520 20 7b 48 31 36 36 32 34 7d 20 46 6f 6c 6c 6f 77 {H16624} Follow
34530 69 6e 67 20 61 20 5b 73 71 6c 69 74 65 33 5f 63 ing a [sqlite3_c
34540 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f reate_collation_
34550 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d v2(B,X,E,P,F,D)]
34560 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 ,.** SQ
34570 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 63 6f Lite uses the co
34580 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f mparison functio
34590 6e 20 46 20 66 6f 72 20 61 6c 6c 20 74 65 78 74 n F for all text
345a0 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 comparison.**
345b0 20 20 20 20 20 20 20 20 6f 70 65 72 61 74 69 6f operatio
345c0 6e 73 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 ns on the [datab
345d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
345e0 42 20 6f 6e 20 74 65 78 74 20 76 61 6c 75 65 73 B on text values
345f0 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 that.**
34600 20 20 75 73 65 20 74 68 65 20 63 6f 6c 6c 61 74 use the collat
34610 69 6e 67 20 73 65 71 75 65 6e 63 65 20 6e 61 6d ing sequence nam
34620 65 64 20 58 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 ed X..**.** {H16
34630 36 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 627} The [sqlite
34640 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
34650 6f 6e 31 36 28 42 2c 58 2c 45 2c 50 2c 46 29 5d on16(B,X,E,P,F)]
34660 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 0a works the same.
34670 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 20 5b ** as [
34680 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
34690 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 ollation(B,X,E,P
346a0 2c 46 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 ,F)] except that
346b0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
346c0 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 collation name
346d0 58 20 69 73 20 75 6e 64 65 72 73 74 6f 6f 64 20 X is understood
346e0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 as UTF-16 in nat
346f0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a ive byte order.*
34700 2a 20 20 20 20 20 20 20 20 20 20 69 6e 73 74 65 * inste
34710 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 0a ad of UTF-8..**.
34720 2a 2a 20 7b 48 31 36 36 33 30 7d 20 57 68 65 6e ** {H16630} When
34730 20 6d 75 6c 74 69 70 6c 65 20 63 6f 6d 70 61 72 multiple compar
34740 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 61 ison functions a
34750 72 65 20 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 re available for
34760 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 the same.**
34770 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 collating
34780 73 65 71 75 65 6e 63 65 2c 20 53 51 4c 69 74 65 sequence, SQLite
34790 20 63 68 6f 6f 73 65 73 20 74 68 65 20 6f 6e 65 chooses the one
347a0 20 77 68 6f 73 65 20 74 65 78 74 20 65 6e 63 6f whose text enco
347b0 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 ding.**
347c0 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65 requires the le
347d0 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f ast amount of co
347e0 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 74 68 nversion from th
347f0 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 20 20 20 e default.**
34800 20 20 20 20 20 20 74 65 78 74 20 65 6e 63 6f 64 text encod
34810 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 ing of the datab
34820 61 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ase..*/.int sqli
34830 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
34840 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a tion(. sqlite3*
34850 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 , . const char
34860 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 *zName, . int e
34870 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 TextRep, . void
34880 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 *,. int(*xCompa
34890 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f re)(void*,int,co
348a0 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f nst void*,int,co
348b0 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e nst void*).);.in
348c0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
348d0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 _collation_v2(.
348e0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f sqlite3*, . co
348f0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
34900 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 . int eTextRep
34910 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e , . void*,. in
34920 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 t(*xCompare)(voi
34930 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 d*,int,const voi
34940 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 d*,int,const voi
34950 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 d*),. void(*xDe
34960 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b stroy)(void*).);
34970 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 .int sqlite3_cre
34980 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 ate_collation16(
34990 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 . sqlite3*, .
349a0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d const void *zNam
349b0 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 e,. int eTextRe
349c0 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 p, . void*,. i
349d0 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f nt(*xCompare)(vo
349e0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f id*,int,const vo
349f0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f id*,int,const vo
34a00 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 id*).);../*.** C
34a10 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 API3REF: Collati
34a20 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 on Needed Callba
34a30 63 6b 73 20 7b 48 31 36 37 30 30 7d 20 3c 53 32 cks {H16700} <S2
34a40 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 0300>.**.** To a
34a50 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 void having to r
34a60 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c egister all coll
34a70 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 ation sequences
34a80 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 before a databas
34a90 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 e.** can be used
34aa0 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 , a single callb
34ab0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 ack function may
34ac0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77 be registered w
34ad0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 ith the.** [data
34ae0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
34af0 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 20 77 68 to be called wh
34b00 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 enever an undefi
34b10 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a ned collation.**
34b20 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 sequence is req
34b30 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 uired..**.** If
34b40 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 the function is
34b50 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 registered using
34b60 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c the sqlite3_col
34b70 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 lation_needed()
34b80 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 API,.** then it
34b90 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 is passed the na
34ba0 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 mes of undefined
34bb0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 collation seque
34bc0 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a nces as strings.
34bd0 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 ** encoded in UT
34be0 46 2d 38 2e 20 7b 48 31 36 37 30 33 7d 20 49 66 F-8. {H16703} If
34bf0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 sqlite3_collati
34c00 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 on_needed16() is
34c10 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 used,.** the na
34c20 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61 mes are passed a
34c30 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 s UTF-16 in mach
34c40 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 ine native byte
34c50 6f 72 64 65 72 2e 0a 2a 2a 20 41 20 63 61 6c 6c order..** A call
34c60 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 to either funct
34c70 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61 6e 79 ion replaces any
34c80 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c 62 61 existing callba
34c90 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 ck..**.** When t
34ca0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 he callback is i
34cb0 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 nvoked, the firs
34cc0 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 t argument passe
34cd0 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f d is a copy.** o
34ce0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 f the second arg
34cf0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 ument to sqlite3
34d00 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 _collation_neede
34d10 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 d() or.** sqlite
34d20 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 3_collation_need
34d30 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 ed16(). The sec
34d40 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ond argument is
34d50 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 the database.**
34d60 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 connection. The
34d70 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 third argument
34d80 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 is one of [SQLIT
34d90 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 E_UTF8], [SQLITE
34da0 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 _UTF16BE],.** or
34db0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 [SQLITE_UTF16LE
34dc0 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 ], indicating th
34dd0 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 e most desirable
34de0 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c form of the col
34df0 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e lation.** sequen
34e00 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 ce function requ
34e10 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 ired. The fourt
34e20 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 h parameter is t
34e30 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a he name of the.*
34e40 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 * required colla
34e50 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a tion sequence..*
34e60 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 *.** The callbac
34e70 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c k function shoul
34e80 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64 d register the d
34e90 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e esired collation
34ea0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 using.** [sqlit
34eb0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
34ec0 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 ion()], [sqlite3
34ed0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
34ee0 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 n16()], or.** [s
34ef0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
34f00 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a llation_v2()]..*
34f10 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
34f20 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 32 7d 20 .**.** {H16702}
34f30 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c A successful cal
34f40 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f l to [sqlite3_co
34f50 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 44 llation_needed(D
34f60 2c 50 2c 46 29 5d 0a 2a 2a 20 20 20 20 20 20 20 ,P,F)].**
34f70 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 or [sqlite3_c
34f80 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 ollation_needed1
34f90 36 28 44 2c 50 2c 46 29 5d 20 63 61 75 73 65 73 6(D,P,F)] causes
34fa0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
34fb0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
34fc0 63 74 69 6f 6e 5d 20 44 20 74 6f 20 69 6e 76 6f ction] D to invo
34fd0 6b 65 20 63 61 6c 6c 62 61 63 6b 20 46 20 77 69 ke callback F wi
34fe0 74 68 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 th first.**
34ff0 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 50 parameter P
35000 20 77 68 65 6e 65 76 65 72 20 69 74 20 6e 65 65 whenever it nee
35010 64 73 20 61 20 63 6f 6d 70 61 72 69 73 6f 6e 20 ds a comparison
35020 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 61 0a 2a function for a.*
35030 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 * colla
35040 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20 74 68 ting sequence th
35050 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 6b at it does not k
35060 6e 6f 77 20 61 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a now about..**.**
35070 20 7b 48 31 36 37 30 34 7d 20 45 61 63 68 20 73 {H16704} Each s
35080 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
35090 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 o [sqlite3_colla
350a0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 6f tion_needed()] o
350b0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 r.** [s
350c0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
350d0 5f 6e 65 65 64 65 64 31 36 28 29 5d 20 6f 76 65 _needed16()] ove
350e0 72 72 69 64 65 73 20 74 68 65 20 63 61 6c 6c 62 rrides the callb
350f0 61 63 6b 20 72 65 67 69 73 74 65 72 65 64 0a 2a ack registered.*
35100 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68 * on th
35110 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 e same [database
35120 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 62 79 20 connection] by
35130 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 65 prior calls to e
35140 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 ither.**
35150 20 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a interface..**.
35160 2a 2a 20 7b 48 31 36 37 30 36 7d 20 54 68 65 20 ** {H16706} The
35170 6e 61 6d 65 20 6f 66 20 74 68 65 20 72 65 71 75 name of the requ
35180 65 73 74 65 64 20 63 6f 6c 6c 61 74 69 6e 67 20 ested collating
35190 66 75 6e 63 74 69 6f 6e 20 70 61 73 73 65 64 20 function passed
351a0 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 in the.**
351b0 20 20 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 4th parameter
351c0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
351d0 20 69 73 20 69 6e 20 55 54 46 2d 38 20 69 66 20 is in UTF-8 if
351e0 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 the callback.**
351f0 20 20 20 20 20 20 20 20 20 77 61 73 20 72 65 67 was reg
35200 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73 istered using [s
35210 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
35220 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 0a 2a _needed()] and.*
35230 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e * is in
35240 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 UTF-16 native b
35250 79 74 65 20 6f 72 64 65 72 20 69 66 20 74 68 65 yte order if the
35260 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 0a 2a 2a callback was.**
35270 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74 regist
35280 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 ered using [sqli
35290 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 te3_collation_ne
352a0 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e eded16()]..*/.in
352b0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 t sqlite3_collat
352c0 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 ion_needed(. sq
352d0 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a lite3*, . void*
352e0 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 , . void(*)(voi
352f0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 d*,sqlite3*,int
35300 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 eTextRep,const c
35310 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c har*).);.int sql
35320 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
35330 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 eeded16(. sqlit
35340 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 e3*, . void*,.
35350 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 void(*)(void*,s
35360 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 qlite3*,int eTex
35370 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a tRep,const void*
35380 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 ).);../*.** Spec
35390 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 ify the key for
353a0 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 an encrypted dat
353b0 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 abase. This rou
353c0 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a tine should be.*
353d0 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 * called right a
353e0 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 fter sqlite3_ope
353f0 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 n()..**.** The c
35400 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 ode to implement
35410 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 this API is not
35420 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 available in th
35430 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 e public release
35440 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a .** of SQLite..*
35450 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 /.int sqlite3_ke
35460 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 y(. sqlite3 *db
35470 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
35480 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
35490 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f to be rekeyed */
354a0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 . const void *p
354b0 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 Key, int nKey
354c0 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a /* The key */.
354d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 );../*.** Change
354e0 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f the key on an o
354f0 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 pen database. I
35500 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 f the current da
35510 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a tabase is not.**
35520 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 encrypted, this
35530 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e routine will en
35540 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e crypt it. If pN
35550 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 ew==0 or nNew==0
35560 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 , the.** databas
35570 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a e is decrypted..
35580 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 **.** The code t
35590 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 o implement this
355a0 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 API is not avai
355b0 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 lable in the pub
355c0 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f lic release.** o
355d0 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 f SQLite..*/.int
355e0 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a sqlite3_rekey(.
355f0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
35600 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
35610 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 /* Database to
35620 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 be rekeyed */.
35630 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 const void *pKey
35640 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f , int nKey /
35650 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f * The new key */
35660 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
35670 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 REF: Suspend Exe
35680 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f cution For A Sho
35690 72 74 20 54 69 6d 65 20 7b 48 31 30 35 33 30 7d rt Time {H10530}
356a0 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 <S40410>.**.**
356b0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 The sqlite3_slee
356c0 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 p() function cau
356d0 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 ses the current
356e0 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e thread to suspen
356f0 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 d execution.** f
35700 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 or at least a nu
35710 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 mber of millisec
35720 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69 onds specified i
35730 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e n its parameter.
35740 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 .**.** If the op
35750 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 erating system d
35760 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 oes not support
35770 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77 sleep requests w
35780 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f ith.** milliseco
35790 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 nd time resoluti
357a0 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d on, then the tim
357b0 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 e will be rounde
357c0 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e d up to.** the n
357d0 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 earest second. T
357e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c he number of mil
357f0 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 liseconds of sle
35800 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 ep actually.** r
35810 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 equested from th
35820 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 e operating syst
35830 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a em is returned..
35840 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 **.** SQLite imp
35850 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 lements this int
35860 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e erface by callin
35870 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a g the xSleep().*
35880 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 * method of the
35890 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 default [sqlite3
358a0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a _vfs] object..**
358b0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
358c0 2a 2a 0a 2a 2a 20 7b 48 31 30 35 33 33 7d 20 54 **.** {H10533} T
358d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 he [sqlite3_slee
358e0 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20 p(M)] interface
358f0 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 6c 65 invokes the xSle
35900 65 70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d ep.** m
35910 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 ethod of the def
35920 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 ault [sqlite3_vf
35930 73 7c 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 s|VFS] in order
35940 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 to.** s
35950 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e uspend execution
35960 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 of the current
35970 74 68 72 65 61 64 20 66 6f 72 20 61 74 20 6c 65 thread for at le
35980 61 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ast.**
35990 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a M milliseconds..
359a0 2a 2a 0a 2a 2a 20 7b 48 31 30 35 33 36 7d 20 54 **.** {H10536} T
359b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 he [sqlite3_slee
359c0 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20 p(M)] interface
359d0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
359e0 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 er of.**
359f0 20 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f milliseconds o
35a00 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 f sleep actually
35a10 20 72 65 71 75 65 73 74 65 64 20 6f 66 20 74 68 requested of th
35a20 65 20 6f 70 65 72 61 74 69 6e 67 0a 2a 2a 20 20 e operating.**
35a30 20 20 20 20 20 20 20 20 73 79 73 74 65 6d 2c 20 system,
35a40 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6c which might be l
35a50 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 70 arger than the p
35a60 61 72 61 6d 65 74 65 72 20 4d 2e 0a 2a 2f 0a 69 arameter M..*/.i
35a70 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 nt sqlite3_sleep
35a80 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 (int);../*.** CA
35a90 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 PI3REF: Name Of
35aa0 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 The Folder Holdi
35ab0 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c ng Temporary Fil
35ac0 65 73 20 7b 48 31 30 33 31 30 7d 20 3c 53 32 30 es {H10310} <S20
35ad0 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 000>.**.** If th
35ae0 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 is global variab
35af0 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f le is made to po
35b00 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 int to a string
35b10 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 which is.** the
35b20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 name of a folder
35b30 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f (a.k.a. directo
35b40 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 ry), then all te
35b50 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a mporary files.**
35b60 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 created by SQLi
35b70 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 te will be place
35b80 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 d in that direct
35b90 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20 76 61 ory. If this va
35ba0 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e riable.** is a N
35bb0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 ULL pointer, the
35bc0 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d n SQLite perform
35bd0 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 s a search for a
35be0 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a n appropriate.**
35bf0 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 temporary file
35c00 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a directory..**.**
35c10 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 It is not safe
35c20 74 6f 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 to modify this v
35c30 61 72 69 61 62 6c 65 20 6f 6e 63 65 20 61 20 5b ariable once a [
35c40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
35c50 69 6f 6e 5d 0a 2a 2a 20 68 61 73 20 62 65 65 6e ion].** has been
35c60 20 6f 70 65 6e 65 64 2e 20 20 49 74 20 69 73 20 opened. It is
35c70 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 intended that th
35c80 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 is variable be s
35c90 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 et once.** as pa
35ca0 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e rt of process in
35cb0 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 itialization and
35cc0 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 before any SQLi
35cd0 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 te interface.**
35ce0 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 routines have be
35cf0 65 6e 20 63 61 6c 6c 20 61 6e 64 20 72 65 6d 61 en call and rema
35d00 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 74 68 65 in unchanged the
35d10 72 65 61 66 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49 reafter..*/.SQLI
35d20 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a TE_EXTERN char *
35d30 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 sqlite3_temp_dir
35d40 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ectory;../*.** C
35d50 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f API3REF: Test Fo
35d60 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f r Auto-Commit Mo
35d70 64 65 20 7b 48 31 32 39 33 30 7d 20 3c 53 36 30 de {H12930} <S60
35d80 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 200>.** KEYWORDS
35d90 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f : {autocommit mo
35da0 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 de}.**.** The sq
35db0 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f lite3_get_autoco
35dc0 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 mmit() interface
35dd0 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 returns non-zer
35de0 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 o or.** zero if
35df0 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 the given databa
35e00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
35e10 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 or is not in au
35e20 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a tocommit mode,.*
35e30 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 * respectively.
35e40 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 Autocommit mode
35e50 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c is on by defaul
35e60 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 t..** Autocommit
35e70 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 mode is disable
35e80 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 d by a [BEGIN] s
35e90 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74 tatement..** Aut
35ea0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 ocommit mode is
35eb0 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20 re-enabled by a
35ec0 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c [COMMIT] or [ROL
35ed0 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 LBACK]..**.** If
35ee0 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f certain kinds o
35ef0 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f f errors occur o
35f00 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 n a statement wi
35f10 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 thin a multi-sta
35f20 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 tement.** transa
35f30 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e ction (errors in
35f40 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f cluding [SQLITE_
35f50 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 FULL], [SQLITE_I
35f60 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 OERR],.** [SQLIT
35f70 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 E_NOMEM], [SQLIT
35f80 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 E_BUSY], and [SQ
35f90 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 LITE_INTERRUPT])
35fa0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 then the.** tra
35fb0 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 nsaction might b
35fc0 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 e rolled back au
35fd0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 tomatically. Th
35fe0 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a e only way to.**
35ff0 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65 find out whethe
36000 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 r SQLite automat
36010 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 ically rolled ba
36020 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 ck the transacti
36030 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 on after.** an e
36040 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 rror is to use t
36050 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a his function..**
36060 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
36070 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33 31 7d 20 54 **.** {H12931} T
36080 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f he [sqlite3_get_
36090 61 75 74 6f 63 6f 6d 6d 69 74 28 44 29 5d 20 69 autocommit(D)] i
360a0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
360b0 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 non-zero or.**
360c0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 69 66 zero if
360d0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
360e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 69 73 20 onnection] D is
360f0 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 or is not in aut
36100 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 20 20 20 20 20 ocommit.**
36110 20 20 20 20 6d 6f 64 65 2c 20 72 65 73 70 65 63 mode, respec
36120 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 tively..**.** {H
36130 31 32 39 33 32 7d 20 41 75 74 6f 63 6f 6d 6d 69 12932} Autocommi
36140 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 t mode is on by
36150 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b default..**.** {
36160 48 31 32 39 33 33 7d 20 41 75 74 6f 63 6f 6d 6d H12933} Autocomm
36170 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 it mode is disab
36180 6c 65 64 20 62 79 20 61 20 73 75 63 63 65 73 73 led by a success
36190 66 75 6c 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 ful [BEGIN] stat
361a0 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ement..**.** {H1
361b0 32 39 33 34 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 2934} Autocommit
361c0 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 mode is enabled
361d0 20 62 79 20 61 20 73 75 63 63 65 73 73 66 75 6c by a successful
361e0 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f [COMMIT] or [RO
361f0 4c 4c 42 41 43 4b 5d 0a 2a 2a 20 20 20 20 20 20 LLBACK].**
36200 20 20 20 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a statement..*
36210 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 *.** ASSUMPTIONS
36220 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 39 33 36 7d :.**.** {A12936}
36230 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 If another thre
36240 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61 ad changes the a
36250 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 utocommit status
36260 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
36270 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e .** con
36280 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 nection while th
36290 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 is routine is ru
362a0 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 nning, then the
362b0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 return value.**
362c0 20 20 20 20 20 20 20 20 20 69 73 20 75 6e 64 65 is unde
362d0 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 fined..*/.int sq
362e0 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f lite3_get_autoco
362f0 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a mmit(sqlite3*);.
36300 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
36310 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 Find The Databa
36320 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 se Handle Of A P
36330 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e repared Statemen
36340 74 20 7b 48 31 33 31 32 30 7d 20 3c 53 36 30 36 t {H13120} <S606
36350 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 00>.**.** The sq
36360 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 lite3_db_handle
36370 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
36380 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 s the [database
36390 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 connection] hand
363a0 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 le.** to which a
363b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
363c0 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 ment] belongs.
363d0 54 68 65 20 64 61 74 61 62 61 73 65 20 68 61 6e The database han
363e0 64 6c 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a dle returned by.
363f0 2a 2a 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 ** sqlite3_db_ha
36400 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 ndle is the same
36410 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 database handle
36420 20 74 68 61 74 20 77 61 73 20 74 68 65 20 66 69 that was the fi
36430 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 rst argument.**
36440 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
36450 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61 prepare_v2()] ca
36460 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69 61 ll (or its varia
36470 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 75 73 nts) that was us
36480 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 ed to.** create
36490 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e the statement in
364a0 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 the first place
364b0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
364c0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 32 TS:.**.** {H1312
364d0 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 3} The [sqlite3_
364e0 64 62 5f 68 61 6e 64 6c 65 28 53 29 5d 20 69 6e db_handle(S)] in
364f0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
36500 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 a pointer.**
36510 20 20 20 20 20 20 74 6f 20 74 68 65 20 5b 64 61 to the [da
36520 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
36530 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 n] associated wi
36540 74 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 th the.**
36550 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 [prepared sta
36560 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 73 71 tement] S..*/.sq
36570 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 lite3 *sqlite3_d
36580 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 b_handle(sqlite3
36590 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 _stmt*);../*.**
365a0 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74 CAPI3REF: Find t
365b0 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65 64 he next prepared
365c0 20 73 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 31 statement {H131
365d0 34 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a 40} <S60600>.**.
365e0 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 ** This interfac
365f0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e e returns a poin
36600 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20 ter to the next
36610 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
36620 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 ent] after.** pS
36630 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 tmt associated w
36640 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 ith the [databas
36650 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 e connection] pD
36660 62 2e 20 20 49 66 20 70 53 74 6d 74 20 69 73 20 b. If pStmt is
36670 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 NULL.** then thi
36680 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 s interface retu
36690 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
366a0 20 74 68 65 20 66 69 72 73 74 20 70 72 65 70 61 the first prepa
366b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a red statement.**
366c0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
366d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
366e0 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 49 nnection pDb. I
366f0 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73 74 f no prepared st
36700 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 atement.** satis
36710 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74 69 fies the conditi
36720 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 ons of this rout
36730 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20 ine, it returns
36740 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 NULL..**.** INVA
36750 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
36760 31 33 31 34 33 7d 20 49 66 20 44 20 69 73 20 61 13143} If D is a
36770 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
36780 63 74 69 6f 6e 5d 20 74 68 61 74 20 68 6f 6c 64 ction] that hold
36790 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a s one or more.**
367a0 20 20 20 20 20 20 20 20 20 20 75 6e 66 69 6e 61 unfina
367b0 6c 69 7a 65 64 20 5b 70 72 65 70 61 72 65 64 20 lized [prepared
367c0 73 74 61 74 65 6d 65 6e 74 73 5d 20 61 6e 64 20 statements] and
367d0 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e S is a NULL poin
367e0 74 65 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ter,.**
367f0 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6e then [sqlite3_n
36800 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20 ext_stmt(D, S)]
36810 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 routine shall re
36820 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a turn a pointer.*
36830 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 6f 6e * to on
36840 65 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 e of the prepare
36850 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 d statements ass
36860 6f 63 69 61 74 65 64 20 77 69 74 68 20 44 2e 0a ociated with D..
36870 2a 2a 0a 2a 2a 20 7b 48 31 33 31 34 36 7d 20 49 **.** {H13146} I
36880 66 20 44 20 69 73 20 61 20 5b 64 61 74 61 62 61 f D is a [databa
36890 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 se connection] t
368a0 68 61 74 20 68 6f 6c 64 73 20 6e 6f 20 75 6e 66 hat holds no unf
368b0 69 6e 61 6c 69 7a 65 64 0a 2a 2a 20 20 20 20 20 inalized.**
368c0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 [prepared s
368d0 74 61 74 65 6d 65 6e 74 73 5d 20 61 6e 64 20 53 tatements] and S
368e0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
368f0 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 er, then.**
36900 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6e 65 [sqlite3_ne
36910 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20 72 xt_stmt(D, S)] r
36920 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 outine shall ret
36930 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 urn a NULL point
36940 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 34 er..**.** {H1314
36950 39 7d 20 49 66 20 53 20 69 73 20 61 20 5b 70 72 9} If S is a [pr
36960 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
36970 5d 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 ] in the [databa
36980 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
36990 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 .** and
369a0 20 53 20 69 73 20 6e 6f 74 20 74 68 65 20 6c 61 S is not the la
369b0 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 st prepared stat
369c0 65 6d 65 6e 74 20 69 6e 20 44 2c 20 74 68 65 6e ement in D, then
369d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
369e0 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 lite3_next_stmt(
369f0 44 2c 20 53 29 5d 20 72 6f 75 74 69 6e 65 20 73 D, S)] routine s
36a00 68 61 6c 6c 20 72 65 74 75 72 6e 20 61 20 70 6f hall return a po
36a10 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 inter.**
36a20 20 20 74 6f 20 74 68 65 20 6e 65 78 74 20 70 72 to the next pr
36a30 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
36a40 20 69 6e 20 44 20 61 66 74 65 72 20 53 2e 0a 2a in D after S..*
36a50 2a 0a 2a 2a 20 7b 48 31 33 31 35 32 7d 20 49 66 *.** {H13152} If
36a60 20 53 20 69 73 20 74 68 65 20 6c 61 73 74 20 5b S is the last [
36a70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
36a80 6e 74 5d 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 nt] in the.**
36a90 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 [database
36aa0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74 connection] D t
36ab0 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 hen the [sqlite3
36ac0 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 _next_stmt(D, S)
36ad0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f ].** ro
36ae0 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 utine shall retu
36af0 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 rn a NULL pointe
36b00 72 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 r..**.** ASSUMPT
36b10 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 IONS:.**.** {A13
36b20 31 35 34 7d 20 54 68 65 20 5b 64 61 74 61 62 61 154} The [databa
36b30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 se connection] p
36b40 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61 ointer D in a ca
36b50 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 ll to.**
36b60 20 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f [sqlite3_next_
36b70 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 stmt(D,S)] must
36b80 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e refer to an open
36b90 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 20 database.**
36ba0 20 20 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e connection
36bb0 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c and in particul
36bc0 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 ar must not be a
36bd0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a NULL pointer..*
36be0 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a /.sqlite3_stmt *
36bf0 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d sqlite3_next_stm
36c00 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 t(sqlite3 *pDb,
36c10 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
36c20 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tmt);../*.** CAP
36c30 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e I3REF: Commit An
36c40 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 d Rollback Notif
36c50 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b ication Callback
36c60 73 20 7b 48 31 32 39 35 30 7d 20 3c 53 36 30 34 s {H12950} <S604
36c70 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 00>.**.** The sq
36c80 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f lite3_commit_hoo
36c90 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 k() interface re
36ca0 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 gisters a callba
36cb0 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 ck.** function t
36cc0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 o be invoked whe
36cd0 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 never a transact
36ce0 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 ion is committed
36cf0 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 ..** Any callbac
36d00 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 k set by a previ
36d10 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 ous call to sqli
36d20 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 te3_commit_hook(
36d30 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d ).** for the sam
36d40 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
36d50 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 ction is overrid
36d60 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 den..** The sqli
36d70 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f te3_rollback_hoo
36d80 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 k() interface re
36d90 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 gisters a callba
36da0 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 ck.** function t
36db0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 o be invoked whe
36dc0 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 never a transact
36dd0 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 ion is committed
36de0 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 ..** Any callbac
36df0 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 k set by a previ
36e00 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 ous call to sqli
36e10 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 te3_commit_hook(
36e20 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d ).** for the sam
36e30 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
36e40 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 ction is overrid
36e50 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 70 41 72 67 den..** The pArg
36e60 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 argument is pas
36e70 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 sed through to t
36e80 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 he callback..**
36e90 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 If the callback
36ea0 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b on a commit hook
36eb0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e function return
36ec0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 s non-zero,.** t
36ed0 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 hen the commit i
36ee0 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f s converted into
36ef0 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a a rollback..**.
36f00 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 ** If another fu
36f10 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 nction was previ
36f20 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 ously registered
36f30 2c 20 69 74 73 0a 2a 2a 20 70 41 72 67 20 76 61 , its.** pArg va
36f40 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e lue is returned.
36f50 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c Otherwise NULL
36f60 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
36f70 0a 2a 2a 20 52 65 67 69 73 74 65 72 69 6e 67 20 .** Registering
36f80 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 a NULL function
36f90 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c disables the cal
36fa0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 lback..**.** For
36fb0 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 the purposes of
36fc0 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 61 this API, a tra
36fd0 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64 nsaction is said
36fe0 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a to have been.**
36ff0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 rolled back if
37000 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c an explicit "ROL
37010 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 LBACK" statement
37020 20 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 is executed, or
37030 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 .** an error or
37040 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 constraint cause
37050 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f s an implicit ro
37060 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e llback to occur.
37070 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b .** The rollback
37080 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 callback is not
37090 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 invoked if a tr
370a0 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 ansaction is.**
370b0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f automatically ro
370c0 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 lled back becaus
370d0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 e the database c
370e0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f onnection is clo
370f0 73 65 64 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c sed..** The roll
37100 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 back callback is
37110 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 not invoked if
37120 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 a transaction is
37130 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 .** rolled back
37140 62 65 63 61 75 73 65 20 61 20 63 6f 6d 6d 69 74 because a commit
37150 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
37160 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 ed non-zero..**
37170 3c 74 6f 64 6f 3e 20 43 68 65 63 6b 20 6f 6e 20 <todo> Check on
37180 74 68 69 73 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a this </todo>.**.
37190 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a ** INVARIANTS:.*
371a0 2a 0a 2a 2a 20 7b 48 31 32 39 35 31 7d 20 54 68 *.** {H12951} Th
371b0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 e [sqlite3_commi
371c0 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 t_hook(D,F,P)] i
371d0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 nterface registe
371e0 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 rs the.**
371f0 20 20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 callback func
37200 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e 76 tion F to be inv
37210 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 oked with argume
37220 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a nt P whenever.**
37230 20 20 20 20 20 20 20 20 20 20 61 20 74 72 61 6e a tran
37240 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 20 saction commits
37250 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 on the [database
37260 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a connection] D..
37270 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 32 7d 20 54 **.** {H12952} T
37280 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d he [sqlite3_comm
37290 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 it_hook(D,F,P)]
372a0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
372b0 73 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 s the P argument
372c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f .** fro
372d0 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 m the previous c
372e0 61 6c 6c 20 77 69 74 68 20 74 68 65 20 73 61 6d all with the sam
372f0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
37300 65 63 74 69 6f 6e 5d 20 44 2c 0a 2a 2a 20 20 20 ection] D,.**
37310 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 6f or NULL o
37320 6e 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c n the first call
37330 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 for a particula
37340 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 r database conne
37350 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b ction D..**.** {
37360 48 31 32 39 35 33 7d 20 45 61 63 68 20 63 61 6c H12953} Each cal
37370 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f l to [sqlite3_co
37380 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65 mmit_hook()] ove
37390 72 77 72 69 74 65 73 20 74 68 65 20 63 61 6c 6c rwrites the call
373a0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 back.**
373b0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 70 registered by p
373c0 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a rior calls..**.*
373d0 2a 20 7b 48 31 32 39 35 34 7d 20 49 66 20 74 68 * {H12954} If th
373e0 65 20 46 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 e F argument to
373f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f [sqlite3_commit_
37400 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20 hook(D,F,P)] is
37410 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 NULL.**
37420 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 then the commit
37430 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 hook callback i
37440 73 20 63 61 6e 63 65 6c 65 64 20 61 6e 64 20 6e s canceled and n
37450 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 o callback.**
37460 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 is invoke
37470 64 20 77 68 65 6e 20 61 20 74 72 61 6e 73 61 63 d when a transac
37480 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 2e 0a 2a 2a tion commits..**
37490 0a 2a 2a 20 7b 48 31 32 39 35 35 7d 20 49 66 20 .** {H12955} If
374a0 74 68 65 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 the commit callb
374b0 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d ack returns non-
374c0 7a 65 72 6f 20 74 68 65 6e 20 74 68 65 20 63 6f zero then the co
374d0 6d 6d 69 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 mmit is.**
374e0 20 20 20 20 63 6f 6e 76 65 72 74 65 64 20 69 6e converted in
374f0 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a to a rollback..*
37500 2a 0a 2a 2a 20 7b 48 31 32 39 36 31 7d 20 54 68 *.** {H12961} Th
37510 65 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 e [sqlite3_rollb
37520 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d ack_hook(D,F,P)]
37530 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 interface regis
37540 74 65 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 ters the.**
37550 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 66 75 callback fu
37560 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 nction F to be i
37570 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 nvoked with argu
37580 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a ment P whenever.
37590 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 74 72 ** a tr
375a0 61 6e 73 61 63 74 69 6f 6e 20 72 6f 6c 6c 73 20 ansaction rolls
375b0 62 61 63 6b 20 6f 6e 20 74 68 65 20 5b 64 61 74 back on the [dat
375c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
375d0 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 ] D..**.** {H129
375e0 36 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 62} The [sqlite3
375f0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 _rollback_hook(D
37600 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 ,F,P)] interface
37610 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 0a 2a returns the P.*
37620 2a 20 20 20 20 20 20 20 20 20 20 61 72 67 75 6d * argum
37630 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 ent from the pre
37640 76 69 6f 75 73 20 63 61 6c 6c 20 77 69 74 68 20 vious call with
37650 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 the same.**
37660 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 [database c
37670 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 onnection] D, or
37680 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69 72 NULL on the fir
37690 73 74 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 st call.**
376a0 20 20 20 20 66 6f 72 20 61 20 70 61 72 74 69 63 for a partic
376b0 75 6c 61 72 20 64 61 74 61 62 61 73 65 20 63 6f ular database co
376c0 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a nnection D..**.*
376d0 2a 20 7b 48 31 32 39 36 33 7d 20 45 61 63 68 20 * {H12963} Each
376e0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
376f0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 _rollback_hook()
37700 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74 68 65 ] overwrites the
37710 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 callback.**
37720 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64 registered
37730 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e by prior calls.
37740 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36 34 7d 20 .**.** {H12964}
37750 49 66 20 74 68 65 20 46 20 61 72 67 75 6d 65 6e If the F argumen
37760 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 6f t to [sqlite3_ro
37770 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c llback_hook(D,F,
37780 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 P)] is NULL.**
37790 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 then the
377a0 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 63 rollback hook c
377b0 61 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e 63 65 allback is cance
377c0 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62 led and no callb
377d0 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ack.**
377e0 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 is invoked when
377f0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f a transaction ro
37800 6c 6c 73 20 62 61 63 6b 2e 0a 2a 2f 0a 76 6f 69 lls back..*/.voi
37810 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 d *sqlite3_commi
37820 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c t_hook(sqlite3*,
37830 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 int(*)(void*),
37840 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 void*);.void *sq
37850 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 lite3_rollback_h
37860 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f ook(sqlite3*, vo
37870 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 id(*)(void *), v
37880 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 oid*);../*.** CA
37890 50 49 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 PI3REF: Data Cha
378a0 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e nge Notification
378b0 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 Callbacks {H129
378c0 37 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 70} <S60400>.**.
378d0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 ** The sqlite3_u
378e0 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 pdate_hook() int
378f0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 erface registers
37900 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 a callback func
37910 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 tion.** with the
37920 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
37930 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 ction] identifie
37940 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 d by the first a
37950 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 rgument.** to be
37960 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 invoked wheneve
37970 72 20 61 20 72 6f 77 20 69 73 20 75 70 64 61 74 r a row is updat
37980 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 ed, inserted or
37990 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 deleted..** Any
379a0 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 callback set by
379b0 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 a previous call
379c0 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e to this function
379d0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 .** for the same
379e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
379f0 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 tion is overridd
37a00 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 en..**.** The se
37a10 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 cond argument is
37a20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
37a30 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e e function to in
37a40 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 voke when a.** r
37a50 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 ow is updated, i
37a60 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 nserted or delet
37a70 65 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 ed..** The first
37a80 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
37a90 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 callback is a c
37aa0 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 opy of the third
37ab0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 argument.** to
37ac0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 sqlite3_update_h
37ad0 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 ook()..** The se
37ae0 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 cond callback ar
37af0 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 gument is one of
37b00 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d [SQLITE_INSERT]
37b10 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 , [SQLITE_DELETE
37b20 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 ],.** or [SQLITE
37b30 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 _UPDATE], depend
37b40 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 ing on the opera
37b50 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 tion that caused
37b60 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a the callback.**
37b70 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a to be invoked..
37b80 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 ** The third and
37b90 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 fourth argument
37ba0 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 s to the callbac
37bb0 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 k contain pointe
37bc0 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 rs to the.** dat
37bd0 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 abase and table
37be0 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 name containing
37bf0 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 the affected row
37c00 2e 0a 2a 2a 20 54 68 65 20 66 69 6e 61 6c 20 63 ..** The final c
37c10 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 allback paramete
37c20 72 20 69 73 20 74 68 65 20 72 6f 77 69 64 20 6f r is the rowid o
37c30 66 20 74 68 65 20 72 6f 77 2e 20 49 6e 20 74 68 f the row. In th
37c40 65 20 63 61 73 65 20 6f 66 0a 2a 2a 20 61 6e 20 e case of.** an
37c50 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 update, this is
37c60 74 68 65 20 72 6f 77 69 64 20 61 66 74 65 72 20 the rowid after
37c70 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65 73 the update takes
37c80 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 place..**.** Th
37c90 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 e update hook is
37ca0 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 not invoked whe
37cb0 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 n internal syste
37cc0 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 m tables are.**
37cd0 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 modified (i.e. s
37ce0 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 qlite_master and
37cf0 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 sqlite_sequence
37d00 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 )..**.** If anot
37d10 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 her function was
37d20 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 previously regi
37d30 73 74 65 72 65 64 2c 20 69 74 73 20 70 41 72 67 stered, its pArg
37d40 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 72 65 74 value.** is ret
37d50 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 urned. Otherwis
37d60 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e e NULL is return
37d70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 ed..**.** INVARI
37d80 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 ANTS:.**.** {H12
37d90 39 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 971} The [sqlite
37da0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 3_update_hook(D,
37db0 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 F,P)] interface
37dc0 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 causes the callb
37dd0 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ack.**
37de0 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 function F to be
37df0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 69 invoked with fi
37e00 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 50 20 rst parameter P
37e10 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 whenever.**
37e20 20 20 20 20 20 61 20 74 61 62 6c 65 20 72 6f 77 a table row
37e30 20 69 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e is modified, in
37e40 73 65 72 74 65 64 2c 20 6f 72 20 64 65 6c 65 74 serted, or delet
37e50 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 ed on.**
37e60 20 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 the [database
37e70 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a connection] D..*
37e80 2a 0a 2a 2a 20 7b 48 31 32 39 37 33 7d 20 54 68 *.** {H12973} Th
37e90 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 e [sqlite3_updat
37ea0 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 e_hook(D,F,P)] i
37eb0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
37ec0 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20 the value.**
37ed0 20 20 20 20 20 20 20 6f 66 20 50 20 66 6f 72 20 of P for
37ee0 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c the previous cal
37ef0 6c 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 l on the same [d
37f00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
37f10 6f 6e 5d 20 44 2c 0a 2a 2a 20 20 20 20 20 20 20 on] D,.**
37f20 20 20 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 20 74 or NULL for t
37f30 68 65 20 66 69 72 73 74 20 63 61 6c 6c 2e 0a 2a he first call..*
37f40 2a 0a 2a 2a 20 7b 48 31 32 39 37 35 7d 20 49 66 *.** {H12975} If
37f50 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b the update hook
37f60 20 63 61 6c 6c 62 61 63 6b 20 46 20 69 6e 20 5b callback F in [
37f70 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 sqlite3_update_h
37f80 6f 6f 6b 28 44 2c 46 2c 50 29 5d 0a 2a 2a 20 20 ook(D,F,P)].**
37f90 20 20 20 20 20 20 20 20 69 73 20 4e 55 4c 4c 20 is NULL
37fa0 74 68 65 6e 20 74 68 65 20 6e 6f 20 75 70 64 61 then the no upda
37fb0 74 65 20 63 61 6c 6c 62 61 63 6b 73 20 61 72 65 te callbacks are
37fc0 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 made..**.** {H1
37fd0 32 39 37 37 7d 20 45 61 63 68 20 63 61 6c 6c 20 2977} Each call
37fe0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 to [sqlite3_upda
37ff0 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 te_hook(D,F,P)]
38000 6f 76 65 72 72 69 64 65 73 20 70 72 69 6f 72 20 overrides prior
38010 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20 calls.**
38020 20 20 74 6f 20 74 68 65 20 73 61 6d 65 20 69 6e to the same in
38030 74 65 72 66 61 63 65 20 6f 6e 20 74 68 65 20 73 terface on the s
38040 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f ame [database co
38050 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a nnection] D..**.
38060 2a 2a 20 7b 48 31 32 39 37 39 7d 20 54 68 65 20 ** {H12979} The
38070 75 70 64 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c update hook call
38080 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f back is not invo
38090 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 ked when interna
380a0 6c 20 73 79 73 74 65 6d 0a 2a 2a 20 20 20 20 20 l system.**
380b0 20 20 20 20 20 74 61 62 6c 65 73 20 73 75 63 68 tables such
380c0 20 61 73 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 as sqlite_maste
380d0 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 r and sqlite_seq
380e0 75 65 6e 63 65 20 61 72 65 20 6d 6f 64 69 66 69 uence are modifi
380f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 38 ed..**.** {H1298
38100 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 1} The second pa
38110 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 75 rameter to the u
38120 70 64 61 74 65 20 63 61 6c 6c 62 61 63 6b 0a 2a pdate callback.*
38130 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6f 6e * is on
38140 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 e of [SQLITE_INS
38150 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 ERT], [SQLITE_DE
38160 4c 45 54 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 LETE] or [SQLITE
38170 5f 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 20 20 20 _UPDATE],.**
38180 20 20 20 20 20 20 64 65 70 65 6e 64 69 6e 67 20 depending
38190 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e on the operation
381a0 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65 that caused the
381b0 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 callback to be
381c0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b invoked..**.** {
381d0 48 31 32 39 38 33 7d 20 54 68 65 20 74 68 69 72 H12983} The thir
381e0 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67 d and fourth arg
381f0 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 uments to the ca
38200 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 llback contain p
38210 6f 69 6e 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 ointers.**
38220 20 20 20 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d to zero-term
38230 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 inated UTF-8 str
38240 69 6e 67 73 20 77 68 69 63 68 20 61 72 65 20 74 ings which are t
38250 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a he names of the.
38260 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61 ** data
38270 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 74 base and table t
38280 68 61 74 20 69 73 20 62 65 69 6e 67 20 75 70 64 hat is being upd
38290 61 74 65 64 2e 0a 0a 2a 2a 20 7b 48 31 32 39 38 ated...** {H1298
382a0 35 7d 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 5} The final cal
382b0 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 lback parameter
382c0 69 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 is the rowid of
382d0 74 68 65 20 72 6f 77 20 61 66 74 65 72 0a 2a 2a the row after.**
382e0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63 68 the ch
382f0 61 6e 67 65 20 6f 63 63 75 72 73 2e 0a 2a 2f 0a ange occurs..*/.
38300 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 void *sqlite3_up
38310 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c date_hook(. sql
38320 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a ite3*, . void(*
38330 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 )(void *,int ,ch
38340 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 ar const *,char
38350 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f const *,sqlite3_
38360 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a int64),. void*.
38370 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
38380 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 EF: Enable Or Di
38390 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61 67 sable Shared Pag
383a0 65 72 20 43 61 63 68 65 20 7b 48 31 30 33 33 30 er Cache {H10330
383b0 7d 20 3c 53 33 30 39 30 30 3e 0a 2a 2a 20 4b 45 } <S30900>.** KE
383c0 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 20 YWORDS: {shared
383d0 63 61 63 68 65 7d 20 7b 73 68 61 72 65 64 20 63 cache} {shared c
383e0 61 63 68 65 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a ache mode}.**.**
383f0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e This routine en
38400 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 ables or disable
38410 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66 s the sharing of
38420 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61 the database ca
38430 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d che.** and schem
38440 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 a data structure
38450 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62 s between [datab
38460 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c ase connection |
38470 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a connections].**
38480 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 to the same dat
38490 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69 abase. Sharing i
384a0 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 s enabled if the
384b0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 argument is tru
384c0 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 e.** and disable
384d0 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e d if the argumen
384e0 74 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a t is false..**.*
384f0 2a 20 43 61 63 68 65 20 73 68 61 72 69 6e 67 20 * Cache sharing
38500 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 is enabled and d
38510 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 65 isabled for an e
38520 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 20 7b ntire process. {
38530 45 4e 44 7d 0a 2a 2a 20 54 68 69 73 20 69 73 20 END}.** This is
38540 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 a change as of S
38550 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e QLite version 3.
38560 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 5.0. In prior ve
38570 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
38580 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 ,.** sharing was
38590 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 enabled or disa
385a0 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 bled for each th
385b0 72 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e read separately.
385c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68 65 .**.** The cache
385d0 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 sharing mode se
385e0 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 t by this interf
385f0 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 ace effects all
38600 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 subsequent.** ca
38610 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
38620 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 open()], [sqlite
38630 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 3_open_v2()], an
38640 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 d [sqlite3_open1
38650 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 6()]..** Existin
38660 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 g database conne
38670 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 ctions continue
38680 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 use the sharing
38690 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 mode.** that was
386a0 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 in effect at th
386b0 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 e time they were
386c0 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 opened..**.** V
386d0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 irtual tables ca
386e0 6e 6e 6f 74 20 62 65 20 75 73 65 64 20 77 69 74 nnot be used wit
386f0 68 20 61 20 73 68 61 72 65 64 20 63 61 63 68 65 h a shared cache
38700 2e 20 20 57 68 65 6e 20 73 68 61 72 65 64 0a 2a . When shared.*
38710 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c * cache is enabl
38720 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 ed, the [sqlite3
38730 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 _create_module()
38740 5d 20 41 50 49 20 75 73 65 64 20 74 6f 20 72 65 ] API used to re
38750 67 69 73 74 65 72 0a 2a 2a 20 76 69 72 74 75 61 gister.** virtua
38760 6c 20 74 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c l tables will al
38770 77 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65 ways return an e
38780 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 rror..**.** This
38790 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
387a0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 [SQLITE_OK] if
387b0 73 68 61 72 65 64 20 63 61 63 68 65 20 77 61 73 shared cache was
387c0 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 enabled or disa
387d0 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65 73 73 66 bled.** successf
387e0 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72 ully. An [error
387f0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e code] is return
38800 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a ed otherwise..**
38810 0a 2a 2a 20 53 68 61 72 65 64 20 63 61 63 68 65 .** Shared cache
38820 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 is disabled by
38830 64 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69 default. But thi
38840 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69