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 2e 68 2e 69 $Id: sqlite.h.i
05e0: 6e 2c 76 20 31 2e 34 32 31 20 32 30 30 38 2f 31 n,v 1.421 2008/1
05f0: 32 2f 33 30 20 30 36 3a 32 34 3a 35 38 20 64 61 2/30 06:24:58 da
0600: 6e 69 65 6c 6b 31 39 37 37 20 45 78 70 20 24 0a nielk1977 Exp $.
0610: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49 */.#ifndef _SQLI
0620: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f TE3_H_.#define _
0630: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c SQLITE3_H_.#incl
0640: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 ude <stdarg.h>
0650: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 /* Needed for
0660: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 the definition
0670: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f of va_list */../
0680: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 *.** Make sure w
0690: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 e can call this
06a0: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a stuff from C++..
06b0: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 */.#ifdef __cplu
06c0: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22 splus.extern "C"
06d0: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a {.#endif.../*.*
06e0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74 * Add the abilit
06f0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65 y to override 'e
0700: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65 xtern'.*/.#ifnde
0710: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a f SQLITE_EXTERN.
0720: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f # define SQLITE_
0730: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 EXTERN extern.#e
0740: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 ndif../*.** Thes
0750: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61 e no-op macros a
0760: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74 re used in front
0770: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74 of interfaces t
0780: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20 o mark those.**
0790: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69 interfaces as ei
07a0: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20 ther deprecated
07b0: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e or experimental.
07c0: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f New applicatio
07d0: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 ns.** should not
07e0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20 use deprecated
07f0: 69 6e 74 72 66 61 63 65 73 20 2d 20 74 68 65 79 intrfaces - they
0800: 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f 72 are support for
0810: 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f backwards.** co
0820: 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 mpatibility only
0830: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 . Application w
0840: 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 riters should be
0850: 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 aware that.** e
0860: 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 xperimental inte
0870: 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 rfaces are subje
0880: 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 ct to change in
0890: 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a point releases..
08a0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 **.** These macr
08b0: 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c os used to resol
08c0: 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 ve to various ki
08d0: 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 nds of compiler
08e0: 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f magic that.** wo
08f0: 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 uld generate war
0900: 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 ning messages wh
0910: 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73 65 en they were use
0920: 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 d. But that.**
0930: 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 compiler magic e
0940: 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 nded up generati
0950: 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 ng such a flurry
0960: 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a of bug reports.
0970: 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65 20 ** that we have
0980: 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 taken it all out
0990: 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 and gone back t
09a0: 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a o using simple.*
09b0: 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a * noop macros..*
09c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
09d0: 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 _DEPRECATED.#def
09e0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 ine SQLITE_EXPER
09f0: 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 IMENTAL../*.** E
0a00: 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 nsure these symb
0a10: 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 ols were not def
0a20: 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 ined by some pre
0a30: 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c vious header fil
0a40: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c e..*/.#ifdef SQL
0a50: 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e ITE_VERSION.# un
0a60: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 def SQLITE_VERSI
0a70: 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 ON.#endif.#ifdef
0a80: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f SQLITE_VERSION_
0a90: 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 NUMBER.# undef S
0aa0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 QLITE_VERSION_NU
0ab0: 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a MBER.#endif../*.
0ac0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d ** CAPI3REF: Com
0ad0: 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 pile-Time Librar
0ae0: 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 y Version Number
0af0: 73 20 7b 48 31 30 30 31 30 7d 20 3c 53 36 30 31 s {H10010} <S601
0b00: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 00>.**.** The SQ
0b10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 61 6e 64 LITE_VERSION and
0b20: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f SQLITE_VERSION_
0b30: 4e 55 4d 42 45 52 20 23 64 65 66 69 6e 65 73 20 NUMBER #defines
0b40: 69 6e 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 in.** the sqlite
0b50: 33 2e 68 20 66 69 6c 65 20 73 70 65 63 69 66 79 3.h file specify
0b60: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 the version of
0b70: 53 51 4c 69 74 65 20 77 69 74 68 20 77 68 69 63 SQLite with whic
0b80: 68 0a 2a 2a 20 74 68 61 74 20 68 65 61 64 65 72 h.** that header
0b90: 20 66 69 6c 65 20 69 73 20 61 73 73 6f 63 69 61 file is associa
0ba0: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 ted..**.** The "
0bb0: 76 65 72 73 69 6f 6e 22 20 6f 66 20 53 51 4c 69 version" of SQLi
0bc0: 74 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 6f te is a string o
0bd0: 66 20 74 68 65 20 66 6f 72 6d 20 22 58 2e 59 2e f the form "X.Y.
0be0: 5a 22 2e 0a 2a 2a 20 54 68 65 20 70 68 72 61 73 Z"..** The phras
0bf0: 65 20 22 61 6c 70 68 61 22 20 6f 72 20 22 62 65 e "alpha" or "be
0c00: 74 61 22 20 6d 69 67 68 74 20 62 65 20 61 70 70 ta" might be app
0c10: 65 6e 64 65 64 20 61 66 74 65 72 20 74 68 65 20 ended after the
0c20: 5a 2e 0a 2a 2a 20 54 68 65 20 58 20 76 61 6c 75 Z..** The X valu
0c30: 65 20 69 73 20 6d 61 6a 6f 72 20 76 65 72 73 69 e is major versi
0c40: 6f 6e 20 6e 75 6d 62 65 72 20 61 6c 77 61 79 73 on number always
0c50: 20 33 20 69 6e 20 53 51 4c 69 74 65 33 2e 0a 2a 3 in SQLite3..*
0c60: 2a 20 54 68 65 20 58 20 76 61 6c 75 65 20 6f 6e * The X value on
0c70: 6c 79 20 63 68 61 6e 67 65 73 20 77 68 65 6e 20 ly changes when
0c80: 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 backwards compat
0c90: 69 62 69 6c 69 74 79 20 69 73 0a 2a 2a 20 62 72 ibility is.** br
0ca0: 6f 6b 65 6e 20 61 6e 64 20 77 65 20 69 6e 74 65 oken and we inte
0cb0: 6e 64 20 74 6f 20 6e 65 76 65 72 20 62 72 65 61 nd to never brea
0cc0: 6b 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 k backwards comp
0cd0: 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 54 68 atibility..** Th
0ce0: 65 20 59 20 76 61 6c 75 65 20 69 73 20 74 68 65 e Y value is the
0cf0: 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e minor version n
0d00: 75 6d 62 65 72 20 61 6e 64 20 6f 6e 6c 79 20 63 umber and only c
0d10: 68 61 6e 67 65 73 20 77 68 65 6e 0a 2a 2a 20 74 hanges when.** t
0d20: 68 65 72 65 20 61 72 65 20 6d 61 6a 6f 72 20 66 here are major f
0d30: 65 61 74 75 72 65 20 65 6e 68 61 6e 63 65 6d 65 eature enhanceme
0d40: 6e 74 73 20 74 68 61 74 20 61 72 65 20 66 6f 72 nts that are for
0d50: 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 6c 65 wards compatible
0d60: 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 62 61 63 6b .** but not back
0d70: 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 6c 65 wards compatible
0d80: 2e 0a 2a 2a 20 54 68 65 20 5a 20 76 61 6c 75 65 ..** The Z value
0d90: 20 69 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 is the release
0da0: 6e 75 6d 62 65 72 20 61 6e 64 20 69 73 20 69 6e number and is in
0db0: 63 72 65 6d 65 6e 74 65 64 20 77 69 74 68 0a 2a cremented with.*
0dc0: 2a 20 65 61 63 68 20 72 65 6c 65 61 73 65 20 62 * each release b
0dd0: 75 74 20 72 65 73 65 74 73 20 62 61 63 6b 20 74 ut resets back t
0de0: 6f 20 30 20 77 68 65 6e 65 76 65 72 20 59 20 69 o 0 whenever Y i
0df0: 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 2e 0a 2a s incremented..*
0e00: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
0e10: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
0e20: 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 on()] and [sqlit
0e30: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 e3_libversion_nu
0e40: 6d 62 65 72 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 mber()]..**.** I
0e50: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
0e60: 20 7b 48 31 30 30 31 31 7d 20 54 68 65 20 53 51 {H10011} The SQ
0e70: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 23 64 65 LITE_VERSION #de
0e80: 66 69 6e 65 20 69 6e 20 74 68 65 20 73 71 6c 69 fine in the sqli
0e90: 74 65 33 2e 68 20 68 65 61 64 65 72 20 66 69 6c te3.h header fil
0ea0: 65 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 e shall.**
0eb0: 20 20 20 20 65 76 61 6c 75 61 74 65 20 74 6f 20 evaluate to
0ec0: 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c a string literal
0ed0: 20 74 68 61 74 20 69 73 20 74 68 65 20 53 51 4c that is the SQL
0ee0: 69 74 65 20 76 65 72 73 69 6f 6e 0a 2a 2a 20 20 ite version.**
0ef0: 20 20 20 20 20 20 20 20 77 69 74 68 20 77 68 69 with whi
0f00: 63 68 20 74 68 65 20 68 65 61 64 65 72 20 66 69 ch the header fi
0f10: 6c 65 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 le is associated
0f20: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 31 34 7d ..**.** {H10014}
0f30: 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 The SQLITE_VERS
0f40: 49 4f 4e 5f 4e 55 4d 42 45 52 20 23 64 65 66 69 ION_NUMBER #defi
0f50: 6e 65 20 73 68 61 6c 6c 20 72 65 73 6f 6c 76 65 ne shall resolve
0f60: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a to an integer.*
0f70: 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20 * with
0f80: 74 68 65 20 76 61 6c 75 65 20 28 58 2a 31 30 30 the value (X*100
0f90: 30 30 30 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 0000 + Y*1000 +
0fa0: 5a 29 20 77 68 65 72 65 20 58 2c 20 59 2c 20 61 Z) where X, Y, a
0fb0: 6e 64 20 5a 0a 2a 2a 20 20 20 20 20 20 20 20 20 nd Z.**
0fc0: 20 61 72 65 20 74 68 65 20 6d 61 6a 6f 72 20 76 are the major v
0fd0: 65 72 73 69 6f 6e 2c 20 6d 69 6e 6f 72 20 76 65 ersion, minor ve
0fe0: 72 73 69 6f 6e 2c 20 61 6e 64 20 72 65 6c 65 61 rsion, and relea
0ff0: 73 65 20 6e 75 6d 62 65 72 2e 0a 2a 2f 0a 23 64 se number..*/.#d
1000: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 efine SQLITE_VER
1010: 53 49 4f 4e 20 20 20 20 20 20 20 20 20 22 33 2e SION "3.
1020: 36 2e 31 30 22 0a 23 64 65 66 69 6e 65 20 53 51 6.10".#define SQ
1030: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d LITE_VERSION_NUM
1040: 42 45 52 20 20 33 30 30 36 30 31 30 0a 0a 2f 2a BER 3006010../*
1050: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 .** CAPI3REF: Ru
1060: 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 n-Time Library V
1070: 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 20 7b ersion Numbers {
1080: 48 31 30 30 32 30 7d 20 3c 53 36 30 31 30 30 3e H10020} <S60100>
1090: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 .** KEYWORDS: sq
10a0: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 0a 2a 2a lite3_version.**
10b0: 0a 2a 2a 20 54 68 65 73 65 20 66 65 61 74 75 72 .** These featur
10c0: 65 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 es provide the s
10d0: 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 ame information
10e0: 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 as the [SQLITE_V
10f0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 61 6e 64 20 5b ERSION].** and [
1100: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e SQLITE_VERSION_N
1110: 55 4d 42 45 52 5d 20 23 64 65 66 69 6e 65 73 20 UMBER] #defines
1120: 69 6e 20 74 68 65 20 68 65 61 64 65 72 2c 20 62 in the header, b
1130: 75 74 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 ut are associate
1140: 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6c 69 d.** with the li
1150: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 brary instead of
1160: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 the header file
1170: 2e 20 20 43 61 75 74 69 6f 75 73 20 70 72 6f 67 . Cautious prog
1180: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 0a 2a 2a rammers might.**
1190: 20 69 6e 63 6c 75 64 65 20 61 20 63 68 65 63 6b include a check
11a0: 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 in their applic
11b0: 61 74 69 6f 6e 20 74 6f 20 76 65 72 69 66 79 20 ation to verify
11c0: 74 68 61 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f that.** sqlite3_
11d0: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 libversion_numbe
11e0: 72 28 29 20 61 6c 77 61 79 73 20 72 65 74 75 72 r() always retur
11f0: 6e 73 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 ns the value.**
1200: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f [SQLITE_VERSION_
1210: 4e 55 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 54 NUMBER]..**.** T
1220: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 he sqlite3_libve
1230: 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e rsion() function
1240: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 61 6d returns the sam
1250: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 e information as
1260: 20 69 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 71 is.** in the sq
1270: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 lite3_version[]
1280: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e string constant.
1290: 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 The function i
12a0: 73 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f s provided.** fo
12b0: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 r use in DLLs si
12c0: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 nce DLL users us
12d0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 ually do not hav
12e0: 65 20 64 69 72 65 63 74 20 61 63 63 65 73 73 20 e direct access
12f0: 74 6f 20 73 74 72 69 6e 67 0a 2a 2a 20 63 6f 6e to string.** con
1300: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 stants within th
1310: 65 20 44 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 e DLL..**.** INV
1320: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
1330: 48 31 30 30 32 31 7d 20 54 68 65 20 5b 73 71 6c H10021} The [sql
1340: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f ite3_libversion_
1350: 6e 75 6d 62 65 72 28 29 5d 20 69 6e 74 65 72 66 number()] interf
1360: 61 63 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e ace shall return
1370: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20 .** an
1380: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f integer equal to
1390: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e [SQLITE_VERSION
13a0: 5f 4e 55 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 _NUMBER]..**.**
13b0: 7b 48 31 30 30 32 32 7d 20 54 68 65 20 5b 73 71 {H10022} The [sq
13c0: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5d 20 73 lite3_version] s
13d0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 73 tring constant s
13e0: 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 0a 2a 2a 20 hall contain.**
13f0: 20 20 20 20 20 20 20 20 20 74 68 65 20 74 65 78 the tex
1400: 74 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 t of the [SQLITE
1410: 5f 56 45 52 53 49 4f 4e 5d 20 73 74 72 69 6e 67 _VERSION] string
1420: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32 33 7d ..**.** {H10023}
1430: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 The [sqlite3_li
1440: 62 76 65 72 73 69 6f 6e 28 29 5d 20 66 75 6e 63 bversion()] func
1450: 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 tion shall retur
1460: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 n.** a
1470: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b pointer to the [
1480: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5d sqlite3_version]
1490: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 string constant
14a0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 ..*/.SQLITE_EXTE
14b0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 RN const char sq
14c0: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b lite3_version[];
14d0: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
14e0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 ite3_libversion(
14f0: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 void);.int sqlit
1500: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 e3_libversion_nu
1510: 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a mber(void);../*.
1520: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 ** CAPI3REF: Tes
1530: 74 20 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 t To See If The
1540: 4c 69 62 72 61 72 79 20 49 73 20 54 68 72 65 61 Library Is Threa
1550: 64 73 61 66 65 20 7b 48 31 30 31 30 30 7d 20 3c dsafe {H10100} <
1560: 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 S60100>.**.** SQ
1570: 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 Lite can be comp
1580: 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 iled with or wit
1590: 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 hout mutexes. W
15a0: 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 hen.** the [SQLI
15b0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 TE_THREADSAFE] C
15c0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 preprocessor ma
15d0: 63 72 6f 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 cro 1 or 2, mute
15e0: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c xes.** are enabl
15f0: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73 ed and SQLite is
1600: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68 threadsafe. Wh
1610: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 en the.** [SQLIT
1620: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 E_THREADSAFE] ma
1630: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 cro is 0, .** th
1640: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d e mutexes are om
1650: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20 itted. Without
1660: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20 the mutexes, it
1670: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 is not safe.** t
1680: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e o use SQLite con
1690: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d currently from m
16a0: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 ore than one thr
16b0: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c ead..**.** Enabl
16c0: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75 ing mutexes incu
16d0: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20 rs a measurable
16e0: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 performance pena
16f0: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 lty..** So if sp
1700: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 eed is of utmost
1710: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 importance, it
1720: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64 makes sense to d
1730: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 isable.** the mu
1740: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20 texes. But for
1750: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 maximum safety,
1760: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62 mutexes should b
1770: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68 e enabled..** Th
1780: 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 e default behavi
1790: 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65 or is for mutexe
17a0: 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e s to be enabled.
17b0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 .**.** This inte
17c0: 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 rface can be use
17d0: 64 20 62 79 20 61 20 70 72 6f 67 72 61 6d 20 74 d by a program t
17e0: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 o make sure that
17f0: 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 the.** version
1800: 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 of SQLite that i
1810: 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 t is linking aga
1820: 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 inst was compile
1830: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 d with.** the de
1840: 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 sired setting of
1850: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
1860: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a EADSAFE] macro..
1870: 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 **.** This inter
1880: 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 face only report
1890: 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 s on the compile
18a0: 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74 -time mutex sett
18b0: 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 ing.** of the [S
18c0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
18d0: 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 ] flag. If SQLi
18e0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
18f0: 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 ith.** SQLITE_TH
1900: 52 45 41 44 53 41 46 45 3d 31 20 74 68 65 6e 20 READSAFE=1 then
1910: 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62 mutexes are enab
1920: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62 led by default b
1930: 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c ut.** can be ful
1940: 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 ly or partially
1950: 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 disabled using a
1960: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
1970: 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 3_config()].** w
1980: 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53 ith the verbs [S
1990: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e QLITE_CONFIG_SIN
19a0: 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c GLETHREAD], [SQL
19b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 ITE_CONFIG_MULTI
19c0: 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b THREAD],.** or [
19d0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
19e0: 54 45 58 5d 2e 20 20 54 68 65 20 72 65 74 75 72 TEX]. The retur
19f0: 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 n value of this
1a00: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 0a 2a function shows.*
1a10: 2a 20 6f 6e 6c 79 20 74 68 65 20 64 65 66 61 75 * only the defau
1a20: 6c 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 lt compile-time
1a30: 73 65 74 74 69 6e 67 2c 20 6e 6f 74 20 61 6e 79 setting, not any
1a40: 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 run-time change
1a50: 73 0a 2a 2a 20 74 6f 20 74 68 61 74 20 73 65 74 s.** to that set
1a60: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 ting..**.** See
1a70: 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d the [threading m
1a80: 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 ode] documentati
1a90: 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 on for additiona
1aa0: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a l information..*
1ab0: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
1ac0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 31 30 31 7d 20 .**.** {H10101}
1ad0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 The [sqlite3_thr
1ae0: 65 61 64 73 61 66 65 28 29 5d 20 66 75 6e 63 74 eadsafe()] funct
1af0: 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 6e ion shall return
1b00: 20 7a 65 72 6f 20 69 66 0a 2a 2a 20 20 20 20 20 zero if.**
1b10: 20 20 20 20 20 61 6e 64 20 6f 6e 6c 79 20 69 66 and only if
1b20: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 SQLite was comp
1b30: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 iled with mutexi
1b40: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 2e ng code omitted.
1b50: 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 31 30 32 7d 20 .**.** {H10102}
1b60: 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e The value return
1b70: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 ed by the [sqlit
1b80: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d e3_threadsafe()]
1b90: 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 function.**
1ba0: 20 20 20 20 20 20 73 68 61 6c 6c 20 72 65 6d 61 shall rema
1bb0: 69 6e 20 74 68 65 20 73 61 6d 65 20 61 63 72 6f in the same acro
1bc0: 73 73 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c ss calls to [sql
1bd0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a ite3_config()]..
1be0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 */.int sqlite3_t
1bf0: 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b hreadsafe(void);
1c00: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1c10: 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 : Database Conne
1c20: 63 74 69 6f 6e 20 48 61 6e 64 6c 65 20 7b 48 31 ction Handle {H1
1c30: 32 30 30 30 7d 20 3c 53 34 30 32 30 30 3e 0a 2a 2000} <S40200>.*
1c40: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 * KEYWORDS: {dat
1c50: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1c60: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e } {database conn
1c70: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 ections}.**.** E
1c80: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 ach open SQLite
1c90: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 database is repr
1ca0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 esented by a poi
1cb0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 nter to an insta
1cc0: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 nce of.** the op
1cd0: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e aque structure n
1ce0: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 amed "sqlite3".
1cf0: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f It is useful to
1d00: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c think of an sql
1d10: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 ite3.** pointer
1d20: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 as an object. T
1d30: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e he [sqlite3_open
1d40: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ()], [sqlite3_op
1d50: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 en16()], and.**
1d60: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
1d70: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 ()] interfaces a
1d80: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 re its construct
1d90: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 ors, and [sqlite
1da0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 69 73 3_close()].** is
1db0: 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 2e its destructor.
1dc0: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 There are many
1dd0: 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 other interface
1de0: 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 s (such as.** [s
1df0: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1e00: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 2()], [sqlite3_c
1e10: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
1e20: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 ], and.** [sqlit
1e30: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 e3_busy_timeout(
1e40: 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 )] to name but t
1e50: 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d hree) that are m
1e60: 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 ethods on an.**
1e70: 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a sqlite3 object..
1e80: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
1e90: 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 t sqlite3 sqlite
1ea0: 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 3;../*.** CAPI3R
1eb0: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 EF: 64-Bit Integ
1ec0: 65 72 20 54 79 70 65 73 20 7b 48 31 30 32 30 30 er Types {H10200
1ed0: 7d 20 3c 53 31 30 31 31 30 3e 0a 2a 2a 20 4b 45 } <S10110>.** KE
1ee0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 YWORDS: sqlite_i
1ef0: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 nt64 sqlite_uint
1f00: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 64.**.** Because
1f10: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f there is no cro
1f20: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 ss-platform way
1f30: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 to specify 64-bi
1f40: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a t integer types.
1f50: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 ** SQLite includ
1f60: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 es typedefs for
1f70: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64-bit signed an
1f80: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 d unsigned integ
1f90: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ers..**.** The s
1fa0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 qlite3_int64 and
1fb0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 sqlite3_uint64
1fc0: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 are the preferre
1fd0: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f d type definitio
1fe0: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 ns..** The sqlit
1ff0: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 e_int64 and sqli
2000: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 te_uint64 types
2010: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f are supported fo
2020: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 r backwards.** c
2030: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c ompatibility onl
2040: 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 y..**.** INVARIA
2050: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 NTS:.**.** {H102
2060: 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 5f 01} The [sqlite_
2070: 69 6e 74 36 34 5d 20 61 6e 64 20 5b 73 71 6c 69 int64] and [sqli
2080: 74 65 33 5f 69 6e 74 36 34 5d 20 74 79 70 65 20 te3_int64] type
2090: 73 68 61 6c 6c 20 73 70 65 63 69 66 79 0a 2a 2a shall specify.**
20a0: 20 20 20 20 20 20 20 20 20 20 61 20 36 34 2d 62 a 64-b
20b0: 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 it signed intege
20c0: 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 30 32 r..**.** {H10202
20d0: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 5f 75 69 } The [sqlite_ui
20e0: 6e 74 36 34 5d 20 61 6e 64 20 5b 73 71 6c 69 74 nt64] and [sqlit
20f0: 65 33 5f 75 69 6e 74 36 34 5d 20 74 79 70 65 20 e3_uint64] type
2100: 73 68 61 6c 6c 20 73 70 65 63 69 66 79 0a 2a 2a shall specify.**
2110: 20 20 20 20 20 20 20 20 20 20 61 20 36 34 2d 62 a 64-b
2120: 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 it unsigned inte
2130: 67 65 72 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 ger..*/.#ifdef S
2140: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 QLITE_INT64_TYPE
2150: 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 . typedef SQLIT
2160: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c E_INT64_TYPE sql
2170: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 ite_int64;. typ
2180: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 edef unsigned SQ
2190: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 LITE_INT64_TYPE
21a0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 sqlite_uint64;.#
21b0: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 elif defined(_MS
21c0: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 C_VER) || define
21d0: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a d(__BORLANDC__).
21e0: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 typedef __int6
21f0: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 4 sqlite_int64;.
2200: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e typedef unsign
2210: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 ed __int64 sqlit
2220: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a e_uint64;.#else.
2230: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c typedef long l
2240: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 ong int sqlite_i
2250: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 nt64;. typedef
2260: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f unsigned long lo
2270: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 ng int sqlite_ui
2280: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 nt64;.#endif.typ
2290: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 edef sqlite_int6
22a0: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 4 sqlite3_int64;
22b0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f .typedef sqlite_
22c0: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 uint64 sqlite3_u
22d0: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 int64;../*.** If
22e0: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 compiling for a
22f0: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 processor that
2300: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 lacks floating p
2310: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a oint support,.**
2320: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 substitute inte
2330: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 ger for floating
2340: 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 -point..*/.#ifde
2350: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c f SQLITE_OMIT_FL
2360: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 OATING_POINT.# d
2370: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c efine double sql
2380: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 ite3_int64.#endi
2390: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 f../*.** CAPI3RE
23a0: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 F: Closing A Dat
23b0: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e abase Connection
23c0: 20 7b 48 31 32 30 31 30 7d 20 3c 53 33 30 31 30 {H12010} <S3010
23d0: 30 3e 3c 53 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 0><S40200>.**.**
23e0: 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 This routine is
23f0: 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 the destructor
2400: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 for the [sqlite3
2410: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 ] object..**.**
2420: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f Applications sho
2430: 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e uld [sqlite3_fin
2440: 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 alize | finalize
2450: 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 ] all [prepared
2460: 73 74 61 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20 61 statements].** a
2470: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 nd [sqlite3_blob
2480: 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 _close | close]
2490: 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 all [BLOB handle
24a0: 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 s] associated wi
24b0: 74 68 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 th.** the [sqlit
24c0: 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 e3] object prior
24d0: 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 to attempting t
24e0: 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 o close the obje
24f0: 63 74 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 ct..** The [sqli
2500: 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d te3_next_stmt()]
2510: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 interface can b
2520: 65 20 75 73 65 64 20 74 6f 20 6c 6f 63 61 74 65 e used to locate
2530: 20 61 6c 6c 0a 2a 2a 20 5b 70 72 65 70 61 72 65 all.** [prepare
2540: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 61 73 d statements] as
2550: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 sociated with a
2560: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2570: 74 69 6f 6e 5d 20 69 66 20 64 65 73 69 72 65 64 tion] if desired
2580: 2e 0a 2a 2a 20 54 79 70 69 63 61 6c 20 63 6f 64 ..** Typical cod
2590: 65 20 6d 69 67 68 74 20 6c 6f 6f 6b 20 6c 69 6b e might look lik
25a0: 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 e this:.**.** <b
25b0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
25c0: 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 ** sqlite3_stmt
25d0: 2a 70 53 74 6d 74 3b 0a 2a 2a 20 77 68 69 6c 65 *pStmt;.** while
25e0: 28 20 28 70 53 74 6d 74 20 3d 20 73 71 6c 69 74 ( (pStmt = sqlit
25f0: 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 64 62 2c e3_next_stmt(db,
2600: 20 30 29 29 21 3d 30 20 29 7b 0a 2a 2a 20 26 6e 0))!=0 ){.** &n
2610: 62 73 70 3b 20 20 20 73 71 6c 69 74 65 33 5f 66 bsp; sqlite3_f
2620: 69 6e 61 6c 69 7a 65 28 70 53 74 6d 74 29 3b 0a inalize(pStmt);.
2630: 2a 2a 20 7d 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f ** }.** </pre></
2640: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
2650: 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 63 6c * If [sqlite3_cl
2660: 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 ose()] is invoke
2670: 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61 d while a transa
2680: 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a ction is open,.*
2690: 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f * the transactio
26a0: 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c n is automatical
26b0: 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a ly rolled back..
26c0: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
26d0: 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 31 7d :.**.** {H12011}
26e0: 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 A successful ca
26f0: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ll to [sqlite3_c
2700: 6c 6f 73 65 28 43 29 5d 20 73 68 61 6c 6c 20 64 lose(C)] shall d
2710: 65 73 74 72 6f 79 20 74 68 65 0a 2a 2a 20 20 20 estroy the.**
2720: 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 [database
2730: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a connection] obj
2740: 65 63 74 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ect C..**.** {H1
2750: 32 30 31 32 7d 20 41 20 73 75 63 63 65 73 73 66 2012} A successf
2760: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 ul call to [sqli
2770: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 73 68 te3_close(C)] sh
2780: 61 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 all return SQLIT
2790: 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 E_OK..**.** {H12
27a0: 30 31 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 013} A successfu
27b0: 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 l call to [sqlit
27c0: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 73 68 61 e3_close(C)] sha
27d0: 6c 6c 20 72 65 6c 65 61 73 65 20 61 6c 6c 0a 2a ll release all.*
27e0: 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 * memor
27f0: 79 20 61 6e 64 20 73 79 73 74 65 6d 20 72 65 73 y and system res
2800: 6f 75 72 63 65 73 20 61 73 73 6f 63 69 61 74 65 ources associate
2810: 64 20 77 69 74 68 20 5b 64 61 74 61 62 61 73 65 d with [database
2820: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 connection].**
2830: 20 20 20 20 20 20 20 20 20 43 2e 0a 2a 2a 0a 2a C..**.*
2840: 2a 20 7b 48 31 32 30 31 34 7d 20 41 20 63 61 6c * {H12014} A cal
2850: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c l to [sqlite3_cl
2860: 6f 73 65 28 43 29 5d 20 6f 6e 20 61 20 5b 64 61 ose(C)] on a [da
2870: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2880: 6e 5d 20 43 20 74 68 61 74 0a 2a 2a 20 20 20 20 n] C that.**
2890: 20 20 20 20 20 20 68 61 73 20 6f 6e 65 20 6f 72 has one or
28a0: 20 6d 6f 72 65 20 6f 70 65 6e 20 5b 70 72 65 70 more open [prep
28b0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d ared statements]
28c0: 20 73 68 61 6c 6c 20 66 61 69 6c 20 77 69 74 68 shall fail with
28d0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20 .** an
28e0: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 [SQLITE_BUSY] er
28f0: 72 6f 72 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 ror code..**.**
2900: 7b 48 31 32 30 31 35 7d 20 41 20 63 61 6c 6c 20 {H12015} A call
2910: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 to [sqlite3_clos
2920: 65 28 43 29 5d 20 77 68 65 72 65 20 43 20 69 73 e(C)] where C is
2930: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
2940: 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 shall.**
2950: 20 20 62 65 20 61 20 68 61 72 6d 6c 65 73 73 20 be a harmless
2960: 6e 6f 2d 6f 70 20 72 65 74 75 72 6e 69 6e 67 20 no-op returning
2970: 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a SQLITE_OK..**.**
2980: 20 7b 48 31 32 30 31 39 7d 20 57 68 65 6e 20 5b {H12019} When [
2990: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 sqlite3_close(C)
29a0: 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 ] is invoked on
29b0: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a [database conn
29c0: 65 63 74 69 6f 6e 5d 20 43 0a 2a 2a 20 20 20 20 ection] C.**
29d0: 20 20 20 20 20 20 74 68 61 74 20 68 61 73 20 61 that has a
29e0: 20 70 65 6e 64 69 6e 67 20 74 72 61 6e 73 61 63 pending transac
29f0: 74 69 6f 6e 2c 20 74 68 65 20 74 72 61 6e 73 61 tion, the transa
2a00: 63 74 69 6f 6e 20 73 68 61 6c 6c 20 62 65 0a 2a ction shall be.*
2a10: 2a 20 20 20 20 20 20 20 20 20 20 72 6f 6c 6c 65 * rolle
2a20: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 41 53 d back..**.** AS
2a30: 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a SUMPTIONS:.**.**
2a40: 20 7b 41 31 32 30 31 36 7d 20 54 68 65 20 43 20 {A12016} The C
2a50: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
2a60: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 lite3_close(C)]
2a70: 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 must be either a
2a80: 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 NULL.**
2a90: 20 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 pointer or an
2aa0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 [sqlite3] object
2ab0: 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 pointer obtaine
2ac0: 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 d.** fr
2ad0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e om [sqlite3_open
2ae0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ()], [sqlite3_op
2af0: 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 20 en16()], or.**
2b00: 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
2b10: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 _open_v2()], and
2b20: 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 not previously
2b30: 63 6c 6f 73 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 closed..*/.int s
2b40: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c qlite3_close(sql
2b50: 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ite3 *);../*.**
2b60: 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 The type for a c
2b70: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
2b80: 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 ..** This is leg
2b90: 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 acy and deprecat
2ba0: 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 ed. It is inclu
2bb0: 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 ded for historic
2bc0: 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c al.** compatibil
2bd0: 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 ity and is not d
2be0: 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 ocumented..*/.ty
2bf0: 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 pedef int (*sqli
2c00: 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f te3_callback)(vo
2c10: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 id*,int,char**,
2c20: 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 char**);../*.**
2c30: 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 CAPI3REF: One-St
2c40: 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69 ep Query Executi
2c50: 6f 6e 20 49 6e 74 65 72 66 61 63 65 20 7b 48 31 on Interface {H1
2c60: 32 31 30 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2100} <S10000>.*
2c70: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
2c80: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 _exec() interfac
2c90: 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e e is a convenien
2ca0: 74 20 77 61 79 20 6f 66 20 72 75 6e 6e 69 6e 67 t way of running
2cb0: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 one or more.**
2cc0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 77 SQL statements w
2cd0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f ithout having to
2ce0: 20 77 72 69 74 65 20 61 20 6c 6f 74 20 6f 66 20 write a lot of
2cf0: 43 20 63 6f 64 65 2e 20 20 54 68 65 20 55 54 46 C code. The UTF
2d00: 2d 38 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 53 51 -8 encoded.** SQ
2d10: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 L statements are
2d20: 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 passed in as th
2d30: 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
2d40: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 er to sqlite3_ex
2d50: 65 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 74 61 ec()..** The sta
2d60: 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c tements are eval
2d70: 75 61 74 65 64 20 6f 6e 65 20 62 79 20 6f 6e 65 uated one by one
2d80: 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 61 6e until either an
2d90: 20 65 72 72 6f 72 20 6f 72 0a 2a 2a 20 61 6e 20 error or.** an
2da0: 69 6e 74 65 72 72 75 70 74 20 69 73 20 65 6e 63 interrupt is enc
2db0: 6f 75 6e 74 65 72 65 64 2c 20 6f 72 20 75 6e 74 ountered, or unt
2dc0: 69 6c 20 74 68 65 79 20 61 72 65 20 61 6c 6c 20 il they are all
2dd0: 64 6f 6e 65 2e 20 20 54 68 65 20 33 72 64 20 70 done. The 3rd p
2de0: 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 61 arameter.** is a
2df0: 6e 20 6f 70 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 n optional callb
2e00: 61 63 6b 20 74 68 61 74 20 69 73 20 69 6e 76 6f ack that is invo
2e10: 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 ked once for eac
2e20: 68 20 72 6f 77 20 6f 66 20 61 6e 79 20 71 75 65 h row of any que
2e30: 72 79 0a 2a 2a 20 72 65 73 75 6c 74 73 20 70 72 ry.** results pr
2e40: 6f 64 75 63 65 64 20 62 79 20 74 68 65 20 53 51 oduced by the SQ
2e50: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 54 L statements. T
2e60: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 he 5th parameter
2e70: 20 74 65 6c 6c 73 20 77 68 65 72 65 0a 2a 2a 20 tells where.**
2e80: 74 6f 20 77 72 69 74 65 20 61 6e 79 20 65 72 72 to write any err
2e90: 6f 72 20 6d 65 73 73 61 67 65 73 2e 0a 2a 2a 0a or messages..**.
2ea0: 2a 2a 20 54 68 65 20 65 72 72 6f 72 20 6d 65 73 ** The error mes
2eb0: 73 61 67 65 20 70 61 73 73 65 64 20 62 61 63 6b sage passed back
2ec0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 through the 5th
2ed0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 68 65 parameter is he
2ee0: 6c 64 0a 2a 2a 20 69 6e 20 6d 65 6d 6f 72 79 20 ld.** in memory
2ef0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 obtained from [s
2f00: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
2f10: 2e 20 20 54 6f 20 61 76 6f 69 64 20 61 20 6d 65 . To avoid a me
2f20: 6d 6f 72 79 20 6c 65 61 6b 2c 0a 2a 2a 20 74 68 mory leak,.** th
2f30: 65 20 63 61 6c 6c 69 6e 67 20 61 70 70 6c 69 63 e calling applic
2f40: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 63 61 6c ation should cal
2f50: 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 l [sqlite3_free(
2f60: 29 5d 20 6f 6e 20 61 6e 79 20 65 72 72 6f 72 0a )] on any error.
2f70: 2a 2a 20 6d 65 73 73 61 67 65 20 72 65 74 75 72 ** message retur
2f80: 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 ned through the
2f90: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 77 68 5th parameter wh
2fa0: 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 en it has finish
2fb0: 65 64 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 ed using.** the
2fc0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a error message..*
2fd0: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 *.** If the SQL
2fe0: 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 statement in the
2ff0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 2nd parameter i
3000: 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 s NULL or an emp
3010: 74 79 20 73 74 72 69 6e 67 0a 2a 2a 20 6f 72 20 ty string.** or
3020: 61 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e a string contain
3030: 69 6e 67 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 ing only whitesp
3040: 61 63 65 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 ace and comments
3050: 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 0a 2a 2a , then no SQL.**
3060: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 statements are
3070: 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 evaluated and th
3080: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f e database is no
3090: 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a t changed..**.**
30a0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 The sqlite3_exe
30b0: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 c() interface is
30c0: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 implemented in
30d0: 74 65 72 6d 73 20 6f 66 0a 2a 2a 20 5b 73 71 6c terms of.** [sql
30e0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
30f0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 )], [sqlite3_ste
3100: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 p()], and [sqlit
3110: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a e3_finalize()]..
3120: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 ** The sqlite3_e
3130: 78 65 63 28 29 20 72 6f 75 74 69 6e 65 20 64 6f xec() routine do
3140: 65 73 20 6e 6f 74 68 69 6e 67 20 74 6f 20 74 68 es nothing to th
3150: 65 20 64 61 74 61 62 61 73 65 20 74 68 61 74 20 e database that
3160: 63 61 6e 6e 6f 74 20 62 65 20 64 6f 6e 65 0a 2a cannot be done.*
3170: 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 * by [sqlite3_pr
3180: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 epare_v2()], [sq
3190: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 lite3_step()], a
31a0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 nd [sqlite3_fina
31b0: 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 lize()]..**.** I
31c0: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
31d0: 20 7b 48 31 32 31 30 31 7d 20 41 20 73 75 63 63 {H12101} A succ
31e0: 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f essful invocatio
31f0: 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 n of [sqlite3_ex
3200: 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 0a 2a ec(D,S,C,A,E)].*
3210: 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c * shall
3220: 20 73 65 71 75 65 6e 74 69 61 6c 6c 79 20 65 76 sequentially ev
3230: 61 6c 75 61 74 65 20 61 6c 6c 20 6f 66 20 74 68 aluate all of th
3240: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c e UTF-8 encoded,
3250: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 65 6d .** sem
3260: 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 icolon-separated
3270: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
3280: 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d in the zero-term
3290: 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 inated.**
32a0: 20 20 20 73 74 72 69 6e 67 20 53 20 77 69 74 68 string S with
32b0: 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f in the context o
32c0: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 f the [database
32d0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a connection] D..*
32e0: 2a 0a 2a 2a 20 7b 48 31 32 31 30 32 7d 20 49 66 *.** {H12102} If
32f0: 20 74 68 65 20 53 20 70 61 72 61 6d 65 74 65 72 the S parameter
3300: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 to [sqlite3_exe
3310: 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 69 73 c(D,S,C,A,E)] is
3320: 20 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20 20 NULL then.**
3330: 20 20 20 20 20 20 20 74 68 65 20 61 63 74 69 6f the actio
3340: 6e 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72 66 ns of the interf
3350: 61 63 65 20 73 68 61 6c 6c 20 62 65 20 74 68 65 ace shall be the
3360: 20 73 61 6d 65 20 61 73 20 69 66 20 74 68 65 0a same as if the.
3370: 2a 2a 20 20 20 20 20 20 20 20 20 20 53 20 70 61 ** S pa
3380: 72 61 6d 65 74 65 72 20 77 65 72 65 20 61 6e 20 rameter were an
3390: 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a empty string..**
33a0: 0a 2a 2a 20 7b 48 31 32 31 30 34 7d 20 54 68 65 .** {H12104} The
33b0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 return value of
33c0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 [sqlite3_exec()
33d0: 5d 20 73 68 61 6c 6c 20 62 65 20 5b 53 51 4c 49 ] shall be [SQLI
33e0: 54 45 5f 4f 4b 5d 20 69 66 20 61 6c 6c 0a 2a 2a TE_OK] if all.**
33f0: 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 73 74 SQL st
3400: 61 74 65 6d 65 6e 74 73 20 72 75 6e 20 73 75 63 atements run suc
3410: 63 65 73 73 66 75 6c 6c 79 20 61 6e 64 20 74 6f cessfully and to
3420: 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a completion..**.
3430: 2a 2a 20 7b 48 31 32 31 30 35 7d 20 54 68 65 20 ** {H12105} The
3440: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
3450: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
3460: 20 73 68 61 6c 6c 20 62 65 20 61 6e 20 61 70 70 shall be an app
3470: 72 6f 70 72 69 61 74 65 0a 2a 2a 20 20 20 20 20 ropriate.**
3480: 20 20 20 20 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 non-zero [e
3490: 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e rror code] if an
34a0: 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 y SQL statement
34b0: 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 fails..**.** {H1
34c0: 32 31 30 37 7d 20 49 66 20 6f 6e 65 20 6f 72 20 2107} If one or
34d0: 6d 6f 72 65 20 6f 66 20 74 68 65 20 53 51 4c 20 more of the SQL
34e0: 73 74 61 74 65 6d 65 6e 74 73 20 68 61 6e 64 65 statements hande
34f0: 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 d to [sqlite3_ex
3500: 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 ec()].**
3510: 20 20 72 65 74 75 72 6e 20 72 65 73 75 6c 74 73 return results
3520: 20 61 6e 64 20 74 68 65 20 33 72 64 20 70 61 72 and the 3rd par
3530: 61 6d 65 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 ameter is not NU
3540: 4c 4c 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 LL, then.**
3550: 20 20 20 20 20 74 68 65 20 63 61 6c 6c 62 61 63 the callbac
3560: 6b 20 66 75 6e 63 74 69 6f 6e 20 73 70 65 63 69 k function speci
3570: 66 69 65 64 20 62 79 20 74 68 65 20 33 72 64 20 fied by the 3rd
3580: 70 61 72 61 6d 65 74 65 72 20 73 68 61 6c 6c 20 parameter shall
3590: 62 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 be.** i
35a0: 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 nvoked once for
35b0: 65 61 63 68 20 72 6f 77 20 6f 66 20 72 65 73 75 each row of resu
35c0: 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 31 lt..**.** {H1211
35d0: 30 7d 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 0} If the callba
35e0: 63 6b 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e ck returns a non
35f0: 2d 7a 65 72 6f 20 76 61 6c 75 65 20 74 68 65 6e -zero value then
3600: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 [sqlite3_exec()
3610: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 ].** sh
3620: 61 6c 6c 20 61 62 6f 72 74 20 74 68 65 20 53 51 all abort the SQ
3630: 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 74 20 69 L statement it i
3640: 73 20 63 75 72 72 65 6e 74 6c 79 20 65 76 61 6c s currently eval
3650: 75 61 74 69 6e 67 2c 0a 2a 2a 20 20 20 20 20 20 uating,.**
3660: 20 20 20 20 73 6b 69 70 20 61 6c 6c 20 73 75 62 skip all sub
3670: 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 sequent SQL stat
3680: 65 6d 65 6e 74 73 2c 20 61 6e 64 20 72 65 74 75 ements, and retu
3690: 72 6e 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 rn [SQLITE_ABORT
36a0: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 31 33 ]..**.** {H12113
36b0: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 } The [sqlite3_e
36c0: 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 xec()] routine s
36d0: 68 61 6c 6c 20 70 61 73 73 20 69 74 73 20 34 74 hall pass its 4t
36e0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 72 6f h parameter thro
36f0: 75 67 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ugh.**
3700: 61 73 20 74 68 65 20 31 73 74 20 70 61 72 61 6d as the 1st param
3710: 65 74 65 72 20 6f 66 20 74 68 65 20 63 61 6c 6c eter of the call
3720: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 back..**.** {H12
3730: 31 31 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 116} The [sqlite
3740: 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 3_exec()] routin
3750: 65 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 e shall set the
3760: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 2nd parameter of
3770: 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 its.**
3780: 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 callback to be
3790: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f the number of co
37a0: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 63 75 72 lumns in the cur
37b0: 72 65 6e 74 20 72 6f 77 20 6f 66 0a 2a 2a 20 20 rent row of.**
37c0: 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 2e 0a result..
37d0: 2a 2a 0a 2a 2a 20 7b 48 31 32 31 31 39 7d 20 54 **.** {H12119} T
37e0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 he [sqlite3_exec
37f0: 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c ()] routine shal
3800: 6c 20 73 65 74 20 74 68 65 20 33 72 64 20 70 61 l set the 3rd pa
3810: 72 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a 2a rameter of its.*
3820: 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 * callb
3830: 61 63 6b 20 74 6f 20 62 65 20 61 6e 20 61 72 72 ack to be an arr
3840: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 ay of pointers t
3850: 6f 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e o strings holdin
3860: 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 g the.**
3870: 20 20 76 61 6c 75 65 73 20 66 6f 72 20 65 61 63 values for eac
3880: 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 h column in the
3890: 63 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20 73 current result s
38a0: 65 74 20 72 6f 77 20 61 73 0a 2a 2a 20 20 20 20 et row as.**
38b0: 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66 obtained f
38c0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c rom [sqlite3_col
38d0: 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a umn_text()]..**.
38e0: 2a 2a 20 7b 48 31 32 31 32 32 7d 20 54 68 65 20 ** {H12122} The
38f0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
3900: 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 routine shall s
3910: 65 74 20 74 68 65 20 34 74 68 20 70 61 72 61 6d et the 4th param
3920: 65 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 eter of its.**
3930: 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b callback
3940: 20 74 6f 20 62 65 20 61 6e 20 61 72 72 61 79 20 to be an array
3950: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 of pointers to s
3960: 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e 67 20 74 trings holding t
3970: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e he.** n
3980: 61 6d 65 73 20 6f 66 20 72 65 73 75 6c 74 20 63 ames of result c
3990: 6f 6c 75 6d 6e 73 20 61 73 20 6f 62 74 61 69 6e olumns as obtain
39a0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
39b0: 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e _column_name()].
39c0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 32 35 7d 20 .**.** {H12125}
39d0: 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d If the 3rd param
39e0: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 eter to [sqlite3
39f0: 5f 65 78 65 63 28 29 5d 20 69 73 20 4e 55 4c 4c _exec()] is NULL
3a00: 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 then.**
3a10: 20 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 [sqlite3_exec(
3a20: 29 5d 20 73 68 61 6c 6c 20 73 69 6c 65 6e 74 6c )] shall silentl
3a30: 79 20 64 69 73 63 61 72 64 20 71 75 65 72 79 20 y discard query
3a40: 72 65 73 75 6c 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b results..**.** {
3a50: 48 31 32 31 33 31 7d 20 49 66 20 61 6e 20 65 72 H12131} If an er
3a60: 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 ror occurs while
3a70: 20 70 61 72 73 69 6e 67 20 6f 72 20 65 76 61 6c parsing or eval
3a80: 75 61 74 69 6e 67 20 61 6e 79 20 6f 66 20 74 68 uating any of th
3a90: 65 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 e SQL.**
3aa0: 20 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 statements in
3ab0: 74 68 65 20 53 20 70 61 72 61 6d 65 74 65 72 20 the S parameter
3ac0: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 of [sqlite3_exec
3ad0: 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 61 6e 64 (D,S,C,A,E)] and
3ae0: 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 if.**
3af0: 74 68 65 20 45 20 70 61 72 61 6d 65 74 65 72 20 the E parameter
3b00: 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 is not NULL, the
3b10: 6e 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 n [sqlite3_exec(
3b20: 29 5d 20 73 68 61 6c 6c 20 73 74 6f 72 65 0a 2a )] shall store.*
3b30: 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 2a 45 * in *E
3b40: 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 an appropriate
3b50: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 77 72 error message wr
3b60: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 itten into memor
3b70: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 20 20 y obtained.**
3b80: 20 20 20 20 20 20 20 66 72 6f 6d 20 5b 73 71 6c from [sql
3b90: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a ite3_malloc()]..
3ba0: 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 34 7d 20 54 **.** {H12134} T
3bb0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 he [sqlite3_exec
3bc0: 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 72 6f 75 (D,S,C,A,E)] rou
3bd0: 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 74 20 74 tine shall set t
3be0: 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 20 he value of.**
3bf0: 20 20 20 20 20 20 20 20 2a 45 20 74 6f 20 4e 55 *E to NU
3c00: 4c 4c 20 69 66 20 45 20 69 73 20 6e 6f 74 20 4e LL if E is not N
3c10: 55 4c 4c 20 61 6e 64 20 74 68 65 72 65 20 61 72 ULL and there ar
3c20: 65 20 6e 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a 0a e no errors..**.
3c30: 2a 2a 20 7b 48 31 32 31 33 37 7d 20 54 68 65 20 ** {H12137} The
3c40: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c [sqlite3_exec(D,
3c50: 53 2c 43 2c 41 2c 45 29 5d 20 66 75 6e 63 74 69 S,C,A,E)] functi
3c60: 6f 6e 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 on shall set the
3c70: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a [error code].**
3c80: 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 6d 65 and me
3c90: 73 73 61 67 65 20 61 63 63 65 73 73 69 62 6c 65 ssage accessible
3ca0: 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 via [sqlite3_er
3cb0: 72 63 6f 64 65 28 29 5d 2c 20 0a 2a 2a 20 20 20 rcode()], .**
3cc0: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
3cd0: 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 extended_errcode
3ce0: 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ()],.**
3cf0: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
3d00: 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 ()], and [sqlite
3d10: 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 3_errmsg16()]..*
3d20: 2a 0a 2a 2a 20 7b 48 31 32 31 33 38 7d 20 49 66 *.** {H12138} If
3d30: 20 74 68 65 20 53 20 70 61 72 61 6d 65 74 65 72 the S parameter
3d40: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 to [sqlite3_exe
3d50: 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 69 73 c(D,S,C,A,E)] is
3d60: 20 4e 55 4c 4c 20 6f 72 20 61 6e 0a 2a 2a 20 20 NULL or an.**
3d70: 20 20 20 20 20 20 20 20 65 6d 70 74 79 20 73 74 empty st
3d80: 72 69 6e 67 20 6f 72 20 63 6f 6e 74 61 69 6e 73 ring or contains
3d90: 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65 72 20 74 nothing other t
3da0: 68 61 6e 20 77 68 69 74 65 73 70 61 63 65 2c 20 han whitespace,
3db0: 63 6f 6d 6d 65 6e 74 73 2c 0a 2a 2a 20 20 20 20 comments,.**
3dc0: 20 20 20 20 20 20 61 6e 64 2f 6f 72 20 73 65 6d and/or sem
3dd0: 69 63 6f 6c 6f 6e 73 2c 20 74 68 65 6e 20 72 65 icolons, then re
3de0: 73 75 6c 74 73 20 6f 66 20 5b 73 71 6c 69 74 65 sults of [sqlite
3df0: 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 3_errcode()],.**
3e00: 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
3e10: 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 e3_extended_errc
3e20: 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 ode()],.**
3e30: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 [sqlite3_err
3e40: 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c msg()], and [sql
3e50: 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d ite3_errmsg16()]
3e60: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 .** sha
3e70: 6c 6c 20 72 65 73 65 74 20 74 6f 20 69 6e 64 69 ll reset to indi
3e80: 63 61 74 65 20 6e 6f 20 65 72 72 6f 72 73 2e 0a cate no errors..
3e90: 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e **.** ASSUMPTION
3ea0: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31 34 31 S:.**.** {A12141
3eb0: 7d 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 } The first para
3ec0: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 meter to [sqlite
3ed0: 33 5f 65 78 65 63 28 29 5d 20 6d 75 73 74 20 62 3_exec()] must b
3ee0: 65 20 61 6e 20 76 61 6c 69 64 20 61 6e 64 20 6f e an valid and o
3ef0: 70 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 pen.**
3f00: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
3f10: 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 tion]..**.** {A1
3f20: 32 31 34 32 7d 20 54 68 65 20 64 61 74 61 62 61 2142} The databa
3f30: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 se connection mu
3f40: 73 74 20 6e 6f 74 20 62 65 20 63 6c 6f 73 65 64 st not be closed
3f50: 20 77 68 69 6c 65 0a 2a 2a 20 20 20 20 20 20 20 while.**
3f60: 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 [sqlite3_exec
3f70: 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a ()] is running..
3f80: 2a 2a 0a 2a 2a 20 7b 41 31 32 31 34 33 7d 20 54 **.** {A12143} T
3f90: 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 he calling funct
3fa0: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 5b ion should use [
3fb0: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 sqlite3_free()]
3fc0: 74 6f 20 66 72 65 65 0a 2a 2a 20 20 20 20 20 20 to free.**
3fd0: 20 20 20 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 the memory t
3fe0: 68 61 74 20 2a 65 72 72 6d 73 67 20 69 73 20 6c hat *errmsg is l
3ff0: 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 61 74 20 eft pointing at
4000: 6f 6e 63 65 20 74 68 65 20 65 72 72 6f 72 0a 2a once the error.*
4010: 2a 20 20 20 20 20 20 20 20 20 20 6d 65 73 73 61 * messa
4020: 67 65 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 ge is no longer
4030: 6e 65 65 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 needed..**.** {A
4040: 31 32 31 34 35 7d 20 54 68 65 20 53 51 4c 20 73 12145} The SQL s
4050: 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e tatement text in
4060: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
4070: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 er to [sqlite3_e
4080: 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 xec()].**
4090: 20 20 20 6d 75 73 74 20 72 65 6d 61 69 6e 20 75 must remain u
40a0: 6e 63 68 61 6e 67 65 64 20 77 68 69 6c 65 20 5b nchanged while [
40b0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 sqlite3_exec()]
40c0: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 is running..*/.i
40d0: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 nt sqlite3_exec(
40e0: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 . sqlite3*,
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
4110: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 An open databas
4120: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
4130: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 r *sql,
4140: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4150: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 /* SQL to be e
4160: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e valuated */. in
4170: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f t (*callback)(vo
4180: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 id*,int,char**,c
4190: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c har**), /* Call
41a0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f back function */
41b0: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 . void *,
41c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
41e0: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 1st argument to
41f0: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 callback */. c
4200: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 har **errmsg
4210: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4220: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 /* Err
4230: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 or msg written h
4240: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a ere */.);../*.**
4250: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c CAPI3REF: Resul
4260: 74 20 43 6f 64 65 73 20 7b 48 31 30 32 31 30 7d t Codes {H10210}
4270: 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 <S10700>.** KEY
4280: 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b WORDS: SQLITE_OK
4290: 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 {error code} {e
42a0: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b rror codes}.** K
42b0: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 EYWORDS: {result
42c0: 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 code} {result c
42d0: 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 odes}.**.** Many
42e0: 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e SQLite function
42f0: 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 s return an inte
4300: 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 ger result code
4310: 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f from the set sho
4320: 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 wn.** here in or
4330: 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 73 der to indicates
4340: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c success or fail
4350: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 ure..**.** New e
4360: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 rror codes may b
4370: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
4380: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
4390: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 Lite..**.** See
43a0: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f also: [SQLITE_IO
43b0: 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e ERR_READ | exten
43c0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
43d0: 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ].*/.#define SQL
43e0: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 ITE_OK
43f0: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 0 /* Successf
4400: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 ul result */./*
4410: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 beginning-of-err
4420: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 or-codes */.#def
4430: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 ine SQLITE_ERROR
4440: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 1 /* S
4450: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 QL error or miss
4460: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a ing database */.
4470: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
4480: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 NTERNAL 2
4490: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 /* Internal logi
44a0: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 c error in SQLit
44b0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
44c0: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20 ITE_PERM
44d0: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70 3 /* Access p
44e0: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 ermission denied
44f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4500: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20 TE_ABORT
4510: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 4 /* Callback
4520: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 routine requeste
4530: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 d an abort */.#d
4540: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 efine SQLITE_BUS
4550: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a Y 5 /*
4560: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69 The database fi
4570: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a le is locked */.
4580: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
4590: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20 OCKED 6
45a0: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68 /* A table in th
45b0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f e database is lo
45c0: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 cked */.#define
45d0: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 SQLITE_NOMEM
45e0: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 7 /* A mal
45f0: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a loc() failed */.
4600: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
4610: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 EADONLY 8
4620: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72 /* Attempt to wr
4630: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 ite a readonly d
4640: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 atabase */.#defi
4650: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 ne SQLITE_INTERR
4660: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 UPT 9 /* Op
4670: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 eration terminat
4680: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e ed by sqlite3_in
4690: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 terrupt()*/.#def
46a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
46b0: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53 10 /* S
46c0: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b ome kind of disk
46d0: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 I/O error occur
46e0: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 red */.#define S
46f0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20 QLITE_CORRUPT
4700: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61 11 /* The da
4710: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67 tabase disk imag
4720: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a e is malformed *
4730: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4740: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20 _NOTFOUND 12
4750: 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 /* NOT USED. T
4760: 61 62 6c 65 20 6f 72 20 72 65 63 6f 72 64 20 6e able or record n
4770: 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 ot found */.#def
4780: 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 ine SQLITE_FULL
4790: 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 13 /* I
47a0: 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 nsertion failed
47b0: 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65 because database
47c0: 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 is full */.#def
47d0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f ine SQLITE_CANTO
47e0: 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 PEN 14 /* U
47f0: 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 nable to open th
4800: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
4810: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4820: 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 E_PROTOCOL 15
4830: 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 /* NOT USED.
4840: 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 Database lock pr
4850: 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a otocol error */.
4860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 #define SQLITE_E
4870: 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 MPTY 16
4880: 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65 /* Database is e
4890: 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 mpty */.#define
48a0: 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 SQLITE_SCHEMA
48b0: 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 17 /* The d
48c0: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 atabase schema c
48d0: 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e hanged */.#defin
48e0: 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 e SQLITE_TOOBIG
48f0: 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 18 /* Str
4900: 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 ing or BLOB exce
4910: 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a eds size limit *
4920: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4930: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 _CONSTRAINT 19
4940: 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 /* Abort due t
4950: 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f o constraint vio
4960: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e lation */.#defin
4970: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 e SQLITE_MISMATC
4980: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 H 20 /* Dat
4990: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 a type mismatch
49a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
49b0: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 E_MISUSE 21
49c0: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 /* Library us
49d0: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a ed incorrectly *
49e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
49f0: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 _NOLFS 22
4a00: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 /* Uses OS fea
4a10: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 tures not suppor
4a20: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 ted on host */.#
4a30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 define SQLITE_AU
4a40: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f TH 23 /
4a50: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 * Authorization
4a60: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e denied */.#defin
4a70: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 e SQLITE_FORMAT
4a80: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 24 /* Aux
4a90: 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20 iliary database
4aa0: 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a format error */.
4ab0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
4ac0: 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 ANGE 25
4ad0: 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 /* 2nd parameter
4ae0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
4af0: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f out of range */
4b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4b10: 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 NOTADB 26
4b20: 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 /* File opened
4b30: 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 that is not a da
4b40: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 tabase file */.#
4b50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f define SQLITE_RO
4b60: 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f W 100 /
4b70: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 * sqlite3_step()
4b80: 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 has another row
4b90: 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e ready */.#defin
4ba0: 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 e SQLITE_DONE
4bb0: 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 101 /* sql
4bc0: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 ite3_step() has
4bd0: 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 finished executi
4be0: 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d ng */./* end-of-
4bf0: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a error-codes */..
4c00: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
4c10: 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 Extended Result
4c20: 43 6f 64 65 73 20 7b 48 31 30 32 32 30 7d 20 3c Codes {H10220} <
4c30: 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f S10700>.** KEYWO
4c40: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 65 RDS: {extended e
4c50: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 65 rror code} {exte
4c60: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 nded error codes
4c70: 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b }.** KEYWORDS: {
4c80: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
4c90: 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 code} {extended
4ca0: 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a result codes}.**
4cb0: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 .** In its defau
4cc0: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e lt configuration
4cd0: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 , SQLite API rou
4ce0: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 tines return one
4cf0: 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a of 26 integer.*
4d00: 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 * [SQLITE_OK | r
4d10: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 esult codes]. H
4d20: 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e owever, experien
4d30: 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 ce has shown tha
4d40: 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 t many of.** the
4d50: 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 se result codes
4d60: 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 are too coarse-g
4d70: 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f rained. They do
4d80: 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a not provide as.
4d90: 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 ** much informat
4da0: 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 ion about proble
4db0: 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 ms as programmer
4dc0: 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 s might like. I
4dd0: 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a n an effort to.*
4de0: 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 * address this,
4df0: 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f newer versions o
4e00: 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f f SQLite (versio
4e10: 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 n 3.3.8 and late
4e20: 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 r) include.** su
4e30: 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 pport for additi
4e40: 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 onal result code
4e50: 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d s that provide m
4e60: 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 ore detailed inf
4e70: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 ormation.** abou
4e80: 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65 78 t errors. The ex
4e90: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
4ea0: 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 des are enabled
4eb0: 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f or disabled.** o
4ec0: 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73 65 n a per database
4ed0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 connection basi
4ee0: 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b s using the.** [
4ef0: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
4f00: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d _result_codes()]
4f10: 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 API..**.** Some
4f20: 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c of the availabl
4f30: 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c e extended resul
4f40: 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 t codes are list
4f50: 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 ed here..** One
4f60: 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20 6e may expect the n
4f70: 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65 umber of extende
4f80: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77 d result codes w
4f90: 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a ill be expand.**
4fa0: 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 over time. Sof
4fb0: 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73 20 tware that uses
4fc0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
4fd0: 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70 codes should exp
4fe0: 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 ect.** to see ne
4ff0: 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69 w result codes i
5000: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
5010: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a s of SQLite..**.
5020: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b ** The SQLITE_OK
5030: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c result code wil
5040: 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e l never be exten
5050: 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c ded. It will al
5060: 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 ways.** be exact
5070: 6c 79 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 49 ly zero..**.** I
5080: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
5090: 20 7b 48 31 30 32 32 33 7d 20 54 68 65 20 73 79 {H10223} The sy
50a0: 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 66 6f 72 20 mbolic name for
50b0: 61 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 an extended resu
50c0: 6c 74 20 63 6f 64 65 20 73 68 61 6c 6c 20 63 6f lt code shall co
50d0: 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 ntains.**
50e0: 20 20 20 61 20 72 65 6c 61 74 65 64 20 70 72 69 a related pri
50f0: 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65 mary result code
5100: 20 61 73 20 61 20 70 72 65 66 69 78 2e 0a 2a 2a as a prefix..**
5110: 0a 2a 2a 20 7b 48 31 30 32 32 34 7d 20 50 72 69 .** {H10224} Pri
5120: 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65 mary result code
5130: 20 6e 61 6d 65 73 20 73 68 61 6c 6c 20 63 6f 6e names shall con
5140: 74 61 69 6e 20 61 20 73 69 6e 67 6c 65 20 22 5f tain a single "_
5150: 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 0a " character..**.
5160: 2a 2a 20 7b 48 31 30 32 32 35 7d 20 45 78 74 65 ** {H10225} Exte
5170: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
5180: 20 6e 61 6d 65 73 20 73 68 61 6c 6c 20 63 6f 6e names shall con
5190: 74 61 69 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 tain two or more
51a0: 20 22 5f 22 20 63 68 61 72 61 63 74 65 72 73 2e "_" characters.
51b0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 36 7d 20 .**.** {H10226}
51c0: 54 68 65 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 The numeric valu
51d0: 65 20 6f 66 20 61 6e 20 65 78 74 65 6e 64 65 64 e of an extended
51e0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 73 68 61 result code sha
51f0: 6c 6c 20 63 6f 6e 74 61 69 6e 20 74 68 65 0a 2a ll contain the.*
5200: 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 65 72 * numer
5210: 69 63 20 76 61 6c 75 65 20 6f 66 20 69 74 73 20 ic value of its
5220: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 70 72 corresponding pr
5230: 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64 imary result cod
5240: 65 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 e in.**
5250: 20 69 74 73 20 6c 65 61 73 74 20 73 69 67 6e 69 its least signi
5260: 66 69 63 61 6e 74 20 38 20 62 69 74 73 2e 0a 2a ficant 8 bits..*
5270: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
5280: 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 _IOERR_READ
5290: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
52a0: 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 _IOERR | (1<<8))
52b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
52c0: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 IOERR_SHORT_READ
52d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
52e0: 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a IOERR | (2<<8)).
52f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5300: 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 OERR_WRITE
5310: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
5320: 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 OERR | (3<<8)).#
5330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
5340: 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 ERR_FSYNC
5350: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
5360: 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 ERR | (4<<8)).#d
5370: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5380: 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 RR_DIR_FSYNC
5390: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
53a0: 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 RR | (5<<8)).#de
53b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
53c0: 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 R_TRUNCATE
53d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
53e0: 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 R | (6<<8)).#def
53f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5400: 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 _FSTAT
5410: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5420: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 | (7<<8)).#defi
5430: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
5440: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 UNLOCK
5450: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
5460: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (8<<8)).#defin
5470: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 e SQLITE_IOERR_R
5480: 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 DLOCK
5490: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
54a0: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (9<<8)).#define
54b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 SQLITE_IOERR_DE
54c0: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 LETE
54d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
54e0: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (10<<8)).#define
54f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c SQLITE_IOERR_BL
5500: 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 OCKED
5510: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5520: 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (11<<8)).#define
5530: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f SQLITE_IOERR_NO
5540: 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 MEM
5550: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5560: 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (12<<8)).#define
5570: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 SQLITE_IOERR_AC
5580: 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 CESS
5590: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
55a0: 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (13<<8)).#define
55b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 SQLITE_IOERR_CH
55c0: 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 ECKRESERVEDLOCK
55d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
55e0: 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (14<<8)).#define
55f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f SQLITE_IOERR_LO
5600: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 CK
5610: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5620: 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (15<<8)).#define
5630: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c SQLITE_IOERR_CL
5640: 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20 OSE
5650: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5660: 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (16<<8)).#define
5670: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 SQLITE_IOERR_DI
5680: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 R_CLOSE
5690: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
56a0: 28 31 37 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 (17<<8))../*.**
56b0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 CAPI3REF: Flags
56c0: 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 For File Open Op
56d0: 65 72 61 74 69 6f 6e 73 20 7b 48 31 30 32 33 30 erations {H10230
56e0: 7d 20 3c 48 31 31 31 32 30 3e 20 3c 48 31 32 37 } <H11120> <H127
56f0: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 00>.**.** These
5700: 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 bit values are i
5710: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 ntended for use
5720: 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 in the.** 3rd pa
5730: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b rameter to the [
5740: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
5750: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 )] interface and
5760: 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 .** in the 4th p
5770: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
5780: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 xOpen method of
5790: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
57a0: 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a vfs] object..*/.
57b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
57c0: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 PEN_READONLY
57d0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 0x00000001.
57e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
57f0: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 PEN_READWRITE
5800: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 0x00000002.
5810: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
5820: 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 PEN_CREATE
5830: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 0x00000004.
5840: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
5850: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 PEN_DELETEONCLOS
5860: 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a E 0x00000008.
5870: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
5880: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 PEN_EXCLUSIVE
5890: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 0x00000010.
58a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
58b0: 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 PEN_MAIN_DB
58c0: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 0x00000100.
58d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
58e0: 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 PEN_TEMP_DB
58f0: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 0x00000200.
5900: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
5910: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 PEN_TRANSIENT_DB
5920: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 0x00000400.
5930: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
5940: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c PEN_MAIN_JOURNAL
5950: 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 0a 0x00000800.
5960: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
5970: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c PEN_TEMP_JOURNAL
5980: 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 0x00001000.
5990: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
59a0: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 PEN_SUBJOURNAL
59b0: 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0x00002000.
59c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
59d0: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e PEN_MASTER_JOURN
59e0: 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 0a AL 0x00004000.
59f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
5a00: 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 PEN_NOMUTEX
5a10: 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30 0a 0x00008000.
5a20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
5a30: 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 PEN_FULLMUTEX
5a40: 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30 0a 0x00010000.
5a50: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
5a60: 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65 Device Characte
5a70: 72 69 73 74 69 63 73 20 7b 48 31 30 32 34 30 7d ristics {H10240}
5a80: 20 3c 48 31 31 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 <H11120>.**.**
5a90: 54 68 65 20 78 44 65 76 69 63 65 43 61 70 61 62 The xDeviceCapab
5aa0: 69 6c 69 74 69 65 73 20 6d 65 74 68 6f 64 20 6f ilities method o
5ab0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 f the [sqlite3_i
5ac0: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 o_methods].** ob
5ad0: 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 ject returns an
5ae0: 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 integer which is
5af0: 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 a vector of the
5b00: 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 these.** bit va
5b10: 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 lues expressing
5b20: 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 I/O characterist
5b30: 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 ics of the mass
5b40: 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 storage.** devic
5b50: 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 e that holds the
5b60: 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b file that the [
5b70: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
5b80: 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f ds].** refers to
5b90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 ..**.** The SQLI
5ba0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 TE_IOCAP_ATOMIC
5bb0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 property means t
5bc0: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f hat all writes o
5bd0: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 f.** any size ar
5be0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 e atomic. The S
5bf0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
5c00: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 ICnnn values.**
5c10: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 mean that writes
5c20: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 of blocks that
5c30: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e are nnn bytes in
5c40: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 size and.** are
5c50: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 aligned to an a
5c60: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 ddress which is
5c70: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 an integer multi
5c80: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 ple of.** nnn ar
5c90: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 e atomic. The S
5ca0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 QLITE_IOCAP_SAFE
5cb0: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 _APPEND value me
5cc0: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e ans.** that when
5cd0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 data is appende
5ce0: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 d to a file, the
5cf0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 data is appende
5d00: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 d.** first then
5d10: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
5d20: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 file is extended
5d30: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 , never the othe
5d40: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e r.** way around.
5d50: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 The SQLITE_IOC
5d60: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 AP_SEQUENTIAL pr
5d70: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 operty means tha
5d80: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e t.** information
5d90: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 is written to d
5da0: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 isk in the same
5db0: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a order as calls.*
5dc0: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a * to xWrite()..*
5dd0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
5de0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 _IOCAP_ATOMIC
5df0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 0x0000000
5e00: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
5e10: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 _IOCAP_ATOMIC512
5e20: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 0x0000000
5e30: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
5e40: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 _IOCAP_ATOMIC1K
5e50: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 0x0000000
5e60: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
5e70: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 _IOCAP_ATOMIC2K
5e80: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 0x0000000
5e90: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 8.#define SQLITE
5ea0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 _IOCAP_ATOMIC4K
5eb0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 0x0000001
5ec0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
5ed0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 _IOCAP_ATOMIC8K
5ee0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 0x0000002
5ef0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
5f00: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b _IOCAP_ATOMIC16K
5f10: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 0x0000004
5f20: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
5f30: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b _IOCAP_ATOMIC32K
5f40: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 0x0000008
5f50: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
5f60: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b _IOCAP_ATOMIC64K
5f70: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 0x0000010
5f80: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
5f90: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 _IOCAP_SAFE_APPE
5fa0: 4e 44 20 20 20 20 20 30 78 30 30 30 30 30 32 30 ND 0x0000020
5fb0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
5fc0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 _IOCAP_SEQUENTIA
5fd0: 4c 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 L 0x0000040
5fe0: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 0../*.** CAPI3RE
5ff0: 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 F: File Locking
6000: 4c 65 76 65 6c 73 20 7b 48 31 30 32 35 30 7d 20 Levels {H10250}
6010: 3c 48 31 31 31 32 30 3e 20 3c 48 31 31 33 31 30 <H11120> <H11310
6020: 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 >.**.** SQLite u
6030: 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 ses one of these
6040: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 integer values
6050: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a as the second.**
6060: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c argument to cal
6070: 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 ls it makes to t
6080: 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 he xLock() and x
6090: 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 Unlock() methods
60a0: 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 .** of an [sqlit
60b0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f e3_io_methods] o
60c0: 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e bject..*/.#defin
60d0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f e SQLITE_LOCK_NO
60e0: 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 NE 0.#d
60f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 efine SQLITE_LOC
6100: 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20 K_SHARED
6110: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
6120: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 _LOCK_RESERVED
6130: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 2.#define SQ
6140: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e LITE_LOCK_PENDIN
6150: 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e G 3.#defin
6160: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 e SQLITE_LOCK_EX
6170: 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f CLUSIVE 4../
6180: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
6190: 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 ynchronization T
61a0: 79 70 65 20 46 6c 61 67 73 20 7b 48 31 30 32 36 ype Flags {H1026
61b0: 30 7d 20 3c 48 31 31 31 32 30 3e 0a 2a 2a 0a 2a 0} <H11120>.**.*
61c0: 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e * When SQLite in
61d0: 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 vokes the xSync(
61e0: 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a ) method of an.*
61f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 * [sqlite3_io_me
6200: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 thods] object it
6210: 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 uses a combinat
6220: 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 ion of.** these
6230: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 integer values a
6240: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 s the second arg
6250: 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 ument..**.** Whe
6260: 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e n the SQLITE_SYN
6270: 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 C_DATAONLY flag
6280: 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e is used, it mean
6290: 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 s that the.** sy
62a0: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c nc operation onl
62b0: 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 y needs to flush
62c0: 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 data to mass st
62d0: 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a orage. Inode.**
62e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 information nee
62f0: 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 d not be flushed
6300: 2e 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e . The SQLITE_SYN
6310: 43 5f 4e 4f 52 4d 41 4c 20 66 6c 61 67 20 6d 65 C_NORMAL flag me
6320: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 6e 6f ans.** to use no
6330: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d rmal fsync() sem
6340: 61 6e 74 69 63 73 2e 20 54 68 65 20 53 51 4c 49 antics. The SQLI
6350: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 TE_SYNC_FULL fla
6360: 67 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 g means.** to us
6370: 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 e Mac OS X style
6380: 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 fullsync instea
6390: 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f d of fsync()..*/
63a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
63b0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 SYNC_NORMAL
63c0: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 0x00002.#defi
63d0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 ne SQLITE_SYNC_F
63e0: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 ULL 0x0
63f0: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 0003.#define SQL
6400: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c ITE_SYNC_DATAONL
6410: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a Y 0x00010..
6420: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
6430: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 OS Interface Ope
6440: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 20 7b 48 n File Handle {H
6450: 31 31 31 31 30 7d 20 3c 53 32 30 31 31 30 3e 0a 11110} <S20110>.
6460: 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 **.** An [sqlite
6470: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 3_file] object r
6480: 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 epresents an ope
6490: 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 4f 53 n file in the OS
64a0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 6c 61 .** interface la
64b0: 79 65 72 2e 20 20 49 6e 64 69 76 69 64 75 61 6c yer. Individual
64c0: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 69 6d OS interface im
64d0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 plementations wi
64e0: 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 ll.** want to su
64f0: 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 bclass this obje
6500: 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 ct by appending
6510: 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 additional field
6520: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f s.** for their o
6530: 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 wn use. The pMe
6540: 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 thods entry is a
6550: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a pointer to an.*
6560: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 * [sqlite3_io_me
6570: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 thods] object th
6580: 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f at defines metho
6590: 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e ds for performin
65a0: 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 g.** I/O operati
65b0: 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 ons on the open
65c0: 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 file..*/.typedef
65d0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
65e0: 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c file sqlite3_fil
65f0: 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 e;.struct sqlite
6600: 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 3_file {. const
6610: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
6620: 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 io_methods *pMet
6630: 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 hods; /* Method
6640: 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 s for an open fi
6650: 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 le */.};../*.**
6660: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 CAPI3REF: OS Int
6670: 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 erface File Virt
6680: 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 ual Methods Obje
6690: 63 74 20 7b 48 31 31 31 32 30 7d 20 3c 53 32 30 ct {H11120} <S20
66a0: 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 110>.**.** Every
66b0: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 file opened by
66c0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 the [sqlite3_vfs
66d0: 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 ] xOpen method p
66e0: 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b opulates an.** [
66f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 sqlite3_file] ob
6700: 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 ject (or, more c
6710: 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c ommonly, a subcl
6720: 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 ass of the.** [s
6730: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a qlite3_file] obj
6740: 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e ect) with a poin
6750: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e ter to an instan
6760: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 ce of this objec
6770: 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 t..** This objec
6780: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 t defines the me
6790: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 thods used to pe
67a0: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 rform various op
67b0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 erations.** agai
67c0: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c nst the open fil
67d0: 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 e represented by
67e0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 the [sqlite3_fi
67f0: 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a le] object..**.*
6800: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 * The flags argu
6810: 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 ment to xSync ma
6820: 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c y be one of [SQL
6830: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d ITE_SYNC_NORMAL]
6840: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 or.** [SQLITE_S
6850: 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 YNC_FULL]. The
6860: 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 first choice is
6870: 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 the normal fsync
6880: 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e ()..** The secon
6890: 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 d choice is a Ma
68a0: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c c OS X style ful
68b0: 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c lsync. The [SQL
68c0: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c ITE_SYNC_DATAONL
68d0: 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 Y].** flag may b
68e0: 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 e ORed in to ind
68f0: 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 icate that only
6900: 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 the data of the
6910: 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 file.** and not
6920: 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 its inode needs
6930: 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a to be synced..**
6940: 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 .** The integer
6950: 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 values to xLock(
6960: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 ) and xUnlock()
6970: 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 are one of.** <u
6980: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 l>.** <li> [SQLI
6990: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a TE_LOCK_NONE],.*
69a0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c * <li> [SQLITE_L
69b0: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 OCK_SHARED],.**
69c0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 <li> [SQLITE_LOC
69d0: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 K_RESERVED],.**
69e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 <li> [SQLITE_LOC
69f0: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a K_PENDING], or.*
6a00: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c * <li> [SQLITE_L
6a10: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a OCK_EXCLUSIVE]..
6a20: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 ** </ul>.** xLoc
6a30: 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 k() increases th
6a40: 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 e lock. xUnlock(
6a50: 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 ) decreases the
6a60: 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 lock..** The xCh
6a70: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 eckReservedLock(
6a80: 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 ) method checks
6a90: 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 whether any data
6aa0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c base connection,
6ab0: 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 .** either in th
6ac0: 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e is process or in
6ad0: 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 some other proc
6ae0: 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 ess, is holding
6af0: 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 a RESERVED,.** P
6b00: 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 ENDING, or EXCLU
6b10: 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 SIVE lock on the
6b20: 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 file. It retur
6b30: 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 ns true.** if su
6b40: 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 ch a lock exists
6b50: 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 and false other
6b60: 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 wise..**.** The
6b70: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d xFileControl() m
6b80: 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 ethod is a gener
6b90: 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 ic interface tha
6ba0: 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a t allows custom.
6bb0: 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 ** VFS implement
6bc0: 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 ations to direct
6bd0: 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 ly control an op
6be0: 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 en file using th
6bf0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 e.** [sqlite3_fi
6c00: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e le_control()] in
6c10: 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 terface. The se
6c20: 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 cond "op" argume
6c30: 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 nt is an.** inte
6c40: 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 ger opcode. The
6c50: 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 third argument
6c60: 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 is a generic poi
6c70: 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f nter intended to
6c80: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 .** point to a s
6c90: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 tructure that ma
6ca0: 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 y contain argume
6cb0: 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 nts or space in
6cc0: 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 which to.** writ
6cd0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e e return values.
6ce0: 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 Potential uses
6cf0: 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f for xFileContro
6d00: 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 l() might be.**
6d10: 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 functions to ena
6d20: 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 ble blocking loc
6d30: 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 ks with timeouts
6d40: 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a , to change the.
6d50: 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 ** locking strat
6d60: 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 egy (for example
6d70: 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 to use dot-file
6d80: 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 locks), to inqu
6d90: 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 ire.** about the
6da0: 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 status of a loc
6db0: 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 k, or to break s
6dc0: 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 tale locks. The
6dd0: 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 SQLite.** core
6de0: 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 reserves all opc
6df0: 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 odes less than 1
6e00: 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 00 for its own u
6e10: 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 se..** A [SQLITE
6e20: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 _FCNTL_LOCKSTATE
6e30: 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 | list of opcod
6e40: 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 es] less than 10
6e50: 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 0 is available..
6e60: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 ** Applications
6e70: 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 that define a cu
6e80: 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f stom xFileContro
6e90: 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 l method should
6ea0: 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 use opcodes.** g
6eb0: 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 reater than 100
6ec0: 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 to avoid conflic
6ed0: 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 ts..**.** The xS
6ee0: 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 ectorSize() meth
6ef0: 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 od returns the s
6f00: 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 ector size of th
6f10: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 e.** device that
6f20: 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 underlies the f
6f30: 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 ile. The sector
6f40: 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 size is the.**
6f50: 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 minimum write th
6f60: 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 at can be perfor
6f70: 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 med without dist
6f80: 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 urbing.** other
6f90: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c bytes in the fil
6fa0: 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43 e. The xDeviceC
6fb0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29 haracteristics()
6fc0: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 .** method retur
6fd0: 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 ns a bit vector
6fe0: 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 describing behav
6ff0: 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 iors of the.** u
7000: 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 nderlying device
7010: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
7020: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
7030: 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c AP_ATOMIC].** <l
7040: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
7050: 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c _ATOMIC512].** <
7060: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
7070: 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c P_ATOMIC1K].** <
7080: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
7090: 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c P_ATOMIC2K].** <
70a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
70b0: 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c P_ATOMIC4K].** <
70c0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
70d0: 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c P_ATOMIC8K].** <
70e0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
70f0: 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 P_ATOMIC16K].**
7100: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
7110: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a AP_ATOMIC32K].**
7120: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
7130: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a CAP_ATOMIC64K].*
7140: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
7150: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 OCAP_SAFE_APPEND
7160: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
7170: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 E_IOCAP_SEQUENTI
7180: 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a AL].** </ul>.**.
7190: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f ** The SQLITE_IO
71a0: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 CAP_ATOMIC prope
71b0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 rty means that a
71c0: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 ll writes of.**
71d0: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f any size are ato
71e0: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 mic. The SQLITE
71f0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e _IOCAP_ATOMICnnn
7200: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 values.** mean
7210: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 that writes of b
7220: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e locks that are n
7230: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 nn bytes in size
7240: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 and.** are alig
7250: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 ned to an addres
7260: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e s which is an in
7270: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f teger multiple o
7280: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f f.** nnn are ato
7290: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 mic. The SQLITE
72a0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 _IOCAP_SAFE_APPE
72b0: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a ND value means.*
72c0: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 * that when data
72d0: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 is appended to
72e0: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 a file, the data
72f0: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 is appended.**
7300: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 first then the s
7310: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 ize of the file
7320: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 is extended, nev
7330: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 er the other.**
7340: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 way around. The
7350: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 SQLITE_IOCAP_SE
7360: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 QUENTIAL propert
7370: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 y means that.**
7380: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 information is w
7390: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 ritten to disk i
73a0: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 n the same order
73b0: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 as calls.** to
73c0: 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 xWrite()..**.**
73d0: 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75 72 If xRead() retur
73e0: 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ns SQLITE_IOERR_
73f0: 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 SHORT_READ it mu
7400: 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 st also fill.**
7410: 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f in the unread po
7420: 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 rtions of the bu
7430: 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e ffer with zeros.
7440: 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 A VFS that.**
7450: 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 fails to zero-fi
7460: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d ll short reads m
7470: 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 ight seem to wor
7480: 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 k. However,.**
7490: 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d failure to zero-
74a0: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 fill short reads
74b0: 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 will eventually
74c0: 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 lead to.** data
74d0: 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e base corruption.
74e0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
74f0: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 ct sqlite3_io_me
7500: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f thods sqlite3_io
7510: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 _methods;.struct
7520: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 sqlite3_io_meth
7530: 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 ods {. int iVer
7540: 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 sion;. int (*xC
7550: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 lose)(sqlite3_fi
7560: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 le*);. int (*xR
7570: 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ead)(sqlite3_fil
7580: 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 e*, void*, int i
7590: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 Amt, sqlite3_int
75a0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 64 iOfst);. int
75b0: 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 (*xWrite)(sqlit
75c0: 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 e3_file*, const
75d0: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c void*, int iAmt,
75e0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 sqlite3_int64 i
75f0: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 Ofst);. int (*x
7600: 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 Truncate)(sqlite
7610: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 3_file*, sqlite3
7620: 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 _int64 size);.
7630: 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c int (*xSync)(sql
7640: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 ite3_file*, int
7650: 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a flags);. int (*
7660: 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 xFileSize)(sqlit
7670: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 e3_file*, sqlite
7680: 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 3_int64 *pSize);
7690: 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 . int (*xLock)(
76a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
76b0: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e nt);. int (*xUn
76c0: 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 lock)(sqlite3_fi
76d0: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 le*, int);. int
76e0: 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 (*xCheckReserve
76f0: 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 dLock)(sqlite3_f
7700: 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f ile*, int *pResO
7710: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 ut);. int (*xFi
7720: 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 leControl)(sqlit
7730: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 e3_file*, int op
7740: 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 , void *pArg);.
7750: 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 int (*xSectorSi
7760: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ze)(sqlite3_file
7770: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 *);. int (*xDev
7780: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 iceCharacteristi
7790: 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 cs)(sqlite3_file
77a0: 2a 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f *);. /* Additio
77b0: 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 nal methods may
77c0: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 be added in futu
77d0: 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d re releases */.}
77e0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
77f0: 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 F: Standard File
7800: 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 Control Opcodes
7810: 20 7b 48 31 31 33 31 30 7d 20 3c 53 33 30 38 30 {H11310} <S3080
7820: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 0>.**.** These i
7830: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 nteger constants
7840: 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 are opcodes for
7850: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f the xFileContro
7860: 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 l method.** of t
7870: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d he [sqlite3_io_m
7880: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 ethods] object a
7890: 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 nd for the [sqli
78a0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
78b0: 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 ()].** interface
78c0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c ..**.** The [SQL
78d0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 ITE_FCNTL_LOCKST
78e0: 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 ATE] opcode is u
78f0: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e sed for debuggin
7900: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f g. This.** opco
7910: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 de causes the xF
7920: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f ileControl metho
7930: 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 d to write the c
7940: 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a urrent state of.
7950: 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 ** the lock (one
7960: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b of [SQLITE_LOCK
7970: 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f _NONE], [SQLITE_
7980: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a LOCK_SHARED],.**
7990: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 [SQLITE_LOCK_RE
79a0: 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 SERVED], [SQLITE
79b0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 _LOCK_PENDING],
79c0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f or [SQLITE_LOCK_
79d0: 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 EXCLUSIVE]).** i
79e0: 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 nto an integer t
79f0: 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 hat the pArg arg
7a00: 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e ument points to.
7a10: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 This capability
7a20: 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 .** is used duri
7a30: 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f ng testing and o
7a40: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 nly needs to be
7a50: 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 supported when S
7a60: 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 QLITE_TEST.** is
7a70: 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 defined..*/.#de
7a80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
7a90: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 L_LOCKSTATE
7aa0: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 1.#define SQL
7ab0: 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 ITE_GET_LOCKPROX
7ac0: 59 46 49 4c 45 20 20 20 20 20 20 32 0a 23 64 65 YFILE 2.#de
7ad0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f fine SQLITE_SET_
7ae0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 LOCKPROXYFILE
7af0: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 3.#define SQL
7b00: 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 ITE_LAST_ERRNO
7b10: 20 20 20 20 20 20 20 20 20 20 20 34 0a 0a 2f 2a 4../*
7b20: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 .** CAPI3REF: Mu
7b30: 74 65 78 20 48 61 6e 64 6c 65 20 7b 48 31 37 31 tex Handle {H171
7b40: 31 30 7d 20 3c 53 32 30 31 33 30 3e 0a 2a 2a 0a 10} <S20130>.**.
7b50: 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 ** The mutex mod
7b60: 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 ule within SQLit
7b70: 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 e defines [sqlit
7b80: 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 e3_mutex] to be
7b90: 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 an.** abstract t
7ba0: 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 ype for a mutex
7bb0: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c object. The SQL
7bc0: 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c ite core never l
7bd0: 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 ooks.** at the i
7be0: 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e nternal represen
7bf0: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 tation of an [sq
7c00: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 lite3_mutex]. I
7c10: 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 t only.** deals
7c20: 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f with pointers to
7c30: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 the [sqlite3_mu
7c40: 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a tex] object..**.
7c50: 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 ** Mutexes are c
7c60: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 reated using [sq
7c70: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f lite3_mutex_allo
7c80: 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 c()]..*/.typedef
7c90: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
7ca0: 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 mutex sqlite3_mu
7cb0: 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 tex;../*.** CAPI
7cc0: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 3REF: OS Interfa
7cd0: 63 65 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 34 ce Object {H1114
7ce0: 30 7d 20 3c 53 32 30 31 30 30 3e 0a 2a 2a 0a 2a 0} <S20100>.**.*
7cf0: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 * An instance of
7d00: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 the sqlite3_vfs
7d10: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 object defines
7d20: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 the interface be
7d30: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c tween.** the SQL
7d40: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 ite core and the
7d50: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 underlying oper
7d60: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 ating system. T
7d70: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 he "vfs".** in t
7d80: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f he name of the o
7d90: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 bject stands for
7da0: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 "virtual file s
7db0: 79 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 ystem"..**.** Th
7dc0: 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 e value of the i
7dd0: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 Version field is
7de0: 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 initially 1 but
7df0: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 may be larger i
7e00: 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 n.** future vers
7e10: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 ions of SQLite.
7e20: 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c Additional fiel
7e30: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 ds may be append
7e40: 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 ed to this.** ob
7e50: 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 ject when the iV
7e60: 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 ersion value is
7e70: 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 increased. Note
7e80: 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 that the struct
7e90: 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 ure.** of the sq
7ea0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 lite3_vfs object
7eb0: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 changes in the
7ec0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 transaction betw
7ed0: 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 een.** SQLite ve
7ee0: 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 rsion 3.5.9 and
7ef0: 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 3.6.0 and yet th
7f00: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 e iVersion field
7f10: 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 was not.** modi
7f20: 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 fied..**.** The
7f30: 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 szOsFile field i
7f40: 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 s the size of th
7f50: 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 e subclassed [sq
7f60: 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 lite3_file].** s
7f70: 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 tructure used by
7f80: 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 this VFS. mxPa
7f90: 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 thname is the ma
7fa0: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a ximum length of.
7fb0: 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e ** a pathname in
7fc0: 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a this VFS..**.**
7fd0: 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 Registered sqli
7fe0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 te3_vfs objects
7ff0: 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 are kept on a li
8000: 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 nked list formed
8010: 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 by.** the pNext
8020: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b pointer. The [
8030: 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 sqlite3_vfs_regi
8040: 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b ster()].** and [
8050: 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 sqlite3_vfs_unre
8060: 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 gister()] interf
8070: 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 aces manage this
8080: 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 list.** in a th
8090: 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 read-safe way.
80a0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 The [sqlite3_vfs
80b0: 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 _find()] interfa
80c0: 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 ce.** searches t
80d0: 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 he list. Neithe
80e0: 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f r the applicatio
80f0: 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 n code nor the V
8100: 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 FS.** implementa
8110: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 tion should use
8120: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 the pNext pointe
8130: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 r..**.** The pNe
8140: 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 xt field is the
8150: 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 only field in th
8160: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a e sqlite3_vfs.**
8170: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 structure that
8180: 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 SQLite will ever
8190: 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 modify. SQLite
81a0: 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 will only acces
81b0: 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 s.** or modify t
81c0: 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 his field while
81d0: 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 holding a partic
81e0: 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 ular static mute
81f0: 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 x..** The applic
8200: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 ation should nev
8210: 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 er modify anythi
8220: 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 ng within the sq
8230: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a lite3_vfs.** obj
8240: 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a ect once the obj
8250: 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 ect has been reg
8260: 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 istered..**.** T
8270: 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 he zName field h
8280: 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 olds the name of
8290: 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e the VFS module.
82a0: 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a The name must.
82b0: 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 ** be unique acr
82c0: 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 oss all VFS modu
82d0: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 les..**.** SQLit
82e0: 65 20 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65 e will guarantee
82f0: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e that the zFilen
8300: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f ame parameter to
8310: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 xOpen.** is eit
8320: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 her a NULL point
8330: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 er or string obt
8340: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 ained.** from xF
8350: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 2e 20 20 ullPathname().
8360: 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 SQLite further g
8370: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a uarantees that.*
8380: 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c * the string wil
8390: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 l be valid and u
83a0: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 nchanged until x
83b0: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 Close() is.** ca
83c0: 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 lled. Because of
83d0: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 the previous se
83e0: 6e 74 65 6e 73 65 2c 0a 2a 2a 20 74 68 65 20 5b ntense,.** the [
83f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 sqlite3_file] ca
8400: 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 n safely store a
8410: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a pointer to the.
8420: 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 ** filename if i
8430: 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d t needs to remem
8440: 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 ber the filename
8450: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e for some reason
8460: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c ..** If the zFil
8470: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 ename parameter
8480: 69 73 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 is xOpen is a NU
8490: 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 LL pointer then
84a0: 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e xOpen.** must in
84b0: 76 69 74 65 20 69 74 73 20 6f 77 6e 20 74 65 6d vite its own tem
84c0: 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 porary name for
84d0: 74 68 65 20 66 69 6c 65 2e 20 20 57 68 65 6e 65 the file. Whene
84e0: 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c ver the .** xFil
84f0: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 ename parameter
8500: 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 is NULL it will
8510: 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 also be the case
8520: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 that the.** fla
8530: 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c gs parameter wil
8540: 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 l include [SQLIT
8550: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 E_OPEN_DELETEONC
8560: 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 LOSE]..**.** The
8570: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 flags argument
8580: 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 to xOpen() inclu
8590: 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 des all bits set
85a0: 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 in.** the flags
85b0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 argument to [sq
85c0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d lite3_open_v2()]
85d0: 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 . Or if [sqlite
85e0: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 3_open()].** or
85f0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 [sqlite3_open16(
8600: 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e )] is used, then
8610: 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 flags includes
8620: 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c at least.** [SQL
8630: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
8640: 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 TE] | [SQLITE_OP
8650: 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 EN_CREATE]. .**
8660: 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 If xOpen() opens
8670: 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c a file read-onl
8680: 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a y then it sets *
8690: 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 pOutFlags to.**
86a0: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f include [SQLITE_
86b0: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 OPEN_READONLY].
86c0: 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a Other bits in *
86d0: 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 pOutFlags may be
86e0: 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 set..**.** SQLi
86f0: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 te will also add
8700: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c one of the foll
8710: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 owing flags to t
8720: 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 he xOpen().** ca
8730: 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e ll, depending on
8740: 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e the object bein
8750: 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 g opened:.**.**
8760: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 <ul>.** <li> [S
8770: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f QLITE_OPEN_MAIN_
8780: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 DB].** <li> [SQ
8790: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a LITE_OPEN_MAIN_J
87a0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 OURNAL].** <li>
87b0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 [SQLITE_OPEN_TE
87c0: 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 MP_DB].** <li>
87d0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d [SQLITE_OPEN_TEM
87e0: 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c P_JOURNAL].** <l
87f0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
8800: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a _TRANSIENT_DB].*
8810: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
8820: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d OPEN_SUBJOURNAL]
8830: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
8840: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f E_OPEN_MASTER_JO
8850: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a URNAL].** </ul>.
8860: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 **.** The file I
8870: 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f /O implementatio
8880: 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 n can use the ob
8890: 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 ject type flags
88a0: 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 to.** change the
88b0: 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 way it deals wi
88c0: 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 th files. For e
88d0: 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 xample, an appli
88e0: 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 cation.** that d
88f0: 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f oes not care abo
8900: 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 ut crash recover
8910: 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 y or rollback mi
8920: 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 ght make.** the
8930: 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 open of a journa
8940: 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 l file a no-op.
8950: 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 Writes to this
8960: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a journal would.**
8970: 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c also be no-ops,
8980: 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 and any attempt
8990: 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 to read the jou
89a0: 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 rnal would retur
89b0: 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 n.** SQLITE_IOER
89c0: 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 R. Or the imple
89d0: 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 mentation might
89e0: 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 recognize that a
89f0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c database.** fil
8a00: 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 e will be doing
8a10: 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 page-aligned sec
8a20: 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 tor reads and wr
8a30: 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d ites in a random
8a40: 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 .** order and se
8a50: 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 t up its I/O sub
8a60: 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 system according
8a70: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 ly..**.** SQLite
8a80: 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 might also add
8a90: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f one of the follo
8aa0: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 wing flags to th
8ab0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a e xOpen method:.
8ac0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
8ad0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f i> [SQLITE_OPEN_
8ae0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a DELETEONCLOSE].*
8af0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f * <li> [SQLITE_O
8b00: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a PEN_EXCLUSIVE].*
8b10: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 * </ul>.**.** Th
8b20: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 e [SQLITE_OPEN_D
8b30: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c ELETEONCLOSE] fl
8b40: 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c ag means the fil
8b50: 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 e should be.** d
8b60: 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 eleted when it i
8b70: 73 20 63 6c 6f 73 65 64 2e 20 20 54 68 65 20 5b s closed. The [
8b80: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 SQLITE_OPEN_DELE
8b90: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 TEONCLOSE].** wi
8ba0: 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 ll be set for TE
8bb0: 4d 50 20 20 64 61 74 61 62 61 73 65 73 2c 20 6a MP databases, j
8bc0: 6f 75 72 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20 ournals and for
8bd0: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a subjournals..**.
8be0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f ** The [SQLITE_O
8bf0: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 PEN_EXCLUSIVE] f
8c00: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 lag means the fi
8c10: 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 le should be ope
8c20: 6e 65 64 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 ned.** for exclu
8c30: 73 69 76 65 20 61 63 63 65 73 73 2e 20 20 54 68 sive access. Th
8c40: 69 73 20 66 6c 61 67 20 69 73 20 73 65 74 20 66 is flag is set f
8c50: 6f 72 20 61 6c 6c 20 66 69 6c 65 73 20 65 78 63 or all files exc
8c60: 65 70 74 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d ept.** for the m
8c70: 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c ain database fil
8c80: 65 2e 0a 2a 2a 0a 2a 2a 20 41 74 20 6c 65 61 73 e..**.** At leas
8c90: 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 t szOsFile bytes
8ca0: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 of memory are a
8cb0: 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 llocated by SQLi
8cc0: 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 te.** to hold th
8cd0: 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 e [sqlite3_file
8ce0: 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 ] structure pass
8cf0: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a ed as the third.
8d00: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 ** argument to x
8d10: 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e Open. The xOpen
8d20: 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 method does not
8d30: 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f have to.** allo
8d40: 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 cate the structu
8d50: 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 re; it should ju
8d60: 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 0a 2a st fill it in..*
8d70: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 *.** The flags a
8d80: 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 rgument to xAcce
8d90: 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c ss() may be [SQL
8da0: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 ITE_ACCESS_EXIST
8db0: 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f S].** to test fo
8dc0: 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 r the existence
8dd0: 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 of a file, or [S
8de0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
8df0: 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 DWRITE] to.** te
8e00: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c st whether a fil
8e10: 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e e is readable an
8e20: 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b d writable, or [
8e30: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 SQLITE_ACCESS_RE
8e40: 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 AD].** to test w
8e50: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 hether a file is
8e60: 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 at least readab
8e70: 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 le. The file c
8e80: 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 an be a.** direc
8e90: 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 tory..**.** SQLi
8ea0: 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 te will always a
8eb0: 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 llocate at least
8ec0: 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 mxPathname+1 by
8ed0: 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f tes for the.** o
8ee0: 75 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 utput buffer xFu
8ef0: 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 llPathname. The
8f00: 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 exact size of t
8f10: 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 he output buffer
8f20: 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 .** is also pass
8f30: 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 ed as a paramete
8f40: 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f r to both metho
8f50: 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 ds. If the outpu
8f60: 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e t buffer.** is n
8f70: 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c ot large enough,
8f80: 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 [SQLITE_CANTOPE
8f90: 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 N] should be ret
8fa0: 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 urned. Since thi
8fb0: 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 s is.** handled
8fc0: 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 as a fatal error
8fd0: 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 by SQLite, vfs
8fe0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
8ff0: 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a should endeavor.
9000: 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 ** to prevent th
9010: 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 is by setting mx
9020: 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 Pathname to a su
9030: 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 fficiently large
9040: 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 value..**.** Th
9050: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c e xRandomness(),
9060: 20 78 53 6c 65 65 70 28 29 2c 20 61 6e 64 20 78 xSleep(), and x
9070: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 6e CurrentTime() in
9080: 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 terfaces.** are
9090: 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 not strictly a p
90a0: 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 art of the files
90b0: 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 ystem, but they
90c0: 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 are.** included
90d0: 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 in the VFS struc
90e0: 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 ture for complet
90f0: 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 eness..** The xR
9100: 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 andomness() func
9110: 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f tion attempts to
9120: 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 return nBytes b
9130: 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d ytes.** of good-
9140: 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 quality randomne
9150: 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 ss into zOut. T
9160: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
9170: 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c is.** the actual
9180: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
9190: 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f of randomness o
91a0: 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 btained..** The
91b0: 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 xSleep() method
91c0: 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 causes the calli
91d0: 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 ng thread to sle
91e0: 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 ep for at.** lea
91f0: 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 st the number of
9200: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 microseconds gi
9210: 76 65 6e 2e 20 20 54 68 65 20 78 43 75 72 72 65 ven. The xCurre
9220: 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 ntTime().** meth
9230: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c od returns a Jul
9240: 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 ian Day Number f
9250: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 or the current d
9260: 61 74 65 20 61 6e 64 20 74 69 6d 65 2e 0a 2a 2a ate and time..**
9270: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
9280: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 ct sqlite3_vfs s
9290: 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 qlite3_vfs;.stru
92a0: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b ct sqlite3_vfs {
92b0: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b . int iVersion;
92c0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 /* S
92d0: 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e tructure version
92e0: 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 69 6e 74 number */. int
92f0: 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 szOsFile;
9300: 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 /* Size of
9310: 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 subclassed sqli
9320: 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e te3_file */. in
9330: 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 t mxPathname;
9340: 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 /* Maximu
9350: 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 m file pathname
9360: 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 length */. sqli
9370: 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 te3_vfs *pNext;
9380: 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 /* Next reg
9390: 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 istered VFS */.
93a0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
93b0: 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d me; /* Nam
93c0: 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 e of this virtua
93d0: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f l file system */
93e0: 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 . void *pAppDat
93f0: 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 a; /* P
9400: 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 ointer to applic
9410: 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 ation-specific d
9420: 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 ata */. int (*x
9430: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 Open)(sqlite3_vf
9440: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a s*, const char *
9450: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 zName, sqlite3_f
9460: 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 ile*,.
9470: 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 int flags,
9480: 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b int *pOutFlags);
9490: 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 . int (*xDelete
94a0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
94b0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
94c0: 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b e, int syncDir);
94d0: 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 . int (*xAccess
94e0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
94f0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
9500: 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e e, int flags, in
9510: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 t *pResOut);. i
9520: 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 nt (*xFullPathna
9530: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a me)(sqlite3_vfs*
9540: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
9550: 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 ame, int nOut, c
9560: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f har *zOut);. vo
9570: 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 id *(*xDlOpen)(s
9580: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
9590: 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 st char *zFilena
95a0: 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 me);. void (*xD
95b0: 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f lError)(sqlite3_
95c0: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c vfs*, int nByte,
95d0: 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b char *zErrMsg);
95e0: 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 . void (*(*xDlS
95f0: 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ym)(sqlite3_vfs*
9600: 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 ,void*, const ch
9610: 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f ar *zSymbol))(vo
9620: 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 id);. void (*xD
9630: 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f lClose)(sqlite3_
9640: 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 vfs*, void*);.
9650: 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 int (*xRandomnes
9660: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c s)(sqlite3_vfs*,
9670: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 int nByte, char
9680: 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 *zOut);. int (
9690: 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 *xSleep)(sqlite3
96a0: 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f _vfs*, int micro
96b0: 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 seconds);. int
96c0: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 (*xCurrentTime)(
96d0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f sqlite3_vfs*, do
96e0: 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a uble*);. int (*
96f0: 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 xGetLastError)(s
9700: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 qlite3_vfs*, int
9710: 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 20 , char *);. /*
9720: 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 New fields may b
9730: 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 e appended in fi
9740: 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 gure versions.
9750: 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a The iVersion. *
9760: 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 * value will inc
9770: 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 rement whenever
9780: 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f this happens. */
9790: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
97a0: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 REF: Flags for t
97b0: 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d he xAccess VFS m
97c0: 65 74 68 6f 64 20 7b 48 31 31 31 39 30 7d 20 3c ethod {H11190} <
97d0: 48 31 31 31 34 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 H11140>.**.** Th
97e0: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 ese integer cons
97f0: 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 tants can be use
9800: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70 d as the third p
9810: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 arameter to.** t
9820: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f he xAccess metho
9830: 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 d of an [sqlite3
9840: 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 7b 45 _vfs] object. {E
9850: 4e 44 7d 20 20 54 68 65 79 20 64 65 74 65 72 6d ND} They determ
9860: 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 ine.** what kind
9870: 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 of permissions
9880: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 the xAccess meth
9890: 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f od is looking fo
98a0: 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 r..** With SQLIT
98b0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c E_ACCESS_EXISTS,
98c0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 the xAccess met
98d0: 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 hod.** simply ch
98e0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 ecks whether the
98f0: 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a file exists..**
9900: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 With SQLITE_ACC
9910: 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 ESS_READWRITE, t
9920: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f he xAccess metho
9930: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 d.** checks whet
9940: 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 her the file is
9950: 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e both readable an
9960: 64 20 77 72 69 74 61 62 6c 65 2e 0a 2a 2a 20 57 d writable..** W
9970: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 ith SQLITE_ACCES
9980: 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 S_READ, the xAcc
9990: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 ess method.** ch
99a0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 ecks whether the
99b0: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c file is readabl
99c0: 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 e..*/.#define SQ
99d0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 LITE_ACCESS_EXIS
99e0: 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 TS 0.#define
99f0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 SQLITE_ACCESS_RE
9a00: 41 44 57 52 49 54 45 20 31 0a 23 64 65 66 69 6e ADWRITE 1.#defin
9a10: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f e SQLITE_ACCESS_
9a20: 52 45 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a READ 2../*.
9a30: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 ** CAPI3REF: Ini
9a40: 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 tialize The SQLi
9a50: 74 65 20 4c 69 62 72 61 72 79 20 7b 48 31 30 31 te Library {H101
9a60: 33 30 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33 30 30} <S20000><S30
9a70: 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 100>.**.** The s
9a80: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
9a90: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 e() routine init
9aa0: 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 ializes the.** S
9ab0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 QLite library.
9ac0: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 The sqlite3_shut
9ad0: 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a down() routine.*
9ae0: 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e * deallocates an
9af0: 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 y resources that
9b00: 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 were allocated
9b10: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 by sqlite3_initi
9b20: 61 6c 69 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 alize()..**.** A
9b30: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
9b40: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 _initialize() is
9b50: 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 an "effective"
9b60: 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a call if it is.**
9b70: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 the first time
9b80: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
9b90: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 ze() is invoked
9ba0: 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 during the lifet
9bb0: 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 ime of.** the pr
9bc0: 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 ocess, or if it
9bd0: 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d is the first tim
9be0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
9bf0: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 lize() is invoke
9c00: 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 d.** following a
9c10: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
9c20: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 4f 6e _shutdown(). On
9c30: 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 ly an effective
9c40: 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 call.** of sqlit
9c50: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
9c60: 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c does any initial
9c70: 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 ization. All ot
9c80: 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 her calls.** are
9c90: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 harmless no-ops
9ca0: 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 ..**.** Among ot
9cb0: 68 65 72 20 74 68 69 6e 67 73 2c 20 73 71 6c 69 her things, sqli
9cc0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
9cd0: 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a shall invoke.**
9ce0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
9cf0: 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 (). Similarly,
9d00: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
9d10: 28 29 0a 2a 2a 20 73 68 61 6c 6c 20 69 6e 76 6f ().** shall invo
9d20: 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e ke sqlite3_os_en
9d30: 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 d()..**.** The s
9d40: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
9d50: 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 e() routine retu
9d60: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 rns [SQLITE_OK]
9d70: 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 49 on success..** I
9d80: 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f f for some reaso
9d90: 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 n, sqlite3_initi
9da0: 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c alize() is unabl
9db0: 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a e to initialize.
9dc0: 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 ** the library (
9dd0: 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e perhaps it is un
9de0: 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 able to allocate
9df0: 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 a needed resour
9e00: 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 ce such.** as a
9e10: 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e mutex) it return
9e20: 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 s an [error code
9e30: 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 ] other than [SQ
9e40: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 LITE_OK]..**.**
9e50: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 The sqlite3_init
9e60: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 ialize() routine
9e70: 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 is called inter
9e80: 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 nally by many ot
9e90: 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e her.** SQLite in
9ea0: 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 terfaces so that
9eb0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 an application
9ec0: 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 usually does not
9ed0: 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f need to.** invo
9ee0: 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 ke sqlite3_initi
9ef0: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 alize() directly
9f00: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 . For example,
9f10: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
9f20: 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 .** calls sqlite
9f30: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 3_initialize() s
9f40: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 o the SQLite lib
9f50: 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 rary will be aut
9f60: 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e omatically.** in
9f70: 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b itialized when [
9f80: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 sqlite3_open()]
9f90: 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 is called if it
9fa0: 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 has not be initi
9fb0: 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 alized.** alread
9fc0: 79 2e 20 20 48 6f 77 65 76 65 72 2c 20 69 66 20 y. However, if
9fd0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
9fe0: 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c ed with the [SQL
9ff0: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 ITE_OMIT_AUTOINI
a000: 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 T].** compile-ti
a010: 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 me option, then
a020: 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 the automatic ca
a030: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 lls to sqlite3_i
a040: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 nitialize().** a
a050: 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 re omitted and t
a060: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d he application m
a070: 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 ust call sqlite3
a080: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 _initialize() di
a090: 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 rectly.** prior
a0a0: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 to using any oth
a0b0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 er SQLite interf
a0c0: 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 ace. For maximu
a0d0: 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a m portability,.*
a0e0: 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e * it is recommen
a0f0: 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 ded that applica
a100: 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 tions always inv
a110: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 oke sqlite3_init
a120: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 ialize().** dire
a130: 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 ctly prior to us
a140: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 ing any other SQ
a150: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 Lite interface.
a160: 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 Future releases
a170: 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 .** of SQLite ma
a180: 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 y require this.
a190: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c In other words,
a1a0: 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 the behavior ex
a1b0: 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 hibited.** when
a1c0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
a1d0: 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f ed with [SQLITE_
a1e0: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d OMIT_AUTOINIT] m
a1f0: 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a ight become the.
a200: 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 ** default behav
a210: 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 ior in some futu
a220: 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 re release of SQ
a230: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 Lite..**.** The
a240: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
a250: 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f ) routine does o
a260: 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 perating-system
a270: 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 specific.** init
a280: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 ialization of th
a290: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 e SQLite library
a2a0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f . The sqlite3_o
a2b0: 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 s_end().** routi
a2c0: 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 ne undoes the ef
a2d0: 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f fect of sqlite3_
a2e0: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 os_init(). Typi
a2f0: 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 cal tasks.** per
a300: 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 formed by these
a310: 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 routines include
a320: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 allocation or d
a330: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f eallocation.** o
a340: 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 f static resourc
a350: 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 es, initializati
a360: 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 on of global var
a370: 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 iables,.** setti
a380: 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 ng up a default
a390: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f [sqlite3_vfs] mo
a3a0: 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 dule, or setting
a3b0: 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 up.** a default
a3c0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 configuration u
a3d0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f sing [sqlite3_co
a3e0: 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 nfig()]..**.** T
a3f0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 he application s
a400: 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f hould never invo
a410: 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 ke either sqlite
a420: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 3_os_init().** o
a430: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 r sqlite3_os_end
a440: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 () directly. Th
a450: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 e application sh
a460: 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 ould only invoke
a470: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 .** sqlite3_init
a480: 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c ialize() and sql
a490: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e ite3_shutdown().
a4a0: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 The sqlite3_os
a4b0: 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 _init().** inter
a4c0: 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 face is called a
a4d0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 utomatically by
a4e0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
a4f0: 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 ze() and.** sqli
a500: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 te3_os_end() is
a510: 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 called by sqlite
a520: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 3_shutdown(). A
a530: 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d ppropriate.** im
a540: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f plementations fo
a550: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 r sqlite3_os_ini
a560: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f t() and sqlite3_
a570: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 os_end().** are
a580: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 built into SQLit
a590: 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d e when it is com
a5a0: 70 69 6c 65 64 20 66 6f 72 20 75 6e 69 78 2c 20 piled for unix,
a5b0: 77 69 6e 64 6f 77 73 2c 20 6f 72 20 6f 73 2f 32 windows, or os/2
a5c0: 2e 0a 2a 2a 20 57 68 65 6e 20 62 75 69 6c 74 20 ..** When built
a5d0: 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f for other platfo
a5e0: 72 6d 73 20 28 75 73 69 6e 67 20 74 68 65 20 5b rms (using the [
a5f0: 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d SQLITE_OS_OTHER=
a600: 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 1] compile-time.
a610: 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 ** option) the a
a620: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
a630: 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c supply a suitabl
a640: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
a650: 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f for.** sqlite3_
a660: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 os_init() and sq
a670: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 lite3_os_end().
a680: 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d An application-
a690: 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c supplied.** impl
a6a0: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 ementation of sq
a6b0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 lite3_os_init()
a6c0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e or sqlite3_os_en
a6d0: 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 d().** must retu
a6e0: 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f rn [SQLITE_OK] o
a6f0: 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f n success and so
a700: 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 me other [error
a710: 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 code] upon.** fa
a720: 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ilure..*/.int sq
a730: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
a740: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 (void);.int sqli
a750: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 te3_shutdown(voi
a760: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f d);.int sqlite3_
a770: 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 os_init(void);.i
a780: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e nt sqlite3_os_en
a790: 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 d(void);../*.**
a7a0: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 CAPI3REF: Config
a7b0: 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 uring The SQLite
a7c0: 20 4c 69 62 72 61 72 79 20 7b 48 31 34 31 30 30 Library {H14100
a7d0: 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33 30 32 30 } <S20000><S3020
a7e0: 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 0>.** EXPERIMENT
a7f0: 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c AL.**.** The sql
a800: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e ite3_config() in
a810: 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 terface is used
a820: 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 to make global c
a830: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 onfiguration.**
a840: 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 changes to SQLit
a850: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 e in order to tu
a860: 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 ne SQLite to the
a870: 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 specific needs
a880: 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 of.** the applic
a890: 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 ation. The defa
a8a0: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ult configuratio
a8b0: 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 n is recommended
a8c0: 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 for most.** app
a8d0: 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f lications and so
a8e0: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 this routine is
a8f0: 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 usually not nec
a900: 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a essary. It is.*
a910: 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 * provided to su
a920: 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 pport rare appli
a930: 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 cations with unu
a940: 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a sual needs..**.*
a950: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f * The sqlite3_co
a960: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 nfig() interface
a970: 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 is not threadsa
a980: 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 fe. The applica
a990: 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 tion.** must ins
a9a0: 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 ure that no othe
a9b0: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 r SQLite interfa
a9c0: 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 ces are invoked
a9d0: 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 by other.** thre
a9e0: 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 ads while sqlite
a9f0: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 3_config() is ru
aa00: 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d nning. Furtherm
aa10: 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e ore, sqlite3_con
aa20: 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c fig().** may onl
aa30: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 y be invoked pri
aa40: 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e or to library in
aa50: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 itialization usi
aa60: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 ng.** [sqlite3_i
aa70: 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 nitialize()] or
aa80: 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 after shutdown b
aa90: 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 y [sqlite3_shutd
aaa0: 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 4e 6f 74 65 2c own()]..** Note,
aab0: 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 73 however, that s
aac0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
aad0: 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 can be called as
aae0: 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 part of the.**
aaf0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
ab00: 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e f an application
ab10: 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 -defined [sqlite
ab20: 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 3_os_init()]..**
ab30: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 .** The first ar
ab40: 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
ab50: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 3_config() is an
ab60: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c integer.** [SQL
ab70: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c ITE_CONFIG_SINGL
ab80: 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 ETHREAD | config
ab90: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 uration option]
aba0: 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a that determines.
abb0: 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 ** what property
abc0: 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f of SQLite is to
abd0: 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 be configured.
abe0: 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 Subsequent argu
abf0: 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 ments.** vary de
ac00: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b pending on the [
ac10: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 SQLITE_CONFIG_SI
ac20: 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e NGLETHREAD | con
ac30: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
ac40: 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 n].** in the fir
ac50: 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a st argument..**.
ac60: 2a 2a 20 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 ** When a config
ac70: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 uration option i
ac80: 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 s set, sqlite3_c
ac90: 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 onfig() returns
aca0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 [SQLITE_OK]..**
acb0: 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 If the option is
acc0: 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 unknown or SQLi
acd0: 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 te is unable to
ace0: 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a set the option.*
acf0: 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 * then this rout
ad00: 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f ine returns a no
ad10: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f n-zero [error co
ad20: 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 de]..**.** INVAR
ad30: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
ad40: 34 31 30 33 7d 20 41 20 73 75 63 63 65 73 73 66 4103} A successf
ad50: 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 ul invocation of
ad60: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
ad70: 28 29 5d 20 73 68 61 6c 6c 20 72 65 74 75 72 6e ()] shall return
ad80: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 .** [SQ
ad90: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 LITE_OK]..**.**
ada0: 7b 48 31 34 31 30 36 7d 20 54 68 65 20 5b 73 71 {H14106} The [sq
adb0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
adc0: 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 interface shall
add0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d return [SQLITE_M
ade0: 49 53 55 53 45 5d 0a 2a 2a 20 20 20 20 20 20 20 ISUSE].**
adf0: 20 20 20 69 66 20 69 74 20 69 73 20 69 6e 76 6f if it is invo
ae00: 6b 65 64 20 69 6e 20 62 65 74 77 65 65 6e 20 63 ked in between c
ae10: 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
ae20: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 _initialize()] a
ae30: 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b nd.** [
ae40: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
ae50: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 ()]..**.** {H141
ae60: 32 30 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20} A successful
ae70: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
ae80: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 3_config]([SQLIT
ae90: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
aea0: 48 52 45 41 44 5d 29 0a 2a 2a 20 20 20 20 20 20 HREAD]).**
aeb0: 20 20 20 20 73 68 61 6c 6c 20 73 65 74 20 74 68 shall set th
aec0: 65 20 64 65 66 61 75 6c 74 20 5b 74 68 72 65 61 e default [threa
aed0: 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 ding mode] to Si
aee0: 6e 67 6c 65 2d 74 68 72 65 61 64 2e 0a 2a 2a 0a ngle-thread..**.
aef0: 2a 2a 20 7b 48 31 34 31 32 33 7d 20 41 20 73 75 ** {H14123} A su
af00: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f ccessful call to
af10: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
af20: 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ]([SQLITE_CONFIG
af30: 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 29 0a 2a _MULTITHREAD]).*
af40: 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c * shall
af50: 20 73 65 74 20 74 68 65 20 64 65 66 61 75 6c 74 set the default
af60: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
af70: 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 ] to Multi-threa
af80: 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 32 36 d..**.** {H14126
af90: 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 } A successful c
afa0: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
afb0: 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f config]([SQLITE_
afc0: 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 CONFIG_SERIALIZE
afd0: 44 5d 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 D]).**
afe0: 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 64 65 shall set the de
aff0: 66 61 75 6c 74 20 5b 74 68 72 65 61 64 69 6e 67 fault [threading
b000: 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c mode] to Serial
b010: 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 ized..**.** {H14
b020: 31 32 39 7d 20 41 20 73 75 63 63 65 73 73 66 75 129} A successfu
b030: 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 l call to [sqlit
b040: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 e3_config]([SQLI
b050: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d TE_CONFIG_MUTEX]
b060: 2c 58 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ,X).**
b070: 77 68 65 72 65 20 58 20 69 73 20 61 20 70 6f 69 where X is a poi
b080: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 69 74 69 nter to an initi
b090: 61 6c 69 7a 65 64 20 5b 73 71 6c 69 74 65 33 5f alized [sqlite3_
b0a0: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a mutex_methods].*
b0b0: 2a 20 20 20 20 20 20 20 20 20 20 6f 62 6a 65 63 * objec
b0c0: 74 20 73 68 61 6c 6c 20 63 61 75 73 65 20 61 6c t shall cause al
b0d0: 6c 20 73 75 62 73 65 71 75 65 6e 74 20 6d 75 74 l subsequent mut
b0e0: 65 78 20 6f 70 65 72 61 74 69 6f 6e 73 20 70 65 ex operations pe
b0f0: 72 66 6f 72 6d 65 64 0a 2a 2a 20 20 20 20 20 20 rformed.**
b100: 20 20 20 20 62 79 20 53 51 4c 69 74 65 20 74 6f by SQLite to
b110: 20 75 73 65 20 74 68 65 20 6d 75 74 65 78 20 6d use the mutex m
b120: 65 74 68 6f 64 73 20 74 68 61 74 20 77 65 72 65 ethods that were
b130: 20 70 72 65 73 65 6e 74 20 69 6e 20 58 0a 2a 2a present in X.**
b140: 20 20 20 20 20 20 20 20 20 20 64 75 72 69 6e 67 during
b150: 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71 the call to [sq
b160: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e lite3_config()].
b170: 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 33 32 7d 20 .**.** {H14132}
b180: 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c A successful cal
b190: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f l to [sqlite3_co
b1a0: 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f nfig]([SQLITE_CO
b1b0: 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 2c 58 NFIG_GETMUTEX],X
b1c0: 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 ).** wh
b1d0: 65 72 65 20 58 20 69 73 20 61 20 70 6f 69 6e 74 ere X is a point
b1e0: 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 er to an [sqlite
b1f0: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 3_mutex_methods]
b200: 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 20 20 20 20 object .**
b210: 20 20 20 20 20 73 68 61 6c 6c 20 6f 76 65 72 77 shall overw
b220: 72 69 74 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 rite the content
b230: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 of [sqlite3_mut
b240: 65 78 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 ex_methods] obje
b250: 63 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 ct.** w
b260: 69 74 68 20 74 68 65 20 6d 75 74 65 78 20 6d 65 ith the mutex me
b270: 74 68 6f 64 73 20 63 75 72 72 65 6e 74 6c 79 20 thods currently
b280: 69 6e 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 in use by SQLite
b290: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 33 35 7d ..**.** {H14135}
b2a0: 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 A successful ca
b2b0: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ll to [sqlite3_c
b2c0: 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 onfig]([SQLITE_C
b2d0: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2c 4d 29 ONFIG_MALLOC],M)
b2e0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 .** whe
b2f0: 72 65 20 4d 20 69 73 20 61 20 70 6f 69 6e 74 65 re M is a pointe
b300: 72 20 74 6f 20 61 6e 20 69 6e 69 74 69 61 6c 69 r to an initiali
b310: 7a 65 64 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d zed [sqlite3_mem
b320: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 20 20 20 _methods].**
b330: 20 20 20 20 20 20 6f 62 6a 65 63 74 20 73 68 61 object sha
b340: 6c 6c 20 63 61 75 73 65 20 61 6c 6c 20 73 75 62 ll cause all sub
b350: 73 65 71 75 65 6e 74 20 6d 65 6d 6f 72 79 20 61 sequent memory a
b360: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 70 65 72 61 74 llocation operat
b370: 69 6f 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 ions.**
b380: 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 53 51 performed by SQ
b390: 4c 69 74 65 20 74 6f 20 75 73 65 20 74 68 65 20 Lite to use the
b3a0: 6d 65 74 68 6f 64 73 20 74 68 61 74 20 77 65 72 methods that wer
b3b0: 65 20 70 72 65 73 65 6e 74 20 69 6e 20 0a 2a 2a e present in .**
b3c0: 20 20 20 20 20 20 20 20 20 20 4d 20 64 75 72 69 M duri
b3d0: 6e 67 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 5b ng the call to [
b3e0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
b3f0: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 33 38 ]..**.** {H14138
b400: 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 } A successful c
b410: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
b420: 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f config]([SQLITE_
b430: 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 CONFIG_GETMALLOC
b440: 5d 2c 4d 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 ],M).**
b450: 20 77 68 65 72 65 20 4d 20 69 73 20 61 20 70 6f where M is a po
b460: 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c inter to an [sql
b470: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
b480: 5d 20 6f 62 6a 65 63 74 20 73 68 61 6c 6c 0a 2a ] object shall.*
b490: 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65 72 77 * overw
b4a0: 72 69 74 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 rite the content
b4b0: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d of [sqlite3_mem
b4c0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 _methods] object
b4d0: 20 77 69 74 68 20 0a 2a 2a 20 20 20 20 20 20 20 with .**
b4e0: 20 20 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c the memory al
b4f0: 6c 6f 63 61 74 69 6f 6e 20 6d 65 74 68 6f 64 73 location methods
b500: 20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 currently in us
b510: 65 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 e by.**
b520: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b SQLite..**.** {
b530: 48 31 34 31 34 31 7d 20 41 20 73 75 63 63 65 73 H14141} A succes
b540: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 sful call to [sq
b550: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 lite3_config]([S
b560: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d QLITE_CONFIG_MEM
b570: 53 54 41 54 55 53 5d 2c 31 29 0a 2a 2a 20 20 20 STATUS],1).**
b580: 20 20 20 20 20 20 20 73 68 61 6c 6c 20 65 6e 61 shall ena
b590: 62 6c 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 ble the memory a
b5a0: 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 75 73 llocation status
b5b0: 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6c 6f 67 69 collection logi
b5c0: 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 34 34 c..**.** {H14144
b5d0: 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 } A successful c
b5e0: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
b5f0: 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f config]([SQLITE_
b600: 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 CONFIG_MEMSTATUS
b610: 5d 2c 30 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 ],0).**
b620: 20 73 68 61 6c 6c 20 64 69 73 61 62 6c 65 20 74 shall disable t
b630: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
b640: 74 69 6f 6e 20 73 74 61 74 75 73 20 63 6f 6c 6c tion status coll
b650: 65 63 74 69 6f 6e 20 6c 6f 67 69 63 2e 0a 2a 2a ection logic..**
b660: 0a 2a 2a 20 7b 48 31 34 31 34 37 7d 20 54 68 65 .** {H14147} The
b670: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
b680: 6f 6e 20 73 74 61 74 75 73 20 63 6f 6c 6c 65 63 on status collec
b690: 74 69 6f 6e 20 6c 6f 67 69 63 20 73 68 61 6c 6c tion logic shall
b6a0: 20 62 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 be.**
b6b0: 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 enabled by defau
b6c0: 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 35 lt..**.** {H1415
b6d0: 30 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 0} A successful
b6e0: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
b6f0: 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 _config]([SQLITE
b700: 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d _CONFIG_SCRATCH]
b710: 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 20 20 20 ,S,Z,N).**
b720: 20 20 20 20 77 68 65 72 65 20 5a 20 61 6e 64 20 where Z and
b730: 4e 20 61 72 65 20 6e 6f 6e 2d 6e 65 67 61 74 69 N are non-negati
b740: 76 65 20 69 6e 74 65 67 65 72 73 20 61 6e 64 20 ve integers and
b750: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 20 69 .** S i
b760: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
b770: 6e 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 n aligned memory
b780: 20 62 75 66 66 65 72 20 6e 6f 74 20 6c 65 73 73 buffer not less
b790: 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 than.**
b7a0: 20 20 5a 2a 4e 20 62 79 74 65 73 20 69 6e 20 73 Z*N bytes in s
b7b0: 69 7a 65 20 73 68 61 6c 6c 20 63 61 75 73 65 20 ize shall cause
b7c0: 53 20 74 6f 20 62 65 20 75 73 65 64 20 62 79 20 S to be used by
b7d0: 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
b7e0: 5b 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 [scratch memory
b7f0: 61 6c 6c 6f 63 61 74 6f 72 5d 20 66 6f 72 20 61 allocator] for a
b800: 73 20 6d 61 6e 79 20 61 73 20 4e 20 73 69 6d 75 s many as N simu
b810: 6c 61 74 61 6e 65 6f 75 73 0a 2a 2a 20 20 20 20 lataneous.**
b820: 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e allocation
b830: 73 20 65 61 63 68 20 6f 66 20 73 69 7a 65 20 28 s each of size (
b840: 5a 20 26 20 7e 37 29 2e 0a 2a 2a 0a 2a 2a 20 7b Z & ~7)..**.** {
b850: 48 31 34 31 35 33 7d 20 41 20 73 75 63 63 65 73 H14153} A succes
b860: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 sful call to [sq
b870: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 lite3_config]([S
b880: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 QLITE_CONFIG_SCR
b890: 41 54 43 48 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20 ATCH],S,Z,N).**
b8a0: 20 20 20 20 20 20 20 20 20 77 68 65 72 65 20 53 where S
b8b0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
b8c0: 65 72 20 73 68 61 6c 6c 20 64 69 73 61 62 6c 65 er shall disable
b8d0: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
b8e0: 20 5b 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 [scratch memory
b8f0: 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e 0a 2a 2a 0a allocator]..**.
b900: 2a 2a 20 7b 48 31 34 31 35 36 7d 20 41 20 73 75 ** {H14156} A su
b910: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f ccessful call to
b920: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
b930: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 lite3_config]([S
b940: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 QLITE_CONFIG_PAG
b950: 45 43 41 43 48 45 5d 2c 53 2c 5a 2c 4e 29 0a 2a ECACHE],S,Z,N).*
b960: 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 72 65 * where
b970: 20 5a 20 61 6e 64 20 4e 20 61 72 65 20 6e 6f 6e Z and N are non
b980: 2d 6e 65 67 61 74 69 76 65 20 69 6e 74 65 67 65 -negative intege
b990: 72 73 20 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20 rs and .**
b9a0: 20 20 20 20 53 20 69 73 20 61 20 70 6f 69 6e 74 S is a point
b9b0: 65 72 20 74 6f 20 61 6e 20 61 6c 69 67 6e 65 64 er to an aligned
b9c0: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 6e memory buffer n
b9d0: 6f 74 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 ot less than.**
b9e0: 20 20 20 20 20 20 20 20 20 5a 2a 4e 20 62 79 74 Z*N byt
b9f0: 65 73 20 69 6e 20 73 69 7a 65 20 73 68 61 6c 6c es in size shall
ba00: 20 63 61 75 73 65 20 53 20 74 6f 20 62 65 20 75 cause S to be u
ba10: 73 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 sed by the.**
ba20: 20 20 20 20 20 20 20 5b 70 61 67 65 63 61 63 68 [pagecach
ba30: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
ba40: 6f 72 5d 20 66 6f 72 20 61 73 20 6d 61 6e 79 20 or] for as many
ba50: 61 73 20 4e 20 73 69 6d 75 6c 61 74 61 6e 65 6f as N simulataneo
ba60: 75 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 us.** a
ba70: 6c 6c 6f 63 61 74 69 6f 6e 73 20 65 61 63 68 20 llocations each
ba80: 6f 66 20 73 69 7a 65 20 28 5a 20 26 20 7e 37 29 of size (Z & ~7)
ba90: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 35 39 7d ..**.** {H14159}
baa0: 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 A successful ca
bab0: 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 ll to.**
bac0: 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 [sqlite3_confi
bad0: 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 g]([SQLITE_CONFI
bae0: 47 5f 50 41 47 45 43 41 43 48 45 5d 2c 53 2c 5a G_PAGECACHE],S,Z
baf0: 2c 4e 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ,N).**
bb00: 77 68 65 72 65 20 53 20 69 73 20 61 20 4e 55 4c where S is a NUL
bb10: 4c 20 70 6f 69 6e 74 65 72 20 73 68 61 6c 6c 20 L pointer shall
bb20: 64 69 73 61 62 6c 65 20 74 68 65 0a 2a 2a 20 20 disable the.**
bb30: 20 20 20 20 20 20 20 20 5b 70 61 67 65 63 61 63 [pagecac
bb40: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
bb50: 74 6f 72 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 tor]..**.** {H14
bb60: 31 36 32 7d 20 41 20 73 75 63 63 65 73 73 66 75 162} A successfu
bb70: 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 l call to [sqlit
bb80: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 e3_config]([SQLI
bb90: 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 2c TE_CONFIG_HEAP],
bba0: 48 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 20 20 20 20 H,Z,N).**
bbb0: 20 20 20 77 68 65 72 65 20 5a 20 61 6e 64 20 4e where Z and N
bbc0: 20 61 72 65 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 are non-negativ
bbd0: 65 20 69 6e 74 65 67 65 72 73 20 61 6e 64 20 0a e integers and .
bbe0: 2a 2a 20 20 20 20 20 20 20 20 20 20 48 20 69 73 ** H is
bbf0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
bc00: 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 aligned memory
bc10: 62 75 66 66 65 72 20 6e 6f 74 20 6c 65 73 73 20 buffer not less
bc20: 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 than.**
bc30: 20 5a 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 Z bytes in size
bc40: 20 73 68 61 6c 6c 20 65 6e 61 62 6c 65 20 74 68 shall enable th
bc50: 65 20 5b 6d 65 6d 73 79 73 35 5d 20 6d 65 6d 6f e [memsys5] memo
bc60: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 0a 2a 2a 20 ry allocator.**
bc70: 20 20 20 20 20 20 20 20 20 61 6e 64 20 63 61 75 and cau
bc80: 73 65 20 69 74 20 74 6f 20 75 73 65 20 62 75 66 se it to use buf
bc90: 66 65 72 20 53 20 61 73 20 69 74 73 20 6d 65 6d fer S as its mem
bca0: 6f 72 79 20 73 6f 75 72 63 65 20 61 6e 64 20 74 ory source and t
bcb0: 6f 20 75 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 o use.**
bcc0: 20 20 61 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f a minimum allo
bcd0: 63 61 74 69 6f 6e 20 73 69 7a 65 20 6f 66 20 4e cation size of N
bce0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 36 35 7d ..**.** {H14165}
bcf0: 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 A successful ca
bd00: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ll to [sqlite3_c
bd10: 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 onfig]([SQLITE_C
bd20: 4f 4e 46 49 47 5f 48 45 41 50 5d 2c 48 2c 5a 2c ONFIG_HEAP],H,Z,
bd30: 4e 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 N).** w
bd40: 68 65 72 65 20 48 20 69 73 20 61 20 4e 55 4c 4c here H is a NULL
bd50: 20 70 6f 69 6e 74 65 72 20 73 68 61 6c 6c 20 64 pointer shall d
bd60: 69 73 61 62 6c 65 20 74 68 65 0a 2a 2a 20 20 20 isable the.**
bd70: 20 20 20 20 20 20 20 5b 6d 65 6d 73 79 73 35 5d [memsys5]
bd80: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
bd90: 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 36 38 r..**.** {H14168
bda0: 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 } A successful c
bdb0: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
bdc0: 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f config]([SQLITE_
bdd0: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
bde0: 5d 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 20 20 20 20 ],Z,N).**
bdf0: 20 20 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74 shall cause t
be00: 68 65 20 64 65 66 61 75 6c 74 20 5b 6c 6f 6f 6b he default [look
be10: 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c aside memory all
be20: 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 ocator] configur
be30: 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 ation.**
be40: 20 20 66 6f 72 20 6e 65 77 20 5b 64 61 74 61 62 for new [datab
be50: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d ase connections]
be60: 20 74 6f 20 62 65 20 4e 20 73 6c 6f 74 73 20 6f to be N slots o
be70: 66 20 5a 20 62 79 74 65 73 20 65 61 63 68 2e 0a f Z bytes each..
be80: 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 */.SQLITE_EXPERI
be90: 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 MENTAL int sqlit
bea0: 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e e3_config(int, .
beb0: 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ..);../*.** CAPI
bec0: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 3REF: Configure
bed0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
bee0: 69 6f 6e 73 20 20 7b 48 31 34 32 30 30 7d 20 3c ions {H14200} <
bef0: 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 S20000>.** EXPER
bf00: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 IMENTAL.**.** Th
bf10: 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e e sqlite3_db_con
bf20: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 fig() interface
bf30: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 is used to make
bf40: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a configuration.**
bf50: 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 changes to a [d
bf60: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
bf70: 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 on]. The interf
bf80: 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 ace is similar t
bf90: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f o.** [sqlite3_co
bfa0: 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 nfig()] except t
bfb0: 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 hat the changes
bfc0: 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c apply to a singl
bfd0: 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 e.** [database c
bfe0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 onnection] (spec
bff0: 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 ified in the fir
c000: 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 20 20 54 st argument). T
c010: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64 62 he.** sqlite3_db
c020: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 _config() interf
c030: 61 63 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 ace can only be
c040: 75 73 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 used immediately
c050: 20 61 66 74 65 72 0a 2a 2a 20 74 68 65 20 64 61 after.** the da
c060: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
c070: 6e 20 69 73 20 63 72 65 61 74 65 64 20 75 73 69 n is created usi
c080: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ng [sqlite3_open
c090: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
c0a0: 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b _open16()], or [
c0b0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
c0c0: 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 )]. .**.** The
c0d0: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
c0e0: 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f to sqlite3_db_co
c0f0: 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 nfig(D,V,...) i
c100: 73 20 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 s the.** configu
c110: 72 61 74 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e ration verb - an
c120: 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 integer code th
c130: 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 at indicates wha
c140: 74 0a 2a 2a 20 61 73 70 65 63 74 20 6f 66 20 74 t.** aspect of t
c150: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
c160: 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e nection] is bein
c170: 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a g configured..**
c180: 20 54 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65 The only choice
c190: 20 66 6f 72 20 74 68 69 73 20 76 61 6c 75 65 20 for this value
c1a0: 69 73 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e is [SQLITE_DBCON
c1b0: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a FIG_LOOKASIDE]..
c1c0: 2a 2a 20 4e 65 77 20 76 65 72 62 73 20 61 72 65 ** New verbs are
c1d0: 20 6c 69 6b 65 6c 79 20 74 6f 20 62 65 20 61 64 likely to be ad
c1e0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
c1f0: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
c200: 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 ..** Additional
c210: 61 72 67 75 6d 65 6e 74 73 20 64 65 70 65 6e 64 arguments depend
c220: 20 6f 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a 2a on the verb..**
c230: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
c240: 2a 2a 0a 2a 2a 20 7b 48 31 34 32 30 33 7d 20 41 **.** {H14203} A
c250: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
c260: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 3_db_config(D,V,
c270: 2e 2e 2e 29 5d 20 73 68 61 6c 6c 20 72 65 74 75 ...)] shall retu
c280: 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 0a 2a rn [SQLITE_OK].*
c290: 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 61 6e * if an
c2a0: 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 63 61 d only if the ca
c2b0: 6c 6c 20 69 73 20 73 75 63 63 65 73 73 66 75 6c ll is successful
c2c0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 32 30 36 7d ..**.** {H14206}
c2d0: 20 49 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 If one or more
c2e0: 73 6c 6f 74 73 20 6f 66 20 74 68 65 20 5b 6c 6f slots of the [lo
c2f0: 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 okaside memory a
c300: 6c 6c 6f 63 61 74 6f 72 5d 20 66 6f 72 0a 2a 2a llocator] for.**
c310: 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 [datab
c320: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
c330: 44 20 61 72 65 20 69 6e 20 75 73 65 2c 20 74 68 D are in use, th
c340: 65 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 en a call to.**
c350: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
c360: 33 5f 64 62 5f 63 6f 6e 66 69 67 5d 28 44 2c 5b 3_db_config](D,[
c370: 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
c380: 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 LOOKASIDE],...)
c390: 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 shall.**
c3a0: 20 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 5b fail with an [
c3b0: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 72 65 74 SQLITE_BUSY] ret
c3c0: 75 72 6e 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 urn code..**.**
c3d0: 7b 48 31 34 32 30 39 7d 20 41 20 73 75 63 63 65 {H14209} A succe
c3e0: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a ssful call to .*
c3f0: 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
c400: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 5d 28 44 te3_db_config](D
c410: 2c 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 ,[SQLITE_DBCONFI
c420: 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 42 2c 5a G_LOOKASIDE],B,Z
c430: 2c 4e 29 20 77 68 65 72 65 0a 2a 2a 20 20 20 20 ,N) where.**
c440: 20 20 20 20 20 20 44 20 69 73 20 61 6e 20 6f 70 D is an op
c450: 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e en [database con
c460: 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5a 20 61 nection] and Z a
c470: 6e 64 20 4e 20 61 72 65 20 70 6f 73 69 74 69 76 nd N are positiv
c480: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e e.** in
c490: 74 65 67 65 72 73 20 61 6e 64 20 42 20 69 73 20 tegers and B is
c4a0: 61 6e 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 an aligned buffe
c4b0: 72 20 61 74 20 6c 65 61 73 74 20 5a 2a 4e 20 62 r at least Z*N b
c4c0: 79 74 65 73 20 69 6e 20 73 69 7a 65 0a 2a 2a 20 ytes in size.**
c4d0: 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 63 shall c
c4e0: 61 75 73 65 20 74 68 65 20 5b 6c 6f 6f 6b 61 73 ause the [lookas
c4f0: 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ide memory alloc
c500: 61 74 6f 72 5d 20 66 6f 72 20 44 20 74 6f 20 75 ator] for D to u
c510: 73 65 20 62 75 66 66 65 72 20 42 20 0a 2a 2a 20 se buffer B .**
c520: 20 20 20 20 20 20 20 20 20 77 69 74 68 20 4e 20 with N
c530: 73 6c 6f 74 73 20 6f 66 20 5a 20 62 79 74 65 73 slots of Z bytes
c540: 20 65 61 63 68 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 each..**.** {H1
c550: 34 32 31 32 7d 20 41 20 73 75 63 63 65 73 73 66 4212} A successf
c560: 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 20 ul call to .**
c570: 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
c580: 5f 64 62 5f 63 6f 6e 66 69 67 5d 28 44 2c 5b 53 _db_config](D,[S
c590: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c QLITE_DBCONFIG_L
c5a0: 4f 4f 4b 41 53 49 44 45 5d 2c 42 2c 5a 2c 4e 29 OOKASIDE],B,Z,N)
c5b0: 20 77 68 65 72 65 0a 2a 2a 20 20 20 20 20 20 20 where.**
c5c0: 20 20 20 44 20 69 73 20 61 6e 20 6f 70 65 6e 20 D is an open
c5d0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
c5e0: 74 69 6f 6e 5d 20 61 6e 64 20 5a 20 61 6e 64 20 tion] and Z and
c5f0: 4e 20 61 72 65 20 70 6f 73 69 74 69 76 65 0a 2a N are positive.*
c600: 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 67 * integ
c610: 65 72 73 20 61 6e 64 20 42 20 69 73 20 4e 55 4c ers and B is NUL
c620: 4c 20 70 6f 69 6e 74 65 72 20 73 68 61 6c 6c 20 L pointer shall
c630: 63 61 75 73 65 20 74 68 65 0a 2a 2a 20 20 20 20 cause the.**
c640: 20 20 20 20 20 20 5b 6c 6f 6f 6b 61 73 69 64 65 [lookaside
c650: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
c660: 72 5d 20 66 6f 72 20 44 20 74 6f 20 61 20 6f 62 r] for D to a ob
c670: 74 61 69 6e 20 5a 2a 4e 20 62 79 74 65 20 62 75 tain Z*N byte bu
c680: 66 66 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 ffer.**
c690: 20 66 72 6f 6d 20 74 68 65 20 70 72 69 6d 61 72 from the primar
c6a0: 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 y memory allocat
c6b0: 6f 72 20 61 6e 64 20 75 73 65 20 74 68 61 74 20 or and use that
c6c0: 62 75 66 66 65 72 0a 2a 2a 20 20 20 20 20 20 20 buffer.**
c6d0: 20 20 20 77 69 74 68 20 4e 20 6c 6f 6f 6b 61 73 with N lookas
c6e0: 69 64 65 20 73 6c 6f 74 73 20 6f 66 20 5a 20 62 ide slots of Z b
c6f0: 79 74 65 73 20 65 61 63 68 2e 0a 2a 2a 0a 2a 2a ytes each..**.**
c700: 20 7b 48 31 34 32 31 35 7d 20 41 20 73 75 63 63 {H14215} A succ
c710: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 0a essful call to .
c720: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
c730: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 5d 28 ite3_db_config](
c740: 44 2c 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 D,[SQLITE_DBCONF
c750: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 42 2c IG_LOOKASIDE],B,
c760: 5a 2c 4e 29 20 77 68 65 72 65 0a 2a 2a 20 20 20 Z,N) where.**
c770: 20 20 20 20 20 20 20 44 20 69 73 20 61 6e 20 6f D is an o
c780: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f pen [database co
c790: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5a 20 nnection] and Z
c7a0: 61 6e 64 20 4e 20 61 72 65 20 7a 65 72 6f 20 73 and N are zero s
c7b0: 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 hall.**
c7c0: 20 64 69 73 61 62 6c 65 20 74 68 65 20 5b 6c 6f disable the [lo
c7d0: 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 okaside memory a
c7e0: 6c 6c 6f 63 61 74 6f 72 5d 20 66 6f 72 20 44 2e llocator] for D.
c7f0: 0a 2a 2a 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 .**.**.*/.SQLITE
c800: 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e _EXPERIMENTAL in
c810: 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e t sqlite3_db_con
c820: 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e fig(sqlite3*, in
c830: 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a t op, ...);../*.
c840: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d ** CAPI3REF: Mem
c850: 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 ory Allocation R
c860: 6f 75 74 69 6e 65 73 20 7b 48 31 30 31 35 35 7d outines {H10155}
c870: 20 3c 53 32 30 31 32 30 3e 0a 2a 2a 20 45 58 50 <S20120>.** EXP
c880: 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
c890: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 An instance of t
c8a0: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e his object defin
c8b0: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 es the interface
c8c0: 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a between SQLite.
c8d0: 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c ** and low-level
c8e0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
c8f0: 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a on routines..**.
c900: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 ** This object i
c910: 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f s used in only o
c920: 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 ne place in the
c930: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
c940: 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 ..** A pointer t
c950: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 o an instance of
c960: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 this object is
c970: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a the argument to.
c980: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ** [sqlite3_conf
c990: 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 ig()] when the c
c9a0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
c9b0: 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 ion is.** [SQLIT
c9c0: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d E_CONFIG_MALLOC]
c9d0: 2e 20 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 . By creating a
c9e0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
c9f0: 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 is object.** and
ca00: 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b passing it to [
ca10: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
ca20: 5d 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 ] during configu
ca30: 72 61 74 69 6f 6e 2c 20 61 6e 0a 2a 2a 20 61 70 ration, an.** ap
ca40: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 plication can sp
ca50: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 ecify an alterna
ca60: 74 69 76 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f tive memory allo
ca70: 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d cation subsystem
ca80: 0a 2a 2a 20 66 6f 72 20 53 51 4c 69 74 65 20 74 .** for SQLite t
ca90: 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 o use for all of
caa0: 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d its dynamic mem
cab0: 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a ory needs..**.**
cac0: 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 Note that SQLit
cad0: 65 20 63 6f 6d 65 73 20 77 69 74 68 20 61 20 62 e comes with a b
cae0: 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 uilt-in memory a
caf0: 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 69 73 llocator that is
cb00: 0a 2a 2a 20 70 65 72 66 65 63 74 6c 79 20 61 64 .** perfectly ad
cb10: 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f equate for the o
cb20: 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f verwhelming majo
cb30: 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 rity of applicat
cb40: 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 ions.** and that
cb50: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 this object is
cb60: 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 only useful to a
cb70: 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f tiny minority o
cb80: 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a f applications.*
cb90: 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a * with specializ
cba0: 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ed memory alloca
cbb0: 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 tion requirement
cbc0: 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 s. This object
cbd0: 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 is.** also used
cbe0: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f during testing o
cbf0: 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 f SQLite in orde
cc00: 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 r to specify an
cc10: 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d alternative.** m
cc20: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 emory allocator
cc30: 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d that simulates m
cc40: 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d emory out-of-mem
cc50: 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 ory conditions i
cc60: 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 n.** order to ve
cc70: 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 rify that SQLite
cc80: 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 recovers gracef
cc90: 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a ully from such.*
cca0: 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a * conditions..**
ccb0: 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c .** The xMalloc,
ccc0: 20 78 46 72 65 65 2c 20 61 6e 64 20 78 52 65 61 xFree, and xRea
ccd0: 6c 6c 6f 63 20 6d 65 74 68 6f 64 73 20 6d 75 73 lloc methods mus
cce0: 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a t work like the.
ccf0: 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 66 72 65 ** malloc(), fre
cd00: 65 28 29 2c 20 61 6e 64 20 72 65 61 6c 6c 6f 63 e(), and realloc
cd10: 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f () functions fro
cd20: 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 6c m the standard l
cd30: 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 78 53 ibrary..**.** xS
cd40: 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 ize should retur
cd50: 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 n the allocated
cd60: 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 size of a memory
cd70: 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 allocation.** p
cd80: 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e reviously obtain
cd90: 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 ed from xMalloc
cda0: 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 or xRealloc. Th
cdb0: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 e allocated size
cdc0: 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 .** is always at
cdd0: 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73 least as big as
cde0: 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73 the requested s
cdf0: 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c ize but may be l
ce00: 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 arger..**.** The
ce10: 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 xRoundup method
ce20: 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f returns what wo
ce30: 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 uld be the alloc
ce40: 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 ated size of.**
ce50: 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 a memory allocat
ce60: 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 ion given a part
ce70: 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 icular requested
ce80: 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d size. Most mem
ce90: 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 ory.** allocator
cea0: 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 s round up memor
ceb0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 y allocations at
cec0: 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 least to the ne
ced0: 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f xt multiple.** o
cee0: 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 f 8. Some alloc
cef0: 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 ators round up t
cf00: 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 o a larger multi
cf10: 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 ple or to a powe
cf20: 72 20 6f 66 20 32 2e 0a 2a 2a 0a 2a 2a 20 54 68 r of 2..**.** Th
cf30: 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 e xInit method i
cf40: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d nitializes the m
cf50: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e emory allocator.
cf60: 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a (For example,.
cf70: 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f ** it might allo
cf80: 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 cate any require
cf90: 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 mutexes or init
cfa0: 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 ialize internal
cfb0: 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 data.** structur
cfc0: 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f es. The xShutdo
cfd0: 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 wn method is inv
cfe0: 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 oked (indirectly
cff0: 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ) by.** [sqlite3
d000: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 _shutdown()] and
d010: 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 should dealloca
d020: 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 te any resources
d030: 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 acquired.** by
d040: 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 xInit. The pApp
d050: 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 Data pointer is
d060: 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 used as the only
d070: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
d080: 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 xInit and xShut
d090: 64 6f 77 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 down..*/.typedef
d0a0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
d0b0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 mem_methods sqli
d0c0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b te3_mem_methods;
d0d0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
d0e0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 mem_methods {.
d0f0: 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 void *(*xMalloc)
d100: 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f (int); /
d110: 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * Memory allocat
d120: 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a ion function */.
d130: 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 void (*xFree)(
d140: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 void*);
d150: 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 /* Free a prior
d160: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 allocation */.
d170: 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f void *(*xReallo
d180: 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 c)(void*,int);
d190: 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c /* Resize an all
d1a0: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 ocation */. int
d1b0: 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 (*xSize)(void*)
d1c0: 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 ; /* R
d1d0: 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f eturn the size o
d1e0: 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 f an allocation
d1f0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e */. int (*xRoun
d200: 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 dup)(int);
d210: 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 /* Round up
d220: 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 request size to
d230: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 allocation size
d240: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 */. int (*xInit
d250: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 )(void*);
d260: 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a /* Initializ
d270: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c e the memory all
d280: 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 ocator */. void
d290: 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f (*xShutdown)(vo
d2a0: 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 id*); /* De
d2b0: 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d initialize the m
d2c0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 emory allocator
d2d0: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 */. void *pAppD
d2e0: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 ata;
d2f0: 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 /* Argument
d300: 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 to xInit() and x
d310: 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b Shutdown() */.};
d320: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
d330: 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 : Configuration
d340: 4f 70 74 69 6f 6e 73 20 7b 48 31 30 31 36 30 7d Options {H10160}
d350: 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 <S20000>.** EXP
d360: 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
d370: 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 These constants
d380: 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c are the availabl
d390: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 e integer config
d3a0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 uration options
d3b0: 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 that.** can be p
d3c0: 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 assed as the fir
d3d0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 st argument to t
d3e0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 he [sqlite3_conf
d3f0: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e ig()] interface.
d400: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 .**.** New confi
d410: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 guration options
d420: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e may be added in
d430: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
d440: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 of SQLite..** E
d450: 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 xisting configur
d460: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 ation options mi
d470: 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e ght be discontin
d480: 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f ued. Applicatio
d490: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 ns.** should che
d4a0: 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f ck the return co
d4b0: 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 de from [sqlite3
d4c0: 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 _config()] to ma
d4d0: 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 ke sure that.**
d4e0: 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e the call worked.
d4f0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 The [sqlite3_c
d500: 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 onfig()] interfa
d510: 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 ce will return a
d520: 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 .** non-zero [er
d530: 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 ror code] if a d
d540: 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 iscontinued or u
d550: 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 nsupported confi
d560: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a guration option.
d570: 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a ** is invoked..*
d580: 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 *.** <dl>.** <dt
d590: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 >SQLITE_CONFIG_S
d5a0: 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e INGLETHREAD</dt>
d5b0: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 .** <dd>There ar
d5c0: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 e no arguments t
d5d0: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 o this option.
d5e0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 This option disa
d5f0: 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 bles.** all mute
d600: 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 xing and puts SQ
d610: 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 Lite into a mode
d620: 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e where it can on
d630: 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 ly be used.** by
d640: 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 a single thread
d650: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
d660: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d >SQLITE_CONFIG_M
d670: 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a ULTITHREAD</dt>.
d680: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 ** <dd>There are
d690: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f no arguments to
d6a0: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 this option. T
d6b0: 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 his option disab
d6c0: 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 les.** mutexing
d6d0: 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e on [database con
d6e0: 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 nection] and [pr
d6f0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
d700: 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 ] objects..** Th
d710: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 e application is
d720: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 responsible for
d730: 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 serializing acc
d740: 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 ess to.** [datab
d750: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d ase connections]
d760: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 and [prepared s
d770: 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 tatements]. But
d780: 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a other mutexes.*
d790: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f * are enabled so
d7a0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c that SQLite wil
d7b0: 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 l be safe to use
d7c0: 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 in a multi-thre
d7d0: 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d aded.** environm
d7e0: 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e ent as long as n
d7f0: 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 o two threads at
d800: 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 tempt to use the
d810: 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 same.** [databa
d820: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 se connection] a
d830: 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e t the same time.
d840: 20 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 See the [threa
d850: 64 69 6e 67 20 6d 6f 64 65 5d 0a 2a 2a 20 64 6f ding mode].** do
d860: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 cumentation for
d870: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 additional infor
d880: 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a mation.</dd>.**.
d890: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
d8a0: 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c NFIG_SERIALIZED<
d8b0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 /dt>.** <dd>Ther
d8c0: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e e are no argumen
d8d0: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f ts to this optio
d8e0: 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 n. This option
d8f0: 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d enables.** all m
d900: 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 utexes including
d910: 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a the recursive.*
d920: 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 * mutexes on [da
d930: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
d940: 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 n] and [prepared
d950: 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 statement] obje
d960: 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 cts..** In this
d970: 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74 mode (which is t
d980: 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 he default when
d990: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
d9a0: 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 ed with.** [SQLI
d9b0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d TE_THREADSAFE=1]
d9c0: 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 ) the SQLite lib
d9d0: 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 rary will itself
d9e0: 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 serialize acces
d9f0: 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 s.** to [databas
da00: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 e connections] a
da10: 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 nd [prepared sta
da20: 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 tements] so that
da30: 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 the.** applicat
da40: 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 ion is free to u
da50: 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 se the same [dat
da60: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
da70: 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 ] or the.** same
da80: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
da90: 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 ment] in differe
daa0: 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68 nt threads at th
dab0: 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 e same time..**
dac0: 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 See the [threadi
dad0: 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e ng mode] documen
dae0: 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 tation for addit
daf0: 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f ional informatio
db00: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 n.</dd>.**.** <d
db10: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
db20: 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c MALLOC</dt>.** <
db30: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 dd>This option t
db40: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
db50: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 gument which is
db60: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a a pointer to an.
db70: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 ** instance of t
db80: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f he [sqlite3_mem_
db90: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
dba0: 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e re. The argumen
dbb0: 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 t specifies.** a
dbc0: 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c lternative low-l
dbd0: 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f evel memory allo
dbe0: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 cation routines
dbf0: 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c to be used in pl
dc00: 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 ace of.** the me
dc10: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
dc20: 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 routines built i
dc30: 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e nto SQLite.</dd>
dc40: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
dc50: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c E_CONFIG_GETMALL
dc60: 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 OC</dt>.** <dd>T
dc70: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
dc80: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
dc90: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f nt which is a po
dca0: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 inter to an.** i
dcb0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b nstance of the [
dcc0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
dcd0: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 ods] structure.
dce0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 The [sqlite3_me
dcf0: 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 m_methods].** st
dd00: 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 ructure is fille
dd10: 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 d with the curre
dd20: 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d ntly defined mem
dd30: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
dd40: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 outines..** This
dd50: 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 option can be u
dd60: 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 sed to overload
dd70: 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f the default memo
dd80: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a ry allocation.**
dd90: 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 routines with a
dda0: 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 wrapper that si
ddb0: 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 mulations memory
ddc0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c allocation fail
ddd0: 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 ure or.** tracks
dde0: 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 memory usage, f
ddf0: 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e or example.</dd>
de00: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
de10: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
de20: 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 US</dt>.** <dd>T
de30: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
de40: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
de50: 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e of type int, in
de60: 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a terpreted as a .
de70: 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 ** boolean, whic
de80: 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 h enables or dis
de90: 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 ables the collec
dea0: 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 tion of memory a
deb0: 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 llocation .** st
dec0: 61 74 69 73 74 69 63 73 2e 20 57 68 65 6e 20 64 atistics. When d
ded0: 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c isabled, the fol
dee0: 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e lowing SQLite in
def0: 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 terfaces become
df00: 0a 2a 2a 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f .** non-operatio
df10: 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a nal:.** <ul>.*
df20: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 * <li> [sqlite
df30: 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 3_memory_used()]
df40: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 .** <li> [sqli
df50: 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 te3_memory_highw
df60: 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 ater()].** <li
df70: 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f > [sqlite3_soft_
df80: 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a heap_limit()].**
df90: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 <li> [sqlite3
dfa0: 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 _status()].**
dfb0: 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a </ul>.** </dd>.*
dfc0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
dfd0: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f CONFIG_SCRATCH</
dfe0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
dff0: 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 option specifies
e000: 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 a static memory
e010: 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c buffer that SQL
e020: 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a ite can use for.
e030: 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 ** scratch memor
e040: 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 y. There are th
e050: 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 ree arguments:
e060: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 A pointer to the
e070: 20 6d 65 6d 6f 72 79 2c 20 74 68 65 0a 2a 2a 20 memory, the.**
e080: 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 size of each scr
e090: 61 74 63 68 20 62 75 66 66 65 72 20 28 73 7a 29 atch buffer (sz)
e0a0: 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 , and the number
e0b0: 20 6f 66 20 62 75 66 66 65 72 73 20 28 4e 29 2e of buffers (N).
e0c0: 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 The sz.** argu
e0d0: 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d ment must be a m
e0e0: 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 20 54 ultiple of 16. T
e0f0: 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 he sz parameter
e100: 73 68 6f 75 6c 64 20 62 65 20 61 20 66 65 77 20 should be a few
e110: 62 79 74 65 73 0a 2a 2a 20 6c 61 72 67 65 72 20 bytes.** larger
e120: 74 68 61 6e 20 74 68 65 20 61 63 74 75 61 6c 20 than the actual
e130: 73 63 72 61 74 63 68 20 73 70 61 63 65 20 72 65 scratch space re
e140: 71 75 69 72 65 64 20 64 75 65 20 69 6e 74 65 72 quired due inter
e150: 6e 61 6c 20 6f 76 65 72 68 65 61 64 2e 0a 2a 2a nal overhead..**
e160: 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 The first.** ar
e170: 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f gument should po
e180: 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 int to an alloca
e190: 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 tion of at least
e1a0: 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d sz*N bytes of m
e1b0: 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 emory..** SQLite
e1c0: 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 will use no mor
e1d0: 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 e than one scrat
e1e0: 63 68 20 62 75 66 66 65 72 20 61 74 20 6f 6e 63 ch buffer at onc
e1f0: 65 20 70 65 72 20 74 68 72 65 61 64 2c 20 73 6f e per thread, so
e200: 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 .** N should be
e210: 73 65 74 20 74 6f 20 74 68 65 20 65 78 70 65 63 set to the expec
e220: 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 ted maximum numb
e230: 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 20 20 er of threads.
e240: 54 68 65 20 73 7a 0a 2a 2a 20 70 61 72 61 6d 65 The sz.** parame
e250: 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 36 20 ter should be 6
e260: 74 69 6d 65 73 20 74 68 65 20 73 69 7a 65 20 6f times the size o
e270: 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 f the largest da
e280: 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 tabase page size
e290: 2e 0a 2a 2a 20 53 63 72 61 74 63 68 20 62 75 66 ..** Scratch buf
e2a0: 66 65 72 73 20 61 72 65 20 75 73 65 64 20 61 73 fers are used as
e2b0: 20 70 61 72 74 20 6f 66 20 74 68 65 20 62 74 72 part of the btr
e2c0: 65 65 20 62 61 6c 61 6e 63 65 20 6f 70 65 72 61 ee balance opera
e2d0: 74 69 6f 6e 2e 20 20 49 66 0a 2a 2a 20 54 68 65 tion. If.** The
e2e0: 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65 72 20 btree balancer
e2f0: 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c needs additional
e300: 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 memory beyond w
e310: 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 hat is provided
e320: 62 79 0a 2a 2a 20 73 63 72 61 74 63 68 20 62 75 by.** scratch bu
e330: 66 66 65 72 73 20 6f 72 20 69 66 20 6e 6f 20 73 ffers or if no s
e340: 63 72 61 74 63 68 20 62 75 66 66 65 72 20 73 70 cratch buffer sp
e350: 61 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64 ace is specified
e360: 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a , then SQLite.**
e370: 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 goes to [sqlite
e380: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 74 6f 20 6f 3_malloc()] to o
e390: 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 btain the memory
e3a0: 20 69 74 20 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a it needs.</dd>.
e3b0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
e3c0: 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 _CONFIG_PAGECACH
e3d0: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 E</dt>.** <dd>Th
e3e0: 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 is option specif
e3f0: 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d ies a static mem
e400: 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 ory buffer that
e410: 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 SQLite can use f
e420: 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 or.** the databa
e430: 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69 se page cache wi
e440: 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 th the default p
e450: 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d age cache implem
e460: 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 enation. .** Th
e470: 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e is configuration
e480: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 should not be u
e490: 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63 sed if an applic
e4a0: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 ation-define pag
e4b0: 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 e.** cache imple
e4c0: 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 mentation is loa
e4d0: 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 ded using the SQ
e4e0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
e4f0: 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 HE option..** Th
e500: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 ere are three ar
e510: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 guments to this
e520: 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 option: A pointe
e530: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f r to the.** memo
e540: 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 ry, the size of
e550: 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72 each page buffer
e560: 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e (sz), and the n
e570: 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 umber of pages (
e580: 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 N)..** The sz ar
e590: 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 gument must be a
e5a0: 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 power of two be
e5b0: 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 tween 512 and 32
e5c0: 37 36 38 2e 20 20 54 68 65 20 66 69 72 73 74 0a 768. The first.
e5d0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 ** argument shou
e5e0: 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 ld point to an a
e5f0: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 llocation of at
e600: 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 least sz*N bytes
e610: 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 of memory..** S
e620: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 QLite will use t
e630: 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 he memory provid
e640: 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 ed by the first
e650: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 argument to sati
e660: 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 sfy its.** memor
e670: 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 y needs for the
e680: 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 first N pages th
e690: 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 at it adds to ca
e6a0: 63 68 65 2e 20 20 49 66 20 61 64 64 69 74 69 6f che. If additio
e6b0: 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 nal.** page cach
e6c0: 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 e memory is need
e6d0: 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 ed beyond what i
e6e0: 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 s provided by th
e6f0: 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a is option, then.
e700: 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 ** SQLite goes t
e710: 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f o [sqlite3_mallo
e720: 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 c()] for the add
e730: 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 itional storage
e740: 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6d space..** The im
e750: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 plementation mig
e760: 68 74 20 75 73 65 20 6f 6e 65 20 6f 72 20 6d 6f ht use one or mo
e770: 72 65 20 6f 66 20 74 68 65 20 4e 20 62 75 66 66 re of the N buff
e780: 65 72 73 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a 20 ers to hold .**
e790: 6d 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e memory accountin
e7a0: 67 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 3c g information. <
e7b0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
e7c0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 QLITE_CONFIG_HEA
e7d0: 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 P</dt>.** <dd>Th
e7e0: 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 is option specif
e7f0: 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d ies a static mem
e800: 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 ory buffer that
e810: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a SQLite will use.
e820: 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 ** for all of it
e830: 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 s dynamic memory
e840: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 allocation need
e850: 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 s beyond those p
e860: 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 rovided.** for b
e870: 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 y [SQLITE_CONFIG
e880: 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 _SCRATCH] and [S
e890: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 QLITE_CONFIG_PAG
e8a0: 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 ECACHE]..** Ther
e8b0: 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 e are three argu
e8c0: 6d 65 6e 74 73 3a 20 41 20 70 6f 69 6e 74 65 72 ments: A pointer
e8d0: 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20 to the memory,
e8e0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a the number of.**
e8f0: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 bytes in the me
e900: 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 mory buffer, and
e910: 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c the minimum all
e920: 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 20 20 49 ocation size. I
e930: 66 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 f.** the first p
e940: 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f ointer (the memo
e950: 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e ry pointer) is N
e960: 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 ULL, then SQLite
e970: 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 reverts.** to u
e980: 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 sing its default
e990: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
e9a0: 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 r (the system ma
e9b0: 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 lloc() implement
e9c0: 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 ation),.** undoi
e9d0: 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 ng any prior inv
e9e0: 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 ocation of [SQLI
e9f0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
ea00: 5d 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 6d 65 ]. If the.** me
ea10: 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 mory pointer is
ea20: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 not NULL and eit
ea30: 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 her [SQLITE_ENAB
ea40: 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a LE_MEMSYS3] or.*
ea50: 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 * [SQLITE_ENABLE
ea60: 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 _MEMSYS5] are de
ea70: 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 fined, then the
ea80: 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f alternative memo
ea90: 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 ry.** allocator
eaa0: 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 is engaged to ha
eab0: 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 ndle all of SQLi
eac0: 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 tes memory alloc
ead0: 61 74 69 6f 6e 20 6e 65 65 64 73 2e 3c 2f 64 64 ation needs.</dd
eae0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
eaf0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c TE_CONFIG_MUTEX<
eb00: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 /dt>.** <dd>This
eb10: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
eb20: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
eb30: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 which is a point
eb40: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 er to an.** inst
eb50: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c ance of the [sql
eb60: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
eb70: 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 ds] structure.
eb80: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 The argument spe
eb90: 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e cifies.** altern
eba0: 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 ative low-level
ebb0: 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 mutex routines t
ebc0: 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 o be used in pla
ebd0: 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 ce.** the mutex
ebe0: 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 routines built i
ebf0: 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e nto SQLite.</dd>
ec00: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
ec10: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 E_CONFIG_GETMUTE
ec20: 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 X</dt>.** <dd>Th
ec30: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
ec40: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
ec50: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 t which is a poi
ec60: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e nter to an.** in
ec70: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 stance of the [s
ec80: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
ec90: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e hods] structure.
eca0: 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 The.** [sqlite
ecb0: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 3_mutex_methods]
ecc0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 .** structure is
ecd0: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 filled with the
ece0: 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e currently defin
ecf0: 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 ed mutex routine
ed00: 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f s..** This optio
ed10: 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f n can be used to
ed20: 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 overload the de
ed30: 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f fault mutex allo
ed40: 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e cation.** routin
ed50: 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 es with a wrappe
ed60: 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 r used to track
ed70: 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 mutex usage for
ed80: 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 performance.** p
ed90: 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 rofiling or test
eda0: 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 ing, for example
edb0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
edc0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c >SQLITE_CONFIG_L
edd0: 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a OOKASIDE</dt>.**
ede0: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e <dd>This option
edf0: 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d takes two argum
ee00: 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d ents that determ
ee10: 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a ine the default.
ee20: 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 63 61 74 ** memory allcat
ee30: 69 6f 6e 20 6c 6f 6f 6b 61 73 69 64 65 20 6f 70 ion lookaside op
ee40: 74 69 6d 69 7a 61 74 69 6f 6e 2e 20 20 54 68 65 timization. The
ee50: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
ee60: 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f is the.** size o
ee70: 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 f each lookaside
ee80: 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 buffer slot and
ee90: 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 the second is t
eea0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 he number of.**
eeb0: 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 slots allocated
eec0: 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 to each database
eed0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 3c 2f 64 64 connection.</dd
eee0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
eef0: 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
ef00: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 </dt>.** <dd>Thi
ef10: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 s option takes a
ef20: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
ef30: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e which is a poin
ef40: 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 ter to.** an [sq
ef50: 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 lite3_pcache_met
ef60: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 hods] object. T
ef70: 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 his object speci
ef80: 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 fies the interfa
ef90: 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f ce.** to a custo
efa0: 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 m page cache imp
efb0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 53 51 lementation. SQ
efc0: 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 Lite makes a cop
efd0: 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 y of the.** obje
efe0: 63 74 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 ct and uses it f
eff0: 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 or page cache me
f000: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 mory allocations
f010: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
f020: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 >SQLITE_CONFIG_G
f030: 45 54 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a ETPCACHE</dt>.**
f040: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e <dd>This option
f050: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
f060: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 argument which i
f070: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
f080: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 n.** [sqlite3_pc
f090: 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 ache_methods] ob
f0a0: 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f ject. SQLite co
f0b0: 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 pies of the curr
f0c0: 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 ent.** page cach
f0d0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
f0e0: 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 into that objec
f0f0: 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f t.</dd>.**.** </
f100: 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 dl>.*/.#define S
f110: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e QLITE_CONFIG_SIN
f120: 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a GLETHREAD 1 /*
f130: 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nil */.#define
f140: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
f150: 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f LTITHREAD 2 /
f160: 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 * nil */.#define
f170: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 SQLITE_CONFIG_S
f180: 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 ERIALIZED 3
f190: 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e /* nil */.#defin
f1a0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
f1b0: 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 MALLOC 4
f1c0: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f /* sqlite3_mem_
f1d0: 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 methods* */.#def
f1e0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
f1f0: 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 G_GETMALLOC
f200: 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 5 /* sqlite3_me
f210: 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 m_methods* */.#d
f220: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
f230: 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 FIG_SCRATCH
f240: 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6 /* void*, i
f250: 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a nt sz, int N */.
f260: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
f270: 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 ONFIG_PAGECACHE
f280: 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 7 /* void*,
f290: 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a int sz, int N *
f2a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
f2b0: 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 _CONFIG_HEAP
f2c0: 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 8 /* void
f2d0: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e *, int nByte, in
f2e0: 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 t min */.#define
f2f0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
f300: 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20 EMSTATUS 9
f310: 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 /* boolean */.#d
f320: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
f330: 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 FIG_MUTEX
f340: 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 10 /* sqlite3_
f350: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a mutex_methods* *
f360: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
f370: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 _CONFIG_GETMUTEX
f380: 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 11 /* sqli
f390: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 te3_mutex_method
f3a0: 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 s* */./* previou
f3b0: 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 sly SQLITE_CONFI
f3c0: 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 G_CHUNKALLOC 12
f3d0: 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 which is now unu
f3e0: 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 sed. */ .#define
f3f0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c SQLITE_CONFIG_L
f400: 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 OOKASIDE 13
f410: 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 /* int int */.#d
f420: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
f430: 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 FIG_PCACHE
f440: 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 14 /* sqlite3_
f450: 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 pcache_methods*
f460: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
f470: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 E_CONFIG_GETPCAC
f480: 48 45 20 20 20 20 31 35 20 20 2f 2a 20 73 71 6c HE 15 /* sql
f490: 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 ite3_pcache_meth
f4a0: 6f 64 73 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 ods* */../*.** C
f4b0: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 API3REF: Configu
f4c0: 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b ration Options {
f4d0: 48 31 30 31 37 30 7d 20 3c 53 32 30 30 30 30 3e H10170} <S20000>
f4e0: 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c .** EXPERIMENTAL
f4f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e .**.** These con
f500: 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 stants are the a
f510: 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 vailable integer
f520: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
f530: 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 ptions that.** c
f540: 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 an be passed as
f550: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d the second argum
f560: 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 ent to the [sqli
f570: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d te3_db_config()]
f580: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a interface..**.*
f590: 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 * New configurat
f5a0: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 ion options may
f5b0: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 be added in futu
f5c0: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 re releases of S
f5d0: 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 QLite..** Existi
f5e0: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ng configuration
f5f0: 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 options might b
f600: 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 e discontinued.
f610: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a Applications.**
f620: 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 should check th
f630: 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 e return code fr
f640: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 om [sqlite3_db_c
f650: 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 onfig()] to make
f660: 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 sure that.** th
f670: 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 e call worked.
f680: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f The [sqlite3_db_
f690: 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
f6a0: 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ace will return
f6b0: 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 a.** non-zero [e
f6c0: 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 rror code] if a
f6d0: 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 discontinued or
f6e0: 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 unsupported conf
f6f0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
f700: 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a .** is invoked..
f710: 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 **.** <dl>.** <d
f720: 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 t>SQLITE_DBCONFI
f730: 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e G_LOOKASIDE</dt>
f740: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 .** <dd>This opt
f750: 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 ion takes three
f760: 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d additional argum
f770: 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d ents that determ
f780: 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f ine the .** [loo
f790: 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c kaside memory al
f7a0: 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 locator] configu
f7b0: 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b ration for the [
f7c0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
f7d0: 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 ion]..** The fir
f7e0: 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 st argument (the
f7f0: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
f800: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f to [sqlite3_db_
f810: 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a config()] is a.*
f820: 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d * pointer to a m
f830: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 emory buffer to
f840: 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 use for lookasid
f850: 65 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 20 66 e memory. The f
f860: 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 irst.** argument
f870: 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 may be NULL in
f880: 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 which case SQLit
f890: 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 e will allocate
f8a0: 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a the lookaside.**
f8b0: 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 buffer itself u
f8c0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 sing [sqlite3_ma
f8d0: 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 73 65 lloc()]. The se
f8e0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 cond argument is
f8f0: 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 the.** size of
f900: 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 each lookaside b
f910: 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 uffer slot and t
f920: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
f930: 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 t is the number
f940: 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 of.** slots. Th
f950: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 e size of the bu
f960: 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 ffer in the firs
f970: 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 t argument must
f980: 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a be greater than.
f990: 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 ** or equal to t
f9a0: 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 he product of th
f9b0: 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 e second and thi
f9c0: 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 3c 2f 64 rd arguments.</d
f9d0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a d>.**.** </dl>.*
f9e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
f9f0: 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 _DBCONFIG_LOOKAS
fa00: 49 44 45 20 20 20 20 31 30 30 31 20 20 2f 2a 20 IDE 1001 /*
fa10: 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f void* int int */
fa20: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 .../*.** CAPI3RE
fa30: 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 F: Enable Or Dis
fa40: 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 able Extended Re
fa50: 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 32 32 sult Codes {H122
fa60: 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 00} <S10700>.**.
fa70: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 ** The sqlite3_e
fa80: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 xtended_result_c
fa90: 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 odes() routine e
faa0: 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c nables or disabl
fab0: 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e es the.** [exten
fac0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
fad0: 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c ] feature of SQL
fae0: 69 74 65 2e 20 54 68 65 20 65 78 74 65 6e 64 65 ite. The extende
faf0: 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 d result.** code
fb00: 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 s are disabled b
fb10: 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 y default for hi
fb20: 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 storical compati
fb30: 62 69 6c 69 74 79 20 63 6f 6e 73 69 64 65 72 61 bility considera
fb40: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 tions..**.** INV
fb50: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
fb60: 48 31 32 32 30 31 7d 20 45 61 63 68 20 6e 65 77 H12201} Each new
fb70: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
fb80: 63 74 69 6f 6e 5d 20 73 68 61 6c 6c 20 68 61 76 ction] shall hav
fb90: 65 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 e the.**
fba0: 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 [extended resu
fbb0: 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 lt codes] featur
fbc0: 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 e disabled by de
fbd0: 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 fault..**.** {H1
fbe0: 32 32 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 2202} The [sqlit
fbf0: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 e3_extended_resu
fc00: 6c 74 5f 63 6f 64 65 73 28 44 2c 46 29 5d 20 69 lt_codes(D,F)] i
fc10: 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 65 nterface shall e
fc20: 6e 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 nable.**
fc30: 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 [extended resu
fc40: 6c 74 20 63 6f 64 65 73 5d 20 66 6f 72 20 74 68 lt codes] for th
fc50: 65 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e e [database con
fc60: 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 nection] D.**
fc70: 20 20 20 20 20 20 20 69 66 20 74 68 65 20 46 20 if the F
fc80: 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 72 75 parameter is tru
fc90: 65 2c 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 e, or disable th
fca0: 65 6d 20 69 66 20 46 20 69 73 20 66 61 6c 73 65 em if F is false
fcb0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
fcc0: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 _extended_result
fcd0: 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c _codes(sqlite3*,
fce0: 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a int onoff);../*
fcf0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 .** CAPI3REF: La
fd00: 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 20 st Insert Rowid
fd10: 7b 48 31 32 32 32 30 7d 20 3c 53 31 30 37 30 30 {H12220} <S10700
fd20: 3e 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74 >.**.** Each ent
fd30: 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 ry in an SQLite
fd40: 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 table has a uniq
fd50: 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 ue 64-bit signed
fd60: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 .** integer key
fd70: 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 called the [ROWI
fd80: 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 54 68 D | "rowid"]. Th
fd90: 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 e rowid is alway
fda0: 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 s available.** a
fdb0: 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 s an undeclared
fdc0: 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 column named ROW
fdd0: 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 ID, OID, or _ROW
fde0: 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 ID_ as long as t
fdf0: 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 hose.** names ar
fe00: 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 e not also used
fe10: 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 by explicitly de
fe20: 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 clared columns.
fe30: 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 If.** the table
fe40: 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 has a column of
fe50: 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 type [INTEGER PR
fe60: 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 IMARY KEY] then
fe70: 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 that column.** i
fe80: 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 s another alias
fe90: 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a for the rowid..*
fea0: 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
feb0: 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 e returns the [r
fec0: 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 owid] of the mos
fed0: 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 t recent.** succ
fee0: 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 essful [INSERT]
fef0: 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 into the databas
ff00: 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 e from the [data
ff10: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
ff20: 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 .** in the first
ff30: 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 6e argument. If n
ff40: 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e o successful [IN
ff50: 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 SERT]s.** have e
ff60: 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 ver occurred on
ff70: 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f that database co
ff80: 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 nnection, zero i
ff90: 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
ffa0: 2a 20 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d * If an [INSERT]
ffb0: 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 occurs within a
ffc0: 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74 trigger, then t
ffd0: 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 he [rowid] of th
ffe0: 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f e inserted.** ro
fff0: 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 w is returned by
10000 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73 this routine as
10010 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 long as the tri
10020 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e gger is running.
10030 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 .** But once the
10040 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61 trigger termina
10050 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 tes, the value r
10060 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 eturned by this
10070 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72 routine.** rever
10080 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76 ts to the last v
10090 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65 alue inserted be
100a0 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 fore the trigger
100b0 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e fired..**.** An
100c0 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 [INSERT] that f
100d0 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f ails due to a co
100e0 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 nstraint violati
100f0 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 on is not a.** s
10100 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 uccessful [INSER
10110 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 T] and does not
10120 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 change the value
10130 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 returned by thi
10140 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54 s.** routine. T
10150 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 hus INSERT OR FA
10160 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 IL, INSERT OR IG
10170 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 NORE, INSERT OR
10180 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 ROLLBACK,.** and
10190 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 INSERT OR ABORT
101a0 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 make no changes
101b0 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 to the return v
101c0 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 alue of this.**
101d0 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 routine when the
101e0 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 ir insertion fai
101f0 6c 73 2e 20 20 57 68 65 6e 20 49 4e 53 45 52 54 ls. When INSERT
10200 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 OR REPLACE.** e
10210 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 ncounters a cons
10220 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e traint violation
10230 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 , it does not fa
10240 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 il. The.** INSE
10250 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 RT continues to
10260 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 completion after
10270 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 deleting rows t
10280 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 hat caused.** th
10290 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f e constraint pro
102a0 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f blem so INSERT O
102b0 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 R REPLACE will a
102c0 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 lways change.**
102d0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
102e0 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 of this interfa
102f0 63 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 ce..**.** For th
10300 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 e purposes of th
10310 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b is routine, an [
10320 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 INSERT] is consi
10330 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 dered to.** be s
10340 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 uccessful even i
10350 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 f it is subseque
10360 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b ntly rolled back
10370 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
10380 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 32 TS:.**.** {H1222
10390 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 1} The [sqlite3_
103a0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 last_insert_rowi
103b0 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 d()] function sh
103c0 61 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 all return.**
103d0 20 20 20 20 20 20 20 74 68 65 20 5b 72 6f 77 69 the [rowi
103e0 64 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f d].** o
103f0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e f the most recen
10400 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e t successful [IN
10410 53 45 52 54 5d 20 70 65 72 66 6f 72 6d 65 64 20 SERT] performed
10420 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 on the same.**
10430 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 [databas
10440 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e e connection] an
10450 64 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d d within the sam
10460 65 20 6f 72 20 68 69 67 68 65 72 20 6c 65 76 65 e or higher leve
10470 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 72 l.** tr
10480 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f igger context, o
10490 72 20 7a 65 72 6f 20 69 66 20 74 68 65 72 65 20 r zero if there
104a0 68 61 76 65 20 62 65 65 6e 20 6e 6f 20 71 75 61 have been no qua
104b0 6c 69 66 79 69 6e 67 0a 2a 2a 20 20 20 20 20 20 lifying.**
104c0 20 20 20 20 5b 49 4e 53 45 52 54 5d 20 73 74 61 [INSERT] sta
104d0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b tements..**.** {
104e0 48 31 32 32 32 33 7d 20 54 68 65 20 5b 73 71 6c H12223} The [sql
104f0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 ite3_last_insert
10500 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 74 69 _rowid()] functi
10510 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 on shall return
10520 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
10530 73 61 6d 65 20 76 61 6c 75 65 20 77 68 65 6e 20 same value when
10540 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 called from the
10550 73 61 6d 65 20 74 72 69 67 67 65 72 20 63 6f 6e same trigger con
10560 74 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 text.**
10570 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 immediately bef
10580 6f 72 65 20 61 6e 64 20 61 66 74 65 72 20 61 20 ore and after a
10590 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a [ROLLBACK]..**.*
105a0 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a * ASSUMPTIONS:.*
105b0 2a 0a 2a 2a 20 7b 41 31 32 32 33 32 7d 20 49 66 *.** {A12232} If
105c0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 a separate thre
105d0 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 ad performs a ne
105e0 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 w [INSERT] on th
105f0 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 e same.**
10600 20 20 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e database conn
10610 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 ection while the
10620 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 [sqlite3_last_i
10630 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a nsert_rowid()].*
10640 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 * funct
10650 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 ion is running a
10660 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 nd thus changes
10670 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 the last insert
10680 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 20 20 20 20 [rowid],.**
10690 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 76 61 then the va
106a0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 lue returned by
106b0 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e [sqlite3_last_in
106c0 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 sert_rowid()] is
106d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 6e 70 .** unp
106e0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d redictable and m
106f0 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 ight not equal e
10700 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 ither the old or
10710 20 74 68 65 20 6e 65 77 0a 2a 2a 20 20 20 20 20 the new.**
10720 20 20 20 20 20 6c 61 73 74 20 69 6e 73 65 72 74 last insert
10730 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c [rowid]..*/.sql
10740 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 ite3_int64 sqlit
10750 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 e3_last_insert_r
10760 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a owid(sqlite3*);.
10770 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
10780 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 Count The Numbe
10790 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 r Of Rows Modifi
107a0 65 64 20 7b 48 31 32 32 34 30 7d 20 3c 53 31 30 ed {H12240} <S10
107b0 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 600>.**.** This
107c0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
107d0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 the number of d
107e0 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 atabase rows tha
107f0 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a t were changed.*
10800 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 * or inserted or
10810 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 deleted by the
10820 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f most recently co
10830 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 mpleted SQL stat
10840 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 ement.** on the
10850 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
10860 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 tion] specified
10870 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72 by the first par
10880 61 6d 65 74 65 72 2e 0a 2a 2a 20 4f 6e 6c 79 20 ameter..** Only
10890 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 changes that are
108a0 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 directly specif
108b0 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 ied by the [INSE
108c0 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a RT], [UPDATE],.*
108d0 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 * or [DELETE] st
108e0 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e atement are coun
108f0 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 ted. Auxiliary
10900 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 changes caused b
10910 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 61 72 y.** triggers ar
10920 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 55 e not counted. U
10930 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f se the [sqlite3_
10940 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d total_changes()]
10950 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 function.** to
10960 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e find the total n
10970 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 umber of changes
10980 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 including chang
10990 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69 es caused by tri
109a0 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 ggers..**.** A "
109b0 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 row change" is a
109c0 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e change to a sin
109d0 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e gle row of a sin
109e0 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 gle table.** cau
109f0 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 sed by an INSERT
10a00 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 , DELETE, or UPD
10a10 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 ATE statement.
10a20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 Rows that.** are
10a30 20 63 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 changed as side
10a40 20 65 66 66 65 63 74 73 20 6f 66 20 52 45 50 4c effects of REPL
10a50 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 ACE constraint r
10a60 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f esolution,.** ro
10a70 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 llback, ABORT pr
10a80 6f 63 65 73 73 69 6e 67 2c 20 44 52 4f 50 20 54 ocessing, DROP T
10a90 41 42 4c 45 2c 20 6f 72 20 62 79 20 61 6e 79 20 ABLE, or by any
10aa0 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 other.** mechani
10ab0 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 sms do not count
10ac0 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 as direct row c
10ad0 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 hanges..**.** A
10ae0 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 "trigger context
10af0 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 " is a scope of
10b00 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 execution that b
10b10 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 egins and.** end
10b20 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70 s with the scrip
10b30 74 20 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20 t of a trigger.
10b40 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d Most SQL statem
10b50 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c ents are.** eval
10b60 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 uated outside of
10b70 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 any trigger. T
10b80 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 his is the "top
10b90 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 level".** trigge
10ba0 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 r context. If a
10bb0 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66 trigger fires f
10bc0 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 rom the top leve
10bd0 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 l, a.** new trig
10be0 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 ger context is e
10bf0 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 ntered for the d
10c00 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 uration of that
10c10 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 one.** trigger.
10c20 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65 Subtriggers cre
10c30 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 ate subcontexts
10c40 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69 for their durati
10c50 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e on..**.** Callin
10c60 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 g [sqlite3_exec(
10c70 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 )] or [sqlite3_s
10c80 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 tep()] recursive
10c90 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 ly does.** not c
10ca0 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 reate a new trig
10cb0 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a ger context..**.
10cc0 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e ** This function
10cd0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
10ce0 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f ber of direct ro
10cf0 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 w changes in the
10d00 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 .** most recent
10d10 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 INSERT, UPDATE,
10d20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d or DELETE statem
10d30 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 ent within the s
10d40 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 ame.** trigger c
10d50 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 ontext..**.** Th
10d60 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 us, when called
10d70 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 from the top lev
10d80 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f el, this functio
10d90 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a n returns the.**
10da0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 number of chang
10db0 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 es in the most r
10dc0 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 ecent INSERT, UP
10dd0 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a DATE, or DELETE.
10de0 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 ** that also occ
10df0 75 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 urred at the top
10e00 20 6c 65 76 65 6c 2e 20 20 57 69 74 68 69 6e 20 level. Within
10e10 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 the body of a tr
10e20 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 igger,.** the sq
10e30 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 lite3_changes()
10e40 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 interface can be
10e50 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 called to find
10e60 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a the number of.**
10e70 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 changes in the
10e80 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f most recently co
10e90 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 mpleted INSERT,
10ea0 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 UPDATE, or DELET
10eb0 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 E.** statement w
10ec0 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f ithin the body o
10ed0 66 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 f the same trigg
10ee0 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 er..** However,
10ef0 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 the number retur
10f00 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 ned does not inc
10f10 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 lude changes.**
10f20 63 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69 caused by subtri
10f30 67 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 ggers since thos
10f40 65 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e e have their own
10f50 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 context..**.**
10f60 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 SQLite implement
10f70 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 s the command "D
10f80 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 ELETE FROM table
10f90 22 20 77 69 74 68 6f 75 74 20 61 20 57 48 45 52 " without a WHER
10fa0 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 E clause.** by d
10fb0 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 ropping and recr
10fc0 65 61 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 eating the table
10fd0 2e 20 20 44 6f 69 6e 67 20 73 6f 20 69 73 20 6d . Doing so is m
10fe0 75 63 68 20 66 61 73 74 65 72 20 74 68 61 6e 20 uch faster than
10ff0 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 going.** through
11000 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e and deleting in
11010 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 dividual element
11020 73 20 66 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 s from the table
11030 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 . Because of th
11040 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 is.** optimizati
11050 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69 6f 6e on, the deletion
11060 73 20 69 6e 20 22 44 45 4c 45 54 45 20 46 52 4f s in "DELETE FRO
11070 4d 20 74 61 62 6c 65 22 20 61 72 65 20 6e 6f 74 M table" are not
11080 20 72 6f 77 20 63 68 61 6e 67 65 73 20 61 6e 64 row changes and
11090 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 .** will not be
110a0 63 6f 75 6e 74 65 64 20 62 79 20 74 68 65 20 73 counted by the s
110b0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 qlite3_changes()
110c0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 or [sqlite3_tot
110d0 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a al_changes()].**
110e0 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72 65 67 61 functions, rega
110f0 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75 rdless of the nu
11100 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 mber of elements
11110 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 67 69 that were origi
11120 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 65 20 nally.** in the
11130 74 61 62 6c 65 2e 20 20 54 6f 20 67 65 74 20 61 table. To get a
11140 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 n accurate count
11150 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f of the number o
11160 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 f rows deleted,
11170 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 use.** "DELETE F
11180 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 ROM table WHERE
11190 31 22 20 69 6e 73 74 65 61 64 2e 20 20 4f 72 20 1" instead. Or
111a0 72 65 63 6f 6d 70 69 6c 65 20 75 73 69 6e 67 20 recompile using
111b0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f the.** [SQLITE_O
111c0 4d 49 54 5f 54 52 55 4e 43 41 54 45 5f 4f 50 54 MIT_TRUNCATE_OPT
111d0 49 4d 49 5a 41 54 49 4f 4e 5d 20 63 6f 6d 70 69 IMIZATION] compi
111e0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 le-time option t
111f0 6f 20 64 69 73 61 62 6c 65 20 74 68 65 0a 2a 2a o disable the.**
11200 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 6f 6e optimization on
11210 20 61 6c 6c 20 71 75 65 72 69 65 73 2e 0a 2a 2a all queries..**
11220 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
11230 2a 2a 0a 2a 2a 20 7b 48 31 32 32 34 31 7d 20 54 **.** {H12241} T
11240 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e he [sqlite3_chan
11250 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 ges()] function
11260 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 shall return the
11270 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 number of.**
11280 20 20 20 20 20 20 20 72 6f 77 20 63 68 61 6e 67 row chang
11290 65 73 20 63 61 75 73 65 64 20 62 79 20 74 68 65 es caused by the
112a0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 most recent INS
112b0 45 52 54 2c 20 55 50 44 41 54 45 2c 0a 2a 2a 20 ERT, UPDATE,.**
112c0 20 20 20 20 20 20 20 20 20 6f 72 20 44 45 4c 45 or DELE
112d0 54 45 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 TE statement on
112e0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
112f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 e connection and
11300 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 .** wit
11310 68 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 20 hin the same or
11320 68 69 67 68 65 72 20 74 72 69 67 67 65 72 20 63 higher trigger c
11330 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20 ontext, or zero
11340 69 66 20 74 68 65 72 65 20 68 61 76 65 0a 2a 2a if there have.**
11350 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20 62 65 not be
11360 65 6e 20 61 6e 79 20 71 75 61 6c 69 66 79 69 6e en any qualifyin
11370 67 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a g row changes..*
11380 2a 0a 2a 2a 20 7b 48 31 32 32 34 33 7d 20 53 74 *.** {H12243} St
11390 61 74 65 6d 65 6e 74 73 20 6f 66 20 74 68 65 20 atements of the
113a0 66 6f 72 6d 20 22 44 45 4c 45 54 45 20 46 52 4f form "DELETE FRO
113b0 4d 20 74 61 62 6c 65 6e 61 6d 65 22 20 77 69 74 M tablename" wit
113c0 68 20 6e 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 h no.**
113d0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 73 68 WHERE clause sh
113e0 61 6c 6c 20 63 61 75 73 65 20 73 75 62 73 65 71 all cause subseq
113f0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a uent calls to.**
11400 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
11410 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 74 6f e3_changes()] to
11420 20 72 65 74 75 72 6e 20 7a 65 72 6f 2c 20 72 65 return zero, re
11430 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 0a gardless of the.
11440 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 ** numb
11450 65 72 20 6f 66 20 72 6f 77 73 20 6f 72 69 67 69 er of rows origi
11460 6e 61 6c 6c 79 20 69 6e 20 74 68 65 20 74 61 62 nally in the tab
11470 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 le..**.** ASSUMP
11480 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 TIONS:.**.** {A1
11490 32 32 35 32 7d 20 49 66 20 61 20 73 65 70 61 72 2252} If a separ
114a0 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 ate thread makes
114b0 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 changes on the
114c0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f same database co
114d0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 nnection.**
114e0 20 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 while [sqli
114f0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 te3_changes()] i
11500 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 s running then t
11510 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
11520 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 d.** is
11530 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 unpredictable a
11540 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 nd not meaningfu
11550 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 l..*/.int sqlite
11560 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 3_changes(sqlite
11570 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 3*);../*.** CAPI
11580 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 3REF: Total Numb
11590 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 er Of Rows Modif
115a0 69 65 64 20 7b 48 31 32 32 36 30 7d 20 3c 53 31 ied {H12260} <S1
115b0 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 0600>.**.** This
115c0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e function return
115d0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
115e0 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 row changes caus
115f0 65 64 20 62 79 20 49 4e 53 45 52 54 2c 0a 2a 2a ed by INSERT,.**
11600 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 UPDATE or DELET
11610 45 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e E statements sin
11620 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 ce the [database
11630 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 connection] was
11640 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 opened..** The
11650 63 6f 75 6e 74 20 69 6e 63 6c 75 64 65 73 20 61 count includes a
11660 6c 6c 20 63 68 61 6e 67 65 73 20 66 72 6f 6d 20 ll changes from
11670 61 6c 6c 20 74 72 69 67 67 65 72 20 63 6f 6e 74 all trigger cont
11680 65 78 74 73 2e 20 20 48 6f 77 65 76 65 72 2c 0a exts. However,.
11690 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 ** the count doe
116a0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 s not include ch
116b0 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d anges used to im
116c0 70 6c 65 6d 65 6e 74 20 52 45 50 4c 41 43 45 20 plement REPLACE
116d0 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 constraints,.**
116e0 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 do rollbacks or
116f0 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 ABORT processing
11700 2c 20 6f 72 20 44 52 4f 50 20 74 61 62 6c 65 20 , or DROP table
11710 70 72 6f 63 65 73 73 69 6e 67 2e 0a 2a 2a 20 54 processing..** T
11720 68 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 he changes are c
11730 6f 75 6e 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 ounted as soon a
11740 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 s the statement
11750 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 that makes them
11760 69 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 is.** completed
11770 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d (when the statem
11780 65 6e 74 20 68 61 6e 64 6c 65 20 69 73 20 70 61 ent handle is pa
11790 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 ssed to [sqlite3
117a0 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 _reset()] or.**
117b0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
117c0 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c e()])..**.** SQL
117d0 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 ite implements t
117e0 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 he command "DELE
117f0 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 TE FROM table" w
11800 69 74 68 6f 75 74 20 61 20 57 48 45 52 45 20 63 ithout a WHERE c
11810 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70 lause.** by drop
11820 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74 ping and recreat
11830 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20 ing the table.
11840 28 54 68 69 73 20 69 73 20 6d 75 63 68 20 66 61 (This is much fa
11850 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a ster than going.
11860 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64 ** through and d
11870 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75 eleting individu
11880 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d al elements from
11890 20 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42 65 the table.) Be
118a0 63 61 75 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a cause of this.**
118b0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 optimization, t
118c0 68 65 20 64 65 6c 65 74 69 6f 6e 73 20 69 6e 20 he deletions in
118d0 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 "DELETE FROM tab
118e0 6c 65 22 20 61 72 65 20 6e 6f 74 20 72 6f 77 20 le" are not row
118f0 63 68 61 6e 67 65 73 20 61 6e 64 0a 2a 2a 20 77 changes and.** w
11900 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 ill not be count
11910 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 ed by the sqlite
11920 33 5f 63 68 61 6e 67 65 73 28 29 20 6f 72 20 5b 3_changes() or [
11930 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
11940 61 6e 67 65 73 28 29 5d 0a 2a 2a 20 66 75 6e 63 anges()].** func
11950 74 69 6f 6e 73 2c 20 72 65 67 61 72 64 6c 65 73 tions, regardles
11960 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 s of the number
11970 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 of elements that
11980 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 were originally
11990 0a 2a 2a 20 69 6e 20 74 68 65 20 74 61 62 6c 65 .** in the table
119a0 2e 20 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63 . To get an acc
119b0 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 urate count of t
119c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 he number of row
119d0 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a s deleted, use.*
119e0 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 * "DELETE FROM t
119f0 61 62 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e able WHERE 1" in
11a00 73 74 65 61 64 2e 20 20 20 4f 72 20 72 65 63 6f stead. Or reco
11a10 6d 70 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a mpile using the.
11a20 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f ** [SQLITE_OMIT_
11a30 54 52 55 4e 43 41 54 45 5f 4f 50 54 49 4d 49 5a TRUNCATE_OPTIMIZ
11a40 41 54 49 4f 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 ATION] compile-t
11a50 69 6d 65 20 6f 70 74 69 6f 6e 20 74 6f 20 64 69 ime option to di
11a60 73 61 62 6c 65 20 74 68 65 0a 2a 2a 20 6f 70 74 sable the.** opt
11a70 69 6d 69 7a 61 74 69 6f 6e 20 6f 6e 20 61 6c 6c imization on all
11a80 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 queries..**.**
11a90 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 See also the [sq
11aa0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d lite3_changes()]
11ab0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a interface..**.*
11ac0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
11ad0 0a 2a 2a 20 7b 48 31 32 32 36 31 7d 20 54 68 65 .** {H12261} The
11ae0 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f [sqlite3_total_
11af0 63 68 61 6e 67 65 73 28 29 5d 20 72 65 74 75 72 changes()] retur
11b00 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d ns the total num
11b10 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ber.**
11b20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 of row changes c
11b30 61 75 73 65 64 20 62 79 20 49 4e 53 45 52 54 2c aused by INSERT,
11b40 20 55 50 44 41 54 45 2c 20 61 6e 64 2f 6f 72 20 UPDATE, and/or
11b50 44 45 4c 45 54 45 0a 2a 2a 20 20 20 20 20 20 20 DELETE.**
11b60 20 20 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e statements on
11b70 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 the same [datab
11b80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c ase connection],
11b90 20 69 6e 20 61 6e 79 0a 2a 2a 20 20 20 20 20 20 in any.**
11ba0 20 20 20 20 74 72 69 67 67 65 72 20 63 6f 6e 74 trigger cont
11bb0 65 78 74 2c 20 73 69 6e 63 65 20 74 68 65 20 64 ext, since the d
11bc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
11bd0 6f 6e 20 77 61 73 20 63 72 65 61 74 65 64 2e 0a on was created..
11be0 2a 2a 0a 2a 2a 20 7b 48 31 32 32 36 33 7d 20 53 **.** {H12263} S
11bf0 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 74 68 65 tatements of the
11c00 20 66 6f 72 6d 20 22 44 45 4c 45 54 45 20 46 52 form "DELETE FR
11c10 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 22 20 77 69 OM tablename" wi
11c20 74 68 20 6e 6f 0a 2a 2a 20 20 20 20 20 20 20 20 th no.**
11c30 20 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 73 WHERE clause s
11c40 68 61 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65 20 hall not change
11c50 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
11c60 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 ed.** b
11c70 79 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c y [sqlite3_total
11c80 5f 63 68 61 6e 67 65 73 28 29 5d 2e 0a 2a 2a 0a _changes()]..**.
11c90 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a ** ASSUMPTIONS:.
11ca0 2a 2a 0a 2a 2a 20 7b 41 31 32 32 36 34 7d 20 49 **.** {A12264} I
11cb0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 f a separate thr
11cc0 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 ead makes change
11cd0 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 s on the same da
11ce0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
11cf0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 n.** wh
11d00 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 ile [sqlite3_tot
11d10 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 al_changes()] is
11d20 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 running then th
11d30 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 e value.**
11d40 20 20 20 20 72 65 74 75 72 6e 65 64 20 69 73 20 returned is
11d50 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e unpredictable an
11d60 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c d not meaningful
11d70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
11d80 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 _total_changes(s
11d90 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
11da0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 CAPI3REF: Inter
11db0 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e rupt A Long-Runn
11dc0 69 6e 67 20 51 75 65 72 79 20 7b 48 31 32 32 37 ing Query {H1227
11dd0 30 7d 20 3c 53 33 30 35 30 30 3e 0a 2a 2a 0a 2a 0} <S30500>.**.*
11de0 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 * This function
11df0 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 causes any pendi
11e00 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 ng database oper
11e10 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 ation to abort a
11e20 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 nd.** return at
11e30 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 its earliest opp
11e40 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 ortunity. This r
11e50 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 outine is typica
11e60 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e lly.** called in
11e70 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 response to a u
11e80 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 ser action such
11e90 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e as pressing "Can
11ea0 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d cel".** or Ctrl-
11eb0 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72 C where the user
11ec0 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 wants a long qu
11ed0 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f ery operation to
11ee0 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 halt.** immedia
11ef0 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 tely..**.** It i
11f00 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 s safe to call t
11f10 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d his routine from
11f20 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72 a thread differ
11f30 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 ent from the.**
11f40 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63 thread that is c
11f50 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 urrently running
11f60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 the database op
11f70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 eration. But it
11f80 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 .** is not safe
11f90 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 to call this rou
11fa0 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 tine with a [dat
11fb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
11fc0 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f ] that.** is clo
11fd0 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f sed or might clo
11fe0 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 se before sqlite
11ff0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 3_interrupt() re
12000 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 turns..**.** If
12010 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e an SQL operation
12020 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 is very nearly
12030 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 finished at the
12040 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c time when.** sql
12050 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
12060 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e is called, then
12070 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 it might not ha
12080 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 ve an opportunit
12090 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 y.** to be inter
120a0 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 rupted and might
120b0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d continue to com
120c0 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 41 pletion..**.** A
120d0 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 n SQL operation
120e0 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 that is interrup
120f0 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ted will return
12100 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 [SQLITE_INTERRUP
12110 54 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69 6e T]..** If the in
12120 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 terrupted SQL op
12130 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e eration is an IN
12140 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 SERT, UPDATE, or
12150 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 DELETE.** that
12160 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 is inside an exp
12170 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f licit transactio
12180 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 n, then the enti
12190 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a re transaction.*
121a0 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 * will be rolled
121b0 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 back automatica
121c0 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c lly..**.** A cal
121d0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 l to sqlite3_int
121e0 65 72 72 75 70 74 28 29 20 68 61 73 20 6e 6f 20 errupt() has no
121f0 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 effect on SQL st
12200 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 atements.** that
12210 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 are started aft
12220 65 72 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 er sqlite3_inter
12230 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a rupt() returns..
12240 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
12250 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 37 31 7d :.**.** {H12271}
12260 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e The [sqlite3_in
12270 74 65 72 72 75 70 74 28 29 5d 20 69 6e 74 65 72 terrupt()] inter
12280 66 61 63 65 20 77 69 6c 6c 20 66 6f 72 63 65 20 face will force
12290 61 6c 6c 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 20 all running.**
122a0 20 20 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 SQL stat
122b0 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 ements associate
122c0 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 d with the same
122d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
122e0 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ion.**
122f0 74 6f 20 68 61 6c 74 20 61 66 74 65 72 20 70 72 to halt after pr
12300 6f 63 65 73 73 69 6e 67 20 61 74 20 6d 6f 73 74 ocessing at most
12310 20 6f 6e 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 one additional
12320 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a row of data..**.
12330 2a 2a 20 7b 48 31 32 32 37 32 7d 20 41 6e 79 20 ** {H12272} Any
12340 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 SQL statement th
12350 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 at is interrupte
12360 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 69 6e d by [sqlite3_in
12370 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20 terrupt()].**
12380 20 20 20 20 20 20 20 77 69 6c 6c 20 72 65 74 75 will retu
12390 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 rn [SQLITE_INTER
123a0 52 55 50 54 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 RUPT]..**.** ASS
123b0 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 UMPTIONS:.**.**
123c0 7b 41 31 32 32 37 39 7d 20 49 66 20 74 68 65 20 {A12279} If the
123d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
123e0 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 ion closes while
123f0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 [sqlite3_interr
12400 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 upt()].**
12410 20 20 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 is running th
12420 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 en bad things wi
12430 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e ll likely happen
12440 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 ..*/.void sqlite
12450 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 3_interrupt(sqli
12460 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
12470 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e PI3REF: Determin
12480 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 e If An SQL Stat
12490 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 ement Is Complet
124a0 65 20 7b 48 31 30 35 31 30 7d 20 3c 53 37 30 32 e {H10510} <S702
124b0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 00>.**.** These
124c0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 routines are use
124d0 66 75 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d ful for command-
124e0 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 line input to de
124f0 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a termine if the.*
12500 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 * currently ente
12510 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 red text seems t
12520 6f 20 66 6f 72 6d 20 63 6f 6d 70 6c 65 74 65 20 o form complete
12530 61 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 a SQL statement
12540 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f or.** if additio
12550 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 nal input is nee
12560 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 ded before sendi
12570 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f ng the text into
12580 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 .** SQLite for p
12590 61 72 73 69 6e 67 2e 20 20 54 68 65 73 65 20 72 arsing. These r
125a0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 outines return t
125b0 72 75 65 20 69 66 20 74 68 65 20 69 6e 70 75 74 rue if the input
125c0 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 string.** appea
125d0 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c rs to be a compl
125e0 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ete SQL statemen
125f0 74 2e 20 20 41 20 73 74 61 74 65 6d 65 6e 74 20 t. A statement
12600 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a is judged to be.
12610 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 ** complete if i
12620 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 t ends with a se
12630 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e micolon token an
12640 64 20 69 73 20 6e 6f 74 20 61 20 66 72 61 67 6d d is not a fragm
12650 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 43 52 45 41 ent of a.** CREA
12660 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 TE TRIGGER state
12670 6d 65 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e ment. Semicolon
12680 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 s that are embed
12690 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 ded within.** st
126a0 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 ring literals or
126b0 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 quoted identifi
126c0 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d er names or comm
126d0 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 ents are not.**
126e0 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 independent toke
126f0 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 ns (they are par
12700 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 t of the token i
12710 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 n which they are
12720 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e .** embedded) an
12730 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f d thus do not co
12740 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 unt as a stateme
12750 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a nt terminator..*
12760 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
12770 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 nes do not parse
12780 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
12790 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c nts thus.** will
127a0 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 not detect synt
127b0 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 actically incorr
127c0 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49 ect SQL..**.** I
127d0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
127e0 20 7b 48 31 30 35 31 31 7d 20 41 20 73 75 63 63 {H10511} A succ
127f0 65 73 73 66 75 6c 20 65 76 61 6c 75 61 74 69 6f essful evaluatio
12800 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63 6f n of [sqlite3_co
12810 6d 70 6c 65 74 65 28 29 5d 20 6f 72 0a 2a 2a 20 mplete()] or.**
12820 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
12830 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 3_complete16()]
12840 66 75 6e 63 74 69 6f 6e 73 20 73 68 61 6c 6c 0a functions shall.
12850 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 ** retu
12860 72 6e 20 61 20 6e 75 6d 65 72 69 63 20 31 20 69 rn a numeric 1 i
12870 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 f and only if th
12880 65 20 6c 61 73 74 20 6e 6f 6e 2d 77 68 69 74 65 e last non-white
12890 73 70 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 space.**
128a0 20 20 74 6f 6b 65 6e 20 69 6e 20 74 68 65 69 72 token in their
128b0 20 69 6e 70 75 74 20 69 73 20 61 20 73 65 6d 69 input is a semi
128c0 63 6f 6c 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f colon that is no
128d0 74 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 t in between.**
128e0 20 20 20 20 20 20 20 20 20 74 68 65 20 42 45 47 the BEG
128f0 49 4e 20 61 6e 64 20 45 4e 44 20 6f 66 20 61 20 IN and END of a
12900 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 CREATE TRIGGER s
12910 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 tatement..**.**
12920 7b 48 31 30 35 31 32 7d 20 49 66 20 61 20 6d 65 {H10512} If a me
12930 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
12940 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 error occurs dur
12950 69 6e 67 20 61 6e 20 69 6e 76 6f 63 61 74 69 6f ing an invocatio
12960 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 n.** of
12970 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 [sqlite3_comple
12980 74 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 te()] or [sqlite
12990 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 3_complete16()]
129a0 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 then the.**
129b0 20 20 20 20 20 72 6f 75 74 69 6e 65 20 73 68 61 routine sha
129c0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ll return [SQLIT
129d0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 E_NOMEM]..**.**
129e0 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a ASSUMPTIONS:.**.
129f0 2a 2a 20 7b 41 31 30 35 31 32 7d 20 54 68 65 20 ** {A10512} The
12a00 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 input to [sqlite
12a10 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 3_complete()] mu
12a20 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 st be a zero-ter
12a30 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 minated.**
12a40 20 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 UTF-8 string
12a50 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31 33 7d ..**.** {A10513}
12a60 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 The input to [s
12a70 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 qlite3_complete1
12a80 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 6()] must be a z
12a90 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a ero-terminated.*
12aa0 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 31 * UTF-1
12ab0 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 6 string in nati
12ac0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a ve byte order..*
12ad0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f /.int sqlite3_co
12ae0 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 mplete(const cha
12af0 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c r *sql);.int sql
12b00 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 ite3_complete16(
12b10 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 const void *sql)
12b20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
12b30 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 F: Register A Ca
12b40 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 llback To Handle
12b50 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 SQLITE_BUSY Err
12b60 6f 72 73 20 7b 48 31 32 33 31 30 7d 20 3c 53 34 ors {H12310} <S4
12b70 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 0400>.**.** This
12b80 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 routine sets a
12b90 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
12ba0 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 n that might be
12bb0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 invoked whenever
12bc0 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 .** an attempt i
12bd0 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 s made to open a
12be0 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 database table
12bf0 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 that another thr
12c00 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 ead.** or proces
12c10 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a s has locked..**
12c20 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79 20 .** If the busy
12c30 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c callback is NULL
12c40 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 , then [SQLITE_B
12c50 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f USY] or [SQLITE_
12c60 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a IOERR_BLOCKED].*
12c70 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d * is returned im
12c80 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 mediately upon e
12c90 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 ncountering the
12ca0 6c 6f 63 6b 2e 20 49 66 20 74 68 65 20 62 75 73 lock. If the bus
12cb0 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 y callback.** is
12cc0 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 not NULL, then
12cd0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c the callback wil
12ce0 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 l be invoked wit
12cf0 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e h two arguments.
12d00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
12d10 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
12d20 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f handler is a co
12d30 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 py of the void*
12d40 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a pointer which.**
12d50 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72 is the third ar
12d60 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
12d70 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 3_busy_handler()
12d80 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 . The second ar
12d90 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 gument to.** the
12da0 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 handler callbac
12db0 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 k is the number
12dc0 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 of times that th
12dd0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 e busy handler h
12de0 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b as.** been invok
12df0 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b ed for this lock
12e00 69 6e 67 20 65 76 65 6e 74 2e 20 20 49 66 20 74 ing event. If t
12e10 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 he.** busy callb
12e20 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 ack returns 0, t
12e30 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 hen no additiona
12e40 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d l attempts are m
12e50 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 ade to.** access
12e60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e the database an
12e70 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 d [SQLITE_BUSY]
12e80 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 or [SQLITE_IOERR
12e90 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 _BLOCKED] is ret
12ea0 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 urned..** If the
12eb0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
12ec0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e s non-zero, then
12ed0 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 another attempt
12ee0 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f .** is made to o
12ef0 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 pen the database
12f00 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 for reading and
12f10 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 the cycle repea
12f20 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 ts..**.** The pr
12f30 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 esence of a busy
12f40 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f handler does no
12f50 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 t guarantee that
12f60 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f it will be invo
12f70 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 ked.** when ther
12f80 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e e is lock conten
12f90 74 69 6f 6e 2e 20 49 66 20 53 51 4c 69 74 65 20 tion. If SQLite
12fa0 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 determines that
12fb0 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 invoking the bus
12fc0 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 y.** handler cou
12fd0 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 ld result in a d
12fe0 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c eadlock, it will
12ff0 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 go ahead and re
13000 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 turn [SQLITE_BUS
13010 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 Y].** or [SQLITE
13020 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 _IOERR_BLOCKED]
13030 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b instead of invok
13040 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e ing the busy han
13050 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 dler..** Conside
13060 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 r a scenario whe
13070 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 re one process i
13080 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 s holding a read
13090 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 lock that.** it
130a0 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 is trying to pr
130b0 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 omote to a reser
130c0 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 ved lock and.**
130d0 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 a second process
130e0 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 is holding a re
130f0 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 served lock that
13100 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a it is trying.**
13110 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 to promote to a
13120 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b n exclusive lock
13130 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f . The first pro
13140 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 cess cannot proc
13150 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 eed.** because i
13160 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 t is blocked by
13170 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 the second and t
13180 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 he second proces
13190 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 s cannot.** proc
131a0 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 eed because it i
131b0 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 s blocked by the
131c0 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 first. If both
131d0 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e processes.** in
131e0 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 voke the busy ha
131f0 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 ndlers, neither
13200 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 will make any pr
13210 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f ogress. Therefo
13220 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 re,.** SQLite re
13230 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 turns [SQLITE_BU
13240 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 SY] for the firs
13250 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e t process, hopin
13260 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 g that this.** w
13270 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 ill induce the f
13280 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 irst process to
13290 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 release its read
132a0 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a lock and allow.
132b0 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 ** the second pr
132c0 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 ocess to proceed
132d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 ..**.** The defa
132e0 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 ult busy callbac
132f0 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a k is NULL..**.**
13300 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 The [SQLITE_BUS
13310 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 Y] error is conv
13320 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 erted to [SQLITE
13330 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a _IOERR_BLOCKED].
13340 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 ** when SQLite i
13350 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 s in the middle
13360 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 of a large trans
13370 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c action where all
13380 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 the.** changes
13390 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 will not fit int
133a0 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 o the in-memory
133b0 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 cache. SQLite w
133c0 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 ill.** already h
133d0 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c old a RESERVED l
133e0 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 ock on the datab
133f0 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 ase file, but it
13400 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f needs.** to pro
13410 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 mote this lock t
13420 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 o EXCLUSIVE so t
13430 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c hat it can spill
13440 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 cache.** pages
13450 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 into the databas
13460 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 e file without h
13470 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e arm to concurren
13480 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 49 t.** readers. I
13490 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 f it is unable t
134a0 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f o promote the lo
134b0 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d ck, then the in-
134c0 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 memory.** cache
134d0 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 will be left in
134e0 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 an inconsistent
134f0 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 state and so the
13500 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 error.** code i
13510 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 s promoted from
13520 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 the relatively b
13530 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 enign [SQLITE_BU
13540 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f SY] to.** the mo
13550 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 re severe [SQLIT
13560 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d E_IOERR_BLOCKED]
13570 2e 20 20 54 68 69 73 20 65 72 72 6f 72 20 63 6f . This error co
13580 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 de promotion.**
13590 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 forces an automa
135a0 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 tic rollback of
135b0 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 the changes. Se
135c0 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 e the.** <a href
135d0 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f ="/cvstrac/wiki?
135e0 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c p=CorruptionFoll
135f0 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e owingBusyError">
13600 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f .** CorruptionFo
13610 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 llowingBusyError
13620 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 </a> wiki page f
13630 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 or a discussion
13640 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 of why.** this i
13650 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a s important..**.
13660 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c ** There can onl
13670 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 y be a single bu
13680 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e sy handler defin
13690 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b ed for each.** [
136a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
136b0 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 ion]. Setting a
136c0 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 new busy handle
136d0 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 r clears any.**
136e0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 previously set h
136f0 61 6e 64 6c 65 72 2e 20 20 4e 6f 74 65 20 74 68 andler. Note th
13700 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 at calling [sqli
13710 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 te3_busy_timeout
13720 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f ()].** will also
13730 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 set or clear th
13740 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a e busy handler..
13750 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 **.** The busy c
13760 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e allback should n
13770 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 ot take any acti
13780 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 ons which modify
13790 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 the.** database
137a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 connection that
137b0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 invoked the bus
137c0 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 y handler. Any
137d0 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 such actions.**
137e0 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 result in undefi
137f0 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a ned behavior..**
13800 20 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a .** INVARIANTS:
13810 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 31 7d 20 .**.** {H12311}
13820 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 The [sqlite3_bus
13830 79 5f 68 61 6e 64 6c 65 72 28 44 2c 43 2c 41 29 y_handler(D,C,A)
13840 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c ] function shall
13850 20 72 65 70 6c 61 63 65 0a 2a 2a 20 20 20 20 20 replace.**
13860 20 20 20 20 20 62 75 73 79 20 63 61 6c 6c 62 61 busy callba
13870 63 6b 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 ck in the [datab
13880 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
13890 44 20 77 69 74 68 20 61 20 6e 65 77 0a 2a 2a 20 D with a new.**
138a0 20 20 20 20 20 20 20 20 20 61 20 6e 65 77 20 62 a new b
138b0 75 73 79 20 68 61 6e 64 6c 65 72 20 43 20 61 6e usy handler C an
138c0 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 d application da
138d0 74 61 20 70 6f 69 6e 74 65 72 20 41 2e 0a 2a 2a ta pointer A..**
138e0 0a 2a 2a 20 7b 48 31 32 33 31 32 7d 20 4e 65 77 .** {H12312} New
138f0 6c 79 20 63 72 65 61 74 65 64 20 5b 64 61 74 61 ly created [data
13900 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
13910 5d 20 73 68 61 6c 6c 20 68 61 76 65 20 61 20 62 ] shall have a b
13920 75 73 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 usy.**
13930 68 61 6e 64 6c 65 72 20 6f 66 20 4e 55 4c 4c 2e handler of NULL.
13940 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 34 7d 20 .**.** {H12314}
13950 57 68 65 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 When two or more
13960 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
13970 63 74 69 6f 6e 73 5d 20 73 68 61 72 65 20 61 0a ctions] share a.
13980 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
13990 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 ite3_enable_shar
139a0 65 64 5f 63 61 63 68 65 20 7c 20 63 6f 6d 6d 6f ed_cache | commo
139b0 6e 20 63 61 63 68 65 5d 2c 0a 2a 2a 20 20 20 20 n cache],.**
139c0 20 20 20 20 20 20 74 68 65 20 62 75 73 79 20 68 the busy h
139d0 61 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20 64 andler for the d
139e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
139f0 6f 6e 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 on currently usi
13a00 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 ng.** t
13a10 68 65 20 63 61 63 68 65 20 73 68 61 6c 6c 20 62 he cache shall b
13a20 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 e invoked when t
13a30 68 65 20 63 61 63 68 65 20 65 6e 63 6f 75 6e 74 he cache encount
13a40 65 72 73 20 61 20 6c 6f 63 6b 2e 0a 2a 2a 0a 2a ers a lock..**.*
13a50 2a 20 7b 48 31 32 33 31 36 7d 20 49 66 20 61 20 * {H12316} If a
13a60 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c busy handler cal
13a70 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 7a 65 lback returns ze
13a80 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c ro, then the SQL
13a90 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a ite interface.**
13aa0 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 70 that p
13ab0 72 6f 76 6f 6b 65 64 20 74 68 65 20 6c 6f 63 6b rovoked the lock
13ac0 69 6e 67 20 65 76 65 6e 74 20 73 68 61 6c 6c 20 ing event shall
13ad0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 return [SQLITE_B
13ae0 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 USY]..**.** {H12
13af0 33 31 38 7d 20 53 51 4c 69 74 65 20 73 68 61 6c 318} SQLite shal
13b00 6c 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 62 75 l invokes the bu
13b10 73 79 20 68 61 6e 64 6c 65 72 20 77 69 74 68 20 sy handler with
13b20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 77 68 two arguments wh
13b30 69 63 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ich.**
13b40 61 72 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 are a copy of th
13b50 65 20 70 6f 69 6e 74 65 72 20 73 75 70 70 6c 69 e pointer suppli
13b60 65 64 20 62 79 20 74 68 65 20 33 72 64 20 70 61 ed by the 3rd pa
13b70 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 rameter to.**
13b80 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
13b90 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 busy_handler()]
13ba0 61 6e 64 20 61 20 63 6f 75 6e 74 20 6f 66 20 74 and a count of t
13bb0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 72 69 he number of pri
13bc0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 or.** i
13bd0 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 nvocations of th
13be0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 e busy handler f
13bf0 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b or the same lock
13c00 69 6e 67 20 65 76 65 6e 74 2e 0a 2a 2a 0a 2a 2a ing event..**.**
13c10 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a ASSUMPTIONS:.**
13c20 0a 2a 2a 20 7b 41 31 32 33 31 39 7d 20 41 20 62 .** {A12319} A b
13c30 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 usy handler must
13c40 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 not close the d
13c50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
13c60 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f on.** o
13c70 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 r [prepared stat
13c80 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f ement] that invo
13c90 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e ked the busy han
13ca0 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c dler..*/.int sql
13cb0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 ite3_busy_handle
13cc0 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 r(sqlite3*, int(
13cd0 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 *)(void*,int), v
13ce0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 oid*);../*.** CA
13cf0 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 PI3REF: Set A Bu
13d00 73 79 20 54 69 6d 65 6f 75 74 20 7b 48 31 32 33 sy Timeout {H123
13d10 34 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 40} <S40410>.**.
13d20 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
13d30 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f sets a [sqlite3_
13d40 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 busy_handler | b
13d50 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 usy handler] tha
13d60 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 t sleeps.** for
13d70 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 a specified amou
13d80 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 nt of time when
13d90 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 a table is locke
13da0 64 2e 20 20 54 68 65 20 68 61 6e 64 6c 65 72 0a d. The handler.
13db0 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 ** will sleep mu
13dc0 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 ltiple times unt
13dd0 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 il at least "ms"
13de0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 milliseconds of
13df0 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 sleeping.** hav
13e00 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 7b e accumulated. {
13e10 48 31 32 33 34 33 7d 20 41 66 74 65 72 20 22 6d H12343} After "m
13e20 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 s" milliseconds
13e30 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 of sleeping,.**
13e40 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 the handler retu
13e50 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 rns 0 which caus
13e60 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 es [sqlite3_step
13e70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a ()] to return.**
13e80 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f [SQLITE_BUSY] o
13e90 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f r [SQLITE_IOERR_
13ea0 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 BLOCKED]..**.**
13eb0 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 Calling this rou
13ec0 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 tine with an arg
13ed0 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 ument less than
13ee0 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f or equal to zero
13ef0 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c .** turns off al
13f00 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e l busy handlers.
13f10 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e .**.** There can
13f20 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c only be a singl
13f30 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 e busy handler f
13f40 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a or a particular.
13f50 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
13f60 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 nection] any any
13f70 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 given moment.
13f80 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 If another busy
13f90 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 handler.** was d
13fa0 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b efined (using [
13fb0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e sqlite3_busy_han
13fc0 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 dler()]) prior t
13fd0 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 o calling.** thi
13fe0 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 s routine, that
13ff0 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c other busy handl
14000 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a er is cleared..*
14010 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
14020 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34 31 7d 20 .**.** {H12341}
14030 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 The [sqlite3_bus
14040 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 66 75 6e y_timeout()] fun
14050 63 74 69 6f 6e 20 73 68 61 6c 6c 20 6f 76 65 72 ction shall over
14060 72 69 64 65 20 61 6e 79 20 70 72 69 6f 72 0a 2a ride any prior.*
14070 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
14080 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 te3_busy_timeout
14090 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
140a0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 busy_handler()]
140b0 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20 setting.**
140c0 20 20 20 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 on the same
140d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
140e0 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 tion]..**.** {H1
140f0 32 33 34 33 7d 20 49 66 20 74 68 65 20 32 6e 64 2343} If the 2nd
14100 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 parameter to [s
14110 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 qlite3_busy_time
14120 6f 75 74 28 29 5d 20 69 73 20 6c 65 73 73 20 74 out()] is less t
14130 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 han.**
14140 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f or equal to zero
14150 2c 20 74 68 65 6e 20 74 68 65 20 62 75 73 79 20 , then the busy
14160 68 61 6e 64 6c 65 72 20 73 68 61 6c 6c 20 62 65 handler shall be
14170 20 63 6c 65 61 72 65 64 20 73 6f 20 74 68 61 74 cleared so that
14180 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c .** all
14190 20 73 75 62 73 65 71 75 65 6e 74 20 6c 6f 63 6b subsequent lock
141a0 69 6e 67 20 65 76 65 6e 74 73 20 69 6d 6d 65 64 ing events immed
141b0 69 61 74 65 6c 79 20 72 65 74 75 72 6e 20 5b 53 iately return [S
141c0 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a QLITE_BUSY]..**.
141d0 2a 2a 20 7b 48 31 32 33 34 34 7d 20 49 66 20 74 ** {H12344} If t
141e0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
141f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 to [sqlite3_bus
14200 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 20 y_timeout()] is
14210 61 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 20 20 a positive.**
14220 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 4e 2c number N,
14230 20 74 68 65 6e 20 61 20 62 75 73 79 20 68 61 6e then a busy han
14240 64 6c 65 72 20 73 68 61 6c 6c 20 62 65 20 73 65 dler shall be se
14250 74 20 74 68 61 74 20 72 65 70 65 61 74 65 64 6c t that repeatedl
14260 79 20 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 y calls.**
14270 20 20 20 20 74 68 65 20 78 53 6c 65 65 70 28 29 the xSleep()
14280 20 6d 65 74 68 6f 64 20 69 6e 20 74 68 65 20 5b method in the [
14290 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 sqlite3_vfs | VF
142a0 53 20 69 6e 74 65 72 66 61 63 65 5d 20 75 6e 74 S interface] unt
142b0 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 il.** e
142c0 69 74 68 65 72 20 74 68 65 20 6c 6f 63 6b 20 63 ither the lock c
142d0 6c 65 61 72 73 20 6f 72 20 75 6e 74 69 6c 20 74 lears or until t
142e0 68 65 20 63 75 6d 75 6c 61 74 69 76 65 20 73 6c he cumulative sl
142f0 65 65 70 20 74 69 6d 65 0a 2a 2a 20 20 20 20 20 eep time.**
14300 20 20 20 20 20 72 65 70 6f 72 74 65 64 20 62 61 reported ba
14310 63 6b 20 62 79 20 78 53 6c 65 65 70 28 29 20 65 ck by xSleep() e
14320 78 63 65 65 64 73 20 4e 20 6d 69 6c 6c 69 73 65 xceeds N millise
14330 63 6f 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 conds..*/.int sq
14340 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f lite3_busy_timeo
14350 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 ut(sqlite3*, int
14360 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ms);../*.** CAP
14370 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e I3REF: Convenien
14380 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 ce Routines For
14390 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 20 Running Queries
143a0 7b 48 31 32 33 37 30 7d 20 3c 53 31 30 30 30 30 {H12370} <S10000
143b0 3e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 >.**.** Definiti
143c0 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 on: A <b>result
143d0 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d table</b> is mem
143e0 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 ory data structu
143f0 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 re created by th
14400 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 e.** [sqlite3_ge
14410 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 t_table()] inter
14420 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 face. A result
14430 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 table records th
14440 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 e.** complete qu
14450 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d ery results from
14460 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 one or more que
14470 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ries..**.** The
14480 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c table conceptual
14490 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 ly has a number
144a0 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 of rows and colu
144b0 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 mns. But.** the
144c0 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e se numbers are n
144d0 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 ot part of the r
144e0 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 esult table itse
144f0 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 lf. These.** nu
14500 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e mbers are obtain
14510 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 ed separately.
14520 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d Let N be the num
14530 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 ber of rows.** a
14540 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 nd M be the numb
14550 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a er of columns..*
14560 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 *.** A result ta
14570 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 ble is an array
14580 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a of pointers to z
14590 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 ero-terminated U
145a0 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a TF-8 strings..**
145b0 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 There are (N+1)
145c0 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 *M elements in t
145d0 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 he array. The f
145e0 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 irst M pointers
145f0 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f point.** to zero
14600 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 -terminated stri
14610 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 ngs that contai
14620 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 n the names of t
14630 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 he columns..** T
14640 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 he remaining ent
14650 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 ries all point t
14660 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e o query results.
14670 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 NULL values re
14680 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 sult.** in NULL
14690 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f pointers. All o
146a0 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 ther values are
146b0 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a in their UTF-8 z
146c0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a ero-terminated.*
146d0 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 * string represe
146e0 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 ntation as retur
146f0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ned by [sqlite3_
14700 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a column_text()]..
14710 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 **.** A result t
14720 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 able might consi
14730 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 st of one or mor
14740 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
14750 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e ions..** It is n
14760 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 ot safe to pass
14770 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 a result table d
14780 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 irectly to [sqli
14790 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 te3_free()]..**
147a0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 A result table s
147b0 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 hould be dealloc
147c0 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 ated using [sqli
147d0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 te3_free_table()
147e0 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 ]..**.** As an e
147f0 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 xample of the re
14800 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 sult table forma
14810 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 t, suppose a que
14820 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 ry result.** is
14830 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a as follows:.**.*
14840 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
14850 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 re>.** Na
14860 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a me | Age.
14870 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d ** ------
14880 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
14890 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 -.** Alic
148a0 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 e | 43.**
148b0 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 Bob
148c0 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 | 28.**
148d0 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 Cindy |
148e0 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 21.** </pre></bl
148f0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
14900 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f There are two co
14910 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 lumn (M==2) and
14920 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 three rows (N==3
14930 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 ). Thus the.**
14940 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 result table has
14950 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 8 entries. Sup
14960 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 pose the result
14970 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a table is stored.
14980 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e ** in an array n
14990 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 ames azResult.
149a0 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f Then azResult ho
149b0 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 lds this content
149c0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
149d0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 ote><pre>.**
149e0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
149f0 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a ;0] = "Name";.**
14a00 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
14a10 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b [1] = "Age";
14a20 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
14a30 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c ult[2] = "Al
14a40 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 ice";.**
14a50 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 azResult[3]
14a60 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 = "43";.**
14a70 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 azResult[4
14a80 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 ] = "Bob";.**
14a90 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
14aa0 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 1;5] = "28";.**
14ab0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
14ac0 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 #91;6] = "Cindy"
14ad0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
14ae0 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 sult[7] = "2
14af0 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 1";.** </pre></b
14b00 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
14b10 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 The sqlite3_get
14b20 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f _table() functio
14b30 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 n evaluates one
14b40 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 or more.** semic
14b50 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 olon-separated S
14b60 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e QL statements in
14b70 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e the zero-termin
14b80 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 ated UTF-8.** st
14b90 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 ring of its 2nd
14ba0 70 61 72 61 6d 65 74 65 72 2e 20 20 49 74 20 72 parameter. It r
14bb0 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 eturns a result
14bc0 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 table to the.**
14bd0 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e pointer given in
14be0 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 its 3rd paramet
14bf0 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 er..**.** After
14c00 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 the calling func
14c10 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 tion has finishe
14c20 64 20 75 73 69 6e 67 20 74 68 65 20 72 65 73 75 d using the resu
14c30 6c 74 2c 20 69 74 20 73 68 6f 75 6c 64 0a 2a 2a lt, it should.**
14c40 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 pass the pointe
14c50 72 20 74 6f 20 74 68 65 20 72 65 73 75 6c 74 20 r to the result
14c60 74 61 62 6c 65 20 74 6f 20 73 71 6c 69 74 65 33 table to sqlite3
14c70 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e _free_table() in
14c80 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c order to.** rel
14c90 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 ease the memory
14ca0 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 that was malloce
14cb0 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 d. Because of t
14cc0 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 he way the.** [s
14cd0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
14ce0 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 happens within
14cf0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
14d00 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 e(), the calling
14d10 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 .** function mus
14d20 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c t not try to cal
14d30 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 l [sqlite3_free(
14d40 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e )] directly. On
14d50 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 ly.** [sqlite3_f
14d60 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 ree_table()] is
14d70 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 able to release
14d80 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 the memory prope
14d90 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a rly and safely..
14da0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
14db0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 3_get_table() in
14dc0 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 terface is imple
14dd0 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 mented as a wrap
14de0 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 per around.** [s
14df0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 qlite3_exec()].
14e00 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 The sqlite3_get
14e10 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 _table() routine
14e20 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 does not have a
14e30 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 ccess.** to any
14e40 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 internal data st
14e50 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 ructures of SQLi
14e60 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c te. It uses onl
14e70 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 y the public.**
14e80 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 interface define
14e90 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f d here. As a co
14ea0 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 nsequence, error
14eb0 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 s that occur in
14ec0 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c the.** wrapper l
14ed0 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 ayer outside of
14ee0 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 the internal [sq
14ef0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 lite3_exec()] ca
14f00 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 ll are not.** re
14f10 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 flected in subse
14f20 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b quent calls to [
14f30 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
14f40 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 )] or [sqlite3_e
14f50 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 rrmsg()]..**.**
14f60 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
14f70 2a 20 7b 48 31 32 33 37 31 7d 20 49 66 20 61 20 * {H12371} If a
14f80 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 [sqlite3_get_tab
14f90 6c 65 28 29 5d 20 66 61 69 6c 73 20 61 20 6d 65 le()] fails a me
14fa0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c mory allocation,
14fb0 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 then.**
14fc0 20 20 69 74 20 73 68 61 6c 6c 20 66 72 65 65 20 it shall free
14fd0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 the result table
14fe0 20 75 6e 64 65 72 20 63 6f 6e 73 74 72 75 63 74 under construct
14ff0 69 6f 6e 2c 20 61 62 6f 72 74 20 74 68 65 0a 2a ion, abort the.*
15000 2a 20 20 20 20 20 20 20 20 20 20 71 75 65 72 79 * query
15010 20 69 6e 20 70 72 6f 63 65 73 73 2c 20 73 6b 69 in process, ski
15020 70 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 p any subsequent
15030 20 71 75 65 72 69 65 73 2c 20 73 65 74 20 74 68 queries, set th
15040 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 2a 70 e.** *p
15050 61 7a 52 65 73 75 6c 74 20 6f 75 74 70 75 74 20 azResult output
15060 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20 pointer to NULL
15070 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 and return [SQLI
15080 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a TE_NOMEM]..**.**
15090 20 7b 48 31 32 33 37 33 7d 20 49 66 20 74 68 65 {H12373} If the
150a0 20 70 6e 43 6f 6c 75 6d 6e 20 70 61 72 61 6d 65 pnColumn parame
150b0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
150c0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 get_table()] is
150d0 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 not NULL.**
150e0 20 20 20 20 20 74 68 65 6e 20 61 20 73 75 63 63 then a succ
150f0 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f essful invocatio
15100 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 n of [sqlite3_ge
15110 74 5f 74 61 62 6c 65 28 29 5d 20 73 68 61 6c 6c t_table()] shall
15120 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 72 69 .** wri
15130 74 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 te the number of
15140 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a columns in the.
15150 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75 ** resu
15160 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20 71 75 lt set of the qu
15170 65 72 79 20 69 6e 74 6f 20 2a 70 6e 43 6f 6c 75 ery into *pnColu
15180 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 mn..**.** {H1237
15190 34 7d 20 49 66 20 74 68 65 20 70 6e 52 6f 77 20 4} If the pnRow
151a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
151b0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
151c0 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a )] is not NULL.*
151d0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 * then
151e0 61 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 a successful inv
151f0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 ocation of [sqli
15200 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d te3_get_table()]
15210 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 shall.**
15220 20 20 20 77 72 69 74 65 73 20 74 68 65 20 6e 75 writes the nu
15230 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 20 mber of rows in
15240 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
15250 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 result set of th
15260 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a 70 6e e query into *pn
15270 52 6f 77 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 Row..**.** {H123
15280 37 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 76} A successful
15290 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b invocation of [
152a0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
152b0 65 28 29 5d 20 74 68 61 74 20 63 6f 6d 70 75 74 e()] that comput
152c0 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e es.** N
152d0 20 72 6f 77 73 20 6f 66 20 72 65 73 75 6c 74 20 rows of result
152e0 77 69 74 68 20 43 20 63 6f 6c 75 6d 6e 73 20 70 with C columns p
152f0 65 72 20 72 6f 77 20 73 68 61 6c 6c 20 6d 61 6b er row shall mak
15300 65 20 2a 70 61 7a 52 65 73 75 6c 74 0a 2a 2a 20 e *pazResult.**
15310 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 20 74 point t
15320 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f o an array of po
15330 69 6e 74 65 72 73 20 74 6f 20 28 4e 2b 31 29 2a inters to (N+1)*
15340 43 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 C strings where
15350 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 the first.**
15360 20 20 20 20 20 20 43 20 73 74 72 69 6e 67 73 20 C strings
15370 61 72 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 are column names
15380 20 61 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f as obtained fro
15390 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 m.** [s
153a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
153b0 6d 65 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 me()] and the re
153c0 73 74 20 61 72 65 20 63 6f 6c 75 6d 6e 20 72 65 st are column re
153d0 73 75 6c 74 20 76 61 6c 75 65 73 0a 2a 2a 20 20 sult values.**
153e0 20 20 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64 obtained
153f0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 from [sqlite3_c
15400 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a olumn_text()]..*
15410 2a 0a 2a 2a 20 7b 48 31 32 33 37 39 7d 20 54 68 *.** {H12379} Th
15420 65 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20 e values in the
15430 70 61 7a 52 65 73 75 6c 74 20 61 72 72 61 79 20 pazResult array
15440 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
15450 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
15460 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 ].** sh
15470 61 6c 6c 20 72 65 6d 61 69 6e 20 76 61 6c 69 64 all remain valid
15480 20 75 6e 74 69 6c 20 63 6c 65 61 72 65 64 20 62 until cleared b
15490 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f y [sqlite3_free_
154a0 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 table()]..**.**
154b0 7b 48 31 32 33 38 32 7d 20 57 68 65 6e 20 61 6e {H12382} When an
154c0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 error occurs du
154d0 72 69 6e 67 20 65 76 61 6c 75 61 74 69 6f 6e 20 ring evaluation
154e0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f of [sqlite3_get_
154f0 74 61 62 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 table()].**
15500 20 20 20 20 20 74 68 65 20 66 75 6e 63 74 69 6f the functio
15510 6e 20 73 68 61 6c 6c 20 73 65 74 20 2a 70 61 7a n shall set *paz
15520 52 65 73 75 6c 74 20 74 6f 20 4e 55 4c 4c 2c 20 Result to NULL,
15530 77 72 69 74 65 20 61 6e 20 65 72 72 6f 72 20 6d write an error m
15540 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 essage.**
15550 20 20 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f into memory o
15560 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
15570 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c lite3_malloc()],
15580 20 6d 61 6b 65 0a 2a 2a 20 20 20 20 20 20 20 20 make.**
15590 20 20 2a 2a 70 7a 45 72 72 6d 73 67 20 70 6f 69 **pzErrmsg poi
155a0 6e 74 20 74 6f 20 74 68 61 74 20 65 72 72 6f 72 nt to that error
155b0 20 6d 65 73 73 61 67 65 2c 20 61 6e 64 20 72 65 message, and re
155c0 74 75 72 6e 20 61 0a 2a 2a 20 20 20 20 20 20 20 turn a.**
155d0 20 20 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b appropriate [
155e0 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a error code]..*/.
155f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f int sqlite3_get_
15600 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 table(. sqlite3
15610 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f *db, /
15620 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 * An open databa
15630 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 se */. const ch
15640 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a ar *zSql, /*
15650 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 SQL to be evalu
15660 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a ated */. char *
15670 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 **pazResult,
15680 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 /* Results of th
15690 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 e query */. int
156a0 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 *pnRow,
156b0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 /* Number of
156c0 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 result rows writ
156d0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e ten here */. in
156e0 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 t *pnColumn,
156f0 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 /* Number of
15700 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 result columns
15710 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a written here */.
15720 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 char **pzErrms
15730 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 g /* Error
15740 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 msg written her
15750 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c e */.);.void sql
15760 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 ite3_free_table(
15770 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a char **result);.
15780 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
15790 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e Formatted Strin
157a0 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 g Printing Funct
157b0 69 6f 6e 73 20 7b 48 31 37 34 30 30 7d 20 3c 53 ions {H17400} <S
157c0 37 30 30 30 30 3e 3c 53 32 30 30 30 30 3e 0a 2a 70000><S20000>.*
157d0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
157e0 6e 65 73 20 61 72 65 20 77 6f 72 6b 61 6c 69 6b nes are workalik
157f0 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 es of the "print
15800 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 f()" family of f
15810 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d unctions.** from
15820 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 the standard C
15830 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 library..**.** T
15840 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e he sqlite3_mprin
15850 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 tf() and sqlite3
15860 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 _vmprintf() rout
15870 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 ines write their
15880 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f .** results into
15890 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 memory obtained
158a0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
158b0 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 alloc()]..** The
158c0 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 strings returne
158d0 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 d by these two r
158e0 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 outines should b
158f0 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 e.** released by
15900 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
15910 5d 2e 20 20 42 6f 74 68 20 72 6f 75 74 69 6e 65 ]. Both routine
15920 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 s return a.** NU
15930 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 LL pointer if [s
15940 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
15950 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c is unable to al
15960 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a locate enough.**
15970 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 memory to hold
15980 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 the resulting st
15990 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 ring..**.** In s
159a0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
159b0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d ) routine is sim
159c0 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 ilar to "snprint
159d0 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 f()" from.** the
159e0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 standard C libr
159f0 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 ary. The result
15a00 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f is written into
15a10 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 the.** buffer s
15a20 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 upplied as the s
15a30 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
15a40 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 whose size is gi
15a50 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 ven by.** the fi
15a60 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e rst parameter. N
15a70 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 ote that the ord
15a80 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 er of the.** fir
15a90 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 st two parameter
15aa0 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 s is reversed fr
15ab0 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 20 20 om snprintf().
15ac0 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 This is an.** hi
15ad0 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e storical acciden
15ae0 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 t that cannot be
15af0 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 fixed without b
15b00 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 reaking.** backw
15b10 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 ards compatibili
15b20 74 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f 20 74 ty. Note also t
15b30 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 hat sqlite3_snpr
15b40 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e intf().** return
15b50 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 s a pointer to i
15b60 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 ts buffer instea
15b70 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 d of the number
15b80 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 of.** characters
15b90 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 actually writte
15ba0 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 n into the buffe
15bb0 72 2e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 r. We admit tha
15bc0 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 t.** the number
15bd0 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 of characters wr
15be0 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 itten would be a
15bf0 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 more useful ret
15c00 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 urn.** value but
15c10 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 we cannot chang
15c20 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 e the implementa
15c30 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f tion of sqlite3_
15c40 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f snprintf().** no
15c50 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 w without breaki
15c60 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ng compatibility
15c70 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 ..**.** As long
15c80 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 as the buffer si
15c90 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 ze is greater th
15ca0 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 an zero, sqlite3
15cb0 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 _snprintf().** g
15cc0 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 uarantees that t
15cd0 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 he buffer is alw
15ce0 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 ays zero-termina
15cf0 74 65 64 2e 20 20 54 68 65 20 66 69 72 73 74 0a ted. The first.
15d00 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 ** parameter "n"
15d10 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 is the total si
15d20 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 ze of the buffer
15d30 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 , including spac
15d40 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 e for.** the zer
15d50 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 o terminator. S
15d60 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 o the longest st
15d70 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 ring that can be
15d80 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 completely.** w
15d90 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e ritten will be n
15da0 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a -1 characters..*
15db0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
15dc0 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e nes all implemen
15dd0 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 t some additiona
15de0 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 l formatting.**
15df0 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 options that are
15e00 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 useful for cons
15e10 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 tructing SQL sta
15e20 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 tements..** All
15e30 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 of the usual pri
15e40 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 ntf() formatting
15e50 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 options apply.
15e60 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 In addition, th
15e70 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 ere.** is are "%
15e80 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 q", "%Q", and "%
15e90 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a z" options..**.*
15ea0 2a 20 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 * The %q option
15eb0 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e works like %s in
15ec0 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 that it substit
15ed0 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d utes a null-term
15ee0 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 inated.** string
15ef0 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 from the argume
15f00 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 nt list. But %q
15f10 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 also doubles ev
15f20 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 ery '\'' charact
15f30 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 er..** %q is des
15f40 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e igned for use in
15f50 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 side a string li
15f60 74 65 72 61 6c 2e 20 20 42 79 20 64 6f 75 62 6c teral. By doubl
15f70 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a ing each '\''.**
15f80 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73 character it es
15f90 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61 capes that chara
15fa0 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 cter and allows
15fb0 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 it to be inserte
15fc0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 d into.** the st
15fd0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 ring..**.** For
15fe0 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 example, assume
15ff0 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 the string varia
16000 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 ble zText contai
16010 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f ns text as follo
16020 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b ws:.**.** <block
16030 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
16040 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 char *zText = "I
16050 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 t's a happy day!
16060 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c ";.** </pre></bl
16070 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
16080 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 One can use this
16090 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 text in an SQL
160a0 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c statement as fol
160b0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f lows:.**.** <blo
160c0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
160d0 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 char *zSQL = s
160e0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 qlite3_mprintf("
160f0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c INSERT INTO tabl
16100 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c e VALUES('%q')",
16110 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c zText);.** sql
16120 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 ite3_exec(db, zS
16130 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a QL, 0, 0, 0);.**
16140 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a sqlite3_free(z
16150 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c SQL);.** </pre><
16160 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
16170 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25 ** Because the %
16180 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 q format string
16190 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 is used, the '\'
161a0 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a ' character in z
161b0 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 Text.** is escap
161c0 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 ed and the SQL g
161d0 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66 enerated is as f
161e0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ollows:.**.** <b
161f0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
16200 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 ** INSERT INTO
16210 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 table1 VALUES('I
16220 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79 t''s a happy day
16230 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 !').** </pre></b
16240 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
16250 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 This is correct
16260 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25 . Had we used %
16270 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c s instead of %q,
16280 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 the generated S
16290 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 QL.** would have
162a0 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 looked like thi
162b0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s:.**.** <blockq
162c0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 uote><pre>.** I
162d0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 NSERT INTO table
162e0 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 1 VALUES('It's a
162f0 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a happy day!');.*
16300 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
16310 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 uote>.**.** This
16320 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 second example
16330 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 is an SQL syntax
16340 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 error. As a ge
16350 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 neral rule you s
16360 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 hould.** always
16370 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f use %q instead o
16380 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 f %s when insert
16390 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 ing text into a
163a0 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a string literal..
163b0 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f 70 74 **.** The %Q opt
163c0 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 ion works like %
163d0 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f q except it also
163e0 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f adds single quo
163f0 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 tes around.** th
16400 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 e outside of the
16410 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 total string.
16420 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 Additionally, if
16430 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 the parameter i
16440 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e n the.** argumen
16450 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c t list is a NULL
16460 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 pointer, %Q sub
16470 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 stitutes the tex
16480 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 t "NULL" (withou
16490 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 t.** single quot
164a0 65 73 29 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 es) in place of
164b0 74 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e 20 20 the %Q option.
164c0 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c So, for example,
164d0 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a one could say:.
164e0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
164f0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 e><pre>.** char
16500 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 *zSQL = sqlite3
16510 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 _mprintf("INSERT
16520 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 INTO table VALU
16530 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b ES(%Q)", zText);
16540 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 .** sqlite3_exe
16550 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 c(db, zSQL, 0, 0
16560 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 , 0);.** sqlite
16570 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 3_free(zSQL);.**
16580 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
16590 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 ote>.**.** The c
165a0 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 ode above will r
165b0 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 ender a correct
165c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e SQL statement in
165d0 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 the zSQL.** var
165e0 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 iable even if th
165f0 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 e zText variable
16600 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
16610 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 25 er..**.** The "%
16620 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 z" formatting op
16630 74 69 6f 6e 20 77 6f 72 6b 73 20 65 78 61 63 74 tion works exact
16640 6c 79 20 6c 69 6b 65 20 22 25 73 22 20 77 69 74 ly like "%s" wit
16650 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f h the.** additio
16660 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 n that after the
16670 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e string has been
16680 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 read and copied
16690 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 into.** the res
166a0 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 ult, [sqlite3_fr
166b0 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 ee()] is called
166c0 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 on the input str
166d0 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a ing. {END}.**.**
166e0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
166f0 2a 2a 20 7b 48 31 37 34 30 33 7d 20 20 54 68 65 ** {H17403} The
16700 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 [sqlite3_mprint
16710 66 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 f()] and [sqlite
16720 33 5f 76 6d 70 72 69 6e 74 66 28 29 5d 20 69 6e 3_vmprintf()] in
16730 74 65 72 66 61 63 65 73 0a 2a 2a 20 20 20 20 20 terfaces.**
16740 20 20 20 20 20 20 72 65 74 75 72 6e 20 65 69 74 return eit
16750 68 65 72 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 her pointers to
16760 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
16770 55 54 46 2d 38 20 73 74 72 69 6e 67 73 20 68 65 UTF-8 strings he
16780 6c 64 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 ld in.**
16790 20 20 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e memory obtain
167a0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
167b0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 4e 55 _malloc()] or NU
167c0 4c 4c 20 70 6f 69 6e 74 65 72 73 20 69 66 0a 2a LL pointers if.*
167d0 2a 20 20 20 20 20 20 20 20 20 20 20 61 20 63 61 * a ca
167e0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d ll to [sqlite3_m
167f0 61 6c 6c 6f 63 28 29 5d 20 66 61 69 6c 73 2e 0a alloc()] fails..
16800 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 36 7d 20 20 **.** {H17406}
16810 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 The [sqlite3_snp
16820 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61 rintf()] interfa
16830 63 65 20 77 72 69 74 65 73 20 61 20 7a 65 72 6f ce writes a zero
16840 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 -terminated.**
16850 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20 73 UTF-8 s
16860 74 72 69 6e 67 20 69 6e 74 6f 20 74 68 65 20 62 tring into the b
16870 75 66 66 65 72 20 70 6f 69 6e 74 65 64 20 74 6f uffer pointed to
16880 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 by the second p
16890 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 arameter.**
168a0 20 20 20 20 20 20 70 72 6f 76 69 64 65 64 20 74 provided t
168b0 68 61 74 20 74 68 65 20 66 69 72 73 74 20 70 61 hat the first pa
168c0 72 61 6d 65 74 65 72 20 69 73 20 67 72 65 61 74 rameter is great
168d0 65 72 20 74 68 61 6e 20 7a 65 72 6f 2e 0a 2a 2a er than zero..**
168e0 0a 2a 2a 20 7b 48 31 37 34 30 37 7d 20 20 54 68 .** {H17407} Th
168f0 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 e [sqlite3_snpri
16900 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ntf()] interface
16910 20 64 6f 65 73 20 6e 6f 74 20 77 72 69 74 65 20 does not write
16920 73 6c 6f 74 73 20 6f 66 0a 2a 2a 20 20 20 20 20 slots of.**
16930 20 20 20 20 20 20 69 74 73 20 6f 75 74 70 75 74 its output
16940 20 62 75 66 66 65 72 20 28 74 68 65 20 73 65 63 buffer (the sec
16950 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 29 20 6f ond parameter) o
16960 75 74 73 69 64 65 20 74 68 65 20 72 61 6e 67 65 utside the range
16970 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 66 .** of
16980 20 30 20 74 68 72 6f 75 67 68 20 4e 2d 31 20 28 0 through N-1 (
16990 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 66 where N is the f
169a0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a irst parameter).
169b0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 67 ** reg
169c0 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6c ardless of the l
169d0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 ength of the str
169e0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ing.**
169f0 20 72 65 71 75 65 73 74 65 64 20 62 79 20 74 68 requested by th
16a00 65 20 66 6f 72 6d 61 74 20 73 70 65 63 69 66 69 e format specifi
16a10 63 61 74 69 6f 6e 2e 0a 2a 2f 0a 63 68 61 72 20 cation..*/.char
16a20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 *sqlite3_mprintf
16a30 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e (const char*,...
16a40 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 );.char *sqlite3
16a50 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 _vmprintf(const
16a60 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b char*, va_list);
16a70 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 .char *sqlite3_s
16a80 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 nprintf(int,char
16a90 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e *,const char*, .
16aa0 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ..);../*.** CAPI
16ab0 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 3REF: Memory All
16ac0 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 ocation Subsyste
16ad0 6d 20 7b 48 31 37 33 30 30 7d 20 3c 53 32 30 30 m {H17300} <S200
16ae0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 00>.**.** The SQ
16af0 4c 69 74 65 20 63 6f 72 65 20 20 75 73 65 73 20 Lite core uses
16b00 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 these three rout
16b10 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 ines for all of
16b20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 its own.** inter
16b30 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 nal memory alloc
16b40 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f ation needs. "Co
16b50 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 re" in the previ
16b60 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 ous sentence.**
16b70 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 does not include
16b80 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 operating-syste
16b90 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 m specific VFS i
16ba0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 mplementation.
16bb0 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 The.** Windows V
16bc0 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d FS uses native m
16bd0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 alloc() and free
16be0 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 () for some oper
16bf0 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 ations..**.** Th
16c00 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 e sqlite3_malloc
16c10 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 () routine retur
16c20 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
16c30 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 a block.** of me
16c40 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 mory at least N
16c50 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c bytes in length,
16c60 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 where N is the
16c70 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 49 66 parameter..** If
16c80 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
16c90 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f ) is unable to o
16ca0 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 btain sufficient
16cb0 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c free.** memory,
16cc0 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 it returns a NU
16cd0 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 LL pointer. If
16ce0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 the parameter N
16cf0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 to.** sqlite3_ma
16d00 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f lloc() is zero o
16d10 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 r negative then
16d20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
16d30 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 returns.** a NU
16d40 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
16d50 2a 20 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 * Calling sqlite
16d60 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20 3_free() with a
16d70 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 pointer previous
16d80 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 ly returned.** b
16d90 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 y sqlite3_malloc
16da0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 () or sqlite3_re
16db0 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 alloc() releases
16dc0 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a that memory so.
16dd0 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 ** that it might
16de0 20 62 65 20 72 65 75 73 65 64 2e 20 20 54 68 65 be reused. The
16df0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 sqlite3_free()
16e00 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 routine is.** a
16e10 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c no-op if is call
16e20 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 ed with a NULL p
16e30 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 ointer. Passing
16e40 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a a NULL pointer.
16e50 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 ** to sqlite3_fr
16e60 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 ee() is harmless
16e70 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 . After being f
16e80 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 reed, memory.**
16e90 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 should neither b
16ea0 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 e read nor writt
16eb0 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e en. Even readin
16ec0 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 g previously fre
16ed0 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 ed.** memory mig
16ee0 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 ht result in a s
16ef0 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c egmentation faul
16f00 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 t or other sever
16f10 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f e error..** Memo
16f20 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 ry corruption, a
16f30 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 segmentation fa
16f40 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 ult, or other se
16f50 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 vere error.** mi
16f60 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 ght result if sq
16f70 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 lite3_free() is
16f80 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f called with a no
16f90 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 n-NULL pointer t
16fa0 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f hat.** was not o
16fb0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c btained from sql
16fc0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 ite3_malloc() or
16fd0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
16fe0 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ()..**.** The sq
16ff0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 lite3_realloc()
17000 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 interface attemp
17010 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a ts to resize a.*
17020 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 * prior memory a
17030 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 llocation to be
17040 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 at least N bytes
17050 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 , where N is the
17060 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d .** second param
17070 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 eter. The memor
17080 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 y allocation to
17090 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 be resized is th
170a0 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d e first.** param
170b0 65 74 65 72 2e 20 20 49 66 20 74 68 65 20 66 69 eter. If the fi
170c0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f rst parameter to
170d0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
170e0 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 ().** is a NULL
170f0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 pointer then its
17100 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 behavior is ide
17110 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e ntical to callin
17120 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c g.** sqlite3_mal
17130 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 loc(N) where N i
17140 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 s the second par
17150 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
17160 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 3_realloc()..**
17170 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 If the second pa
17180 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
17190 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 e3_realloc() is
171a0 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 zero or.** negat
171b0 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 ive then the beh
171c0 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 avior is exactly
171d0 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c the same as cal
171e0 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ling.** sqlite3_
171f0 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20 free(P) where P
17200 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 is the first par
17210 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
17220 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 3_realloc()..**
17230 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
17240 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e ) returns a poin
17250 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 ter to a memory
17260 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 allocation.** of
17270 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 at least N byte
17280 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c s in size or NUL
17290 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 L if sufficient
172a0 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 memory is unavai
172b0 6c 61 62 6c 65 2e 0a 2a 2a 20 49 66 20 4d 20 69 lable..** If M i
172c0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 s the size of th
172d0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 e prior allocati
172e0 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d on, then min(N,M
172f0 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 ) bytes.** of th
17300 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 e prior allocati
17310 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e on are copied in
17320 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 to the beginning
17330 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72 of buffer retur
17340 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 ned.** by sqlite
17350 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 3_realloc() and
17360 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 the prior alloca
17370 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a tion is freed..*
17380 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 * If sqlite3_rea
17390 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e lloc() returns N
173a0 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 ULL, then the pr
173b0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a ior allocation.*
173c0 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a * is not freed..
173d0 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 **.** The memory
173e0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
173f0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e ite3_malloc() an
17400 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f d sqlite3_reallo
17410 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 c().** is always
17420 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c aligned to at l
17430 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 east an 8 byte b
17440 6f 75 6e 64 61 72 79 2e 20 7b 45 4e 44 7d 0a 2a oundary. {END}.*
17450 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 *.** The default
17460 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
17470 6f 66 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c of the memory al
17480 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 location subsyst
17490 65 6d 20 75 73 65 73 0a 2a 2a 20 74 68 65 20 6d em uses.** the m
174a0 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 alloc(), realloc
174b0 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 70 72 () and free() pr
174c0 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 73 74 ovided by the st
174d0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 andard C library
174e0 2e 0a 2a 2a 20 7b 48 31 37 33 38 32 7d 20 48 6f ..** {H17382} Ho
174f0 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 wever, if SQLite
17500 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
17510 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f h the.** SQLITE_
17520 4d 45 4d 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e MEMORY_SIZE=<i>N
17530 4e 4e 3c 2f 69 3e 20 43 20 70 72 65 70 72 6f 63 NN</i> C preproc
17540 65 73 73 6f 72 20 6d 61 63 72 6f 20 28 77 68 65 essor macro (whe
17550 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 0a 2a 2a re <i>NNN</i>.**
17560 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 29 2c is an integer),
17570 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 72 65 then SQLite cre
17580 61 74 65 20 61 20 73 74 61 74 69 63 20 61 72 72 ate a static arr
17590 61 79 20 6f 66 20 61 74 20 6c 65 61 73 74 0a 2a ay of at least.*
175a0 2a 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74 * <i>NNN</i> byt
175b0 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 20 75 es in size and u
175c0 73 65 73 20 74 68 61 74 20 61 72 72 61 79 20 66 ses that array f
175d0 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 or all of its dy
175e0 6e 61 6d 69 63 0a 2a 2a 20 6d 65 6d 6f 72 79 20 namic.** memory
175f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 allocation needs
17600 2e 20 7b 45 4e 44 7d 20 20 41 64 64 69 74 69 6f . {END} Additio
17610 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 nal memory alloc
17620 61 74 6f 72 20 6f 70 74 69 6f 6e 73 0a 2a 2a 20 ator options.**
17630 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 may be added in
17640 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e future releases.
17650 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 .**.** In SQLite
17660 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 version 3.5.0 a
17670 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 nd 3.5.1, it was
17680 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 possible to def
17690 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 ine.** the SQLIT
176a0 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c E_OMIT_MEMORY_AL
176b0 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 LOCATION which w
176c0 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 ould cause the b
176d0 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 uilt-in.** imple
176e0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 mentation of the
176f0 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 se routines to b
17700 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 e omitted. That
17710 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 capability.** i
17720 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 s no longer prov
17730 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c ided. Only buil
17740 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f t-in memory allo
17750 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 cators can be us
17760 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 ed..**.** The Wi
17770 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 ndows OS interfa
17780 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a ce layer calls.*
17790 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c * the system mal
177a0 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 loc() and free()
177b0 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 directly when c
177c0 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c onverting.** fil
177d0 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 enames between t
177e0 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e he UTF-8 encodin
177f0 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 g used by SQLite
17800 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 .** and whatever
17810 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 filename encodi
17820 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 ng is used by th
17830 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e e particular Win
17840 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 dows.** installa
17850 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c tion. Memory al
17860 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 location errors
17870 61 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 are detected, bu
17880 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 t.** they are re
17890 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b ported back as [
178a0 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d SQLITE_CANTOPEN]
178b0 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 or.** [SQLITE_I
178c0 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 OERR] rather tha
178d0 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d n [SQLITE_NOMEM]
178e0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
178f0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 TS:.**.** {H1730
17900 33 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 3} The [sqlite3
17910 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 _malloc(N)] inte
17920 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 rface returns ei
17930 74 68 65 72 20 61 20 70 6f 69 6e 74 65 72 20 74 ther a pointer t
17940 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 o.** a
17950 20 6e 65 77 6c 79 20 63 68 65 63 6b 65 64 2d 6f newly checked-o
17960 75 74 20 62 6c 6f 63 6b 20 6f 66 20 61 74 20 6c ut block of at l
17970 65 61 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 east N bytes of
17980 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 memory.**
17990 20 20 20 20 74 68 61 74 20 69 73 20 38 2d 62 79 that is 8-by
179a0 74 65 20 61 6c 69 67 6e 65 64 2c 20 6f 72 20 69 te aligned, or i
179b0 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 t returns NULL i
179c0 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 0a 2a f it is unable.*
179d0 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 66 * to f
179e0 75 6c 66 69 6c 6c 20 74 68 65 20 72 65 71 75 65 ulfill the reque
179f0 73 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 st..**.** {H1730
17a00 34 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 4} The [sqlite3
17a10 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 _malloc(N)] inte
17a20 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
17a30 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 0a NULL pointer if.
17a40 2a 2a 20 20 20 20 20 20 20 20 20 20 20 4e 20 69 ** N i
17a50 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 s less than or e
17a60 71 75 61 6c 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a qual to zero..**
17a70 0a 2a 2a 20 7b 48 31 37 33 30 35 7d 20 20 54 68 .** {H17305} Th
17a80 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 e [sqlite3_free(
17a90 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 P)] interface re
17aa0 6c 65 61 73 65 73 20 6d 65 6d 6f 72 79 20 70 72 leases memory pr
17ab0 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 eviously.**
17ac0 20 20 20 20 20 20 72 65 74 75 72 6e 65 64 20 66 returned f
17ad0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c rom [sqlite3_mal
17ae0 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 loc()] or [sqlit
17af0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a e3_realloc()],.*
17b00 2a 20 20 20 20 20 20 20 20 20 20 20 6d 61 6b 69 * maki
17b10 6e 67 20 69 74 20 61 76 61 69 6c 61 62 6c 65 20 ng it available
17b20 66 6f 72 20 72 65 75 73 65 2e 0a 2a 2a 0a 2a 2a for reuse..**.**
17b30 20 7b 48 31 37 33 30 36 7d 20 20 41 20 63 61 6c {H17306} A cal
17b40 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 l to [sqlite3_fr
17b50 65 65 28 4e 55 4c 4c 29 5d 20 69 73 20 61 20 68 ee(NULL)] is a h
17b60 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a armless no-op..*
17b70 2a 0a 2a 2a 20 7b 48 31 37 33 31 30 7d 20 20 41 *.** {H17310} A
17b80 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
17b90 33 5f 72 65 61 6c 6c 6f 63 28 30 2c 4e 29 5d 20 3_realloc(0,N)]
17ba0 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f is equivalent to
17bb0 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 a call.**
17bc0 20 20 20 20 20 74 6f 20 5b 73 71 6c 69 74 65 33 to [sqlite3
17bd0 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 2e 0a 2a 2a 0a _malloc(N)]..**.
17be0 2a 2a 20 7b 48 31 37 33 31 32 7d 20 20 41 20 63 ** {H17312} A c
17bf0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
17c00 72 65 61 6c 6c 6f 63 28 50 2c 30 29 5d 20 69 73 realloc(P,0)] is
17c10 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 61 equivalent to a
17c20 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 call.**
17c30 20 20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 to [sqlite3_f
17c40 72 65 65 28 50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b ree(P)]..**.** {
17c50 48 31 37 33 31 35 7d 20 20 54 68 65 20 53 51 4c H17315} The SQL
17c60 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 5b 73 ite core uses [s
17c70 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
17c80 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c , [sqlite3_reall
17c90 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 oc()],.**
17ca0 20 20 20 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 and [sqlite3
17cb0 5f 66 72 65 65 28 29 5d 20 66 6f 72 20 61 6c 6c _free()] for all
17cc0 20 6f 66 20 69 74 73 20 6d 65 6d 6f 72 79 20 61 of its memory a
17cd0 6c 6c 6f 63 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a llocation and.**
17ce0 20 20 20 20 20 20 20 20 20 20 20 64 65 61 6c 6c deall
17cf0 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a ocation needs..*
17d00 2a 0a 2a 2a 20 7b 48 31 37 33 31 38 7d 20 20 54 *.** {H17318} T
17d10 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c he [sqlite3_real
17d20 6c 6f 63 28 50 2c 4e 29 5d 20 69 6e 74 65 72 66 loc(P,N)] interf
17d30 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 ace returns eith
17d40 65 72 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 er a pointer.**
17d50 20 20 20 20 20 20 20 20 20 20 74 6f 20 61 20 62 to a b
17d60 6c 6f 63 6b 20 6f 66 20 63 68 65 63 6b 65 64 2d lock of checked-
17d70 6f 75 74 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 out memory of at
17d80 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 least N bytes i
17d90 6e 20 73 69 7a 65 0a 2a 2a 20 20 20 20 20 20 20 n size.**
17da0 20 20 20 20 74 68 61 74 20 69 73 20 38 2d 62 79 that is 8-by
17db0 74 65 20 61 6c 69 67 6e 65 64 2c 20 6f 72 20 61 te aligned, or a
17dc0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a NULL pointer..*
17dd0 2a 0a 2a 2a 20 7b 48 31 37 33 32 31 7d 20 20 57 *.** {H17321} W
17de0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 hen [sqlite3_rea
17df0 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 lloc(P,N)] retur
17e00 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f ns a non-NULL po
17e10 69 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74 0a inter, it first.
17e20 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f 70 ** cop
17e30 69 65 73 20 74 68 65 20 66 69 72 73 74 20 4b 20 ies the first K
17e40 62 79 74 65 73 20 6f 66 20 63 6f 6e 74 65 6e 74 bytes of content
17e50 20 66 72 6f 6d 20 50 20 69 6e 74 6f 20 74 68 65 from P into the
17e60 20 6e 65 77 6c 79 0a 2a 2a 20 20 20 20 20 20 20 newly.**
17e70 20 20 20 20 61 6c 6c 6f 63 61 74 65 64 20 62 6c allocated bl
17e80 6f 63 6b 2c 20 77 68 65 72 65 20 4b 20 69 73 20 ock, where K is
17e90 74 68 65 20 6c 65 73 73 65 72 20 6f 66 20 4e 20 the lesser of N
17ea0 61 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 0a and the size of.
17eb0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65 ** the
17ec0 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a buffer P..**.**
17ed0 20 7b 48 31 37 33 32 32 7d 20 20 57 68 65 6e 20 {H17322} When
17ee0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
17ef0 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 (P,N)] returns a
17f00 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 non-NULL pointe
17f10 72 2c 20 69 74 20 66 69 72 73 74 0a 2a 2a 20 20 r, it first.**
17f20 20 20 20 20 20 20 20 20 20 72 65 6c 65 61 73 65 release
17f30 73 20 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a s the buffer P..
17f40 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 33 7d 20 20 **.** {H17323}
17f50 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 When [sqlite3_re
17f60 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 alloc(P,N)] retu
17f70 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 20 62 75 rns NULL, the bu
17f80 66 66 65 72 20 50 20 69 73 0a 2a 2a 20 20 20 20 ffer P is.**
17f90 20 20 20 20 20 20 20 6e 6f 74 20 6d 6f 64 69 66 not modif
17fa0 69 65 64 20 6f 72 20 72 65 6c 65 61 73 65 64 2e ied or released.
17fb0 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f .**.** ASSUMPTIO
17fc0 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 37 33 35 NS:.**.** {A1735
17fd0 30 7d 20 20 54 68 65 20 70 6f 69 6e 74 65 72 20 0} The pointer
17fe0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 arguments to [sq
17ff0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e lite3_free()] an
18000 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c d [sqlite3_reall
18010 6f 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 oc()].**
18020 20 20 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 must be eithe
18030 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 r NULL or else p
18040 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 ointers obtained
18050 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a from a prior.**
18060 20 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f 63 invoc
18070 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 ation of [sqlite
18080 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 3_malloc()] or [
18090 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
180a0 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 )] that have.**
180b0 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20 79 65 not ye
180c0 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e t been released.
180d0 0a 2a 2a 0a 2a 2a 20 7b 41 31 37 33 35 31 7d 20 .**.** {A17351}
180e0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
180f0 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f must not read o
18100 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 r write any part
18110 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 of.**
18120 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f a block of memo
18130 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 ry after it has
18140 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 been released us
18150 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ing.**
18160 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
18170 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ] or [sqlite3_re
18180 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 alloc()]..*/.voi
18190 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f d *sqlite3_mallo
181a0 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 c(int);.void *sq
181b0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f lite3_realloc(vo
181c0 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 id*, int);.void
181d0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 sqlite3_free(voi
181e0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d*);../*.** CAPI
181f0 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 3REF: Memory All
18200 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 ocator Statistic
18210 73 20 7b 48 31 37 33 37 30 7d 20 3c 53 33 30 32 s {H17370} <S302
18220 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 10>.**.** SQLite
18230 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 provides these
18240 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 two interfaces f
18250 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 or reporting on
18260 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 the status.** of
18270 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 the [sqlite3_ma
18280 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 lloc()], [sqlite
18290 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 3_free()], and [
182a0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
182b0 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 )].** routines,
182c0 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 which form the b
182d0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 uilt-in memory a
182e0 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 llocation subsys
182f0 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 tem..**.** INVAR
18300 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
18310 37 33 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 7371} The [sqlit
18320 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
18330 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ] routine return
18340 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
18350 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 bytes.**
18360 20 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 of memory curr
18370 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e ently outstandin
18380 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 g (malloced but
18390 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 0a 2a not freed)..**.*
183a0 2a 20 7b 48 31 37 33 37 33 7d 20 54 68 65 20 5b * {H17373} The [
183b0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 sqlite3_memory_h
183c0 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 ighwater()] rout
183d0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ine returns the
183e0 6d 61 78 69 6d 75 6d 0a 2a 2a 20 20 20 20 20 20 maximum.**
183f0 20 20 20 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 value of [sq
18400 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 lite3_memory_use
18410 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 d()] since the h
18420 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a igh-water mark.*
18430 2a 20 20 20 20 20 20 20 20 20 20 77 61 73 20 6c * was l
18440 61 73 74 20 72 65 73 65 74 2e 0a 2a 2a 0a 2a 2a ast reset..**.**
18450 20 7b 48 31 37 33 37 34 7d 20 54 68 65 20 76 61 {H17374} The va
18460 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 lues returned by
18470 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
18480 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 _used()] and.**
18490 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
184a0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 3_memory_highwat
184b0 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e er()] include an
184c0 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 20 20 y overhead.**
184d0 20 20 20 20 20 20 20 61 64 64 65 64 20 62 79 20 added by
184e0 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d SQLite in its im
184f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
18500 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
18510 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 )],.**
18520 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 but not overhead
18530 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e added by the an
18540 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 y underlying sys
18550 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 20 tem library.**
18560 20 20 20 20 20 20 20 20 72 6f 75 74 69 6e 65 73 routines
18570 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d that [sqlite3_m
18580 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c alloc()] may cal
18590 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 35 l..**.** {H17375
185a0 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 } The memory hig
185b0 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 h-water mark is
185c0 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 reset to the cur
185d0 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a rent value of.**
185e0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
185f0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
18600 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 ] if and only if
18610 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 the parameter t
18620 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 o.** [s
18630 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
18640 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 ghwater()] is tr
18650 75 65 2e 20 20 54 68 65 20 76 61 6c 75 65 20 72 ue. The value r
18660 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 eturned.**
18670 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f by [sqlite3_
18680 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
18690 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 (1)] is the high
186a0 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 20 -water mark.**
186b0 20 20 20 20 20 20 20 20 70 72 69 6f 72 20 74 6f prior to
186c0 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 the reset..*/.s
186d0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c qlite3_int64 sql
186e0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 ite3_memory_used
186f0 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f (void);.sqlite3_
18700 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 int64 sqlite3_me
18710 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 mory_highwater(i
18720 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a nt resetFlag);..
18730 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
18740 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 Pseudo-Random Nu
18750 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 20 7b mber Generator {
18760 48 31 37 33 39 30 7d 20 3c 53 32 30 30 30 30 3e H17390} <S20000>
18770 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f .**.** SQLite co
18780 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 ntains a high-qu
18790 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e ality pseudo-ran
187a0 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 dom number gener
187b0 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 ator (PRNG) used
187c0 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 to.** select ra
187d0 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f ndom [ROWID | RO
187e0 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 WIDs] when inser
187f0 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 ting new records
18800 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 into a table th
18810 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 at.** already us
18820 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 es the largest p
18830 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e ossible [ROWID].
18840 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c The PRNG is al
18850 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 so used for.** t
18860 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 he build-in rand
18870 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 om() and randomb
18880 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 lob() SQL functi
18890 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 ons. This inter
188a0 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 face allows.** a
188b0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 pplications to a
188c0 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 ccess the same P
188d0 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 RNG for other pu
188e0 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 rposes..**.** A
188f0 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 call to this rou
18900 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 tine stores N by
18910 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 tes of randomnes
18920 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e s into buffer P.
18930 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
18940 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 time this routi
18950 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 ne is invoked (e
18960 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 ither internally
18970 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 or by.** the ap
18980 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 plication) the P
18990 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73 RNG is seeded us
189a0 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f ing randomness o
189b0 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 btained.** from
189c0 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 the xRandomness
189d0 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 method of the de
189e0 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 fault [sqlite3_v
189f0 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 4f fs] object..** O
18a00 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 n all subsequent
18a10 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 invocations, th
18a20 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e e pseudo-randomn
18a30 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 ess is generated
18a40 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 .** internally a
18a50 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 nd without recou
18a60 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 rse to the [sqli
18a70 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d te3_vfs] xRandom
18a80 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a ness.** method..
18a90 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 **.** INVARIANTS
18aa0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 39 32 7d :.**.** {H17392}
18ab0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 61 The [sqlite3_ra
18ac0 6e 64 6f 6d 6e 65 73 73 28 4e 2c 50 29 5d 20 69 ndomness(N,P)] i
18ad0 6e 74 65 72 66 61 63 65 20 77 72 69 74 65 73 20 nterface writes
18ae0 4e 20 62 79 74 65 73 20 6f 66 0a 2a 2a 20 20 20 N bytes of.**
18af0 20 20 20 20 20 20 20 68 69 67 68 2d 71 75 61 6c high-qual
18b00 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f ity pseudo-rando
18b10 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 mness into buffe
18b20 72 20 50 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c r P..*/.void sql
18b30 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 ite3_randomness(
18b40 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b int N, void *P);
18b50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
18b60 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 : Compile-Time A
18b70 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c uthorization Cal
18b80 6c 62 61 63 6b 73 20 7b 48 31 32 35 30 30 7d 20 lbacks {H12500}
18b90 3c 53 37 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S70100>.**.** T
18ba0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 his routine regi
18bb0 73 74 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a sters a authoriz
18bc0 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 er callback with
18bd0 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a a particular.**
18be0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
18bf0 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 ction], supplied
18c00 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
18c10 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 gument..** The a
18c20 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
18c30 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 ck is invoked as
18c40 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
18c50 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c are being compil
18c60 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 ed.** by [sqlite
18c70 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 3_prepare()] or
18c80 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 its variants [sq
18c90 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
18ca0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
18cb0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e _prepare16()] an
18cc0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 d [sqlite3_prepa
18cd0 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 re16_v2()]. At
18ce0 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 various.** point
18cf0 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d s during the com
18d00 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 pilation process
18d10 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 , as logic is be
18d20 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 ing created.** t
18d30 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 o perform variou
18d40 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 s actions, the a
18d50 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
18d60 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f ck is invoked to
18d70 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 .** see if those
18d80 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c actions are all
18d90 6f 77 65 64 2e 20 20 54 68 65 20 61 75 74 68 6f owed. The autho
18da0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 rizer callback s
18db0 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 hould.** return
18dc0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 [SQLITE_OK] to a
18dd0 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c llow the action,
18de0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d [SQLITE_IGNORE]
18df0 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 to disallow the
18e00 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 .** specific act
18e10 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 ion but allow th
18e20 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
18e30 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 to continue to b
18e40 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f e.** compiled, o
18e50 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 r [SQLITE_DENY]
18e60 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 to cause the ent
18e70 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ire SQL statemen
18e80 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 t to be.** rejec
18e90 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f ted with an erro
18ea0 72 2e 20 20 49 66 20 74 68 65 20 61 75 74 68 6f r. If the autho
18eb0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 rizer callback r
18ec0 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 eturns.** any va
18ed0 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b lue other than [
18ee0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 SQLITE_IGNORE],
18ef0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 [SQLITE_OK], or
18f00 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a [SQLITE_DENY].**
18f10 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 then the [sqlit
18f20 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
18f30 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 or equivalent c
18f40 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 all that trigger
18f50 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 ed.** the author
18f60 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 izer will fail w
18f70 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 ith an error mes
18f80 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e sage..**.** When
18f90 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
18fa0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b turns [SQLITE_OK
18fb0 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 ], that means th
18fc0 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 e operation.** r
18fd0 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 equested is ok.
18fe0 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 When the callba
18ff0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ck returns [SQLI
19000 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a TE_DENY], the.**
19010 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
19020 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 e_v2()] or equiv
19030 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 alent call that
19040 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a triggered the.**
19050 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c authorizer will
19060 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 fail with an er
19070 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c ror message expl
19080 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 aining that.** a
19090 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e ccess is denied.
190a0 20 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 If the authori
190b0 7a 65 72 20 63 6f 64 65 20 69 73 20 5b 53 51 4c zer code is [SQL
190c0 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 ITE_READ].** and
190d0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
190e0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 turns [SQLITE_IG
190f0 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a NORE] then the.*
19100 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 * [prepared stat
19110 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 ement] statement
19120 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 is constructed
19130 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a to substitute.**
19140 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e a NULL value in
19150 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 place of the ta
19160 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 ble column that
19170 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 would have.** be
19180 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 en read if [SQLI
19190 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 TE_OK] had been
191a0 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b returned. The [
191b0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a SQLITE_IGNORE].*
191c0 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 * return can be
191d0 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 used to deny an
191e0 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 untrusted user a
191f0 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 ccess to individ
19200 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f ual.** columns o
19210 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a f a table..**.**
19220 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d The first param
19230 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 eter to the auth
19240 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
19250 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 is a copy of the
19260 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 third.** parame
19270 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ter to the sqlit
19280 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
19290 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 54 r() interface. T
192a0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
192b0 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 ter.** to the ca
192c0 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 llback is an int
192d0 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 eger [SQLITE_COP
192e0 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d Y | action code]
192f0 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a that specifies.
19300 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 ** the particula
19310 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 r action to be a
19320 75 74 68 6f 72 69 7a 65 64 2e 20 54 68 65 20 74 uthorized. The t
19330 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 hird through six
19340 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a th parameters.**
19350 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
19360 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e are zero-termin
19370 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 ated strings tha
19380 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 t contain additi
19390 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 onal.** details
193a0 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e about the action
193b0 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 to be authorize
193c0 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 d..**.** An auth
193d0 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 orizer is used w
193e0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 hen [sqlite3_pre
193f0 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 pare | preparing
19400 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 ].** SQL stateme
19410 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 nts from an untr
19420 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f usted source, to
19430 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 ensure that the
19440 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a SQL statements.
19450 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f ** do not try to
19460 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 access data the
19470 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 y are not allowe
19480 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 d to see, or tha
19490 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a t they do not.**
194a0 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 try to execute
194b0 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d malicious statem
194c0 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 ents that damage
194d0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 the database.
194e0 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 For.** example,
194f0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d an application m
19500 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 ay allow a user
19510 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 to enter arbitra
19520 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 ry.** SQL querie
19530 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e s for evaluation
19540 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 by a database.
19550 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 But the applica
19560 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 tion does.** not
19570 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 want the user t
19580 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b o be able to mak
19590 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e e arbitrary chan
195a0 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 ges to the.** da
195b0 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 tabase. An auth
195c0 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 orizer could the
195d0 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 n be put in plac
195e0 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 e while the.** u
195f0 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 ser-entered SQL
19600 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 is being [sqlite
19610 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 3_prepare | prep
19620 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 ared] that.** di
19630 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 sallows everythi
19640 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 ng except [SELEC
19650 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a T] statements..*
19660 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e *.** Application
19670 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 s that need to p
19680 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 rocess SQL from
19690 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 untrusted source
196a0 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 s.** might also
196b0 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e consider lowerin
196c0 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 g resource limit
196d0 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 s using [sqlite3
196e0 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 _limit()].** and
196f0 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 limiting databa
19700 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 se size using th
19710 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e e [max_page_coun
19720 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 t] [PRAGMA].** i
19730 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 n addition to us
19740 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 ing an authorize
19750 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 r..**.** Only a
19760 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 single authorize
19770 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 r can be in plac
19780 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 e on a database
19790 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 connection.** at
197a0 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 a time. Each c
197b0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
197c0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 et_authorizer ov
197d0 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 errides the.** p
197e0 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44 revious call. D
197f0 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f isable the autho
19800 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c rizer by install
19810 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 ing a NULL callb
19820 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 ack..** The auth
19830 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c orizer is disabl
19840 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a ed by default..*
19850 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 *.** The authori
19860 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 zer callback mus
19870 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e t not do anythin
19880 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 g that will modi
19890 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 fy.** the databa
198a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 se connection th
198b0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 at invoked the a
198c0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
198d0 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 ck..** Note that
198e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
198f0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c e_v2()] and [sql
19900 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 ite3_step()] bot
19910 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a h modify their.*
19920 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
19930 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d ctions for the m
19940 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 eaning of "modif
19950 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 y" in this parag
19960 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e raph..**.** When
19970 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
19980 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 e_v2()] is used
19990 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61 to prepare a sta
199a0 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 tement, the.** s
199b0 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 tatement might b
199c0 65 20 72 65 70 72 65 70 61 72 65 64 20 64 75 72 e reprepared dur
199d0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 ing [sqlite3_ste
199e0 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a p()] due to a .*
199f0 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e * schema change.
19a00 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 Hence, the app
19a10 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 lication should
19a20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a ensure that the.
19a30 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f ** correct autho
19a40 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 rizer callback r
19a50 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 emains in place
19a60 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 during the [sqli
19a70 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a te3_step()]..**.
19a80 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 ** Note that the
19a90 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
19aa0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
19ab0 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b only during.** [
19ac0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
19ad0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e )] or its varian
19ae0 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 ts. Authorizati
19af0 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 on is not.** per
19b00 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 formed during st
19b10 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 atement evaluati
19b20 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 on in [sqlite3_s
19b30 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e tep()]..**.** IN
19b40 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
19b50 7b 48 31 32 35 30 31 7d 20 54 68 65 20 5b 73 71 {H12501} The [sq
19b60 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
19b70 69 7a 65 72 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 izer(D,...)] int
19b80 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 erface registers
19b90 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 a.** a
19ba0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
19bb0 63 6b 20 77 69 74 68 20 64 61 74 61 62 61 73 65 ck with database
19bc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a connection D..*
19bd0 2a 0a 2a 2a 20 7b 48 31 32 35 30 32 7d 20 54 68 *.** {H12502} Th
19be0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
19bf0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
19c00 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e as SQL statemen
19c10 74 73 20 61 72 65 0a 2a 2a 20 20 20 20 20 20 20 ts are.**
19c20 20 20 20 62 65 69 6e 67 20 70 61 72 73 65 65 64 being parseed
19c30 20 61 6e 64 20 63 6f 6d 70 69 6c 65 64 2e 0a 2a and compiled..*
19c40 2a 0a 2a 2a 20 7b 48 31 32 35 30 33 7d 20 49 66 *.** {H12503} If
19c50 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
19c60 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
19c70 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 any value other
19c80 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 than.**
19c90 20 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 [SQLITE_IGNORE
19ca0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 ], [SQLITE_OK],
19cb0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d or [SQLITE_DENY]
19cc0 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 , then.**
19cd0 20 20 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 the applicati
19ce0 6f 6e 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c on interface cal
19cf0 6c 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a l that caused.**
19d00 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61 75 the au
19d10 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
19d20 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20 66 k to run shall f
19d30 61 69 6c 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 ail with an.**
19d40 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f [SQLITE_
19d50 45 52 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f 64 ERROR] error cod
19d60 65 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 e and an appropr
19d70 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 iate error messa
19d80 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 ge..**.** {H1250
19d90 34 7d 20 57 68 65 6e 20 74 68 65 20 61 75 74 68 4} When the auth
19da0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
19db0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
19dc0 4f 4b 5d 2c 20 74 68 65 20 6f 70 65 72 61 74 69 OK], the operati
19dd0 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 on.** d
19de0 65 73 63 72 69 62 65 64 20 69 73 20 70 72 6f 63 escribed is proc
19df0 65 73 73 65 64 20 6e 6f 72 6d 61 6c 6c 79 2e 0a essed normally..
19e00 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 35 7d 20 57 **.** {H12505} W
19e10 68 65 6e 20 74 68 65 20 61 75 74 68 6f 72 69 7a hen the authoriz
19e20 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 er callback retu
19e30 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 rns [SQLITE_DENY
19e40 5d 2c 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 ], the.**
19e50 20 20 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 application i
19e60 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 74 68 nterface call th
19e70 61 74 20 63 61 75 73 65 64 20 74 68 65 0a 2a 2a at caused the.**
19e80 20 20 20 20 20 20 20 20 20 20 61 75 74 68 6f 72 author
19e90 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f izer callback to
19ea0 20 72 75 6e 20 73 68 61 6c 6c 20 66 61 69 6c 0a run shall fail.
19eb0 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 ** with
19ec0 20 61 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f an [SQLITE_ERRO
19ed0 52 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e R] error code an
19ee0 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 d an error messa
19ef0 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 ge.** e
19f00 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 20 61 xplaining that a
19f10 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e ccess is denied.
19f20 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 36 7d 20 .**.** {H12506}
19f30 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 If the authorize
19f40 72 20 63 6f 64 65 20 28 74 68 65 20 32 6e 64 20 r code (the 2nd
19f50 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
19f60 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 authorizer.**
19f70 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b callback
19f80 29 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 ) is [SQLITE_REA
19f90 44 5d 20 61 6e 64 20 74 68 65 20 61 75 74 68 6f D] and the autho
19fa0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 rizer callback r
19fb0 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 eturns.**
19fc0 20 20 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 [SQLITE_IGNOR
19fd0 45 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 72 65 E], then the pre
19fe0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
19ff0 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 is constructed t
1a000 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e o.** in
1a010 73 65 72 74 20 61 20 4e 55 4c 4c 20 76 61 6c 75 sert a NULL valu
1a020 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 e in place of th
1a030 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 e table column t
1a040 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a hat would have.*
1a050 2a 20 20 20 20 20 20 20 20 20 20 62 65 65 6e 20 * been
1a060 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f read if [SQLITE_
1a070 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 OK] had been ret
1a080 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 urned..**.** {H1
1a090 32 35 30 37 7d 20 49 66 20 74 68 65 20 61 75 74 2507} If the aut
1a0a0 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 28 74 68 horizer code (th
1a0b0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 e 2nd parameter
1a0c0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 to the authorize
1a0d0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 r.** ca
1a0e0 6c 6c 62 61 63 6b 29 20 69 73 20 61 6e 79 74 68 llback) is anyth
1a0f0 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b ing other than [
1a100 53 51 4c 49 54 45 5f 52 45 41 44 5d 2c 20 74 68 SQLITE_READ], th
1a110 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 en.** a
1a120 20 72 65 74 75 72 6e 20 6f 66 20 5b 53 51 4c 49 return of [SQLI
1a130 54 45 5f 49 47 4e 4f 52 45 5d 20 68 61 73 20 74 TE_IGNORE] has t
1a140 68 65 20 73 61 6d 65 20 65 66 66 65 63 74 20 61 he same effect a
1a150 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2e s [SQLITE_DENY].
1a160 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31 30 7d 20 .**.** {H12510}
1a170 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 The first parame
1a180 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f ter to the autho
1a190 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 rizer callback i
1a1a0 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 s a copy of.**
1a1b0 20 20 20 20 20 20 20 20 74 68 65 20 74 68 69 72 the thir
1a1c0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 d parameter to t
1a1d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f he [sqlite3_set_
1a1e0 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e authorizer()] in
1a1f0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b terface..**.** {
1a200 48 31 32 35 31 31 7d 20 54 68 65 20 73 65 63 6f H12511} The seco
1a210 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 nd parameter to
1a220 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 the callback is
1a230 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 an integer.**
1a240 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 [SQLITE_C
1a250 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 OPY | action cod
1a260 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 e] that specifie
1a270 73 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 s the particular
1a280 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 action.**
1a290 20 20 20 20 74 6f 20 62 65 20 61 75 74 68 6f 72 to be author
1a2a0 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 ized..**.** {H12
1a2b0 35 31 32 7d 20 54 68 65 20 74 68 69 72 64 20 74 512} The third t
1a2c0 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 hrough sixth par
1a2d0 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 63 ameters to the c
1a2e0 61 6c 6c 62 61 63 6b 20 61 72 65 0a 2a 2a 20 20 allback are.**
1a2f0 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 zero-ter
1a300 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 minated strings
1a310 74 68 61 74 20 63 6f 6e 74 61 69 6e 0a 2a 2a 20 that contain.**
1a320 20 20 20 20 20 20 20 20 20 61 64 64 69 74 69 6f additio
1a330 6e 61 6c 20 64 65 74 61 69 6c 73 20 61 62 6f 75 nal details abou
1a340 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 t the action to
1a350 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a be authorized..*
1a360 2a 0a 2a 2a 20 7b 48 31 32 35 32 30 7d 20 45 61 *.** {H12520} Ea
1a370 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 ch call to [sqli
1a380 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
1a390 65 72 28 29 5d 20 6f 76 65 72 72 69 64 65 73 0a er()] overrides.
1a3a0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 79 20 ** any
1a3b0 70 72 65 76 69 6f 75 73 6c 79 20 69 6e 73 74 61 previously insta
1a3c0 6c 6c 65 64 20 61 75 74 68 6f 72 69 7a 65 72 2e lled authorizer.
1a3d0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 32 31 7d 20 .**.** {H12521}
1a3e0 41 20 4e 55 4c 4c 20 61 75 74 68 6f 72 69 7a 65 A NULL authorize
1a3f0 72 20 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f 20 r means that no
1a400 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a authorization.**
1a410 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 callba
1a420 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a ck is invoked..*
1a430 2a 0a 2a 2a 20 7b 48 31 32 35 32 32 7d 20 54 68 *.** {H12522} Th
1a440 65 20 64 65 66 61 75 6c 74 20 61 75 74 68 6f 72 e default author
1a450 69 7a 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2f izer is NULL..*/
1a460 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 .int sqlite3_set
1a470 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 _authorizer(. s
1a480 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 qlite3*,. int (
1a490 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e *xAuth)(void*,in
1a4a0 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f t,const char*,co
1a4b0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 nst char*,const
1a4c0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 char*,const char
1a4d0 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 *),. void *pUse
1a4e0 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 rData.);../*.**
1a4f0 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 CAPI3REF: Author
1a500 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 izer Return Code
1a510 73 20 7b 48 31 32 35 39 30 7d 20 3c 48 31 32 35 s {H12590} <H125
1a520 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 00>.**.** The [s
1a530 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
1a540 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a rizer | authoriz
1a550 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 er callback func
1a560 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 tion] must.** re
1a570 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c turn either [SQL
1a580 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f ITE_OK] or one o
1a590 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 f these two cons
1a5a0 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a tants in order.*
1a5b0 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 * to signal SQLi
1a5c0 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f te whether or no
1a5d0 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 t the action is
1a5e0 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 permitted. See
1a5f0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
1a600 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c set_authorizer |
1a610 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 authorizer docu
1a620 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 mentation] for a
1a630 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 dditional.** inf
1a640 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 ormation..*/.#de
1a650 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 fine SQLITE_DENY
1a660 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 1 /* Abort
1a670 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
1a680 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 t with an error
1a690 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1a6a0 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 E_IGNORE 2 /*
1a6b0 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 Don't allow acce
1a6c0 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 ss, but don't ge
1a6d0 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 nerate an error
1a6e0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
1a6f0 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 EF: Authorizer A
1a700 63 74 69 6f 6e 20 43 6f 64 65 73 20 7b 48 31 32 ction Codes {H12
1a710 35 35 30 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 550} <H12500>.**
1a720 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 .** The [sqlite3
1a730 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 _set_authorizer(
1a740 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 )] interface reg
1a750 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 isters a callbac
1a760 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 k function.** th
1a770 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f at is invoked to
1a780 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 authorize certa
1a790 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 in SQL statement
1a7a0 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a actions. The.*
1a7b0 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 * second paramet
1a7c0 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 er to the callba
1a7d0 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ck is an integer
1a7e0 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 code that speci
1a7f0 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 fies.** what act
1a800 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 ion is being aut
1a810 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 horized. These
1a820 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 are the integer
1a830 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 action codes tha
1a840 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 t.** the authori
1a850 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 zer callback may
1a860 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a be passed..**.*
1a870 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 * These action c
1a880 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 ode values signi
1a890 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 fy what kind of
1a8a0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 operation is to
1a8b0 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 be.** authorized
1a8c0 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 . The 3rd and 4
1a8d0 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f th parameters to
1a8e0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 the authorizati
1a8f0 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 on.** callback f
1a900 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 unction will be
1a910 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 parameters or NU
1a920 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 LL depending on
1a930 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a which of these.*
1a940 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 * codes is used
1a950 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 as the second pa
1a960 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 35 74 rameter. The 5t
1a970 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
1a980 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 he.** authorizer
1a990 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 callback is the
1a9a0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 name of the dat
1a9b0 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 abase ("main", "
1a9c0 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 temp",.** etc.)
1a9d0 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 20 20 if applicable.
1a9e0 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 The 6th paramete
1a9f0 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 r to the authori
1aa00 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 zer callback.**
1aa10 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 is the name of t
1aa20 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 he inner-most tr
1aa30 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 igger or view th
1aa40 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c at is responsibl
1aa50 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 e for.** the acc
1aa60 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e ess attempt or N
1aa70 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 ULL if this acce
1aa80 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 ss attempt is di
1aa90 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 rectly from.** t
1aaa0 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 op-level SQL cod
1aab0 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 e..**.** INVARIA
1aac0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 NTS:.**.** {H125
1aad0 35 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 51} The second p
1aae0 61 72 61 6d 65 74 65 72 20 74 6f 20 61 6e 0a 2a arameter to an.*
1aaf0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
1ab00 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
1ab10 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 er | authorizer
1ab20 63 61 6c 6c 62 61 63 6b 5d 20 73 68 61 6c 6c 20 callback] shall
1ab30 62 65 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a be an integer.**
1ab40 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 [SQLIT
1ab50 45 5f 43 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 E_COPY | authori
1ab60 7a 65 72 20 63 6f 64 65 5d 20 74 68 61 74 20 73 zer code] that s
1ab70 70 65 63 69 66 69 65 73 20 77 68 61 74 20 61 63 pecifies what ac
1ab80 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 tion.**
1ab90 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 is being author
1aba0 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 ized..**.** {H12
1abb0 35 35 32 7d 20 54 68 65 20 33 72 64 20 61 6e 64 552} The 3rd and
1abc0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 4th parameters
1abd0 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 to the.**
1abe0 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f [sqlite3_set_
1abf0 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 authorizer | aut
1ac00 68 6f 72 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 horization callb
1ac10 61 63 6b 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 ack].**
1ac20 20 73 68 61 6c 6c 20 62 65 20 70 61 72 61 6d 65 shall be parame
1ac30 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 ters or NULL dep
1ac40 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 0a ending on which.
1ac50 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c ** [SQL
1ac60 49 54 45 5f 43 4f 50 59 20 7c 20 61 75 74 68 6f ITE_COPY | autho
1ac70 72 69 7a 65 72 20 63 6f 64 65 5d 20 69 73 20 75 rizer code] is u
1ac80 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e sed as the secon
1ac90 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a d parameter..**.
1aca0 2a 2a 20 7b 48 31 32 35 35 33 7d 20 54 68 65 20 ** {H12553} The
1acb0 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 5th parameter to
1acc0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
1acd0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
1ace0 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f thorizer | autho
1acf0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 rizer callback]
1ad00 73 68 61 6c 6c 20 62 65 20 74 68 65 20 6e 61 6d shall be the nam
1ad10 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 e.** of
1ad20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 65 the database (e
1ad30 78 61 6d 70 6c 65 3a 20 22 6d 61 69 6e 22 2c 20 xample: "main",
1ad40 22 74 65 6d 70 22 2c 20 65 74 63 2e 29 20 69 66 "temp", etc.) if
1ad50 20 61 70 70 6c 69 63 61 62 6c 65 2e 0a 2a 2a 0a applicable..**.
1ad60 2a 2a 20 7b 48 31 32 35 35 34 7d 20 54 68 65 20 ** {H12554} The
1ad70 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 6th parameter to
1ad80 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
1ad90 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
1ada0 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f thorizer | autho
1adb0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 rizer callback]
1adc0 73 68 61 6c 6c 20 62 65 20 74 68 65 20 6e 61 6d shall be the nam
1add0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 e.** of
1ade0 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 the inner-most
1adf0 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 trigger or view
1ae00 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 that is responsi
1ae10 62 6c 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 ble for.**
1ae20 20 20 20 20 74 68 65 20 61 63 63 65 73 73 20 61 the access a
1ae30 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 ttempt or NULL i
1ae40 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 f this access at
1ae50 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c tempt is directl
1ae60 79 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 y from.**
1ae70 20 20 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c top-level SQL
1ae80 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a code..*/./*****
1ae90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1aea0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1aeb0 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a ****** 3rd *****
1aec0 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a ******* 4th ****
1aed0 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 *******/.#define
1aee0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 SQLITE_CREATE_I
1aef0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 NDEX 1
1af00 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 /* Index Name
1af10 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 Table Name
1af20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1af30 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 SQLITE_CREATE_TA
1af40 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 BLE 2
1af50 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
1af60 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
1af70 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1af80 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d QLITE_CREATE_TEM
1af90 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 P_INDEX 3
1afa0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 /* Index Name
1afb0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
1afc0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1afd0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 LITE_CREATE_TEMP
1afe0 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f _TABLE 4 /
1aff0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
1b000 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
1b010 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1b020 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f ITE_CREATE_TEMP_
1b030 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a TRIGGER 5 /*
1b040 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 Trigger Name
1b050 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
1b060 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1b070 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 TE_CREATE_TEMP_V
1b080 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 IEW 6 /*
1b090 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 View Name
1b0a0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
1b0b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1b0c0 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 E_CREATE_TRIGGER
1b0d0 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 7 /* T
1b0e0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 rigger Name T
1b0f0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
1b100 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1b110 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 _CREATE_VIEW
1b120 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 8 /* Vi
1b130 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 ew Name NU
1b140 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
1b150 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1b160 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 DELETE
1b170 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 9 /* Tab
1b180 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
1b190 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
1b1a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
1b1b0 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 ROP_INDEX
1b1c0 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 10 /* Inde
1b1d0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c x Name Tabl
1b1e0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
1b1f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
1b200 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 OP_TABLE
1b210 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 11 /* Table
1b220 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
1b230 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
1b240 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
1b250 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 P_TEMP_INDEX
1b260 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 12 /* Index
1b270 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 Name Table
1b280 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
1b290 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
1b2a0 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 _TEMP_TABLE
1b2b0 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 13 /* Table N
1b2c0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
1b2d0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
1b2e0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
1b2f0 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 TEMP_TRIGGER
1b300 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 14 /* Trigger
1b310 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 Name Table Na
1b320 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
1b330 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
1b340 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 EMP_VIEW 1
1b350 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 5 /* View Name
1b360 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
1b370 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
1b380 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 e SQLITE_DROP_TR
1b390 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 IGGER 16
1b3a0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 /* Trigger Na
1b3b0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 me Table Name
1b3c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1b3d0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 SQLITE_DROP_VIE
1b3e0 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 W 17
1b3f0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 /* View Name
1b400 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
1b410 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1b420 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 SQLITE_INSERT
1b430 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 18
1b440 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
1b450 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
1b460 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1b470 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 QLITE_PRAGMA
1b480 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 19
1b490 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 /* Pragma Name
1b4a0 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 1st arg or NU
1b4b0 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 LL */.#define SQ
1b4c0 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 LITE_READ
1b4d0 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 20 /
1b4e0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
1b4f0 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 Column Name
1b500 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1b510 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 ITE_SELECT
1b520 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 21 /*
1b530 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
1b540 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
1b550 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1b560 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 TE_TRANSACTION
1b570 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 22 /*
1b580 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 Operation
1b590 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
1b5a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1b5b0 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 E_UPDATE
1b5c0 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 23 /* T
1b5d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 able Name C
1b5e0 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a olumn Name *
1b5f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1b600 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 _ATTACH
1b610 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 24 /* Fi
1b620 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 lename NU
1b630 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
1b640 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1b650 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 DETACH
1b660 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 25 /* Dat
1b670 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c abase Name NUL
1b680 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
1b690 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
1b6a0 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 LTER_TABLE
1b6b0 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 26 /* Data
1b6c0 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c base Name Tabl
1b6d0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
1b6e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 define SQLITE_RE
1b6f0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 INDEX
1b700 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 27 /* Index
1b710 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
1b720 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
1b730 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 efine SQLITE_ANA
1b740 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 LYZE
1b750 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 28 /* Table
1b760 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
1b770 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
1b780 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
1b790 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 TE_VTABLE
1b7a0 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 29 /* Table N
1b7b0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 ame Module
1b7c0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 Name */.#def
1b7d0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
1b7e0 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 VTABLE
1b7f0 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 30 /* Table Na
1b800 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e me Module N
1b810 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 ame */.#defi
1b820 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 ne SQLITE_FUNCTI
1b830 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 ON 3
1b840 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 1 /* NULL
1b850 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 Function
1b860 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e Name */.#defin
1b870 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 e SQLITE_SAVEPOI
1b880 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 NT 32
1b890 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 /* Operation
1b8a0 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 Savepoint
1b8b0 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 Name */.#define
1b8c0 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 SQLITE_COPY
1b8d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 0
1b8e0 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 /* No longer u
1b8f0 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 sed */../*.** CA
1b900 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 PI3REF: Tracing
1b910 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 And Profiling Fu
1b920 6e 63 74 69 6f 6e 73 20 7b 48 31 32 32 38 30 7d nctions {H12280}
1b930 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 20 45 58 50 <S60400>.** EXP
1b940 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
1b950 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
1b960 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b egister callback
1b970 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 functions that
1b980 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a can be used for.
1b990 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 ** tracing and p
1b9a0 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 rofiling the exe
1b9b0 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 cution of SQL st
1b9c0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 atements..**.**
1b9d0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e The callback fun
1b9e0 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 ction registered
1b9f0 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 by sqlite3_trac
1ba00 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 e() is invoked a
1ba10 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d t.** various tim
1ba20 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 es when an SQL s
1ba30 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e tatement is bein
1ba40 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 g run by [sqlite
1ba50 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 3_step()]..** Th
1ba60 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 e callback retur
1ba70 6e 73 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 ns a UTF-8 rende
1ba80 72 69 6e 67 20 6f 66 20 74 68 65 20 53 51 4c 20 ring of the SQL
1ba90 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 0a 2a statement text.*
1baa0 2a 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 * as the stateme
1bab0 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 nt first begins
1bac0 65 78 65 63 75 74 69 6e 67 2e 20 20 41 64 64 69 executing. Addi
1bad0 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 tional callbacks
1bae0 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 occur.** as eac
1baf0 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 h triggered subp
1bb00 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 rogram is entere
1bb10 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b d. The callback
1bb20 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a s for triggers.*
1bb30 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d * contain a UTF-
1bb40 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 8 SQL comment th
1bb50 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 at identifies th
1bb60 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a e trigger..**.**
1bb70 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 The callback fu
1bb80 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 nction registere
1bb90 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f d by sqlite3_pro
1bba0 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 file() is invoke
1bbb0 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c d.** as each SQL
1bbc0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 statement finis
1bbd0 68 65 73 2e 20 20 54 68 65 20 70 72 6f 66 69 6c hes. The profil
1bbe0 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 e callback conta
1bbf0 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 ins.** the origi
1bc00 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 nal statement te
1bc10 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 xt and an estima
1bc20 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b te of wall-clock
1bc30 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 time.** of how
1bc40 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d long that statem
1bc50 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e ent took to run.
1bc60 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
1bc70 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 31 S:.**.** {H12281
1bc80 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 } The callback f
1bc90 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 unction register
1bca0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 74 ed by [sqlite3_t
1bcb0 72 61 63 65 28 29 5d 20 0a 2a 2a 20 20 20 20 20 race()] .**
1bcc0 20 20 20 20 20 73 68 61 6c 6c 20 62 65 20 69 6e shall be in
1bcd0 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 voked.**
1bce0 20 20 77 68 65 6e 65 76 65 72 20 61 6e 20 53 51 whenever an SQ
1bcf0 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 L statement firs
1bd00 74 20 62 65 67 69 6e 73 20 74 6f 20 65 78 65 63 t begins to exec
1bd10 75 74 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 ute and.**
1bd20 20 20 20 20 77 68 65 6e 65 76 65 72 20 61 20 74 whenever a t
1bd30 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 rigger subprogra
1bd40 6d 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 74 m first begins t
1bd50 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 o run..**.** {H1
1bd60 32 32 38 32 7d 20 45 61 63 68 20 63 61 6c 6c 20 2282} Each call
1bd70 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 to [sqlite3_trac
1bd80 65 28 29 5d 20 73 68 61 6c 6c 20 6f 76 65 72 72 e()] shall overr
1bd90 69 64 65 20 74 68 65 20 70 72 65 76 69 6f 75 73 ide the previous
1bda0 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 ly.** r
1bdb0 65 67 69 73 74 65 72 65 64 20 74 72 61 63 65 20 egistered trace
1bdc0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 callback..**.**
1bdd0 7b 48 31 32 32 38 33 7d 20 41 20 4e 55 4c 4c 20 {H12283} A NULL
1bde0 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 73 trace callback s
1bdf0 68 61 6c 6c 20 64 69 73 61 62 6c 65 20 74 72 61 hall disable tra
1be00 63 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 cing..**.** {H12
1be10 32 38 34 7d 20 54 68 65 20 66 69 72 73 74 20 61 284} The first a
1be20 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 rgument to the t
1be30 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 73 68 race callback sh
1be40 61 6c 6c 20 62 65 20 61 20 63 6f 70 79 20 6f 66 all be a copy of
1be50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
1be60 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 pointer which w
1be70 61 73 20 74 68 65 20 33 72 64 20 61 72 67 75 6d as the 3rd argum
1be80 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ent to [sqlite3_
1be90 74 72 61 63 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 trace()]..**.**
1bea0 7b 48 31 32 32 38 35 7d 20 54 68 65 20 73 65 63 {H12285} The sec
1beb0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ond argument to
1bec0 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 the trace callba
1bed0 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 ck is a.**
1bee0 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 zero-termina
1bef0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 ted UTF-8 string
1bf00 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 containing the
1bf10 6f 72 69 67 69 6e 61 6c 20 74 65 78 74 0a 2a 2a original text.**
1bf20 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 of the
1bf30 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 SQL statement a
1bf40 73 20 69 74 20 77 61 73 20 70 61 73 73 65 64 20 s it was passed
1bf50 69 6e 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 into [sqlite3_pr
1bf60 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 epare_v2()].**
1bf70 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 65 or the e
1bf80 71 75 69 76 61 6c 65 6e 74 2c 20 6f 72 20 61 6e quivalent, or an
1bf90 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 69 6e 64 SQL comment ind
1bfa0 69 63 61 74 69 6e 67 20 74 68 65 20 62 65 67 69 icating the begi
1bfb0 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 nning.**
1bfc0 20 20 6f 66 20 61 20 74 72 69 67 67 65 72 20 73 of a trigger s
1bfd0 75 62 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a ubprogram..**.**
1bfe0 20 7b 48 31 32 32 38 37 7d 20 54 68 65 20 63 61 {H12287} The ca
1bff0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
1c000 72 65 67 69 73 74 65 72 65 64 20 62 79 20 5b 73 registered by [s
1c010 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 qlite3_profile()
1c020 5d 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 ] is invoked.**
1c030 20 20 20 20 20 20 20 20 20 61 73 20 65 61 63 68 as each
1c040 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 SQL statement f
1c050 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b inishes..**.** {
1c060 48 31 32 32 38 38 7d 20 54 68 65 20 66 69 72 73 H12288} The firs
1c070 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 t parameter to t
1c080 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 he profile callb
1c090 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 ack is a copy of
1c0a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
1c0b0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 3rd parameter t
1c0c0 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 o [sqlite3_profi
1c0d0 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 le()]..**.** {H1
1c0e0 32 32 38 39 7d 20 54 68 65 20 73 65 63 6f 6e 64 2289} The second
1c0f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
1c100 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 e profile callba
1c110 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 ck is a.**
1c120 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 zero-termina
1c130 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 ted UTF-8 string
1c140 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 74 that contains t
1c150 68 65 20 63 6f 6d 70 6c 65 74 65 20 74 65 78 74 he complete text
1c160 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 of.**
1c170 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
1c180 74 20 61 73 20 69 74 20 77 61 73 20 70 72 6f 63 t as it was proc
1c190 65 73 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 essed by [sqlite
1c1a0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 3_prepare_v2()].
1c1b0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 ** or t
1c1c0 68 65 20 65 71 75 69 76 61 6c 65 6e 74 2e 0a 2a he equivalent..*
1c1d0 2a 0a 2a 2a 20 7b 48 31 32 32 39 30 7d 20 54 68 *.** {H12290} Th
1c1e0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
1c1f0 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 r to the profile
1c200 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 callback is an
1c210 65 73 74 69 6d 61 74 65 0a 2a 2a 20 20 20 20 20 estimate.**
1c220 20 20 20 20 20 6f 66 20 74 68 65 20 6e 75 6d 62 of the numb
1c230 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 er of nanosecond
1c240 73 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 s of wall-clock
1c250 74 69 6d 65 20 72 65 71 75 69 72 65 64 20 74 6f time required to
1c260 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 75 6e .** run
1c270 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
1c280 6e 74 20 66 72 6f 6d 20 73 74 61 72 74 20 74 6f nt from start to
1c290 20 66 69 6e 69 73 68 2e 0a 2a 2f 0a 53 51 4c 49 finish..*/.SQLI
1c2a0 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 TE_EXPERIMENTAL
1c2b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 void *sqlite3_tr
1c2c0 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f ace(sqlite3*, vo
1c2d0 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 id(*xTrace)(void
1c2e0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 *,const char*),
1c2f0 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 void*);.SQLITE_E
1c300 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 XPERIMENTAL void
1c310 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c *sqlite3_profil
1c320 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 e(sqlite3*,. v
1c330 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 oid(*xProfile)(v
1c340 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a oid*,const char*
1c350 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 ,sqlite3_uint64)
1c360 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a , void*);../*.**
1c370 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 CAPI3REF: Query
1c380 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 Progress Callba
1c390 63 6b 73 20 7b 48 31 32 39 31 30 7d 20 3c 53 36 cks {H12910} <S6
1c3a0 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 0400>.**.** This
1c3b0 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 routine configu
1c3c0 72 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 res a callback f
1c3d0 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a unction - the.**
1c3e0 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 progress callba
1c3f0 63 6b 20 2d 20 74 68 61 74 20 69 73 20 69 6e 76 ck - that is inv
1c400 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c oked periodicall
1c410 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a y during long.**
1c420 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 running calls t
1c430 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 o [sqlite3_exec(
1c440 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 )], [sqlite3_ste
1c450 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c p()] and.** [sql
1c460 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
1c470 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 ]. An example u
1c480 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 se for this.** i
1c490 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b nterface is to k
1c4a0 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 eep a GUI update
1c4b0 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 d during a large
1c4c0 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 query..**.** If
1c4d0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 the progress ca
1c4e0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e llback returns n
1c4f0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 on-zero, the ope
1c500 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 ration is.** int
1c510 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 errupted. This
1c520 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 feature can be u
1c530 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 sed to implement
1c540 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 a.** "Cancel" b
1c550 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 utton on a GUI p
1c560 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 rogress dialog b
1c570 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 ox..**.** The pr
1c580 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d ogress handler m
1c590 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 ust not do anyth
1c5a0 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f ing that will mo
1c5b0 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 dify.** the data
1c5c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
1c5d0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 that invoked the
1c5e0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 progress handle
1c5f0 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 r..** Note that
1c600 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1c610 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 _v2()] and [sqli
1c620 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 te3_step()] both
1c630 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a modify their.**
1c640 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1c650 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 tions for the me
1c660 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 aning of "modify
1c670 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 " in this paragr
1c680 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 aph..**.** INVAR
1c690 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
1c6a0 32 39 31 31 7d 20 54 68 65 20 63 61 6c 6c 62 61 2911} The callba
1c6b0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 ck function regi
1c6c0 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 stered by sqlite
1c6d0 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 3_progress_handl
1c6e0 65 72 28 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 er().**
1c6f0 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 is invoked peri
1c700 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 odically during
1c710 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c long running cal
1c720 6c 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 ls to.**
1c730 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 [sqlite3_step(
1c740 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 )]..**.** {H1291
1c750 32 7d 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 2} The progress
1c760 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
1c770 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 76 65 ked once for eve
1c780 72 79 20 4e 20 76 69 72 74 75 61 6c 0a 2a 2a 20 ry N virtual.**
1c790 20 20 20 20 20 20 20 20 20 6d 61 63 68 69 6e 65 machine
1c7a0 20 6f 70 63 6f 64 65 73 2c 20 77 68 65 72 65 20 opcodes, where
1c7b0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 N is the second
1c7c0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 argument to.**
1c7d0 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c the [sql
1c7e0 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 ite3_progress_ha
1c7f0 6e 64 6c 65 72 28 29 5d 20 63 61 6c 6c 20 74 68 ndler()] call th
1c800 61 74 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a at registered.**
1c810 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63 61 the ca
1c820 6c 6c 62 61 63 6b 2e 20 20 49 66 20 4e 20 69 73 llback. If N is
1c830 20 6c 65 73 73 20 74 68 61 6e 20 31 2c 20 73 71 less than 1, sq
1c840 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 lite3_progress_h
1c850 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 20 20 20 20 andler().**
1c860 20 20 20 20 20 61 63 74 73 20 61 73 20 69 66 20 acts as if
1c870 61 20 4e 55 4c 4c 20 70 72 6f 67 72 65 73 73 20 a NULL progress
1c880 68 61 6e 64 6c 65 72 20 68 61 64 20 62 65 65 6e handler had been
1c890 20 73 70 65 63 69 66 69 65 64 2e 0a 2a 2a 0a 2a specified..**.*
1c8a0 2a 20 7b 48 31 32 39 31 33 7d 20 54 68 65 20 70 * {H12913} The p
1c8b0 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b rogress callback
1c8c0 20 69 74 73 65 6c 66 20 69 73 20 69 64 65 6e 74 itself is ident
1c8d0 69 66 69 65 64 20 62 79 20 74 68 65 20 74 68 69 ified by the thi
1c8e0 72 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 rd.** a
1c8f0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
1c900 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 e3_progress_hand
1c910 6c 65 72 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ler()..**.** {H1
1c920 32 39 31 34 7d 20 54 68 65 20 66 6f 75 72 74 68 2914} The fourth
1c930 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
1c940 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 ite3_progress_ha
1c950 6e 64 6c 65 72 28 29 20 69 73 20 61 0a 2a 2a 20 ndler() is a.**
1c960 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 70 6f void po
1c970 69 6e 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 inter passed to
1c980 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c the progress cal
1c990 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 lback.**
1c9a0 20 20 66 75 6e 63 74 69 6f 6e 20 65 61 63 68 20 function each
1c9b0 74 69 6d 65 20 69 74 20 69 73 20 69 6e 76 6f 6b time it is invok
1c9c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 ed..**.** {H1291
1c9d0 35 7d 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5} If a call to
1c9e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1c9f0 20 72 65 73 75 6c 74 73 20 69 6e 20 66 65 77 65 results in fewe
1ca00 72 20 74 68 61 6e 20 4e 20 6f 70 63 6f 64 65 73 r than N opcodes
1ca10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 69 .** bei
1ca20 6e 67 20 65 78 65 63 75 74 65 64 2c 20 74 68 65 ng executed, the
1ca30 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 n the progress c
1ca40 61 6c 6c 62 61 63 6b 20 69 73 20 6e 65 76 65 72 allback is never
1ca50 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 invoked..**.**
1ca60 7b 48 31 32 39 31 36 7d 20 45 76 65 72 79 20 63 {H12916} Every c
1ca70 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
1ca80 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 progress_handler
1ca90 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ()].**
1caa0 6f 76 65 72 77 72 69 74 65 73 20 61 6e 79 20 70 overwrites any p
1cab0 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 reviously regist
1cac0 65 72 65 64 20 70 72 6f 67 72 65 73 73 20 68 61 ered progress ha
1cad0 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ndler..**.** {H1
1cae0 32 39 31 37 7d 20 49 66 20 74 68 65 20 70 72 6f 2917} If the pro
1caf0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 gress handler ca
1cb00 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 20 74 llback is NULL t
1cb10 68 65 6e 20 6e 6f 20 70 72 6f 67 72 65 73 73 0a hen no progress.
1cb20 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61 6e 64 ** hand
1cb30 6c 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a ler is invoked..
1cb40 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 38 7d 20 49 **.** {H12918} I
1cb50 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 f the progress c
1cb60 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
1cb70 61 20 72 65 73 75 6c 74 20 6f 74 68 65 72 20 74 a result other t
1cb80 68 61 6e 20 30 2c 20 74 68 65 6e 0a 2a 2a 20 20 han 0, then.**
1cb90 20 20 20 20 20 20 20 20 74 68 65 20 62 65 68 61 the beha
1cba0 76 69 6f 72 20 69 73 20 61 20 69 66 20 5b 73 71 vior is a if [sq
1cbb0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
1cbc0 29 5d 20 68 61 64 20 62 65 65 6e 20 63 61 6c 6c )] had been call
1cbd0 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ed..**
1cbe0 3c 53 33 30 35 30 30 3e 0a 2a 2f 0a 76 6f 69 64 <S30500>.*/.void
1cbf0 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 sqlite3_progres
1cc00 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 s_handler(sqlite
1cc10 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 3*, int, int(*)(
1cc20 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a void*), void*);.
1cc30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1cc40 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 Opening A New D
1cc50 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 atabase Connecti
1cc60 6f 6e 20 7b 48 31 32 37 30 30 7d 20 3c 53 34 30 on {H12700} <S40
1cc70 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 200>.**.** These
1cc80 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 routines open a
1cc90 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 n SQLite databas
1cca0 65 20 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d e file whose nam
1ccb0 65 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 e is given by th
1ccc0 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 e.** filename ar
1ccd0 67 75 6d 65 6e 74 2e 20 54 68 65 20 66 69 6c 65 gument. The file
1cce0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 name argument is
1ccf0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
1cd00 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c UTF-8 for.** sql
1cd10 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 ite3_open() and
1cd20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
1cd30 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 ) and as UTF-16
1cd40 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 in the native by
1cd50 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 te.** order for
1cd60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
1cd70 2e 20 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f . A [database co
1cd80 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 nnection] handle
1cd90 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 is usually.** r
1cda0 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 eturned in *ppDb
1cdb0 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 , even if an err
1cdc0 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 or occurs. The
1cdd0 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 only exception i
1cde0 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c s that.** if SQL
1cdf0 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f ite is unable to
1ce00 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 allocate memory
1ce10 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 to hold the [sq
1ce20 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a lite3] object,.*
1ce30 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 * a NULL will be
1ce40 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 written into *p
1ce50 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 pDb instead of a
1ce60 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
1ce70 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a [sqlite3].** obj
1ce80 65 63 74 2e 20 49 66 20 74 68 65 20 64 61 74 61 ect. If the data
1ce90 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 base is opened (
1cea0 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 and/or created)
1ceb0 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 successfully, th
1cec0 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b en.** [SQLITE_OK
1ced0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 ] is returned.
1cee0 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 Otherwise an [er
1cef0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 ror code] is ret
1cf00 75 72 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b urned. The.** [
1cf10 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
1cf20 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 ] or [sqlite3_er
1cf30 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e rmsg16()] routin
1cf40 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 es can be used t
1cf50 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 o obtain.** an E
1cf60 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 nglish language
1cf70 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 description of t
1cf80 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 he error..**.**
1cf90 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f The default enco
1cfa0 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 ding for the dat
1cfb0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 abase will be UT
1cfc0 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 F-8 if.** sqlite
1cfd0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 3_open() or sqli
1cfe0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 te3_open_v2() is
1cff0 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 called and.** U
1d000 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 TF-16 in the nat
1d010 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 ive byte order i
1d020 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 f sqlite3_open16
1d030 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a () is used..**.*
1d040 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 * Whether or not
1d050 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
1d060 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e when it is open
1d070 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a ed, resources.**
1d080 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
1d090 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
1d0a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c onnection] handl
1d0b0 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 e should be rele
1d0c0 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 ased by.** passi
1d0d0 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 ng it to [sqlite
1d0e0 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 3_close()] when
1d0f0 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 it is no longer
1d100 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 required..**.**
1d110 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e The sqlite3_open
1d120 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 _v2() interface
1d130 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 works like sqlit
1d140 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 e3_open().** exc
1d150 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 ept that it acce
1d160 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e pts two addition
1d170 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f al parameters fo
1d180 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e r additional con
1d190 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 trol.** over the
1d1a0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f new database co
1d1b0 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 nnection. The f
1d1c0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 63 lags parameter c
1d1d0 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a an take one of.*
1d1e0 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 * the following
1d1f0 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 three values, op
1d200 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 tionally combine
1d210 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b d with the .** [
1d220 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 SQLITE_OPEN_NOMU
1d230 54 45 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f TEX] or [SQLITE_
1d240 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 OPEN_FULLMUTEX]
1d250 66 6c 61 67 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c flags:.**.** <dl
1d260 3e 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 >.** <dt>[SQLITE
1d270 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c _OPEN_READONLY]<
1d280 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
1d290 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
1d2a0 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 ed in read-only
1d2b0 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 mode. If the da
1d2c0 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a tabase does not.
1d2d0 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 ** already exist
1d2e0 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 , an error is re
1d2f0 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a turned.</dd>.**.
1d300 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f ** <dt>[SQLITE_O
1d310 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f PEN_READWRITE]</
1d320 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 dt>.** <dd>The d
1d330 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 atabase is opene
1d340 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e d for reading an
1d350 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 d writing if pos
1d360 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e sible, or readin
1d370 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 g.** only if the
1d380 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 file is write p
1d390 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 rotected by the
1d3a0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d operating system
1d3b0 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 . In either.**
1d3c0 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 case the databas
1d3d0 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 e must already e
1d3e0 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 xist, otherwise
1d3f0 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 an error is retu
1d400 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a rned.</dd>.**.**
1d410 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 <dt>[SQLITE_OPE
1d420 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b N_READWRITE] | [
1d430 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 SQLITE_OPEN_CREA
1d440 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TE]</dt>.** <dd>
1d450 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 The database is
1d460 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 opened for readi
1d470 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 ng and writing,
1d480 61 6e 64 20 69 73 20 63 72 65 61 74 65 73 20 69 and is creates i
1d490 74 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 t if.** it does
1d4a0 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 not already exis
1d4b0 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 t. This is the b
1d4c0 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 ehavior that is
1d4d0 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a always used for.
1d4e0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 ** sqlite3_open(
1d4f0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 ) and sqlite3_op
1d500 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20 en16().</dd>.**
1d510 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 </dl>.**.** If t
1d520 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 he 3rd parameter
1d530 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e to sqlite3_open
1d540 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 _v2() is not one
1d550 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 of the.** combi
1d560 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 nations shown ab
1d570 6f 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 ove or one of th
1d580 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 e combinations s
1d590 68 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 hown above combi
1d5a0 6e 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 ned.** with the
1d5b0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d [SQLITE_OPEN_NOM
1d5c0 55 54 45 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45 UTEX] or [SQLITE
1d5d0 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d _OPEN_FULLMUTEX]
1d5e0 20 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 flags,.** then
1d5f0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 the behavior is
1d600 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
1d610 20 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f If the [SQLITE_
1d620 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c OPEN_NOMUTEX] fl
1d630 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 ag is set, then
1d640 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
1d650 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 nection.** opens
1d660 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 in the multi-th
1d670 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 read [threading
1d680 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 mode] as long as
1d690 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 the single-thre
1d6a0 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e ad.** mode has n
1d6b0 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 ot been set at c
1d6c0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 ompile-time or s
1d6d0 74 61 72 74 2d 74 69 6d 65 2e 20 20 49 66 20 74 tart-time. If t
1d6e0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 he.** [SQLITE_OP
1d6f0 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c EN_FULLMUTEX] fl
1d700 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 ag is set then t
1d710 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
1d720 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 ection opens.**
1d730 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 in the serialize
1d740 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 d [threading mod
1d750 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 e] unless single
1d760 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 -thread was.** p
1d770 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 reviously select
1d780 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 ed at compile-ti
1d790 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 me or start-time
1d7a0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 ..**.** If the f
1d7b0 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d ilename is ":mem
1d7c0 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 ory:", then a pr
1d7d0 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 ivate, temporary
1d7e0 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 in-memory datab
1d7f0 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 ase.** is create
1d800 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 d for the connec
1d810 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d tion. This in-m
1d820 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 emory database w
1d830 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a ill vanish when.
1d840 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
1d850 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c connection is cl
1d860 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 osed. Future ve
1d870 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
1d880 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 might.** make u
1d890 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c se of additional
1d8a0 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d special filenam
1d8b0 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 es that begin wi
1d8c0 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 th the ":" chara
1d8d0 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 cter..** It is r
1d8e0 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 ecommended that
1d8f0 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 when a database
1d900 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c filename actuall
1d910 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 y does begin wit
1d920 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 h.** a ":" chara
1d930 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 cter you should
1d940 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e prefix the filen
1d950 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e ame with a pathn
1d960 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 ame such as.** "
1d970 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 ./" to avoid amb
1d980 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 iguity..**.** If
1d990 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 the filename is
1d9a0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
1d9b0 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 , then a private
1d9c0 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f , temporary.** o
1d9d0 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 n-disk database
1d9e0 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e will be created.
1d9f0 20 20 54 68 69 73 20 70 72 69 76 61 74 65 20 64 This private d
1da00 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a atabase will be.
1da10 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ** automatically
1da20 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e deleted as soon
1da30 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 as the database
1da40 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 connection is c
1da50 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 losed..**.** The
1da60 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
1da70 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 r to sqlite3_ope
1da80 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 n_v2() is the na
1da90 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 me of the.** [sq
1daa0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
1dab0 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 t that defines t
1dac0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 he operating sys
1dad0 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 tem interface th
1dae0 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 at.** the new da
1daf0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1db00 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 n should use. I
1db10 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 f the fourth par
1db20 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e ameter is.** a N
1db30 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e ULL pointer then
1db40 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 the default [sq
1db50 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
1db60 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a t is used..**.**
1db70 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 <b>Note to Wind
1db80 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 ows users:</b>
1db90 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 The encoding use
1dba0 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 d for the filena
1dbb0 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f me argument.** o
1dbc0 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 f sqlite3_open()
1dbd0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 and sqlite3_ope
1dbe0 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 n_v2() must be U
1dbf0 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 TF-8, not whatev
1dc00 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 er.** codepage i
1dc10 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 s currently defi
1dc20 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 ned. Filenames
1dc30 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 containing inter
1dc40 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 national.** char
1dc50 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 acters must be c
1dc60 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d onverted to UTF-
1dc70 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 8 prior to passi
1dc80 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 ng them into.**
1dc90 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f sqlite3_open() o
1dca0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
1dcb0 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 2()..**.** INVAR
1dcc0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
1dcd0 32 37 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 2701} The [sqlit
1dce0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c e3_open()], [sql
1dcf0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 ite3_open16()],
1dd00 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 and.**
1dd10 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
1dd20 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 63 ()] interfaces c
1dd30 72 65 61 74 65 20 61 20 6e 65 77 0a 2a 2a 20 20 reate a new.**
1dd40 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 [databas
1dd50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 e connection] as
1dd60 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a sociated with.**
1dd70 20 20 20 20 20 20 20 20 20 20 74 68 65 20 64 61 the da
1dd80 74 61 62 61 73 65 20 66 69 6c 65 20 67 69 76 65 tabase file give
1dd90 6e 20 69 6e 20 74 68 65 69 72 20 66 69 72 73 74 n in their first
1dda0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a parameter..**.*
1ddb0 2a 20 7b 48 31 32 37 30 32 7d 20 54 68 65 20 66 * {H12702} The f
1ddc0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 ilename argument
1ddd0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 is interpreted
1dde0 61 73 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 as UTF-8.**
1ddf0 20 20 20 20 20 66 6f 72 20 5b 73 71 6c 69 74 65 for [sqlite
1de00 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73 3_open()] and [s
1de10 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
1de20 5d 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 0a ] and as UTF-16.
1de30 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 74 ** in t
1de40 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f he native byte o
1de50 72 64 65 72 20 66 6f 72 20 5b 73 71 6c 69 74 65 rder for [sqlite
1de60 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 3_open16()]..**.
1de70 2a 2a 20 7b 48 31 32 37 30 33 7d 20 41 20 73 75 ** {H12703} A su
1de80 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 ccessful invocat
1de90 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f ion of [sqlite3_
1dea0 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 open()], [sqlite
1deb0 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 3_open16()],.**
1dec0 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c or [sql
1ded0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 ite3_open_v2()]
1dee0 77 72 69 74 65 73 20 61 20 70 6f 69 6e 74 65 72 writes a pointer
1def0 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 to a new.**
1df00 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 [database
1df10 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 74 6f connection] into
1df20 20 2a 70 70 44 62 2e 0a 2a 2a 0a 2a 2a 20 7b 48 *ppDb..**.** {H
1df30 31 32 37 30 34 7d 20 54 68 65 20 5b 73 71 6c 69 12704} The [sqli
1df40 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 te3_open()], [sq
1df50 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c lite3_open16()],
1df60 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 and.**
1df70 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
1df80 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 2()] interfaces
1df90 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f return [SQLITE_O
1dfa0 4b 5d 20 75 70 6f 6e 20 73 75 63 63 65 73 73 2c K] upon success,
1dfb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 .** or
1dfc0 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b an appropriate [
1dfd0 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 66 error code] on f
1dfe0 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ailure..**.** {H
1dff0 31 32 37 30 36 7d 20 54 68 65 20 64 65 66 61 75 12706} The defau
1e000 6c 74 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 lt text encoding
1e010 20 66 6f 72 20 61 20 6e 65 77 20 64 61 74 61 62 for a new datab
1e020 61 73 65 20 63 72 65 61 74 65 64 20 75 73 69 6e ase created usin
1e030 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 g.** [s
1e040 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f qlite3_open()] o
1e050 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f r [sqlite3_open_
1e060 76 32 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 54 v2()] will be UT
1e070 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 F-8..**.** {H127
1e080 30 37 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 07} The default
1e090 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f text encoding fo
1e0a0 72 20 61 20 6e 65 77 20 64 61 74 61 62 61 73 65 r a new database
1e0b0 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a created using.*
1e0c0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
1e0d0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 77 69 te3_open16()] wi
1e0e0 6c 6c 20 62 65 20 55 54 46 2d 31 36 2e 0a 2a 2a ll be UTF-16..**
1e0f0 0a 2a 2a 20 7b 48 31 32 37 30 39 7d 20 54 68 65 .** {H12709} The
1e100 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 46 [sqlite3_open(F
1e110 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 ,D)] interface i
1e120 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 0a s equivalent to.
1e130 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
1e140 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 ite3_open_v2(F,D
1e150 2c 47 2c 30 29 5d 20 77 68 65 72 65 20 74 68 65 ,G,0)] where the
1e160 20 47 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a G parameter is.
1e170 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c ** [SQL
1e180 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
1e190 54 45 5d 7c 5b 53 51 4c 49 54 45 5f 4f 50 45 4e TE]|[SQLITE_OPEN
1e1a0 5f 43 52 45 41 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 _CREATE]..**.**
1e1b0 7b 48 31 32 37 31 31 7d 20 49 66 20 74 68 65 20 {H12711} If the
1e1c0 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b G parameter to [
1e1d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
1e1e0 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 F,D,G,V)] contai
1e1f0 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 ns the.**
1e200 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 bit value [SQ
1e210 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e LITE_OPEN_READON
1e220 4c 59 5d 20 74 68 65 6e 20 74 68 65 20 64 61 74 LY] then the dat
1e230 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 0a abase is opened.
1e240 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 ** for
1e250 72 65 61 64 69 6e 67 20 6f 6e 6c 79 2e 0a 2a 2a reading only..**
1e260 0a 2a 2a 20 7b 48 31 32 37 31 32 7d 20 49 66 20 .** {H12712} If
1e270 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 the G parameter
1e280 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e to [sqlite3_open
1e290 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f _v2(F,D,G,V)] co
1e2a0 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 ntains the.**
1e2b0 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 bit value
1e2c0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 [SQLITE_OPEN_RE
1e2d0 41 44 57 52 49 54 45 5d 20 74 68 65 6e 20 74 68 ADWRITE] then th
1e2e0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
1e2f0 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 ened.**
1e300 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 reading and wri
1e310 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 ting if possible
1e320 2c 20 6f 72 20 66 6f 72 20 72 65 61 64 69 6e 67 , or for reading
1e330 20 6f 6e 6c 79 20 69 66 20 74 68 65 0a 2a 2a 20 only if the.**
1e340 20 20 20 20 20 20 20 20 20 66 69 6c 65 20 69 73 file is
1e350 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 write protected
1e360 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e by the operatin
1e370 67 20 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 g system..**.**
1e380 7b 48 31 32 37 31 33 7d 20 49 66 20 74 68 65 20 {H12713} If the
1e390 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b G parameter to [
1e3a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
1e3b0 46 2c 44 2c 47 2c 56 29 5d 20 6f 6d 69 74 73 20 F,D,G,V)] omits
1e3c0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
1e3d0 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 bit value [SQLIT
1e3e0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 E_OPEN_CREATE] a
1e3f0 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 nd the database
1e400 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 does not.**
1e410 20 20 20 20 20 70 72 65 76 69 6f 75 73 6c 79 20 previously
1e420 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 exist, an error
1e430 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
1e440 2a 2a 20 7b 48 31 32 37 31 34 7d 20 49 66 20 74 ** {H12714} If t
1e450 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 he G parameter t
1e460 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f o [sqlite3_open_
1e470 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e v2(F,D,G,V)] con
1e480 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 tains the.**
1e490 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 bit value
1e4a0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 [SQLITE_OPEN_CRE
1e4b0 41 54 45 5d 20 61 6e 64 20 74 68 65 20 64 61 74 ATE] and the dat
1e4c0 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a abase does not.*
1e4d0 2a 20 20 20 20 20 20 20 20 20 20 70 72 65 76 69 * previ
1e4e0 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 74 68 65 ously exist, the
1e4f0 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 n an attempt is
1e500 6d 61 64 65 20 74 6f 20 63 72 65 61 74 65 20 61 made to create a
1e510 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 nd.** i
1e520 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 64 61 nitialize the da
1e530 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 tabase..**.** {H
1e540 31 32 37 31 37 7d 20 49 66 20 74 68 65 20 66 69 12717} If the fi
1e550 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 lename argument
1e560 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e to [sqlite3_open
1e570 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ()], [sqlite3_op
1e580 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 en16()],.**
1e590 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 or [sqlite3
1e5a0 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73 20 22 _open_v2()] is "
1e5b0 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 :memory:", then
1e5c0 61 6e 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20 an private,.**
1e5d0 20 20 20 20 20 20 20 20 65 70 68 65 6d 65 72 61 ephemera
1e5e0 6c 2c 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 l, in-memory dat
1e5f0 61 62 61 73 65 20 69 73 20 63 72 65 61 74 65 64 abase is created
1e600 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 for the connect
1e610 69 6f 6e 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 ion..**
1e620 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45 <todo>Is SQLITE
1e630 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c _OPEN_CREATE|SQL
1e640 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
1e650 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 20 TE required.**
1e660 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69 74 in sqlit
1e670 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 e3_open_v2()?</t
1e680 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 odo>.**.** {H127
1e690 31 39 7d 20 49 66 20 74 68 65 20 66 69 6c 65 6e 19} If the filen
1e6a0 61 6d 65 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 ame is NULL or a
1e6b0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 n empty string,
1e6c0 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 0a then a private,.
1e6d0 2a 2a 20 20 20 20 20 20 20 20 20 20 65 70 68 65 ** ephe
1e6e0 6d 65 72 61 6c 20 6f 6e 2d 64 69 73 6b 20 64 61 meral on-disk da
1e6f0 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 tabase will be c
1e700 72 65 61 74 65 64 2e 0a 2a 2a 20 20 20 20 20 20 reated..**
1e710 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c <todo>Is SQL
1e720 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c ITE_OPEN_CREATE|
1e730 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
1e740 57 52 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a WRITE required.*
1e750 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 73 71 * in sq
1e760 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f lite3_open_v2()?
1e770 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 </todo>.**.** {H
1e780 31 32 37 32 31 7d 20 54 68 65 20 5b 64 61 74 61 12721} The [data
1e790 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
1e7a0 20 63 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c created by [sql
1e7b0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 ite3_open_v2(F,D
1e7c0 2c 47 2c 56 29 5d 0a 2a 2a 20 20 20 20 20 20 20 ,G,V)].**
1e7d0 20 20 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 will use the
1e7e0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
1e7f0 6a 65 63 74 20 69 64 65 6e 74 69 66 69 65 64 20 ject identified
1e800 62 79 20 74 68 65 20 56 20 70 61 72 61 6d 65 74 by the V paramet
1e810 65 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 er,.**
1e820 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b or the default [
1e830 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
1e840 65 63 74 20 69 66 20 56 20 69 73 20 61 20 4e 55 ect if V is a NU
1e850 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
1e860 2a 20 7b 48 31 32 37 32 33 7d 20 54 77 6f 20 5b * {H12723} Two [
1e870 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1e880 69 6f 6e 73 5d 20 77 69 6c 6c 20 73 68 61 72 65 ions] will share
1e890 20 61 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 20 a common cache
1e8a0 69 66 20 62 6f 74 68 20 77 65 72 65 0a 2a 2a 20 if both were.**
1e8b0 20 20 20 20 20 20 20 20 20 6f 70 65 6e 65 64 20 opened
1e8c0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 56 46 with the same VF
1e8d0 53 20 77 68 69 6c 65 20 5b 73 68 61 72 65 64 20 S while [shared
1e8e0 63 61 63 68 65 20 6d 6f 64 65 5d 20 77 61 73 20 cache mode] was
1e8f0 65 6e 61 62 6c 65 64 20 61 6e 64 0a 2a 2a 20 20 enabled and.**
1e900 20 20 20 20 20 20 20 20 69 66 20 62 6f 74 68 20 if both
1e910 66 69 6c 65 6e 61 6d 65 73 20 63 6f 6d 70 61 72 filenames compar
1e920 65 20 65 71 75 61 6c 20 75 73 69 6e 67 20 6d 65 e equal using me
1e930 6d 63 6d 70 28 29 20 61 66 74 65 72 20 68 61 76 mcmp() after hav
1e940 69 6e 67 20 62 65 65 6e 0a 2a 2a 20 20 20 20 20 ing been.**
1e950 20 20 20 20 20 70 72 6f 63 65 73 73 65 64 20 62 processed b
1e960 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 y the [sqlite3_v
1e970 66 73 20 7c 20 78 46 75 6c 6c 50 61 74 68 6e 61 fs | xFullPathna
1e980 6d 65 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 me] method of th
1e990 65 20 56 46 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 e VFS..*/.int sq
1e9a0 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f lite3_open(. co
1e9b0 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 nst char *filena
1e9c0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 me, /* Databas
1e9d0 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d e filename (UTF-
1e9e0 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 8) */. sqlite3
1e9f0 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 **ppDb
1ea00 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 /* OUT: SQLite d
1ea10 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 b handle */.);.i
1ea20 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 nt sqlite3_open1
1ea30 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 6(. const void
1ea40 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 *filename, /*
1ea50 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d Database filenam
1ea60 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 e (UTF-16) */.
1ea70 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 sqlite3 **ppDb
1ea80 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 /* OUT:
1ea90 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 SQLite db handle
1eaa0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 */.);.int sqlit
1eab0 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f e3_open_v2(. co
1eac0 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 nst char *filena
1ead0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 me, /* Databas
1eae0 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d e filename (UTF-
1eaf0 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 8) */. sqlite3
1eb00 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 **ppDb,
1eb10 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 /* OUT: SQLite d
1eb20 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e b handle */. in
1eb30 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 t flags,
1eb40 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a /* Flags *
1eb50 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
1eb60 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e zVfs /* N
1eb70 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c ame of VFS modul
1eb80 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a e to use */.);..
1eb90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1eba0 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 Error Codes And
1ebb0 4d 65 73 73 61 67 65 73 20 7b 48 31 32 38 30 30 Messages {H12800
1ebc0 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 0a 2a 2a } <S60200>.**.**
1ebd0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 The sqlite3_err
1ebe0 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 code() interface
1ebf0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
1ec00 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 eric [result cod
1ec10 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 e] or.** [extend
1ec20 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 ed result code]
1ec30 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 for the most rec
1ec40 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 ent failed sqlit
1ec50 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a e3_* API call.**
1ec60 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
1ec70 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e a [database con
1ec80 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 nection]. If a p
1ec90 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 rior API call fa
1eca0 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 iled.** but the
1ecb0 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 most recent API
1ecc0 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 call succeeded,
1ecd0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
1ece0 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 from.** sqlite3
1ecf0 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e _errcode() is un
1ed00 64 65 66 69 6e 65 64 2e 20 20 54 68 65 20 73 71 defined. The sq
1ed10 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 lite3_extended_e
1ed20 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 rrcode().** inte
1ed30 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d rface is the sam
1ed40 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 e except that it
1ed50 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 always returns
1ed60 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 the .** [extende
1ed70 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 d result code] e
1ed80 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 ven when extende
1ed90 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 d result codes a
1eda0 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a re.** disabled..
1edb0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
1edc0 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 3_errmsg() and s
1edd0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 qlite3_errmsg16(
1ede0 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 ) return English
1edf0 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 -language.** tex
1ee00 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 t that describes
1ee10 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 the error, as e
1ee20 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 ither UTF-8 or U
1ee30 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 TF-16 respective
1ee40 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f ly..** Memory to
1ee50 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 hold the error
1ee60 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 message string i
1ee70 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e s managed intern
1ee80 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 ally..** The app
1ee90 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f lication does no
1eea0 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 t need to worry
1eeb0 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 about freeing th
1eec0 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 e result..** How
1eed0 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 ever, the error
1eee0 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 string might be
1eef0 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 overwritten or d
1ef00 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a eallocated by.**
1ef10 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
1ef20 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 s to other SQLit
1ef30 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 e interface func
1ef40 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 tions..**.** Whe
1ef50 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 n the serialized
1ef60 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
1ef70 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 ] is in use, it
1ef80 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 might be the.**
1ef90 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f case that a seco
1efa0 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 nd error occurs
1efb0 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68 on a separate th
1efc0 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a read in between.
1efd0 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 ** the time of t
1efe0 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 he first error a
1eff0 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 nd the call to t
1f000 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e hese interfaces.
1f010 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 .** When that ha
1f020 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e ppens, the secon
1f030 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 d error will be
1f040 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 reported since t
1f050 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 hese.** interfac
1f060 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 es always report
1f070 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
1f080 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f result. To avo
1f090 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 id.** this, each
1f0a0 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 thread can obta
1f0b0 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 in exclusive use
1f0c0 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 of the [databas
1f0d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a e connection] D.
1f0e0 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b ** by invoking [
1f0f0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e sqlite3_mutex_en
1f100 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 ter]([sqlite3_db
1f110 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f _mutex](D)) befo
1f120 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 re beginning.**
1f130 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 to use D and inv
1f140 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d oking [sqlite3_m
1f150 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c utex_leave]([sql
1f160 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 ite3_db_mutex](D
1f170 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 )) after.** all
1f180 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 calls to the int
1f190 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 erfaces listed h
1f1a0 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 ere are complete
1f1b0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 d..**.** If an i
1f1c0 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 nterface fails w
1f1d0 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 ith SQLITE_MISUS
1f1e0 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 E, that means th
1f1f0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 e interface.** w
1f200 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 as invoked incor
1f210 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 rectly by the ap
1f220 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 plication. In t
1f230 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a hat case, the.**
1f240 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 error code and
1f250 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d message may or m
1f260 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a ay not be set..*
1f270 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a *.** INVARIANTS:
1f280 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 31 7d 20 .**.** {H12801}
1f290 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 The [sqlite3_err
1f2a0 63 6f 64 65 28 44 29 5d 20 69 6e 74 65 72 66 61 code(D)] interfa
1f2b0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e ce returns the n
1f2c0 75 6d 65 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 umeric.**
1f2d0 20 20 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d [result code]
1f2e0 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 or [extended re
1f2f0 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 sult code] for t
1f300 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 he most recently
1f310 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 61 69 .** fai
1f320 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20 63 61 led interface ca
1f330 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ll associated wi
1f340 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 th the [database
1f350 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a connection] D..
1f360 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 32 7d 20 54 **.** {H12802} T
1f370 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 he [sqlite3_exte
1f380 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 44 29 5d nded_errcode(D)]
1f390 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
1f3a0 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a ns the numeric.*
1f3b0 2a 20 20 20 20 20 20 20 20 20 20 5b 65 78 74 65 * [exte
1f3c0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
1f3d0 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 ] for the most r
1f3e0 65 63 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20 ecently.**
1f3f0 20 20 20 20 66 61 69 6c 65 64 20 69 6e 74 65 72 failed inter
1f400 66 61 63 65 20 63 61 6c 6c 20 61 73 73 6f 63 69 face call associ
1f410 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 ated with the [d
1f420 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1f430 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 on] D..**.** {H1
1f440 32 38 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 2803} The [sqlit
1f450 65 33 5f 65 72 72 6d 73 67 28 44 29 5d 20 61 6e e3_errmsg(D)] an
1f460 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 d [sqlite3_errms
1f470 67 31 36 28 44 29 5d 0a 2a 2a 20 20 20 20 20 20 g16(D)].**
1f480 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 interfaces r
1f490 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 eturn English-la
1f4a0 6e 67 75 61 67 65 20 74 65 78 74 20 74 68 61 74 nguage text that
1f4b0 20 64 65 73 63 72 69 62 65 73 0a 2a 2a 20 20 20 describes.**
1f4c0 20 20 20 20 20 20 20 74 68 65 20 65 72 72 6f 72 the error
1f4d0 20 69 6e 20 74 68 65 20 6d 6f 73 74 6c 79 20 72 in the mostly r
1f4e0 65 63 65 6e 74 6c 79 20 66 61 69 6c 65 64 20 69 ecently failed i
1f4f0 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 2c 0a 2a nterface call,.*
1f500 2a 20 20 20 20 20 20 20 20 20 20 65 6e 63 6f 64 * encod
1f510 65 64 20 61 73 20 65 69 74 68 65 72 20 55 54 46 ed as either UTF
1f520 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 -8 or UTF-16 res
1f530 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a pectively..**.**
1f540 20 7b 48 31 32 38 30 37 7d 20 54 68 65 20 73 74 {H12807} The st
1f550 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 rings returned b
1f560 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 y [sqlite3_errms
1f570 67 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 g()] and [sqlite
1f580 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 3_errmsg16()].**
1f590 20 20 20 20 20 20 20 20 20 20 61 72 65 20 76 61 are va
1f5a0 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 lid until the ne
1f5b0 78 74 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 xt SQLite interf
1f5c0 61 63 65 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 ace call..**.**
1f5d0 7b 48 31 32 38 30 38 7d 20 43 61 6c 6c 73 20 74 {H12808} Calls t
1f5e0 6f 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 74 o API routines t
1f5f0 68 61 74 20 64 6f 20 6e 6f 74 20 72 65 74 75 72 hat do not retur
1f600 6e 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 0a n an error code.
1f610 2a 2a 20 20 20 20 20 20 20 20 20 20 28 65 78 61 ** (exa
1f620 6d 70 6c 65 3a 20 5b 73 71 6c 69 74 65 33 5f 64 mple: [sqlite3_d
1f630 61 74 61 5f 63 6f 75 6e 74 28 29 5d 29 20 64 6f ata_count()]) do
1f640 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 not.**
1f650 20 63 68 61 6e 67 65 20 74 68 65 20 65 72 72 6f change the erro
1f660 72 20 63 6f 64 65 20 6f 72 20 6d 65 73 73 61 67 r code or messag
1f670 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a e returned by.**
1f680 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
1f690 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b e3_errcode()], [
1f6a0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
1f6b0 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 _errcode()],.**
1f6c0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
1f6d0 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20 3_errmsg()], or
1f6e0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 [sqlite3_errmsg1
1f6f0 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 6()]..**.** {H12
1f700 38 30 39 7d 20 49 6e 74 65 72 66 61 63 65 73 20 809} Interfaces
1f710 74 68 61 74 20 61 72 65 20 6e 6f 74 20 61 73 73 that are not ass
1f720 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 73 ociated with a s
1f730 70 65 63 69 66 69 63 0a 2a 2a 20 20 20 20 20 20 pecific.**
1f740 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f [database co
1f750 6e 6e 65 63 74 69 6f 6e 5d 20 28 65 78 61 6d 70 nnection] (examp
1f760 6c 65 73 3a 0a 2a 2a 20 20 20 20 20 20 20 20 20 les:.**
1f770 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 [sqlite3_mprint
1f780 66 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 f()] or [sqlite3
1f790 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 _enable_shared_c
1f7a0 61 63 68 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 ache()].**
1f7b0 20 20 20 20 64 6f 20 6e 6f 74 20 63 68 61 6e 67 do not chang
1f7c0 65 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 e the values ret
1f7d0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 urned by.**
1f7e0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 [sqlite3_er
1f7f0 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 rcode()], [sqlit
1f800 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 e3_extended_errc
1f810 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 ode()],.**
1f820 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 [sqlite3_err
1f830 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 msg()], or [sqli
1f840 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e te3_errmsg16()].
1f850 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
1f860 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 errcode(sqlite3
1f870 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 *db);.int sqlite
1f880 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 3_extended_errco
1f890 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b de(sqlite3 *db);
1f8a0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
1f8b0 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 ite3_errmsg(sqli
1f8c0 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 te3*);.const voi
1f8d0 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 d *sqlite3_errms
1f8e0 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a g16(sqlite3*);..
1f8f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1f900 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 SQL Statement Ob
1f910 6a 65 63 74 20 7b 48 31 33 30 30 30 7d 20 3c 48 ject {H13000} <H
1f920 31 33 30 31 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 13010>.** KEYWOR
1f930 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 DS: {prepared st
1f940 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 atement} {prepar
1f950 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a ed statements}.*
1f960 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 *.** An instance
1f970 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 of this object
1f980 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e represents a sin
1f990 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e gle SQL statemen
1f9a0 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 t..** This objec
1f9b0 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b t is variously k
1f9c0 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 nown as a "prepa
1f9d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f red statement" o
1f9e0 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 r a.** "compiled
1f9f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 SQL statement"
1fa00 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 or simply as a "
1fa10 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a statement"..**.*
1fa20 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 * The life of a
1fa30 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 statement object
1fa40 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 goes something
1fa50 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a like this:.**.**
1fa60 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 <ol>.** <li> Cr
1fa70 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 eate the object
1fa80 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 using [sqlite3_p
1fa90 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
1faa0 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 a related.**
1fab0 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c function..** <
1fac0 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 li> Bind values
1fad0 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 to [host paramet
1fae0 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 ers] using the s
1faf0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a qlite3_bind_*().
1fb00 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 ** interfac
1fb10 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 es..** <li> Run
1fb20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 the SQL by calli
1fb30 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ng [sqlite3_step
1fb40 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 ()] one or more
1fb50 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 times..** <li> R
1fb60 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 eset the stateme
1fb70 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 nt using [sqlite
1fb80 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 3_reset()] then
1fb90 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 go back.**
1fba0 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 to step 2. Do t
1fbb0 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 his zero or more
1fbc0 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 times..** <li>
1fbd0 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 Destroy the obje
1fbe0 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ct using [sqlite
1fbf0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 3_finalize()]..*
1fc00 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 * </ol>.**.** Re
1fc10 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 fer to documenta
1fc20 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 tion on individu
1fc30 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 al methods above
1fc40 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a for additional.
1fc50 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a ** information..
1fc60 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
1fc70 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 t sqlite3_stmt s
1fc80 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a qlite3_stmt;../*
1fc90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 .** CAPI3REF: Ru
1fca0 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 20 7b 48 n-time Limits {H
1fcb0 31 32 37 36 30 7d 20 3c 53 32 30 36 30 30 3e 0a 12760} <S20600>.
1fcc0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 **.** This inter
1fcd0 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 face allows the
1fce0 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 size of various
1fcf0 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 constructs to be
1fd00 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 limited.** on a
1fd10 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 connection by c
1fd20 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e onnection basis.
1fd30 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 The first para
1fd40 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 meter is the.**
1fd50 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
1fd60 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 tion] whose limi
1fd70 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f t is to be set o
1fd80 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a r queried. The.
1fd90 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 ** second parame
1fda0 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 ter is one of th
1fdb0 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 e [limit categor
1fdc0 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 ies] that define
1fdd0 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 a.** class of c
1fde0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 onstructs to be
1fdf0 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 size limited. T
1fe00 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
1fe10 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 er is the.** new
1fe20 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 limit for that
1fe30 63 6f 6e 73 74 72 75 63 74 2e 20 20 54 68 65 20 construct. The
1fe40 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
1fe50 20 74 68 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a the old limit..
1fe60 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 65 77 **.** If the new
1fe70 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 limit is a nega
1fe80 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 tive number, the
1fe90 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e limit is unchan
1fea0 67 65 64 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20 ged..** For the
1feb0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 6f limit category o
1fec0 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 f SQLITE_LIMIT_X
1fed0 59 5a 20 74 68 65 72 65 20 69 73 20 61 20 68 61 YZ there is a ha
1fee0 72 64 20 75 70 70 65 72 0a 2a 2a 20 62 6f 75 6e rd upper.** boun
1fef0 64 20 73 65 74 20 62 79 20 61 20 63 6f 6d 70 69 d set by a compi
1ff00 6c 65 2d 74 69 6d 65 20 43 20 70 72 65 70 72 6f le-time C prepro
1ff10 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 6e 61 6d cessor macro nam
1ff20 65 64 20 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59 ed SQLITE_MAX_XY
1ff30 5a 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d Z..** (The "_LIM
1ff40 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 IT_" in the name
1ff50 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 is changed to "
1ff60 5f 4d 41 58 5f 22 2e 29 0a 2a 2a 20 41 74 74 65 _MAX_".).** Atte
1ff70 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 mpts to increase
1ff80 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 a limit above i
1ff90 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f ts hard upper bo
1ffa0 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e und are.** silen
1ffb0 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f tly truncated to
1ffc0 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 the hard upper
1ffd0 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e limit..**.** Run
1ffe0 20 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 time limits are
1fff0 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 intended for us
20000 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e e in application
20010 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a s that manage.**
20020 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 both their own
20030 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 internal databas
20040 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 e and also datab
20050 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f ases that are co
20060 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 ntrolled.** by u
20070 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 ntrusted externa
20080 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 l sources. An e
20090 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 xample applicati
200a0 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a on might be a.**
200b0 20 77 65 62 62 72 6f 77 73 65 72 20 74 68 61 74 webbrowser that
200c0 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 has its own dat
200d0 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 abases for stori
200e0 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a ng history and.*
200f0 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 * separate datab
20100 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 ases controlled
20110 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 by JavaScript ap
20120 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c plications downl
20130 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 oaded.** off the
20140 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 Internet. The
20150 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 internal databas
20160 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 es can be given
20170 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 the.** large, de
20180 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 fault limits. D
20190 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 atabases managed
201a0 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 by external sou
201b0 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 rces can.** be g
201c0 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 iven much smalle
201d0 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 r limits designe
201e0 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 d to prevent a d
201f0 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 enial of service
20200 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 .** attack. Dev
20210 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c elopers might al
20220 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 so want to use t
20230 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f he [sqlite3_set_
20240 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a authorizer()].**
20250 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 interface to fu
20260 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e rther control un
20270 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 trusted SQL. Th
20280 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 e size of the da
20290 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 tabase.** create
202a0 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 d by an untruste
202b0 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 d script can be
202c0 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 contained using
202d0 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 the.** [max_page
202e0 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d _count] [PRAGMA]
202f0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d ..**.** New run-
20300 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 time limit categ
20310 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 ories may be add
20320 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c ed in future rel
20330 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 eases..**.** INV
20340 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
20350 48 31 32 37 36 32 7d 20 41 20 73 75 63 63 65 73 H12762} A succes
20360 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 sful call to [sq
20370 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c lite3_limit(D,C,
20380 56 29 5d 20 77 68 65 72 65 20 56 20 69 73 0a 2a V)] where V is.*
20390 2a 20 20 20 20 20 20 20 20 20 20 70 6f 73 69 74 * posit
203a0 69 76 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 ive changes the
203b0 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 73 69 7a limit on the siz
203c0 65 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 20 43 e of construct C
203d0 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 in the.**
203e0 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f [database co
203f0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74 6f 20 74 nnection] D to t
20400 68 65 20 6c 65 73 73 65 72 20 6f 66 20 56 20 61 he lesser of V a
20410 6e 64 20 74 68 65 20 68 61 72 64 20 75 70 70 65 nd the hard uppe
20420 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 6f r.** bo
20430 75 6e 64 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 und on the size
20440 6f 66 20 43 20 74 68 61 74 20 69 73 20 73 65 74 of C that is set
20450 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 at compile-time
20460 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 36 7d ..**.** {H12766}
20470 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 A successful ca
20480 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c ll to [sqlite3_l
20490 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20 77 68 65 imit(D,C,V)] whe
204a0 72 65 20 56 20 69 73 20 6e 65 67 61 74 69 76 65 re V is negative
204b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 65 61 .** lea
204c0 76 65 73 20 74 68 65 20 73 74 61 74 65 20 6f 66 ves the state of
204d0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
204e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 75 6e 63 onnection] D unc
204f0 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 hanged..**.** {H
20500 31 32 37 36 39 7d 20 41 20 73 75 63 63 65 73 73 12769} A success
20510 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ful call to [sql
20520 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 ite3_limit(D,C,V
20530 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a )] returns the.*
20540 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 * value
20550 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e of the limit on
20560 20 74 68 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e the size of con
20570 73 74 72 75 63 74 20 43 20 69 6e 20 74 68 65 0a struct C in the.
20580 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 ** [dat
20590 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
205a0 5d 20 44 20 61 73 20 69 74 20 77 61 73 20 70 72 ] D as it was pr
205b0 69 6f 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 2e ior to the call.
205c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
205d0 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 limit(sqlite3*,
205e0 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 int id, int newV
205f0 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 al);../*.** CAPI
20600 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 3REF: Run-Time L
20610 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 20 imit Categories
20620 7b 48 31 32 37 39 30 7d 20 3c 48 31 32 37 36 30 {H12790} <H12760
20630 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b >.** KEYWORDS: {
20640 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 limit category}
20650 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 {limit categorie
20660 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 s}.**.** These c
20670 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 onstants define
20680 76 61 72 69 6f 75 73 20 61 73 70 65 63 74 73 20 various aspects
20690 6f 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 of a [database c
206a0 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 onnection].** th
206b0 61 74 20 63 61 6e 20 62 65 20 6c 69 6d 69 74 65 at can be limite
206c0 64 20 69 6e 20 73 69 7a 65 20 62 79 20 63 61 6c d in size by cal
206d0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c ls to [sqlite3_l
206e0 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 imit()]..** The
206f0 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 meanings of the
20700 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 61 various limits a
20710 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a re as follows:.*
20720 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 *.** <dl>.** <dt
20730 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 >SQLITE_LIMIT_LE
20740 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 NGTH</dt>.** <dd
20750 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a >The maximum siz
20760 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 e of any string
20770 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 or BLOB or table
20780 20 72 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 row.<dd>.**.**
20790 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
207a0 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e _SQL_LENGTH</dt>
207b0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
207c0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e mum length of an
207d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c SQL statement.<
207e0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
207f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 QLITE_LIMIT_COLU
20800 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 MN</dt>.** <dd>T
20810 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
20820 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 r of columns in
20830 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 a table definiti
20840 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 on or in the.**
20850 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 result set of a
20860 53 45 4c 45 43 54 20 6f 72 20 74 68 65 20 6d 61 SELECT or the ma
20870 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
20880 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e columns in an in
20890 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 dex.** or in an
208a0 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 ORDER BY or GROU
208b0 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 P BY clause.</dd
208c0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
208d0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 TE_LIMIT_EXPR_DE
208e0 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e PTH</dt>.** <dd>
208f0 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 The maximum dept
20900 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 h of the parse t
20910 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 ree on any expre
20920 73 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ssion.</dd>.**.*
20930 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d * <dt>SQLITE_LIM
20940 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 IT_COMPOUND_SELE
20950 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 CT</dt>.** <dd>T
20960 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
20970 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 r of terms in a
20980 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 compound SELECT
20990 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a statement.</dd>.
209a0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
209b0 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f _LIMIT_VDBE_OP</
209c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
209d0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
209e0 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e instructions in
209f0 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 a virtual machi
20a00 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 ne program.** us
20a10 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 ed to implement
20a20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 an SQL statement
20a30 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 .</dd>.**.** <dt
20a40 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 >SQLITE_LIMIT_FU
20a50 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a NCTION_ARG</dt>.
20a60 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
20a70 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 um number of arg
20a80 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 uments on a func
20a90 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a tion.</dd>.**.**
20aa0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 <dt>SQLITE_LIMI
20ab0 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a T_ATTACHED</dt>.
20ac0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
20ad0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 74 74 um number of att
20ae0 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 2e ached databases.
20af0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
20b00 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b SQLITE_LIMIT_LIK
20b10 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 E_PATTERN_LENGTH
20b20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
20b30 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 maximum length
20b40 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 of the pattern a
20b50 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 4c rgument to the L
20b60 49 4b 45 20 6f 72 0a 2a 2a 20 47 4c 4f 42 20 6f IKE or.** GLOB o
20b70 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a perators.</dd>.*
20b80 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
20b90 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e LIMIT_VARIABLE_N
20ba0 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 UMBER</dt>.** <d
20bb0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 d>The maximum nu
20bc0 6d 62 65 72 20 6f 66 20 76 61 72 69 61 62 6c 65 mber of variable
20bd0 73 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 s in an SQL stat
20be0 65 6d 65 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a ement that can.*
20bf0 2a 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e * be bound.</dd>
20c00 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 .** </dl>.*/.#de
20c10 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
20c20 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 T_LENGTH
20c30 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 0.#d
20c40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
20c50 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 IT_SQL_LENGTH
20c60 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 1.#
20c70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
20c80 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 MIT_COLUMN
20c90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 2.
20ca0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
20cb0 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 IMIT_EXPR_DEPTH
20cc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 3
20cd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
20ce0 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 LIMIT_COMPOUND_S
20cf0 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 ELECT
20d00 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
20d10 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 _LIMIT_VDBE_OP
20d20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
20d30 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 5.#define SQLIT
20d40 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e E_LIMIT_FUNCTION
20d50 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 _ARG
20d60 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 6.#define SQLI
20d70 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 TE_LIMIT_ATTACHE
20d80 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 D
20d90 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 7.#define SQL
20da0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 ITE_LIMIT_LIKE_P
20db0 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 ATTERN_LENGTH
20dc0 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 8.#define SQ
20dd0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 LITE_LIMIT_VARIA
20de0 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 BLE_NUMBER
20df0 20 20 20 20 20 39 0a 0a 2f 2a 0a 2a 2a 20 43 41 9../*.** CA
20e00 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e PI3REF: Compilin
20e10 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 g An SQL Stateme
20e20 6e 74 20 7b 48 31 33 30 31 30 7d 20 3c 53 31 30 nt {H13010} <S10
20e30 30 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 000>.** KEYWORDS
20e40 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 : {SQL statement
20e50 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a compiler}.**.**
20e60 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 To execute an S
20e70 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 QL query, it mus
20e80 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 t first be compi
20e90 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d led into a byte-
20ea0 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 code.** program
20eb0 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 using one of the
20ec0 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a se routines..**.
20ed0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 ** The first arg
20ee0 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 ument, "db", is
20ef0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a [database conn
20f00 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 ection] obtained
20f10 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 from a.** prior
20f20 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
20f30 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 3_open()], [sqli
20f40 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f te3_open_v2()] o
20f50 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 r [sqlite3_open1
20f60 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6()]..**.** The
20f70 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c second argument,
20f80 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 "zSql", is the
20f90 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 statement to be
20fa0 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 compiled, encode
20fb0 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 d.** as either U
20fc0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 TF-8 or UTF-16.
20fd0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 The sqlite3_pre
20fe0 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 pare() and sqlit
20ff0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a e3_prepare_v2().
21000 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 ** interfaces us
21010 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c e UTF-8, and sql
21020 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
21030 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 and sqlite3_pre
21040 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 pare16_v2().** u
21050 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a se UTF-16..**.**
21060 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 If the nByte ar
21070 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 gument is less t
21080 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a han zero, then z
21090 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 Sql is read up t
210a0 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a o the.** first z
210b0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 ero terminator.
210c0 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d If nByte is non-
210d0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 negative, then i
210e0 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d t is the maximum
210f0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 .** number of b
21100 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a ytes read from z
21110 53 71 6c 2e 20 20 57 68 65 6e 20 6e 42 79 74 65 Sql. When nByte
21120 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 is non-negative
21130 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 , the.** zSql st
21140 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 ring ends at eit
21150 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c her the first '\
21160 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 000' or '\u0000'
21170 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a character or.**
21180 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 the nByte-th by
21190 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f te, whichever co
211a0 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 mes first. If th
211b0 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a e caller knows.*
211c0 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c * that the suppl
211d0 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 ied string is nu
211e0 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 l-terminated, th
211f0 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d en there is a sm
21200 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e all.** performan
21210 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 ce advantage to
21220 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 be gained by pas
21230 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 sing an nByte pa
21240 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 rameter that.**
21250 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 is equal to the
21260 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
21270 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 in the input str
21280 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 ing <i>including
21290 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d </i>.** the nul-
212a0 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 terminator bytes
212b0 2e 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20 ..**.** *pzTail
212c0 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 is made to point
212d0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 to the first by
212e0 74 65 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 te past the end
212f0 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 of the.** first
21300 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e SQL statement in
21310 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f zSql. These ro
21320 75 74 69 6e 65 73 20 6f 6e 6c 79 20 63 6f 6d 70 utines only comp
21330 69 6c 65 20 74 68 65 20 66 69 72 73 74 0a 2a 2a ile the first.**
21340 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 statement in zS
21350 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 ql, so *pzTail i
21360 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 s left pointing
21370 74 6f 20 77 68 61 74 20 72 65 6d 61 69 6e 73 0a to what remains.
21380 2a 2a 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a ** uncompiled..*
21390 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69 73 20 *.** *ppStmt is
213a0 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f left pointing to
213b0 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 a compiled [pre
213c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
213d0 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 that can be.**
213e0 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b executed using [
213f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e sqlite3_step()].
21400 20 20 49 66 20 74 68 65 72 65 20 69 73 20 61 6e If there is an
21410 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 error, *ppStmt
21420 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c is set.** to NUL
21430 4c 2e 20 20 49 66 20 74 68 65 20 69 6e 70 75 74 L. If the input
21440 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e text contains n
21450 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e o SQL (if the in
21460 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a put is an empty.
21470 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 ** string or a c
21480 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 omment) then *pp
21490 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e Stmt is set to N
214a0 55 4c 4c 2e 0a 2a 2a 20 7b 41 31 33 30 31 38 7d ULL..** {A13018}
214b0 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f The calling pro
214c0 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e cedure is respon
214d0 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 sible for deleti
214e0 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a ng the compiled.
214f0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
21500 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
21510 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 finalize()] afte
21520 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 r it has finishe
21530 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 0a 2a 2a d with it..**.**
21540 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51 On success, [SQ
21550 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 LITE_OK] is retu
21560 72 6e 65 64 2c 20 6f 74 68 65 72 77 69 73 65 20 rned, otherwise
21570 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 an [error code]
21580 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
21590 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 ** The sqlite3_p
215a0 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 repare_v2() and
215b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
215c0 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 6_v2() interface
215d0 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 s are.** recomme
215e0 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 nded for all new
215f0 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 programs. The t
21600 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 wo older interfa
21610 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 ces are retained
21620 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 .** for backward
21630 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c s compatibility,
21640 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 but their use i
21650 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a s discouraged..*
21660 2a 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e * In the "v2" in
21670 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 terfaces, the pr
21680 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
21690 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 .** that is retu
216a0 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 rned (the [sqlit
216b0 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 e3_stmt] object)
216c0 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 contains a copy
216d0 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 of the.** origi
216e0 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 nal SQL text. Th
216f0 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 is causes the [s
21700 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 qlite3_step()] i
21710 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 nterface to.** b
21720 65 68 61 76 65 20 61 20 64 69 66 66 65 72 65 6e ehave a differen
21730 74 6c 79 20 69 6e 20 74 77 6f 20 77 61 79 73 3a tly in two ways:
21740 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c .**.** <ol>.** <
21750 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 li>.** If the da
21760 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 tabase schema ch
21770 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f anges, instead o
21780 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c f returning [SQL
21790 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 ITE_SCHEMA] as i
217a0 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 t.** always used
217b0 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 to do, [sqlite3
217c0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 _step()] will au
217d0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f tomatically reco
217e0 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a mpile the SQL.**
217f0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 statement and t
21800 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 ry to run it aga
21810 69 6e 2e 20 20 49 66 20 74 68 65 20 73 63 68 65 in. If the sche
21820 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64 20 69 ma has changed i
21830 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68 61 74 20 n.** a way that
21840 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74 65 6d makes the statem
21850 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 ent no longer va
21860 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 lid, [sqlite3_st
21870 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c ep()] will still
21880 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 .** return [SQLI
21890 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75 74 TE_SCHEMA]. But
218a0 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67 61 unlike the lega
218b0 63 79 20 62 65 68 61 76 69 6f 72 2c 20 5b 53 51 cy behavior, [SQ
218c0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a LITE_SCHEMA] is.
218d0 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c 20 65 ** now a fatal e
218e0 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b rror. Calling [
218f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
21900 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c v2()] again will
21910 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a not make the.**
21920 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79 2e 20 error go away.
21930 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71 6c 69 Note: use [sqli
21940 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f te3_errmsg()] to
21950 20 66 69 6e 64 20 74 68 65 20 74 65 78 74 0a 2a find the text.*
21960 2a 20 6f 66 20 74 68 65 20 70 61 72 73 69 6e 67 * of the parsing
21970 20 65 72 72 6f 72 20 74 68 61 74 20 72 65 73 75 error that resu
21980 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 lts in an [SQLIT
21990 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75 72 6e E_SCHEMA] return
219a0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a ..** </li>.**.**
219b0 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e <li>.** When an
219c0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b error occurs, [
219d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
219e0 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 will return one
219f0 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a of the detailed.
21a00 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d ** [error codes]
21a10 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 or [extended er
21a20 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 54 68 65 ror codes]. The
21a30 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 legacy behavior
21a40 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 was that.** [sq
21a50 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f lite3_step()] wo
21a60 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 uld only return
21a70 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 a generic [SQLIT
21a80 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 E_ERROR] result
21a90 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 79 6f 75 20 code.** and you
21aa0 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 would have to ma
21ab0 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c ke a second call
21ac0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 to [sqlite3_res
21ad0 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72 0a 2a et()] in order.*
21ae0 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e * to find the un
21af0 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f derlying cause o
21b00 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 f the problem. W
21b10 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 ith the "v2" pre
21b20 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 pare.** interfac
21b30 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 es, the underlyi
21b40 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 ng reason for th
21b50 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 e error is retur
21b60 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e ned immediately.
21b70 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f .** </li>.** </o
21b80 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 l>.**.** INVARIA
21b90 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 NTS:.**.** {H130
21ba0 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 11} The [sqlite3
21bb0 5f 70 72 65 70 61 72 65 28 64 62 2c 7a 53 71 6c _prepare(db,zSql
21bc0 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 ,...)] and.**
21bd0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f [sqlite3_
21be0 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 prepare_v2(db,zS
21bf0 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 ql,...)] interfa
21c00 63 65 73 20 69 6e 74 65 72 70 72 65 74 20 74 68 ces interpret th
21c10 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65 e.** te
21c20 78 74 20 69 6e 20 74 68 65 69 72 20 7a 53 71 6c xt in their zSql
21c30 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 55 54 parameter as UT
21c40 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 F-8..**.** {H130
21c50 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 12} The [sqlite3
21c60 5f 70 72 65 70 61 72 65 31 36 28 64 62 2c 7a 53 _prepare16(db,zS
21c70 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 ql,...)] and.**
21c80 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
21c90 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 64 3_prepare16_v2(d
21ca0 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 b,zSql,...)] int
21cb0 65 72 66 61 63 65 73 20 69 6e 74 65 72 70 72 65 erfaces interpre
21cc0 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 t the.**
21cd0 20 20 74 65 78 74 20 69 6e 20 74 68 65 69 72 20 text in their
21ce0 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20 61 zSql parameter a
21cf0 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 s UTF-16 in the
21d00 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
21d10 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 33 r..**.** {H13013
21d20 7d 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 } If the nByte a
21d30 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 rgument to [sqli
21d40 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 te3_prepare_v2(d
21d50 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e b,zSql,nByte,...
21d60 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 )].** a
21d70 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 nd its variants
21d80 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 is less than zer
21d90 6f 2c 20 74 68 65 20 53 51 4c 20 74 65 78 74 20 o, the SQL text
21da0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 is.** r
21db0 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 20 69 73 ead from zSql is
21dc0 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 20 read up to the
21dd0 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 first zero termi
21de0 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 nator..**.** {H1
21df0 33 30 31 34 7d 20 49 66 20 74 68 65 20 6e 42 79 3014} If the nBy
21e00 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b te argument to [
21e10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
21e20 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 v2(db,zSql,nByte
21e30 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 ,...)].**
21e40 20 20 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 and its varia
21e50 6e 74 73 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 nts is non-negat
21e60 69 76 65 2c 20 74 68 65 6e 20 61 74 20 6d 6f 73 ive, then at mos
21e70 74 20 6e 42 79 74 65 73 20 62 79 74 65 73 20 6f t nBytes bytes o
21e80 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 f.** SQ
21e90 4c 20 74 65 78 74 20 69 73 20 72 65 61 64 20 66 L text is read f
21ea0 72 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20 rom zSql..**.**
21eb0 7b 48 31 33 30 31 35 7d 20 49 6e 20 5b 73 71 6c {H13015} In [sql
21ec0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
21ed0 64 62 2c 7a 53 71 6c 2c 4e 2c 50 2c 70 7a 54 61 db,zSql,N,P,pzTa
21ee0 69 6c 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 il)] and its var
21ef0 69 61 6e 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 iants.**
21f00 20 20 69 66 20 74 68 65 20 7a 53 71 6c 20 69 6e if the zSql in
21f10 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e put text contain
21f20 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 s more than one
21f30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a SQL statement.**
21f40 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 70 7a and pz
21f50 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c Tail is not NULL
21f60 2c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 , then *pzTail i
21f70 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 s made to point
21f80 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 to the.**
21f90 20 20 20 66 69 72 73 74 20 62 79 74 65 20 70 61 first byte pa
21fa0 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 st the end of th
21fb0 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 e first SQL stat
21fc0 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 0a 2a ement in zSql..*
21fd0 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f * <todo
21fe0 3e 57 68 61 74 20 64 6f 65 73 20 2a 70 7a 54 61 >What does *pzTa
21ff0 69 6c 20 70 6f 69 6e 74 20 74 6f 20 69 66 20 74 il point to if t
22000 68 65 72 65 20 69 73 20 6f 6e 65 20 73 74 61 74 here is one stat
22010 65 6d 65 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a ement?</todo>.**
22020 0a 2a 2a 20 7b 48 31 33 30 31 36 7d 20 41 20 73 .** {H13016} A s
22030 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
22040 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 o [sqlite3_prepa
22050 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c re_v2(db,zSql,N,
22060 70 70 53 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20 ppStmt,...)].**
22070 20 20 20 20 20 20 20 20 20 6f 72 20 6f 6e 65 20 or one
22080 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 of its variants
22090 77 72 69 74 65 73 20 69 6e 74 6f 20 2a 70 70 53 writes into *ppS
220a0 74 6d 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f tmt a pointer to
220b0 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 a new.**
220c0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 [prepared sta
220d0 74 65 6d 65 6e 74 5d 20 6f 72 20 61 20 70 6f 69 tement] or a poi
220e0 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20 69 66 20 nter to NULL if
220f0 7a 53 71 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a zSql contains.**
22100 20 20 20 20 20 20 20 20 20 20 6e 6f 74 68 69 6e nothin
22110 67 20 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69 g other than whi
22120 74 65 73 70 61 63 65 20 6f 72 20 63 6f 6d 6d 65 tespace or comme
22130 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 nts..**.** {H130
22140 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 19} The [sqlite3
22150 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 _prepare_v2()] i
22160 6e 74 65 72 66 61 63 65 20 61 6e 64 20 69 74 73 nterface and its
22170 20 76 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e variants return
22180 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 .** [SQ
22190 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 61 6e 20 61 LITE_OK] or an a
221a0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f ppropriate [erro
221b0 72 20 63 6f 64 65 5d 20 75 70 6f 6e 20 66 61 69 r code] upon fai
221c0 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 lure..**.** {H13
221d0 30 32 31 7d 20 42 65 66 6f 72 65 20 5b 73 71 6c 021} Before [sql
221e0 69 74 65 33 5f 70 72 65 70 61 72 65 28 64 62 2c ite3_prepare(db,
221f0 7a 53 71 6c 2c 6e 42 79 74 65 2c 70 70 53 74 6d zSql,nByte,ppStm
22200 74 2c 70 7a 54 61 69 6c 29 5d 20 6f 72 20 69 74 t,pzTail)] or it
22210 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 s.** va
22220 72 69 61 6e 74 73 20 72 65 74 75 72 6e 73 20 61 riants returns a
22230 6e 20 65 72 72 6f 72 20 28 61 6e 79 20 76 61 6c n error (any val
22240 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 ue other than [S
22250 51 4c 49 54 45 5f 4f 4b 5d 29 2c 0a 2a 2a 20 20 QLITE_OK]),.**
22260 20 20 20 20 20 20 20 20 74 68 65 79 20 66 69 72 they fir
22270 73 74 20 73 65 74 20 2a 70 70 53 74 6d 74 20 74 st set *ppStmt t
22280 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 o NULL..*/.int s
22290 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a qlite3_prepare(.
222a0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
222b0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
222c0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a abase handle */.
222d0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 const char *zS
222e0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c ql, /* SQL
222f0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d statement, UTF-
22300 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 8 encoded */. i
22310 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 nt nByte,
22320 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 /* Maximu
22330 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c m length of zSql
22340 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 in bytes. */.
22350 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 sqlite3_stmt **p
22360 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 pStmt, /* OUT:
22370 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 Statement handle
22380 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
22390 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a **pzTail /*
223a0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f OUT: Pointer to
223b0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 unused portion
223c0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e of zSql */.);.in
223d0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 t sqlite3_prepar
223e0 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 e_v2(. sqlite3
223f0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
22400 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 /* Database hand
22410 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 le */. const ch
22420 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 ar *zSql,
22430 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 /* SQL statement
22440 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 , UTF-8 encoded
22450 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 */. int nByte,
22460 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
22470 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f Maximum length o
22480 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e f zSql in bytes.
22490 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 */. sqlite3_st
224a0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a mt **ppStmt, /*
224b0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 OUT: Statement
224c0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
224d0 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 t char **pzTail
224e0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e /* OUT: Poin
224f0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f ter to unused po
22500 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f rtion of zSql */
22510 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .);.int sqlite3_
22520 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c prepare16(. sql
22530 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
22540 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
22550 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
22560 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 st void *zSql,
22570 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 /* SQL stat
22580 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e ement, UTF-16 en
22590 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e coded */. int n
225a0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 Byte,
225b0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 /* Maximum le
225c0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 ngth of zSql in
225d0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 bytes. */. sqli
225e0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d te3_stmt **ppStm
225f0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 t, /* OUT: Stat
22600 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a ement handle */.
22610 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 const void **p
22620 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 zTail /* OUT
22630 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 : Pointer to unu
22640 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a sed portion of z
22650 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 Sql */.);.int sq
22660 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
22670 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 v2(. sqlite3 *d
22680 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a b, /*
22690 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 Database handle
226a0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 */. const void
226b0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a *zSql, /*
226c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 SQL statement,
226d0 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a UTF-16 encoded *
226e0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 /. int nByte,
226f0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d /* M
22700 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
22710 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 zSql in bytes.
22720 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d */. sqlite3_stm
22730 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 t **ppStmt, /*
22740 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 OUT: Statement h
22750 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
22760 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 void **pzTail
22770 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 /* OUT: Point
22780 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 er to unused por
22790 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a tion of zSql */.
227a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
227b0 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 EF: Retrieving S
227c0 74 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b 48 31 tatement SQL {H1
227d0 33 31 30 30 7d 20 3c 48 31 33 30 30 30 3e 0a 2a 3100} <H13000>.*
227e0 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 *.** This interf
227f0 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ace can be used
22800 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61 to retrieve a sa
22810 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 ved copy of the
22820 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 original.** SQL
22830 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 text used to cre
22840 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 ate a [prepared
22850 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 statement] if th
22860 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 at statement was
22870 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 .** compiled usi
22880 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 ng either [sqlit
22890 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
228a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 or [sqlite3_pre
228b0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a pare16_v2()]..**
228c0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
228d0 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30 31 7d 20 49 **.** {H13101} I
228e0 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 f the [prepared
228f0 73 74 61 74 65 6d 65 6e 74 5d 20 70 61 73 73 65 statement] passe
22900 64 20 61 73 20 74 68 65 20 61 72 67 75 6d 65 6e d as the argumen
22910 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 t to.**
22920 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d [sqlite3_sql()]
22930 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 75 73 was compiled us
22940 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 ing either [sqli
22950 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
22960 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 ] or.**
22970 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
22980 65 31 36 5f 76 32 28 29 5d 2c 20 74 68 65 6e 20 e16_v2()], then
22990 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 [sqlite3_sql()]
229a0 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 returns.**
229b0 20 20 20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f a pointer to
229c0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
229d0 65 64 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 ed string contai
229e0 6e 69 6e 67 20 61 20 55 54 46 2d 38 20 72 65 6e ning a UTF-8 ren
229f0 64 65 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 dering.**
22a00 20 20 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e of the origin
22a10 61 6c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 al SQL statement
22a20 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30 32 7d ..**.** {H13102}
22a30 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 If the [prepare
22a40 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61 73 d statement] pas
22a50 73 65 64 20 61 73 20 74 68 65 20 61 72 67 75 6d sed as the argum
22a60 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 ent to.**
22a70 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 [sqlite3_sql(
22a80 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 )] was compiled
22a90 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 using either [sq
22aa0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d lite3_prepare()]
22ab0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 or.**
22ac0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
22ad0 31 36 28 29 5d 2c 20 74 68 65 6e 20 5b 73 71 6c 16()], then [sql
22ae0 69 74 65 33 5f 73 71 6c 28 29 5d 20 72 65 74 75 ite3_sql()] retu
22af0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 rns a NULL point
22b00 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30 er..**.** {H1310
22b10 33 7d 20 54 68 65 20 73 74 72 69 6e 67 20 72 65 3} The string re
22b20 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
22b30 65 33 5f 73 71 6c 28 53 29 5d 20 69 73 20 76 61 e3_sql(S)] is va
22b40 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 0a 2a 2a lid until the.**
22b50 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 [prepa
22b60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
22b70 20 69 73 20 64 65 6c 65 74 65 64 20 75 73 69 6e is deleted usin
22b80 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c g [sqlite3_final
22b90 69 7a 65 28 53 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 ize(S)]..*/.cons
22ba0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
22bb0 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 sql(sqlite3_stmt
22bc0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
22bd0 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d CAPI3REF: Dynam
22be0 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c ically Typed Val
22bf0 75 65 20 4f 62 6a 65 63 74 20 7b 48 31 35 30 30 ue Object {H1500
22c00 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 0} <S20200>.** K
22c10 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 EYWORDS: {protec
22c20 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
22c30 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 e} {unprotected
22c40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a sqlite3_value}.*
22c50 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 *.** SQLite uses
22c60 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c the sqlite3_val
22c70 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 ue object to rep
22c80 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 resent all value
22c90 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 s.** that can be
22ca0 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 stored in a dat
22cb0 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c abase table. SQL
22cc0 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 ite uses dynamic
22cd0 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 typing.** for t
22ce0 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f he values it sto
22cf0 72 65 73 2e 20 56 61 6c 75 65 73 20 73 74 6f 72 res. Values stor
22d00 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 ed in sqlite3_va
22d10 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 lue objects.** c
22d20 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 an be integers,
22d30 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 floating point v
22d40 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 alues, strings,
22d50 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a BLOBs, or NULL..
22d60 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 **.** An sqlite3
22d70 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 _value object ma
22d80 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f y be either "pro
22d90 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 tected" or "unpr
22da0 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d otected"..** Som
22db0 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 e interfaces req
22dc0 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 uire a protected
22dd0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 sqlite3_value.
22de0 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 Other interface
22df0 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 s.** will accept
22e00 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 either a protec
22e10 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 ted or an unprot
22e20 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
22e30 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e lue..** Every in
22e40 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 terface that acc
22e50 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c epts sqlite3_val
22e60 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 ue arguments spe
22e70 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 cifies.** whethe
22e80 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 r or not it requ
22e90 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 ires a protected
22ea0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a sqlite3_value..
22eb0 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 **.** The terms
22ec0 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 "protected" and
22ed0 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 "unprotected" re
22ee0 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f fer to whether o
22ef0 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 r not.** a mutex
22f00 20 69 73 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 is held. A int
22f10 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 ernal mutex is h
22f20 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 eld for a protec
22f30 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 ted.** sqlite3_v
22f40 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 alue object but
22f50 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 no mutex is held
22f60 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 for an unprotec
22f70 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 ted.** sqlite3_v
22f80 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 alue object. If
22f90 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
22fa0 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 led to be single
22fb0 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 -threaded.** (wi
22fc0 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 th [SQLITE_THREA
22fd0 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 DSAFE=0] and wit
22fe0 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 h [sqlite3_threa
22ff0 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 dsafe()] returni
23000 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 ng 0).** or if S
23010 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 QLite is run in
23020 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d one of reduced m
23030 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b utex modes .** [
23040 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 SQLITE_CONFIG_SI
23050 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b NGLETHREAD] or [
23060 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
23070 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 LTITHREAD].** th
23080 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 en there is no d
23090 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 istinction betwe
230a0 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 en protected and
230b0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 unprotected.**
230c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
230d0 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 jects and they c
230e0 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 an be used inter
230f0 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 changeably. How
23100 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 ever,.** for max
23110 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 imum code portab
23120 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f ility it is reco
23130 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 mmended that app
23140 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 lications.** sti
23150 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 ll make the dist
23160 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 inction between
23170 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 between protecte
23180 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 d and unprotecte
23190 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c d.** sqlite3_val
231a0 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 ue objects even
231b0 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c when not strictl
231c0 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a y required..**.*
231d0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 * The sqlite3_va
231e0 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 lue objects that
231f0 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 are passed as p
23200 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 arameters into t
23210 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 he.** implementa
23220 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 tion of [applica
23230 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c tion-defined SQL
23240 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 functions] are
23250 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 54 68 protected..** Th
23260 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 e sqlite3_value
23270 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 object returned
23280 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 by.** [sqlite3_c
23290 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 olumn_value()] i
232a0 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a s unprotected..*
232b0 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 * Unprotected sq
232c0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
232d0 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 cts may only be
232e0 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 used with.** [sq
232f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
23300 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ue()] and [sqlit
23310 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d e3_bind_value()]
23320 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 ..** The [sqlite
23330 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 3_value_blob | s
23340 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 qlite3_value_typ
23350 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a e()] family of.*
23360 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 * interfaces req
23370 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 uire protected s
23380 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
23390 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 ects..*/.typedef
233a0 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 struct Mem sqli
233b0 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a te3_value;../*.*
233c0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 * CAPI3REF: SQL
233d0 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 Function Context
233e0 20 4f 62 6a 65 63 74 20 7b 48 31 36 30 30 31 7d Object {H16001}
233f0 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S20200>.**.**
23400 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 The context in w
23410 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 hich an SQL func
23420 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 tion executes is
23430 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a stored in an.**
23440 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
23450 20 6f 62 6a 65 63 74 2e 20 20 41 20 70 6f 69 6e object. A poin
23460 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 ter to an sqlite
23470 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 3_context object
23480 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 .** is always fi
23490 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f rst parameter to
234a0 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 [application-de
234b0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 fined SQL functi
234c0 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 ons]..** The app
234d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
234e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d SQL function im
234f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c plementation wil
23500 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 l pass this.** p
23510 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 ointer through i
23520 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 nto calls to [sq
23530 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 lite3_result_int
23540 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c | sqlite3_resul
23550 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 t()],.** [sqlite
23560 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 3_aggregate_cont
23570 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 ext()], [sqlite3
23580 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a _user_data()],.*
23590 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 * [sqlite3_conte
235a0 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c xt_db_handle()],
235b0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 [sqlite3_get_au
235c0 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 xdata()],.** and
235d0 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 /or [sqlite3_set
235e0 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a _auxdata()]..*/.
235f0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
23600 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 qlite3_context s
23610 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a qlite3_context;.
23620 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
23630 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 Binding Values
23640 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 To Prepared Stat
23650 65 6d 65 6e 74 73 20 7b 48 31 33 35 30 30 7d 20 ements {H13500}
23660 3c 53 37 30 33 30 30 3e 0a 2a 2a 20 4b 45 59 57 <S70300>.** KEYW
23670 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 ORDS: {host para
23680 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 meter} {host par
23690 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 ameters} {host p
236a0 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a arameter name}.*
236b0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c * KEYWORDS: {SQL
236c0 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c parameter} {SQL
236d0 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 parameters} {pa
236e0 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d rameter binding}
236f0 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 53 51 .**.** In the SQ
23700 4c 20 73 74 72 69 6e 67 73 20 69 6e 70 75 74 20 L strings input
23710 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 to [sqlite3_prep
23720 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 are_v2()] and it
23730 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c s variants,.** l
23740 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 iterals may be r
23750 65 70 6c 61 63 65 64 20 62 79 20 61 20 70 61 72 eplaced by a par
23760 61 6d 65 74 65 72 20 69 6e 20 6f 6e 65 20 6f 66 ameter in one of
23770 20 74 68 65 73 65 20 66 6f 72 6d 73 3a 0a 2a 2a these forms:.**
23780 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
23790 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e ?.** <li> ?NN
237a0 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a N.** <li> :VVV.
237b0 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a ** <li> @VVV.**
237c0 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c <li> $VVV.** <
237d0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 /ul>.**.** In th
237e0 65 20 70 61 72 61 6d 65 74 65 72 20 66 6f 72 6d e parameter form
237f0 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 4e 4e s shown above NN
23800 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 N is an integer
23810 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 literal,.** and
23820 56 56 56 20 69 73 20 61 6e 20 61 6c 70 68 61 2d VVV is an alpha-
23830 6e 75 6d 65 72 69 63 20 70 61 72 61 6d 65 74 65 numeric paramete
23840 72 20 6e 61 6d 65 2e 20 54 68 65 20 76 61 6c 75 r name. The valu
23850 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 es of these.** p
23860 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 arameters (also
23870 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 called "host par
23880 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 ameter names" or
23890 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 "SQL parameters
238a0 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 ").** can be set
238b0 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 using the sqlit
238c0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 e3_bind_*() rout
238d0 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 ines defined her
238e0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 e..**.** The fir
238f0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 st argument to t
23900 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
23910 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 *() routines is
23920 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e always.** a poin
23930 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 ter to the [sqli
23940 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 te3_stmt] object
23950 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a returned from.*
23960 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
23970 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 re_v2()] or its
23980 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 variants..**.**
23990 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d The second argum
239a0 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 ent is the index
239b0 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 of the SQL para
239c0 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e meter to be set.
239d0 0a 2a 2a 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 .** The leftmost
239e0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 SQL parameter h
239f0 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 as an index of 1
23a00 2e 20 20 57 68 65 6e 20 74 68 65 20 73 61 6d 65 . When the same
23a10 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 named.** SQL pa
23a20 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 rameter is used
23a30 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 more than once,
23a40 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 second and subse
23a50 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 quent.** occurre
23a60 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 nces have the sa
23a70 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 me index as the
23a80 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 first occurrence
23a90 2e 0a 2a 2a 20 54 68 65 20 69 6e 64 65 78 20 66 ..** The index f
23aa0 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 or named paramet
23ab0 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 ers can be looke
23ac0 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a d up using the.*
23ad0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
23ae0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 parameter_index(
23af0 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 )] API if desire
23b00 64 2e 20 20 54 68 65 20 69 6e 64 65 78 0a 2a 2a d. The index.**
23b10 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 for "?NNN" para
23b20 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 meters is the va
23b30 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 lue of NNN..** T
23b40 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 he NNN value mus
23b50 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 t be between 1 a
23b60 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f nd the [sqlite3_
23b70 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 limit()].** para
23b80 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 meter [SQLITE_LI
23b90 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d MIT_VARIABLE_NUM
23ba0 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 BER] (default va
23bb0 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a lue: 999)..**.**
23bc0 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d The third argum
23bd0 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 ent is the value
23be0 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 to bind to the
23bf0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a parameter..**.**
23c00 20 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e In those routin
23c10 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 es that have a f
23c20 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 ourth argument,
23c30 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 its value is the
23c40 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 .** number of by
23c50 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d tes in the param
23c60 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 eter. To be cle
23c70 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 ar: the value is
23c80 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f the.** number o
23c90 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 f <u>bytes</u> i
23ca0 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 n the value, not
23cb0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 the number of c
23cc0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 49 66 haracters..** If
23cd0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
23ce0 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 meter is negativ
23cf0 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 e, the length of
23d00 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a the string is.*
23d10 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 * the number of
23d20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 bytes up to the
23d30 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 first zero termi
23d40 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 nator..**.** The
23d50 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 fifth argument
23d60 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f to sqlite3_bind_
23d70 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f blob(), sqlite3_
23d80 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 bind_text(), and
23d90 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 .** sqlite3_bind
23da0 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64 _text16() is a d
23db0 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 estructor used t
23dc0 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 o dispose of the
23dd0 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 BLOB or.** stri
23de0 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 ng after SQLite
23df0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 has finished wit
23e00 68 20 69 74 2e 20 49 66 20 74 68 65 20 66 69 66 h it. If the fif
23e10 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a th argument is.*
23e20 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 * the special va
23e30 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 lue [SQLITE_STAT
23e40 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 IC], then SQLite
23e50 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 assumes that th
23e60 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e e.** information
23e70 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 is in static, u
23e80 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 nmanaged space a
23e90 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 nd does not need
23ea0 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a to be freed..**
23eb0 20 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 If the fifth ar
23ec0 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 gument has the v
23ed0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 alue [SQLITE_TRA
23ee0 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a NSIENT], then.**
23ef0 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 SQLite makes it
23f00 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f s own private co
23f10 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 py of the data i
23f20 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f mmediately, befo
23f30 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 re.** the sqlite
23f40 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 3_bind_*() routi
23f50 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a ne returns..**.*
23f60 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 * The sqlite3_bi
23f70 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f nd_zeroblob() ro
23f80 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c utine binds a BL
23f90 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 OB of length N t
23fa0 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 hat.** is filled
23fb0 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 41 with zeroes. A
23fc0 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 zeroblob uses a
23fd0 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 fixed amount of
23fe0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 memory.** (just
23ff0 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 an integer to h
24000 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 old its size) wh
24010 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 ile it is being
24020 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 processed..** Ze
24030 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 roblobs are inte
24040 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 nded to serve as
24050 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f placeholders fo
24060 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a r BLOBs whose.**
24070 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 content is late
24080 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a r written using.
24090 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 ** [sqlite3_blob
240a0 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e _open | incremen
240b0 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f tal BLOB I/O] ro
240c0 75 74 69 6e 65 73 2e 0a 2a 2a 20 41 20 6e 65 67 utines..** A neg
240d0 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 ative value for
240e0 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 the zeroblob res
240f0 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c ults in a zero-l
24100 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a ength BLOB..**.*
24110 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 * The sqlite3_bi
24120 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 nd_*() routines
24130 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 61 must be called a
24140 66 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 fter.** [sqlite3
24150 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 28 _prepare_v2()] (
24160 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 and its variants
24170 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ) or [sqlite3_re
24180 73 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 set()] and.** be
24190 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 fore [sqlite3_st
241a0 65 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e ep()]..** Bindin
241b0 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 gs are not clear
241c0 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 ed by the [sqlit
241d0 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 e3_reset()] rout
241e0 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 ine..** Unbound
241f0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 parameters are i
24200 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 nterpreted as NU
24210 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 LL..**.** These
24220 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
24230 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 [SQLITE_OK] on s
24240 75 63 63 65 73 73 20 6f 72 20 61 6e 20 65 72 72 uccess or an err
24250 6f 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e or code if.** an
24260 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e ything goes wron
24270 67 2e 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 g. [SQLITE_RANG
24280 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 E] is returned i
24290 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a f the parameter.
242a0 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 ** index is out
242b0 6f 66 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49 of range. [SQLI
242c0 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 TE_NOMEM] is ret
242d0 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 urned if malloc(
242e0 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c ) fails..** [SQL
242f0 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 69 67 68 ITE_MISUSE] migh
24300 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 t be returned if
24310 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
24320 61 72 65 20 63 61 6c 6c 65 64 20 6f 6e 20 61 0a are called on a.
24330 2a 2a 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 ** virtual machi
24340 6e 65 20 74 68 61 74 20 69 73 20 74 68 65 20 77 ne that is the w
24350 72 6f 6e 67 20 73 74 61 74 65 20 6f 72 20 77 68 rong state or wh
24360 69 63 68 20 68 61 73 20 61 6c 72 65 61 64 79 20 ich has already
24370 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a been finalized..
24380 2a 2a 20 44 65 74 65 63 74 69 6f 6e 20 6f 66 20 ** Detection of
24390 6d 69 73 75 73 65 20 69 73 20 75 6e 72 65 6c 69 misuse is unreli
243a0 61 62 6c 65 2e 20 20 41 70 70 6c 69 63 61 74 69 able. Applicati
243b0 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 64 ons should not d
243c0 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49 epend.** on SQLI
243d0 54 45 5f 4d 49 53 55 53 45 20 72 65 74 75 72 6e TE_MISUSE return
243e0 73 2e 20 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 s. SQLITE_MISUS
243f0 45 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f E is intended to
24400 20 69 6e 64 69 63 61 74 65 20 61 0a 2a 2a 20 61 indicate a.** a
24410 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 logic error in
24420 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e the application.
24430 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e Future version
24440 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 s of SQLite migh
24450 74 0a 2a 2a 20 70 61 6e 69 63 20 72 61 74 68 65 t.** panic rathe
24460 72 20 74 68 61 6e 20 72 65 74 75 72 6e 20 53 51 r than return SQ
24470 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a LITE_MISUSE..**.
24480 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
24490 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
244a0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a eter_count()],.*
244b0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
244c0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 parameter_name()
244d0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ], and [sqlite3_
244e0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 bind_parameter_i
244f0 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 ndex()]..**.** I
24500 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
24510 20 7b 48 31 33 35 30 36 7d 20 54 68 65 20 5b 53 {H13506} The [S
24520 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d QL statement com
24530 70 69 6c 65 72 5d 20 72 65 63 6f 67 6e 69 7a 65 piler] recognize
24540 73 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 20 s tokens of the
24550 66 6f 72 6d 73 0a 2a 2a 20 20 20 20 20 20 20 20 forms.**
24560 20 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 "?", "?NNN", "
24570 24 56 56 56 22 2c 20 22 3a 56 56 56 22 2c 20 61 $VVV", ":VVV", a
24580 6e 64 20 22 40 56 56 56 22 20 61 73 20 53 51 4c nd "@VVV" as SQL
24590 20 70 61 72 61 6d 65 74 65 72 73 2c 0a 2a 2a 20 parameters,.**
245a0 20 20 20 20 20 20 20 20 20 77 68 65 72 65 20 4e where N
245b0 4e 4e 20 69 73 20 61 6e 79 20 73 65 71 75 65 6e NN is any sequen
245c0 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 ce of one or mor
245d0 65 20 64 69 67 69 74 73 0a 2a 2a 20 20 20 20 20 e digits.**
245e0 20 20 20 20 20 61 6e 64 20 77 68 65 72 65 20 56 and where V
245f0 56 56 20 69 73 20 61 6e 79 20 73 65 71 75 65 6e VV is any sequen
24600 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 ce of one or mor
24610 65 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 0a 2a e alphanumeric.*
24620 2a 20 20 20 20 20 20 20 20 20 20 63 68 61 72 61 * chara
24630 63 74 65 72 73 20 6f 72 20 22 3a 3a 22 20 6f 70 cters or "::" op
24640 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77 65 tionally followe
24650 64 20 62 79 20 61 20 73 74 72 69 6e 67 20 63 6f d by a string co
24660 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 ntaining.**
24670 20 20 20 20 20 6e 6f 20 73 70 61 63 65 73 20 61 no spaces a
24680 6e 64 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 nd contained wit
24690 68 69 6e 20 70 61 72 65 6e 74 68 65 73 65 73 2e hin parentheses.
246a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 30 39 7d 20 .**.** {H13509}
246b0 54 68 65 20 69 6e 69 74 69 61 6c 20 76 61 6c 75 The initial valu
246c0 65 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 e of an SQL para
246d0 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a meter is NULL..*
246e0 2a 0a 2a 2a 20 7b 48 31 33 35 31 32 7d 20 54 68 *.** {H13512} Th
246f0 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f e index of an "?
24700 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 " SQL parameter
24710 69 73 20 6f 6e 65 20 6c 61 72 67 65 72 20 74 68 is one larger th
24720 61 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 an the.**
24730 20 20 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 largest index
24740 20 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65 of SQL paramete
24750 72 20 74 6f 20 74 68 65 20 6c 65 66 74 2c 20 6f r to the left, o
24760 72 20 31 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 r 1 if.**
24770 20 20 20 74 68 65 20 22 3f 22 20 69 73 20 74 68 the "?" is th
24780 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 e leftmost SQL p
24790 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 arameter..**.**
247a0 7b 48 31 33 35 31 35 7d 20 54 68 65 20 69 6e 64 {H13515} The ind
247b0 65 78 20 6f 66 20 61 6e 20 22 3f 4e 4e 4e 22 20 ex of an "?NNN"
247c0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 SQL parameter is
247d0 20 74 68 65 20 69 6e 74 65 67 65 72 20 4e 4e 4e the integer NNN
247e0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 38 7d ..**.** {H13518}
247f0 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e The index of an
24800 20 22 3a 56 56 56 22 2c 20 22 24 56 56 56 22 2c ":VVV", "$VVV",
24810 20 6f 72 20 22 40 56 56 56 22 20 53 51 4c 20 70 or "@VVV" SQL p
24820 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20 arameter is.**
24830 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 the same
24840 20 61 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 as the index of
24850 20 6c 65 66 74 6d 6f 73 74 20 6f 63 63 75 72 72 leftmost occurr
24860 65 6e 63 65 73 20 6f 66 20 74 68 65 20 73 61 6d ences of the sam
24870 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 e.** pa
24880 72 61 6d 65 74 65 72 2c 20 6f 72 20 6f 6e 65 20 rameter, or one
24890 6d 6f 72 65 20 74 68 61 6e 20 74 68 65 20 6c 61 more than the la
248a0 72 67 65 73 74 20 69 6e 64 65 78 20 6f 76 65 72 rgest index over
248b0 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 all.**
248c0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 parameters to t
248d0 68 65 20 6c 65 66 74 20 69 66 20 74 68 69 73 20 he left if this
248e0 69 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 is the first occ
248f0 75 72 72 65 6e 63 65 0a 2a 2a 20 20 20 20 20 20 urrence.**
24900 20 20 20 20 6f 66 20 74 68 69 73 20 70 61 72 61 of this para
24910 6d 65 74 65 72 2c 20 6f 72 20 31 20 69 66 20 74 meter, or 1 if t
24920 68 69 73 20 69 73 20 74 68 65 20 6c 65 66 74 6d his is the leftm
24930 6f 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a ost parameter..*
24940 2a 0a 2a 2a 20 7b 48 31 33 35 32 31 7d 20 54 68 *.** {H13521} Th
24950 65 20 5b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 e [SQL statement
24960 20 63 6f 6d 70 69 6c 65 72 5d 20 66 61 69 6c 73 compiler] fails
24970 20 77 69 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 with an [SQLITE
24980 5f 52 41 4e 47 45 5d 0a 2a 2a 20 20 20 20 20 20 _RANGE].**
24990 20 20 20 20 65 72 72 6f 72 20 69 66 20 74 68 65 error if the
249a0 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c index of an SQL
249b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 parameter is le
249c0 73 73 20 74 68 61 6e 20 31 0a 2a 2a 20 20 20 20 ss than 1.**
249d0 20 20 20 20 20 20 6f 72 20 67 72 65 61 74 65 72 or greater
249e0 20 74 68 61 6e 20 74 68 65 20 63 6f 6d 70 69 6c than the compil
249f0 65 2d 74 69 6d 65 20 53 51 4c 49 54 45 5f 4d 41 e-time SQLITE_MA
24a00 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 X_VARIABLE_NUMBE
24a10 52 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 R.** pa
24a20 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b rameter..**.** {
24a30 48 31 33 35 32 34 7d 20 43 61 6c 6c 73 20 74 6f H13524} Calls to
24a40 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 [sqlite3_bind_t
24a50 65 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 ext | sqlite3_bi
24a60 6e 64 28 53 2c 4e 2c 56 2c 2e 2e 2e 29 5d 0a 2a nd(S,N,V,...)].*
24a70 2a 20 20 20 20 20 20 20 20 20 20 61 73 73 6f 63 * assoc
24a80 69 61 74 65 20 74 68 65 20 76 61 6c 75 65 20 56 iate the value V
24a90 20 77 69 74 68 20 61 6c 6c 20 53 51 4c 20 70 61 with all SQL pa
24aa0 72 61 6d 65 74 65 72 73 20 68 61 76 69 6e 67 20 rameters having
24ab0 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 an.** i
24ac0 6e 64 65 78 20 6f 66 20 4e 20 69 6e 20 74 68 65 ndex of N in the
24ad0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
24ae0 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b ment] S..**.** {
24af0 48 31 33 35 32 37 7d 20 43 61 6c 6c 73 20 74 6f H13527} Calls to
24b00 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 [sqlite3_bind_t
24b10 65 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 ext | sqlite3_bi
24b20 6e 64 28 53 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 nd(S,N,...)].**
24b30 20 20 20 20 20 20 20 20 20 6f 76 65 72 72 69 64 overrid
24b40 65 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 77 69 e prior calls wi
24b50 74 68 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 th the same valu
24b60 65 73 20 6f 66 20 53 20 61 6e 64 20 4e 2e 0a 2a es of S and N..*
24b70 2a 0a 2a 2a 20 7b 48 31 33 35 33 30 7d 20 42 69 *.** {H13530} Bi
24b80 6e 64 69 6e 67 73 20 65 73 74 61 62 6c 69 73 68 ndings establish
24b90 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 ed by [sqlite3_b
24ba0 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 ind_text | sqlit
24bb0 65 33 5f 62 69 6e 64 28 53 2c 2e 2e 2e 29 5d 0a e3_bind(S,...)].
24bc0 2a 2a 20 20 20 20 20 20 20 20 20 20 70 65 72 73 ** pers
24bd0 69 73 74 20 61 63 72 6f 73 73 20 63 61 6c 6c 73 ist across calls
24be0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 to [sqlite3_res
24bf0 65 74 28 53 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 et(S)]..**.** {H
24c00 31 33 35 33 33 7d 20 49 6e 20 63 61 6c 6c 73 20 13533} In calls
24c10 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 to [sqlite3_bind
24c20 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 _blob(S,N,V,L,D)
24c30 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b ],.** [
24c40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
24c50 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f t(S,N,V,L,D)], o
24c60 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 r.** [s
24c70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
24c80 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 16(S,N,V,L,D)] S
24c90 51 4c 69 74 65 20 62 69 6e 64 73 20 74 68 65 20 QLite binds the
24ca0 66 69 72 73 74 20 4c 0a 2a 2a 20 20 20 20 20 20 first L.**
24cb0 20 20 20 20 62 79 74 65 73 20 6f 66 20 74 68 65 bytes of the
24cc0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 BLOB or string
24cd0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 56 2c pointed to by V,
24ce0 20 77 68 65 6e 20 4c 0a 2a 2a 20 20 20 20 20 20 when L.**
24cf0 20 20 20 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 is non-negat
24d00 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 ive..**.** {H135
24d10 33 36 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 36} In calls to
24d20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 [sqlite3_bind_te
24d30 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 6f xt(S,N,V,L,D)] o
24d40 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 r.** [s
24d50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
24d60 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 16(S,N,V,L,D)] S
24d70 51 4c 69 74 65 20 62 69 6e 64 73 20 63 68 61 72 QLite binds char
24d80 61 63 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 acters.**
24d90 20 20 20 66 72 6f 6d 20 56 20 74 68 72 6f 75 67 from V throug
24da0 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f h the first zero
24db0 20 63 68 61 72 61 63 74 65 72 20 77 68 65 6e 20 character when
24dc0 4c 20 69 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a L is negative..*
24dd0 2a 0a 2a 2a 20 7b 48 31 33 35 33 39 7d 20 49 6e *.** {H13539} In
24de0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
24df0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e e3_bind_blob(S,N
24e00 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 ,V,L,D)],.**
24e10 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 [sqlite3_b
24e20 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c ind_text(S,N,V,L
24e30 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 ,D)], or.**
24e40 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 [sqlite3_bi
24e50 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c nd_text16(S,N,V,
24e60 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 L,D)] when D is
24e70 74 68 65 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 the special.**
24e80 20 20 20 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 constant
24e90 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d [SQLITE_STATIC]
24ea0 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 , SQLite assumes
24eb0 20 74 68 61 74 20 74 68 65 20 76 61 6c 75 65 20 that the value
24ec0 56 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 V.** is
24ed0 20 68 65 6c 64 20 69 6e 20 73 74 61 74 69 63 20 held in static
24ee0 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 unmanaged space
24ef0 74 68 61 74 20 77 69 6c 6c 20 6e 6f 74 20 63 68 that will not ch
24f00 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 ange.**
24f10 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 during the life
24f20 74 69 6d 65 20 6f 66 20 74 68 65 20 62 69 6e 64 time of the bind
24f30 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 ing..**.** {H135
24f40 34 32 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 42} In calls to
24f50 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
24f60 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a ob(S,N,V,L,D)],.
24f70 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
24f80 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 ite3_bind_text(S
24f90 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a ,N,V,L,D)], or.*
24fa0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
24fb0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 te3_bind_text16(
24fc0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e S,N,V,L,D)] when
24fd0 20 44 20 69 73 20 74 68 65 20 73 70 65 63 69 61 D is the specia
24fe0 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f l.** co
24ff0 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 54 nstant [SQLITE_T
25000 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 20 72 RANSIENT], the r
25010 6f 75 74 69 6e 65 20 6d 61 6b 65 73 20 61 0a 2a outine makes a.*
25020 2a 20 20 20 20 20 20 20 20 20 20 70 72 69 76 61 * priva
25030 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 te copy of the v
25040 61 6c 75 65 20 56 20 62 65 66 6f 72 65 20 69 74 alue V before it
25050 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 returns..**.**
25060 7b 48 31 33 35 34 35 7d 20 49 6e 20 63 61 6c 6c {H13545} In call
25070 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 s to [sqlite3_bi
25080 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c nd_blob(S,N,V,L,
25090 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 D)],.**
250a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 [sqlite3_bind_t
250b0 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c ext(S,N,V,L,D)],
250c0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 or.**
250d0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 [sqlite3_bind_te
250e0 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d xt16(S,N,V,L,D)]
250f0 20 77 68 65 6e 20 44 20 69 73 20 61 20 70 6f 69 when D is a poi
25100 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 nter to.**
25110 20 20 20 20 61 20 66 75 6e 63 74 69 6f 6e 2c 20 a function,
25120 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 SQLite invokes t
25130 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 hat function to
25140 64 65 73 74 72 6f 79 20 74 68 65 0a 2a 2a 20 20 destroy the.**
25150 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 56 20 value V
25160 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e after it has fin
25170 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 65 20 ished using the
25180 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b value V..**.** {
25190 48 31 33 35 34 38 7d 20 49 6e 20 63 61 6c 6c 73 H13548} In calls
251a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e to [sqlite3_bin
251b0 64 5f 7a 65 72 6f 62 6c 6f 62 28 53 2c 4e 2c 56 d_zeroblob(S,N,V
251c0 2c 4c 29 5d 20 74 68 65 20 76 61 6c 75 65 20 62 ,L)] the value b
251d0 6f 75 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 ound.**
251e0 20 69 73 20 61 20 42 4c 4f 42 20 6f 66 20 4c 20 is a BLOB of L
251f0 62 79 74 65 73 2c 20 6f 72 20 61 20 7a 65 72 6f bytes, or a zero
25200 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 66 20 -length BLOB if
25210 4c 20 69 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a L is negative..*
25220 2a 0a 2a 2a 20 7b 48 31 33 35 35 31 7d 20 49 6e *.** {H13551} In
25230 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
25240 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 53 2c e3_bind_value(S,
25250 4e 2c 56 29 5d 20 74 68 65 20 56 20 61 72 67 75 N,V)] the V argu
25260 6d 65 6e 74 20 6d 61 79 0a 2a 2a 20 20 20 20 20 ment may.**
25270 20 20 20 20 20 62 65 20 65 69 74 68 65 72 20 61 be either a
25280 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 [protected sqli
25290 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
252a0 74 20 6f 72 20 61 6e 0a 2a 2a 20 20 20 20 20 20 t or an.**
252b0 20 20 20 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 [unprotected
252c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
252d0 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73 object..*/.int s
252e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
252f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
25300 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a int, const void*
25310 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 , int n, void(*)
25320 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 (void*));.int sq
25330 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c lite3_bind_doubl
25340 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
25350 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 int, double);.i
25360 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
25370 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 int(sqlite3_stmt
25380 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e *, int, int);.in
25390 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 t sqlite3_bind_i
253a0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d nt64(sqlite3_stm
253b0 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 t*, int, sqlite3
253c0 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c _int64);.int sql
253d0 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 ite3_bind_null(s
253e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
253f0 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f t);.int sqlite3_
25400 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 bind_text(sqlite
25410 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 3_stmt*, int, co
25420 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e nst char*, int n
25430 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 , void(*)(void*)
25440 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 );.int sqlite3_b
25450 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 ind_text16(sqlit
25460 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 e3_stmt*, int, c
25470 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c onst void*, int,
25480 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 void(*)(void*))
25490 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 ;.int sqlite3_bi
254a0 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 nd_value(sqlite3
254b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e _stmt*, int, con
254c0 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 st sqlite3_value
254d0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f *);.int sqlite3_
254e0 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 bind_zeroblob(sq
254f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
25500 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a , int n);../*.**
25510 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 CAPI3REF: Numbe
25520 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 r Of SQL Paramet
25530 65 72 73 20 7b 48 31 33 36 30 30 7d 20 3c 53 37 ers {H13600} <S7
25540 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 0300>.**.** This
25550 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 routine can be
25560 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 used to find the
25570 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 number of [SQL
25580 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 parameters].** i
25590 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 n a [prepared st
255a0 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 atement]. SQL p
255b0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f arameters are to
255c0 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 kens of the.** f
255d0 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c orm "?", "?NNN",
255e0 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c ":AAA", "$AAA",
255f0 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 or "@AAA" that
25600 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 serve as.** plac
25610 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c eholders for val
25620 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 ues that are [sq
25630 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 lite3_bind_blob
25640 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 | bound].** to t
25650 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 he parameters at
25660 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a a later time..*
25670 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
25680 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 e actually retur
25690 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 ns the index of
256a0 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 the largest (rig
256b0 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d htmost).** param
256c0 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f eter. For all fo
256d0 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c rms except ?NNN,
256e0 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 this will corre
256f0 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 spond to the.**
25700 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 number of unique
25710 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 parameters. If
25720 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 parameters of t
25730 68 65 20 3f 4e 4e 4e 20 61 72 65 20 75 73 65 64 he ?NNN are used
25740 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 ,.** there may b
25750 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 e gaps in the li
25760 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c st..**.** See al
25770 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e so: [sqlite3_bin
25780 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 d_blob|sqlite3_b
25790 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 ind()],.** [sqli
257a0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
257b0 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a er_name()], and.
257c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
257d0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 _parameter_index
257e0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 ()]..**.** INVAR
257f0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
25800 33 36 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 3601} The [sqlit
25810 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
25820 72 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 r_count(S)] inte
25830 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a rface returns.**
25840 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6c 61 the la
25850 72 67 65 73 74 20 69 6e 64 65 78 20 6f 66 20 61 rgest index of a
25860 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 ll SQL parameter
25870 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 s in the.**
25880 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 [prepared s
25890 74 61 74 65 6d 65 6e 74 5d 20 53 2c 20 6f 72 20 tatement] S, or
258a0 30 20 69 66 20 53 20 63 6f 6e 74 61 69 6e 73 20 0 if S contains
258b0 6e 6f 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 no SQL parameter
258c0 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 s..*/.int sqlite
258d0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
258e0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 _count(sqlite3_s
258f0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 tmt*);../*.** CA
25900 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 PI3REF: Name Of
25910 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 A Host Parameter
25920 20 7b 48 31 33 36 32 30 7d 20 3c 53 37 30 33 30 {H13620} <S7030
25930 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 0>.**.** This ro
25940 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 utine returns a
25950 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e pointer to the n
25960 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74 68 0a ame of the n-th.
25970 2a 2a 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 ** [SQL paramete
25980 72 5d 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 r] in a [prepare
25990 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a d statement]..**
259a0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 SQL parameters
259b0 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e of the form "?NN
259c0 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 N" or ":AAA" or
259d0 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 "@AAA" or "$AAA"
259e0 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 .** have a name
259f0 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 which is the str
25a00 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a ing "?NNN" or ":
25a10 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f AAA" or "@AAA" o
25a20 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 r "$AAA".** resp
25a30 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 ectively..** In
25a40 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 other words, the
25a50 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 initial ":" or
25a60 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f "$" or "@" or "?
25a70 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 ".** is included
25a80 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 as part of the
25a90 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 name..** Paramet
25aa0 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 ers of the form
25ab0 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f "?" without a fo
25ac0 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 llowing integer
25ad0 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 have no name.**
25ae0 61 6e 64 20 61 72 65 20 61 6c 73 6f 20 72 65 66 and are also ref
25af0 65 72 72 65 64 20 74 6f 20 61 73 20 22 61 6e 6f erred to as "ano
25b00 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 nymous parameter
25b10 73 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 s"..**.** The fi
25b20 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 rst host paramet
25b30 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 er has an index
25b40 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a of 1, not 0..**.
25b50 2a 2a 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 ** If the value
25b60 6e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 n is out of rang
25b70 65 20 6f 72 20 69 66 20 74 68 65 20 6e 2d 74 68 e or if the n-th
25b80 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a parameter is.**
25b90 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 nameless, then
25ba0 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 NULL is returned
25bb0 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 . The returned
25bc0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 string is.** alw
25bd0 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 ays in UTF-8 enc
25be0 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 oding even if th
25bf0 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 e named paramete
25c00 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 r was.** origina
25c10 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73 lly specified as
25c20 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 UTF-16 in [sqli
25c30 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d te3_prepare16()]
25c40 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
25c50 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e prepare16_v2()].
25c60 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
25c70 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
25c80 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 lob|sqlite3_bind
25c90 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
25ca0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
25cb0 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a count()], and.**
25cc0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
25cd0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 arameter_index()
25ce0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 ]..**.** INVARIA
25cf0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 NTS:.**.** {H136
25d00 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 21} The [sqlite3
25d10 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
25d20 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 name(S,N)] inter
25d30 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 face returns.**
25d40 20 20 20 20 20 20 20 20 20 61 20 55 54 46 2d 38 a UTF-8
25d50 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 rendering of th
25d60 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 e name of the SQ
25d70 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a L parameter in.*
25d80 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b * the [
25d90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
25da0 6e 74 5d 20 53 20 68 61 76 69 6e 67 20 69 6e 64 nt] S having ind
25db0 65 78 20 4e 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 ex N, or.**
25dc0 20 20 20 20 20 4e 55 4c 4c 20 69 66 20 74 68 65 NULL if the
25dd0 72 65 20 69 73 20 6e 6f 20 53 51 4c 20 70 61 72 re is no SQL par
25de0 61 6d 65 74 65 72 20 77 69 74 68 20 69 6e 64 65 ameter with inde
25df0 78 20 4e 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a x N or if the.**
25e00 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 parame
25e10 74 65 72 20 77 69 74 68 20 69 6e 64 65 78 20 4e ter with index N
25e20 20 69 73 20 61 6e 20 61 6e 6f 6e 79 6d 6f 75 73 is an anonymous
25e30 20 70 61 72 61 6d 65 74 65 72 20 22 3f 22 2e 0a parameter "?"..
25e40 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 */.const char *s
25e50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
25e60 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 meter_name(sqlit
25e70 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a e3_stmt*, int);.
25e80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
25e90 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 Index Of A Para
25ea0 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 meter With A Giv
25eb0 65 6e 20 4e 61 6d 65 20 7b 48 31 33 36 34 30 7d en Name {H13640}
25ec0 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S70300>.**.**
25ed0 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 Return the index
25ee0 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d of an SQL param
25ef0 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e eter given its n
25f00 61 6d 65 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 64 ame. The.** ind
25f10 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 ex value returne
25f20 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f d is suitable fo
25f30 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 r use as the sec
25f40 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ond.** parameter
25f50 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e to [sqlite3_bin
25f60 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 d_blob|sqlite3_b
25f70 69 6e 64 28 29 5d 2e 20 20 41 20 7a 65 72 6f 0a ind()]. A zero.
25f80 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 ** is returned i
25f90 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 f no matching pa
25fa0 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 rameter is found
25fb0 2e 20 20 54 68 65 20 70 61 72 61 6d 65 74 65 72 . The parameter
25fc0 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 .** name must be
25fd0 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 given in UTF-8
25fe0 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 even if the orig
25ff0 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a inal statement.*
26000 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 * was prepared f
26010 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 rom UTF-16 text
26020 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 using [sqlite3_p
26030 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a repare16_v2()]..
26040 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
26050 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
26060 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 ob|sqlite3_bind(
26070 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
26080 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 bind_parameter_c
26090 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 ount()], and.**
260a0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
260b0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d rameter_index()]
260c0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
260d0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 34 TS:.**.** {H1364
260e0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 1} The [sqlite3_
260f0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 bind_parameter_i
26100 6e 64 65 78 28 53 2c 4e 29 5d 20 69 6e 74 65 72 ndex(S,N)] inter
26110 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 face returns.**
26120 20 20 20 20 20 20 20 20 20 74 68 65 20 69 6e 64 the ind
26130 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 ex of SQL parame
26140 74 65 72 20 69 6e 20 74 68 65 20 5b 70 72 65 70 ter in the [prep
26150 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a ared statement].
26160 2a 2a 20 20 20 20 20 20 20 20 20 20 53 20 77 68 ** S wh
26170 6f 73 65 20 6e 61 6d 65 20 6d 61 74 63 68 65 73 ose name matches
26180 20 74 68 65 20 55 54 46 2d 38 20 73 74 72 69 6e the UTF-8 strin
26190 67 20 4e 2c 20 6f 72 20 30 20 69 66 20 74 68 65 g N, or 0 if the
261a0 72 65 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 re is.**
261b0 20 20 6e 6f 20 6d 61 74 63 68 2e 0a 2a 2f 0a 69 no match..*/.i
261c0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
261d0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 parameter_index(
261e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 sqlite3_stmt*, c
261f0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
26200 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
26210 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 EF: Reset All Bi
26220 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 ndings On A Prep
26230 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 7b ared Statement {
26240 48 31 33 36 36 30 7d 20 3c 53 37 30 33 30 30 3e H13660} <S70300>
26250 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20 .**.** Contrary
26260 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e to the intuition
26270 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 of many, [sqlit
26280 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 e3_reset()] does
26290 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 not reset.** th
262a0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f e [sqlite3_bind_
262b0 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d blob | bindings]
262c0 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 on a [prepared
262d0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 55 statement]..** U
262e0 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 se this routine
262f0 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 to reset all hos
26300 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 t parameters to
26310 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 NULL..**.** INVA
26320 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
26330 31 33 36 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 13661} The [sqli
26340 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e te3_clear_bindin
26350 67 73 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 gs(S)] interface
26360 20 72 65 73 65 74 73 20 61 6c 6c 20 53 51 4c 0a resets all SQL.
26370 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 ** para
26380 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 73 20 69 meter bindings i
26390 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 n the [prepared
263a0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 62 61 63 statement] S bac
263b0 6b 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e k to NULL..*/.in
263c0 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f t sqlite3_clear_
263d0 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 bindings(sqlite3
263e0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 _stmt*);../*.**
263f0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 CAPI3REF: Number
26400 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 Of Columns In A
26410 20 52 65 73 75 6c 74 20 53 65 74 20 7b 48 31 33 Result Set {H13
26420 37 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 710} <S10700>.**
26430 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e .** Return the n
26440 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
26450 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 in the result s
26460 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 et returned by t
26470 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 he.** [prepared
26480 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68 69 73 statement]. This
26490 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
264a0 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 0 if pStmt is a
264b0 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 n SQL.** stateme
264c0 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 nt that does not
264d0 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f return data (fo
264e0 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 r example an [UP
264f0 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e DATE])..**.** IN
26500 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
26510 7b 48 31 33 37 31 31 7d 20 54 68 65 20 5b 73 71 {H13711} The [sq
26520 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 lite3_column_cou
26530 6e 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 nt(S)] interface
26540 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
26550 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 ber of.**
26560 20 20 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 columns in th
26570 65 20 72 65 73 75 6c 74 20 73 65 74 20 67 65 6e e result set gen
26580 65 72 61 74 65 64 20 62 79 20 74 68 65 20 5b 70 erated by the [p
26590 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
265a0 74 5d 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 t] S,.**
265b0 20 20 6f 72 20 30 20 69 66 20 53 20 64 6f 65 73 or 0 if S does
265c0 20 6e 6f 74 20 67 65 6e 65 72 61 74 65 20 61 20 not generate a
265d0 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69 result set..*/.i
265e0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nt sqlite3_colum
265f0 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f n_count(sqlite3_
26600 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f stmt *pStmt);../
26610 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
26620 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 olumn Names In A
26630 20 52 65 73 75 6c 74 20 53 65 74 20 7b 48 31 33 Result Set {H13
26640 37 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 720} <S10700>.**
26650 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
26660 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 es return the na
26670 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 me assigned to a
26680 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 particular colu
26690 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 mn.** in the res
266a0 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 ult set of a [SE
266b0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e LECT] statement.
266c0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f The sqlite3_co
266d0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 lumn_name().** i
266e0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
266f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
26700 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
26710 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 UTF-8 string.**
26720 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 and sqlite3_colu
26730 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 mn_name16() retu
26740 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
26750 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
26760 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 ed.** UTF-16 str
26770 69 6e 67 2e 20 20 54 68 65 20 66 69 72 73 74 20 ing. The first
26780 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
26790 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
267a0 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d ment].** that im
267b0 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 plements the [SE
267c0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e LECT] statement.
267d0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 The second para
267e0 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 meter is the.**
267f0 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 column number.
26800 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c The leftmost col
26810 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e umn is number 0.
26820 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 .**.** The retur
26830 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 ned string point
26840 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 er is valid unti
26850 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 l either the [pr
26860 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
26870 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 ].** is destroye
26880 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 d by [sqlite3_fi
26890 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 nalize()] or unt
268a0 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c il the next call
268b0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 to.** sqlite3_c
268c0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 olumn_name() or
268d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e sqlite3_column_n
268e0 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 ame16() on the s
268f0 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a ame column..**.*
26900 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c * If sqlite3_mal
26910 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 loc() fails duri
26920 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e ng the processin
26930 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 g of either rout
26940 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d ine.** (for exam
26950 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e ple during a con
26960 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 version from UTF
26970 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 -8 to UTF-16) th
26980 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 en a.** NULL poi
26990 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 nter is returned
269a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 ..**.** The name
269b0 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c of a result col
269c0 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 umn is the value
269d0 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 of the "AS" cla
269e0 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 use for.** that
269f0 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 column, if there
26a00 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 is an AS clause
26a10 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e . If there is n
26a20 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 o AS clause.** t
26a30 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 hen the name of
26a40 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e the column is un
26a50 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 specified and ma
26a60 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a y change from.**
26a70 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 one release of
26a80 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 SQLite to the ne
26a90 78 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 xt..**.** INVARI
26aa0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 ANTS:.**.** {H13
26ab0 37 32 31 7d 20 41 20 73 75 63 63 65 73 73 66 75 721} A successfu
26ac0 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 l invocation of
26ad0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c the [sqlite3_col
26ae0 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 0a 2a umn_name(S,N)].*
26af0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 * inter
26b00 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 face returns the
26b10 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 74 68 name of the Nth
26b20 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65 20 30 column (where 0
26b30 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 is.**
26b40 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c the leftmost col
26b50 75 6d 6e 29 20 66 6f 72 20 74 68 65 20 72 65 73 umn) for the res
26b60 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 0a 2a ult set of the.*
26b70 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 * [prep
26b80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
26b90 53 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d S as a zero-term
26ba0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 inated UTF-8 str
26bb0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 ing..**.** {H137
26bc0 32 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 23} A successful
26bd0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 invocation of t
26be0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 he [sqlite3_colu
26bf0 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 0a mn_name16(S,N)].
26c00 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 ** inte
26c10 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 rface returns th
26c20 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 74 e name of the Nt
26c30 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65 20 h column (where
26c40 30 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 0 is.**
26c50 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f the leftmost co
26c60 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65 20 72 65 lumn) for the re
26c70 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 0a sult set of the.
26c80 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 ** [pre
26c90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
26ca0 20 53 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 72 S as a zero-ter
26cb0 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20 73 minated UTF-16 s
26cc0 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 tring.**
26cd0 20 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 in the native
26ce0 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a byte order..**.*
26cf0 2a 20 7b 48 31 33 37 32 34 7d 20 54 68 65 20 5b * {H13724} The [
26d00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e sqlite3_column_n
26d10 61 6d 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 ame()] and [sqli
26d20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 te3_column_name1
26d30 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 6()].**
26d40 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 interfaces retu
26d50 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 rn a NULL pointe
26d60 72 20 69 66 20 74 68 65 79 20 61 72 65 20 75 6e r if they are un
26d70 61 62 6c 65 20 74 6f 0a 2a 2a 20 20 20 20 20 20 able to.**
26d80 20 20 20 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d allocate mem
26d90 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 69 ory to hold thei
26da0 72 20 6e 6f 72 6d 61 6c 20 72 65 74 75 72 6e 20 r normal return
26db0 73 74 72 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b strings..**.** {
26dc0 48 31 33 37 32 35 7d 20 49 66 20 74 68 65 20 4e H13725} If the N
26dd0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 parameter to [s
26de0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
26df0 6d 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 me(S,N)] or.**
26e00 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
26e10 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 _column_name16(S
26e20 2c 4e 29 5d 20 69 73 20 6f 75 74 20 6f 66 20 72 ,N)] is out of r
26e30 61 6e 67 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a ange, then the.*
26e40 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 * inter
26e50 66 61 63 65 73 20 72 65 74 75 72 6e 20 61 20 4e faces return a N
26e60 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a ULL pointer..**.
26e70 2a 2a 20 7b 48 31 33 37 32 36 7d 20 54 68 65 20 ** {H13726} The
26e80 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 strings returned
26e90 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c by [sqlite3_col
26ea0 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 61 umn_name(S,N)] a
26eb0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b nd.** [
26ec0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e sqlite3_column_n
26ed0 61 6d 65 31 36 28 53 2c 4e 29 5d 20 61 72 65 20 ame16(S,N)] are
26ee0 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 valid until the
26ef0 6e 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 next.**
26f00 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 call to either
26f10 72 6f 75 74 69 6e 65 20 77 69 74 68 20 74 68 65 routine with the
26f20 20 73 61 6d 65 20 53 20 61 6e 64 20 4e 20 70 61 same S and N pa
26f30 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20 20 rameters.**
26f40 20 20 20 20 20 6f 72 20 75 6e 74 69 6c 20 5b 73 or until [s
26f50 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
26f60 53 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a S)] is called..*
26f70 2a 0a 2a 2a 20 7b 48 31 33 37 32 37 7d 20 57 68 *.** {H13727} Wh
26f80 65 6e 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 en a result colu
26f90 6d 6e 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d mn of a [SELECT]
26fa0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6e 74 61 statement conta
26fb0 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ins.**
26fc0 61 6e 20 41 53 20 63 6c 61 75 73 65 2c 20 74 68 an AS clause, th
26fd0 65 20 6e 61 6d 65 20 6f 66 20 74 68 61 74 20 63 e name of that c
26fe0 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 69 64 65 olumn is the ide
26ff0 6e 74 69 66 69 65 72 0a 2a 2a 20 20 20 20 20 20 ntifier.**
27000 20 20 20 20 74 6f 20 74 68 65 20 72 69 67 68 74 to the right
27010 20 6f 66 20 74 68 65 20 41 53 20 6b 65 79 77 6f of the AS keywo
27020 72 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 rd..*/.const cha
27030 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d r *sqlite3_colum
27040 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 n_name(sqlite3_s
27050 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f tmt*, int N);.co
27060 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
27070 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 3_column_name16(
27080 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
27090 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 nt N);../*.** CA
270a0 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f PI3REF: Source O
270b0 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 f Data In A Quer
270c0 79 20 52 65 73 75 6c 74 20 7b 48 31 33 37 34 30 y Result {H13740
270d0 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a } <S10700>.**.**
270e0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
270f0 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 provide a means
27100 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 77 68 61 to determine wha
27110 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74 t column of what
27120 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20 77 68 69 .** table in whi
27130 63 68 20 64 61 74 61 62 61 73 65 20 61 20 72 65 ch database a re
27140 73 75 6c 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 sult of a [SELEC
27150 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d T] statement com
27160 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 es from..** The
27170 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 name of the data
27180 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 base or table or
27190 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 column can be r
271a0 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 eturned as.** ei
271b0 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 ther a UTF-8 or
271c0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 UTF-16 string.
271d0 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 The _database_ r
271e0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a outines return.*
271f0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e * the database n
27200 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f ame, the _table_
27210 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
27220 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c the table name,
27230 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 and.** the orig
27240 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 in_ routines ret
27250 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e urn the column n
27260 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 ame..** The retu
27270 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 rned string is v
27280 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b alid until the [
27290 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
272a0 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 nt] is destroyed
272b0 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 .** using [sqlit
272c0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f e3_finalize()] o
272d0 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 r until the same
272e0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 information is
272f0 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 requested.** aga
27300 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e in in a differen
27310 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a t encoding..**.*
27320 2a 20 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 * The names retu
27330 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 rned are the ori
27340 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 ginal un-aliased
27350 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a names of the.**
27360 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 database, table
27370 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a , and column..**
27380 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 .** The first ar
27390 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 66 6f gument to the fo
273a0 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69 73 llowing calls is
273b0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
273c0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 tement]..** Thes
273d0 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 e functions retu
273e0 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 rn information a
273f0 62 6f 75 74 20 74 68 65 20 4e 74 68 20 63 6f 6c bout the Nth col
27400 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a umn returned by.
27410 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 ** the statement
27420 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 , where N is the
27430 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e second function
27440 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
27450 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 If the Nth colu
27460 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 mn returned by t
27470 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 he statement is
27480 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 an expression or
27490 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 .** subquery and
274a0 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e is not a column
274b0 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c value, then all
274c0 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 of these functi
274d0 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 ons return.** NU
274e0 4c 4c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 LL. These routi
274f0 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 ne might also re
27500 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d turn NULL if a m
27510 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
27520 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 error.** occurs
27530 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 74 68 . Otherwise, th
27540 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 ey return the na
27550 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 me of the attach
27560 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 ed database, tab
27570 6c 65 0a 2a 2a 20 61 6e 64 20 63 6f 6c 75 6d 6e le.** and column
27580 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75 that query resu
27590 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 lt column was ex
275a0 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a tracted from..**
275b0 0a 2a 2a 20 41 73 20 77 69 74 68 20 61 6c 6c 20 .** As with all
275c0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 other SQLite API
275d0 73 2c 20 74 68 6f 73 65 20 70 6f 73 74 66 69 78 s, those postfix
275e0 65 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 ed with "16" ret
275f0 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e urn.** UTF-16 en
27600 63 6f 64 65 64 20 73 74 72 69 6e 67 73 2c 20 74 coded strings, t
27610 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f he other functio
27620 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e ns return UTF-8.
27630 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 {END}.**.** The
27640 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 se APIs are only
27650 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 available if th
27660 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f e library was co
27670 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a mpiled with the.
27680 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c ** [SQLITE_ENABL
27690 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 E_COLUMN_METADAT
276a0 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f A] C-preprocesso
276b0 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 r symbol defined
276c0 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35 31 7d ..**.** {A13751}
276d0 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f .** If two or mo
276e0 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 re threads call
276f0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 one or more of t
27700 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 hese routines ag
27710 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a ainst the same.*
27720 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 * prepared state
27730 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 ment and column
27740 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 at the same time
27750 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 then the result
27760 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e s are.** undefin
27770 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 ed..**.** INVARI
27780 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 ANTS:.**.** {H13
27790 37 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 741} The [sqlite
277a0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 3_column_databas
277b0 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 e_name(S,N)] int
277c0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 erface returns e
277d0 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 ither.**
277e0 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f the UTF-8 zero
277f0 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 -terminated name
27800 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
27810 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a from which the.
27820 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 ** Nth
27830 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 result column of
27840 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
27850 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 tatement] S is e
27860 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 xtracted,.**
27870 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 or NULL if
27880 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
27890 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 of S is a genera
278a0 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 l expression.**
278b0 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 or if u
278c0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 nable to allocat
278d0 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 e memory to stor
278e0 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a e the name..**.*
278f0 2a 20 7b 48 31 33 37 34 32 7d 20 54 68 65 20 5b * {H13742} The [
27900 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
27910 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 53 atabase_name16(S
27920 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 ,N)] interface r
27930 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a eturns either.**
27940 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 the UT
27950 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 F-16 native byte
27960 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d order zero-term
27970 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 inated name of t
27980 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 20 he database.**
27990 20 20 20 20 20 20 20 20 66 72 6f 6d 20 77 68 69 from whi
279a0 63 68 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c ch the Nth resul
279b0 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 t column of the
279c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
279d0 65 6e 74 5d 20 53 20 69 73 0a 2a 2a 20 20 20 20 ent] S is.**
279e0 20 20 20 20 20 20 65 78 74 72 61 63 74 65 64 2c extracted,
279f0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 or NULL if the
27a00 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 Nth column of S
27a10 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 is a general exp
27a20 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 ression.**
27a30 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 or if unable
27a40 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d to allocate mem
27a50 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65 ory to store the
27a60 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 name..**.** {H1
27a70 33 37 34 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 3743} The [sqlit
27a80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f e3_column_table_
27a90 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 name(S,N)] inter
27aa0 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 face returns eit
27ab0 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 her.**
27ac0 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 the UTF-8 zero-t
27ad0 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f erminated name o
27ae0 66 20 74 68 65 20 74 61 62 6c 65 20 66 72 6f 6d f the table from
27af0 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 20 20 which the.**
27b00 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c Nth resul
27b10 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 t column of the
27b20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
27b30 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61 63 ent] S is extrac
27b40 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 ted,.**
27b50 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 or NULL if the
27b60 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 Nth column of S
27b70 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 is a general exp
27b80 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 ression.**
27b90 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 or if unable
27ba0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d to allocate mem
27bb0 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65 ory to store the
27bc0 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 name..**.** {H1
27bd0 33 37 34 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 3744} The [sqlit
27be0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f e3_column_table_
27bf0 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 name16(S,N)] int
27c00 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 erface returns e
27c10 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 ither.**
27c20 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 the UTF-16 nat
27c30 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 7a ive byte order z
27c40 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e ero-terminated n
27c50 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 ame of the table
27c60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f .** fro
27c70 6d 20 77 68 69 63 68 20 74 68 65 20 4e 74 68 20 m which the Nth
27c80 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 result column of
27c90 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
27ca0 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 0a 2a tatement] S is.*
27cb0 2a 20 20 20 20 20 20 20 20 20 20 65 78 74 72 61 * extra
27cc0 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 cted, or NULL if
27cd0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
27ce0 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 of S is a genera
27cf0 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 l expression.**
27d00 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 or if u
27d10 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 nable to allocat
27d20 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 e memory to stor
27d30 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a e the name..**.*
27d40 2a 20 7b 48 31 33 37 34 35 7d 20 54 68 65 20 5b * {H13745} The [
27d50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f sqlite3_column_o
27d60 72 69 67 69 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d rigin_name(S,N)]
27d70 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
27d80 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 ns either.**
27d90 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20 the UTF-8
27da0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
27db0 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c name of the tabl
27dc0 65 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 e column from wh
27dd0 69 63 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 ich the.**
27de0 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 Nth result c
27df0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 olumn of the [pr
27e00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
27e10 5d 20 53 20 69 73 20 65 78 74 72 61 63 74 65 64 ] S is extracted
27e20 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 ,.** or
27e30 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 NULL if the Nth
27e40 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 column of S is
27e50 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 a general expres
27e60 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 sion.**
27e70 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f or if unable to
27e80 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 allocate memory
27e90 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 to store the na
27ea0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 me..**.** {H1374
27eb0 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6} The [sqlite3_
27ec0 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 column_origin_na
27ed0 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 me16(S,N)] inter
27ee0 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 face returns eit
27ef0 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 her.**
27f00 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 the UTF-16 nativ
27f10 65 20 62 79 74 65 20 6f 72 64 65 72 20 7a 65 72 e byte order zer
27f20 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d o-terminated nam
27f30 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a e of the table.*
27f40 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 75 6d * colum
27f50 6e 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 n from which the
27f60 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 Nth result colu
27f70 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 mn of the.**
27f80 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 [prepared
27f90 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 statement] S is
27fa0 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 extracted, or NU
27fb0 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f LL if the Nth co
27fc0 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 lumn.**
27fd0 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 of S is a gener
27fe0 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 al expression or
27ff0 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c if unable to al
28000 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a locate memory.**
28010 20 20 20 20 20 20 20 20 20 20 74 6f 20 73 74 6f to sto
28020 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a re the name..**.
28030 2a 2a 20 7b 48 31 33 37 34 38 7d 20 54 68 65 20 ** {H13748} The
28040 72 65 74 75 72 6e 20 76 61 6c 75 65 73 20 66 72 return values fr
28050 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b om.** [
28060 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
28070 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 atabase_name | c
28080 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 olumn metadata i
28090 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20 nterfaces].**
280a0 20 20 20 20 20 20 20 61 72 65 20 76 61 6c 69 64 are valid
280b0 20 66 6f 72 20 74 68 65 20 6c 69 66 65 74 69 6d for the lifetim
280c0 65 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 e of the [prepar
280d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a ed statement].**
280e0 20 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74 or unt
280f0 69 6c 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 il the encoding
28100 69 73 20 63 68 61 6e 67 65 64 20 62 79 20 61 6e is changed by an
28110 6f 74 68 65 72 20 6d 65 74 61 64 61 74 61 0a 2a other metadata.*
28120 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 * inter
28130 66 61 63 65 20 63 61 6c 6c 20 66 6f 72 20 74 68 face call for th
28140 65 20 73 61 6d 65 20 70 72 65 70 61 72 65 64 20 e same prepared
28150 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f statement and co
28160 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 lumn..**.** ASSU
28170 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b MPTIONS:.**.** {
28180 41 31 33 37 35 31 7d 20 49 66 20 74 77 6f 20 6f A13751} If two o
28190 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 r more threads c
281a0 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a all one or more.
281b0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
281c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 ite3_column_data
281d0 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 base_name | colu
281e0 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 mn metadata inte
281f0 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20 rfaces].**
28200 20 20 20 20 66 6f 72 20 74 68 65 20 73 61 6d 65 for the same
28210 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
28220 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 ment] and result
28230 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20 20 column.**
28240 20 20 20 20 61 74 20 74 68 65 20 73 61 6d 65 20 at the same
28250 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 time then the re
28260 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 sults are undefi
28270 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 ned..*/.const ch
28280 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ar *sqlite3_colu
28290 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 mn_database_name
282a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
282b0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 nt);.const void
282c0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
282d0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 database_name16(
282e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
282f0 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a t);.const char *
28300 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
28310 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 able_name(sqlite
28320 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 3_stmt*,int);.co
28330 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
28340 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 3_column_table_n
28350 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ame16(sqlite3_st
28360 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 mt*,int);.const
28370 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
28380 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 lumn_origin_name
28390 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
283a0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 nt);.const void
283b0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
283c0 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 origin_name16(sq
283d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
283e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
283f0 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 F: Declared Data
28400 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 type Of A Query
28410 52 65 73 75 6c 74 20 7b 48 31 33 37 36 30 7d 20 Result {H13760}
28420 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S10700>.**.** T
28430 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
28440 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 er is a [prepare
28450 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a d statement]..**
28460 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 If this stateme
28470 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d nt is a [SELECT]
28480 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 statement and t
28490 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 he Nth column of
284a0 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 the.** returned
284b0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 result set of t
284c0 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 hat [SELECT] is
284d0 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 a table column (
284e0 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 not an.** expres
284f0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 sion or subquery
28500 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 ) then the decla
28510 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 red type of the
28520 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 table.** column
28530 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 49 66 is returned. If
28540 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
28550 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 of the result se
28560 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 t is an.** expre
28570 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 ssion or subquer
28580 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 y, then a NULL p
28590 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e ointer is return
285a0 65 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 ed..** The retur
285b0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c ned string is al
285c0 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 ways UTF-8 encod
285d0 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 ed. {END}.**.**
285e0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 For example, giv
285f0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
28600 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 schema:.**.** CR
28610 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 EATE TABLE t1(c1
28620 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a VARIANT);.**.**
28630 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 and the followi
28640 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 ng statement to
28650 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a be compiled:.**.
28660 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 ** SELECT c1 + 1
28670 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a , c1 FROM t1;.**
28680 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 .** this routine
28690 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 would return th
286a0 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e e string "VARIAN
286b0 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e T" for the secon
286c0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 d result.** colu
286d0 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 mn (i==1), and a
286e0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f NULL pointer fo
286f0 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 r the first resu
28700 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 lt column (i==0)
28710 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 ..**.** SQLite u
28720 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d ses dynamic run-
28730 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 53 6f time typing. So
28740 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 just because a
28750 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 column.** is dec
28760 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e lared to contain
28770 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 a particular ty
28780 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e pe does not mean
28790 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 that the.** dat
287a0 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 a stored in that
287b0 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 column is of th
287c0 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e e declared type.
287d0 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 SQLite is.** s
287e0 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 trongly typed, b
287f0 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 ut the typing is
28800 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 dynamic not sta
28810 74 69 63 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73 tic. Type.** is
28820 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
28830 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 individual valu
28840 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 es, not with the
28850 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 containers.** u
28860 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 sed to hold thos
28870 65 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 e values..**.**
28880 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
28890 2a 20 7b 48 31 33 37 36 31 7d 20 20 41 20 73 75 * {H13761} A su
288a0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f ccessful call to
288b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
288c0 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d 20 _decltype(S,N)]
288d0 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 returns a.**
288e0 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d zero-term
288f0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 inated UTF-8 str
28900 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 ing containing t
28910 68 65 20 64 65 63 6c 61 72 65 64 20 64 61 74 61 he declared data
28920 74 79 70 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 type.**
28930 20 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 of the table c
28940 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 70 65 61 olumn that appea
28950 72 73 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f rs as the Nth co
28960 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 0a 2a lumn (numbered.*
28970 2a 20 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d * from
28980 20 30 29 20 6f 66 20 74 68 65 20 72 65 73 75 6c 0) of the resul
28990 74 20 73 65 74 20 74 6f 20 74 68 65 20 5b 70 72 t set to the [pr
289a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
289b0 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 ] S..**.** {H137
289c0 36 32 7d 20 20 41 20 73 75 63 63 65 73 73 66 75 62} A successfu
289d0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 l call to [sqlit
289e0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 e3_column_declty
289f0 70 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 pe16(S,N)].**
28a00 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 returns
28a10 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
28a20 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 d UTF-16 native
28a30 62 79 74 65 20 6f 72 64 65 72 20 73 74 72 69 6e byte order strin
28a40 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 g.** c
28a50 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 65 ontaining the de
28a60 63 6c 61 72 65 64 20 64 61 74 61 74 79 70 65 20 clared datatype
28a70 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c of the table col
28a80 75 6d 6e 20 74 68 61 74 20 61 70 70 65 61 72 73 umn that appears
28a90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 73 .** as
28aa0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
28ab0 28 6e 75 6d 62 65 72 65 64 20 66 72 6f 6d 20 30 (numbered from 0
28ac0 29 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 ) of the result
28ad0 73 65 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 set to the.**
28ae0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 [prepare
28af0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a d statement] S..
28b00 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36 33 7d 20 20 **.** {H13763}
28b10 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 If N is less tha
28b20 6e 20 30 20 6f 72 20 4e 20 69 73 20 67 72 65 61 n 0 or N is grea
28b30 74 65 72 20 74 68 61 6e 20 6f 72 20 65 71 75 61 ter than or equa
28b40 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 l to.**
28b50 20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 the number of
28b60 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 5b columns in the [
28b70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
28b80 6e 74 5d 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 nt] S,.**
28b90 20 20 20 20 6f 72 20 69 66 20 74 68 65 20 4e 74 or if the Nt
28ba0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 h column of S is
28bb0 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f an expression o
28bc0 72 20 73 75 62 71 75 65 72 79 20 72 61 74 68 65 r subquery rathe
28bd0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 r.** t
28be0 68 61 6e 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 han a table colu
28bf0 6d 6e 2c 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f mn, or if a memo
28c00 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 ry allocation fa
28c10 69 6c 75 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 ilure.**
28c20 20 20 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 occurs during
28c30 20 65 6e 63 6f 64 69 6e 67 20 63 6f 6e 76 65 72 encoding conver
28c40 73 69 6f 6e 73 2c 20 74 68 65 6e 0a 2a 2a 20 20 sions, then.**
28c50 20 20 20 20 20 20 20 20 20 63 61 6c 6c 73 20 74 calls t
28c60 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d o [sqlite3_colum
28c70 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d n_decltype(S,N)]
28c80 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 or.**
28c90 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
28ca0 5f 64 65 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 _decltype16(S,N)
28cb0 5d 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a ] return NULL..*
28cc0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 /.const char *sq
28cd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 lite3_column_dec
28ce0 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 ltype(sqlite3_st
28cf0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 mt*,int);.const
28d00 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
28d10 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 lumn_decltype16(
28d20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
28d30 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
28d40 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e REF: Evaluate An
28d50 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b SQL Statement {
28d60 48 31 33 32 30 30 7d 20 3c 53 31 30 30 30 30 3e H13200} <S10000>
28d70 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b .**.** After a [
28d80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
28d90 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 nt] has been pre
28da0 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 pared using eith
28db0 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 er.** [sqlite3_p
28dc0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
28dd0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
28de0 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 16_v2()] or one
28df0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a of the legacy.**
28e00 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c interfaces [sql
28e10 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
28e20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 or [sqlite3_prep
28e30 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 are16()], this f
28e40 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 unction.** must
28e50 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 be called one or
28e60 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 more times to e
28e70 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 valuate the stat
28e80 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ement..**.** The
28e90 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 details of the
28ea0 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 behavior of the
28eb0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 sqlite3_step() i
28ec0 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a nterface depend.
28ed0 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 ** on whether th
28ee0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 e statement was
28ef0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 prepared using t
28f00 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e he newer "v2" in
28f10 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 terface.** [sqli
28f20 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
28f30 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 ] and [sqlite3_p
28f40 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f repare16_v2()] o
28f50 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 r the older lega
28f60 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 cy.** interface
28f70 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
28f80 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
28f90 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 _prepare16()].
28fa0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a The use of the.*
28fb0 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 * new "v2" inter
28fc0 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e face is recommen
28fd0 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c ded for new appl
28fe0 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 ications but the
28ff0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 legacy.** inter
29000 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e face will contin
29010 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 ue to be support
29020 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 ed..**.** In the
29030 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 legacy interfac
29040 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 e, the return va
29050 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 lue will be eith
29060 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d er [SQLITE_BUSY]
29070 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e ,.** [SQLITE_DON
29080 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d E], [SQLITE_ROW]
29090 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d , [SQLITE_ERROR]
290a0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 , or [SQLITE_MIS
290b0 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 USE]..** With th
290c0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 e "v2" interface
290d0 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 , any of the oth
290e0 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 er [result codes
290f0 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 ] or.** [extende
29100 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 d result codes]
29110 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 might be returne
29120 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a d as well..**.**
29130 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d [SQLITE_BUSY] m
29140 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 eans that the da
29150 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 tabase engine wa
29160 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 s unable to acqu
29170 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 ire the.** datab
29180 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 ase locks it nee
29190 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 ds to do its job
291a0 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d . If the statem
291b0 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 ent is a [COMMIT
291c0 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f ].** or occurs o
291d0 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 utside of an exp
291e0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f licit transactio
291f0 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 n, then you can
29200 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 retry the.** sta
29210 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 tement. If the
29220 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 statement is not
29230 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 a [COMMIT] and
29240 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a occurs within a.
29250 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e ** explicit tran
29260 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 saction then you
29270 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b should rollback
29280 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e the transaction
29290 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 before.** conti
292a0 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 nuing..**.** [SQ
292b0 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 LITE_DONE] means
292c0 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d that the statem
292d0 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 ent has finished
292e0 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 executing.** su
292f0 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c ccessfully. sql
29300 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 ite3_step() shou
29310 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 ld not be called
29320 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 again on this v
29330 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e irtual.** machin
29340 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 e without first
29350 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 calling [sqlite3
29360 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 _reset()] to res
29370 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a et the virtual.*
29380 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 * machine back t
29390 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 o its initial st
293a0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ate..**.** If th
293b0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
293c0 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 being executed r
293d0 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c eturns any data,
293e0 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f then [SQLITE_RO
293f0 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 W].** is returne
29400 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 d each time a ne
29410 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 w row of data is
29420 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 ready for proce
29430 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 ssing by the.**
29440 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 caller. The valu
29450 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 es may be access
29460 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f ed using the [co
29470 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 lumn access func
29480 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 tions]..** sqlit
29490 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c e3_step() is cal
294a0 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 led again to ret
294b0 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 rieve the next r
294c0 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a ow of data..**.*
294d0 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d * [SQLITE_ERROR]
294e0 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 means that a ru
294f0 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 n-time error (su
29500 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 ch as a constrai
29510 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 nt.** violation)
29520 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 has occurred.
29530 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 sqlite3_step() s
29540 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c hould not be cal
29550 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 led again on.**
29560 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 the VM. More inf
29570 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 ormation may be
29580 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 found by calling
29590 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
295a0 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 ()]..** With the
295b0 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 legacy interfac
295c0 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 e, a more specif
295d0 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 ic error code (f
295e0 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b or example,.** [
295f0 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 SQLITE_INTERRUPT
29600 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d ], [SQLITE_SCHEM
29610 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 A], [SQLITE_CORR
29620 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 UPT], and so for
29630 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 th).** can be ob
29640 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e tained by callin
29650 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 g [sqlite3_reset
29660 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 ()] on the.** [p
29670 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
29680 74 5d 2e 20 20 49 6e 20 74 68 65 20 22 76 32 22 t]. In the "v2"
29690 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 interface,.** t
296a0 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 he more specific
296b0 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 error code is r
296c0 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 eturned directly
296d0 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 by sqlite3_step
296e0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 ()..**.** [SQLIT
296f0 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 E_MISUSE] means
29700 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f that the this ro
29710 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 utine was called
29720 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 inappropriately
29730 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 ..** Perhaps it
29740 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 was called on a
29750 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
29760 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a ent] that has.**
29770 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 already been [s
29780 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 qlite3_finalize
29790 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 | finalized] or
297a0 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a on one that had.
297b0 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 ** previously re
297c0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 turned [SQLITE_E
297d0 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 RROR] or [SQLITE
297e0 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 _DONE]. Or it c
297f0 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 ould.** be the c
29800 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d ase that the sam
29810 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
29820 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 ction is being u
29830 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a sed by two or.**
29840 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 more threads at
29850 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 the same moment
29860 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 in time..**.**
29870 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 <b>Goofy Interfa
29880 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e ce Alert:</b> In
29890 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 the legacy inte
298a0 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 rface, the sqlit
298b0 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 e3_step().** API
298c0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 always returns
298d0 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 a generic error
298e0 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 code, [SQLITE_ER
298f0 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 ROR], following
29900 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 any.** error oth
29910 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
29920 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 BUSY] and [SQLIT
29930 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 E_MISUSE]. You
29940 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 must call.** [sq
29950 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f lite3_reset()] o
29960 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c r [sqlite3_final
29970 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 ize()] in order
29980 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 to find one of t
29990 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b he.** specific [
299a0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 error codes] tha
299b0 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 t better describ
299c0 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a es the error..**
299d0 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 We admit that t
299e0 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 his is a goofy d
299f0 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 esign. The prob
29a00 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 lem has been fix
29a10 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 ed.** with the "
29a20 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 v2" interface.
29a30 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 If you prepare a
29a40 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 ll of your SQL s
29a50 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 tatements.** usi
29a60 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 ng either [sqlit
29a70 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
29a80 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 or [sqlite3_pre
29a90 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 pare16_v2()] ins
29aa0 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c tead.** of the l
29ab0 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 egacy [sqlite3_p
29ac0 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 repare()] and [s
29ad0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
29ae0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a ()] interfaces,.
29af0 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 ** then the more
29b00 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 specific [error
29b10 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 codes] are retu
29b20 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a rned directly.**
29b30 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 by sqlite3_step
29b40 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 (). The use of
29b50 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
29b60 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 ce is recommende
29b70 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 d..**.** INVARIA
29b80 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 32 NTS:.**.** {H132
29b90 30 32 7d 20 20 49 66 20 74 68 65 20 5b 70 72 65 02} If the [pre
29ba0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
29bb0 20 53 20 69 73 20 72 65 61 64 79 20 74 6f 20 62 S is ready to b
29bc0 65 20 72 75 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20 e run, then.**
29bd0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
29be0 33 5f 73 74 65 70 28 53 29 5d 20 61 64 76 61 6e 3_step(S)] advan
29bf0 63 65 73 20 74 68 61 74 20 70 72 65 70 61 72 65 ces that prepare
29c00 64 20 73 74 61 74 65 6d 65 6e 74 20 75 6e 74 69 d statement unti
29c10 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 l.** c
29c20 6f 6d 70 6c 65 74 69 6f 6e 20 6f 72 20 75 6e 74 ompletion or unt
29c30 69 6c 20 69 74 20 69 73 20 72 65 61 64 79 20 74 il it is ready t
29c40 6f 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 65 72 o return another
29c50 20 72 6f 77 20 6f 66 20 74 68 65 0a 2a 2a 20 20 row of the.**
29c60 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 result
29c70 73 65 74 2c 20 6f 72 20 75 6e 74 69 6c 20 61 6e set, or until an
29c80 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 [sqlite3_interr
29c90 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d upt | interrupt]
29ca0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 72 .** or
29cb0 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f a run-time erro
29cc0 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 r occurs..**.**
29cd0 7b 48 31 35 33 30 34 7d 20 20 57 68 65 6e 20 61 {H15304} When a
29ce0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
29cf0 33 5f 73 74 65 70 28 53 29 5d 20 63 61 75 73 65 3_step(S)] cause
29d00 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 s the [prepared
29d10 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 statement].**
29d20 20 20 20 20 20 20 20 20 53 20 74 6f 20 72 75 6e S to run
29d30 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2c 20 to completion,
29d40 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 the function ret
29d50 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 4f 4e urns [SQLITE_DON
29d60 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 E]..**.** {H1530
29d70 36 7d 20 20 57 68 65 6e 20 61 20 63 61 6c 6c 20 6} When a call
29d80 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 to [sqlite3_step
29d90 28 53 29 5d 20 73 74 6f 70 73 20 62 65 63 61 75 (S)] stops becau
29da0 73 65 20 69 74 20 69 73 20 72 65 61 64 79 20 74 se it is ready t
29db0 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 o.** r
29dc0 65 74 75 72 6e 20 61 6e 6f 74 68 65 72 20 72 6f eturn another ro
29dd0 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 w of the result
29de0 73 65 74 2c 20 69 74 20 72 65 74 75 72 6e 73 20 set, it returns
29df0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2e 0a 2a 2a [SQLITE_ROW]..**
29e00 0a 2a 2a 20 7b 48 31 35 33 30 38 7d 20 20 49 66 .** {H15308} If
29e10 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 a call to [sqli
29e20 74 65 33 5f 73 74 65 70 28 53 29 5d 20 65 6e 63 te3_step(S)] enc
29e30 6f 75 6e 74 65 72 73 20 61 6e 0a 2a 2a 20 20 20 ounters an.**
29e40 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
29e50 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 _interrupt | int
29e60 65 72 72 75 70 74 5d 20 6f 72 20 61 20 72 75 6e errupt] or a run
29e70 2d 74 69 6d 65 20 65 72 72 6f 72 2c 0a 2a 2a 20 -time error,.**
29e80 20 20 20 20 20 20 20 20 20 20 69 74 20 72 65 74 it ret
29e90 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 urns an appropri
29ea0 61 74 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 ate error code t
29eb0 68 61 74 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f hat is not one o
29ec0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b f.** [
29ed0 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 5b 53 51 4c SQLITE_OK], [SQL
29ee0 49 54 45 5f 52 4f 57 5d 2c 20 6f 72 20 5b 53 51 ITE_ROW], or [SQ
29ef0 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a LITE_DONE]..**.*
29f00 2a 20 7b 48 31 35 33 31 30 7d 20 20 49 66 20 61 * {H15310} If a
29f10 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 n [sqlite3_inter
29f20 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 rupt | interrupt
29f30 5d 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 ] or a run-time
29f40 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 error.**
29f50 20 20 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 occurs during
29f60 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 a call to [sqli
29f70 74 65 33 5f 73 74 65 70 28 53 29 5d 0a 2a 2a 20 te3_step(S)].**
29f80 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 61 20 for a
29f90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
29fa0 65 6e 74 5d 20 53 20 63 72 65 61 74 65 64 20 75 ent] S created u
29fb0 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 sing.**
29fc0 20 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 legacy interfa
29fd0 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 ces [sqlite3_pre
29fe0 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 pare()] or.**
29ff0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
2a000 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 _prepare16()], t
2a010 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e hen the function
2a020 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a returns either.
2a030 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53 51 ** [SQ
2a040 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 5b 53 51 LITE_ERROR], [SQ
2a050 4c 49 54 45 5f 42 55 53 59 5d 2c 20 6f 72 20 5b LITE_BUSY], or [
2a060 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a SQLITE_MISUSE]..
2a070 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 */.int sqlite3_s
2a080 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 tep(sqlite3_stmt
2a090 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
2a0a0 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 REF: Number of c
2a0b0 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 olumns in a resu
2a0c0 6c 74 20 73 65 74 20 7b 48 31 33 37 37 30 7d 20 lt set {H13770}
2a0d0 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 <S10700>.**.** R
2a0e0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
2a0f0 72 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 74 r of values in t
2a100 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f he current row o
2a110 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 f the result set
2a120 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
2a130 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 37 TS:.**.** {H1377
2a140 31 7d 20 20 41 66 74 65 72 20 61 20 63 61 6c 6c 1} After a call
2a150 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 to [sqlite3_ste
2a160 70 28 53 29 5d 20 74 68 61 74 20 72 65 74 75 72 p(S)] that retur
2a170 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c ns [SQLITE_ROW],
2a180 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 .** th
2a190 65 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f e [sqlite3_data_
2a1a0 63 6f 75 6e 74 28 53 29 5d 20 72 6f 75 74 69 6e count(S)] routin
2a1b0 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 e will return th
2a1c0 65 20 73 61 6d 65 20 76 61 6c 75 65 0a 2a 2a 20 e same value.**
2a1d0 20 20 20 20 20 20 20 20 20 20 61 73 20 74 68 65 as the
2a1e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
2a1f0 5f 63 6f 75 6e 74 28 53 29 5d 20 66 75 6e 63 74 _count(S)] funct
2a200 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 ion..**.** {H137
2a210 37 32 7d 20 20 41 66 74 65 72 20 5b 73 71 6c 69 72} After [sqli
2a220 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 te3_step(S)] has
2a230 20 72 65 74 75 72 6e 65 64 20 61 6e 79 20 76 61 returned any va
2a240 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a lue other than.*
2a250 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c * [SQL
2a260 49 54 45 5f 52 4f 57 5d 20 6f 72 20 62 65 66 6f ITE_ROW] or befo
2a270 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 re [sqlite3_step
2a280 28 53 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 (S)] has been ca
2a290 6c 6c 65 64 20 6f 6e 20 74 68 65 0a 2a 2a 20 20 lled on the.**
2a2a0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 [prepar
2a2b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 66 6f ed statement] fo
2a2c0 72 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 r the first time
2a2d0 20 73 69 6e 63 65 20 69 74 20 77 61 73 0a 2a 2a since it was.**
2a2e0 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 [sqli
2a2f0 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 te3_prepare | pr
2a300 65 70 61 72 65 64 5d 20 6f 72 20 5b 73 71 6c 69 epared] or [sqli
2a310 74 65 33 5f 72 65 73 65 74 20 7c 20 72 65 73 65 te3_reset | rese
2a320 74 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 t],.**
2a330 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 61 the [sqlite3_da
2a340 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20 72 6f 75 ta_count(S)] rou
2a350 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 tine returns zer
2a360 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 o..*/.int sqlite
2a370 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 3_data_count(sql
2a380 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
2a390 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2a3a0 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 EF: Fundamental
2a3b0 44 61 74 61 74 79 70 65 73 20 7b 48 31 30 32 36 Datatypes {H1026
2a3c0 35 7d 20 3c 53 31 30 31 31 30 3e 3c 53 31 30 31 5} <S10110><S101
2a3d0 32 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20>.** KEYWORDS:
2a3e0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a SQLITE_TEXT.**.
2a3f0 2a 2a 20 7b 48 31 30 32 36 36 7d 20 45 76 65 72 ** {H10266} Ever
2a400 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 y value in SQLit
2a410 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 e has one of fiv
2a420 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 e fundamental da
2a430 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c tatypes:.**.** <
2a440 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 ul>.** <li> 64-b
2a450 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 it signed intege
2a460 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 r.** <li> 64-bit
2a470 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 IEEE floating p
2a480 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c oint number.** <
2a490 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c li> string.** <l
2a4a0 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 i> BLOB.** <li>
2a4b0 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 NULL.** </ul> {E
2a4c0 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ND}.**.** These
2a4d0 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f constants are co
2a4e0 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 des for each of
2a4f0 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a those types..**.
2a500 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 ** Note that the
2a510 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e SQLITE_TEXT con
2a520 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 stant was also u
2a530 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 sed in SQLite ve
2a540 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 rsion 2.** for a
2a550 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 completely diff
2a560 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 erent meaning.
2a570 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 Software that li
2a580 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 nks against both
2a590 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 .** SQLite versi
2a5a0 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 on 2 and SQLite
2a5b0 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 version 3 should
2a5c0 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 use SQLITE3_TEX
2a5d0 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 T, not.** SQLITE
2a5e0 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e _TEXT..*/.#defin
2a5f0 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 e SQLITE_INTEGER
2a600 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 1.#define SQLI
2a610 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 TE_FLOAT 2.#d
2a620 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f efine SQLITE_BLO
2a630 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 B 4.#define
2a640 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 SQLITE_NULL
2a650 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 5.#ifdef SQLITE_
2a660 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c TEXT.# undef SQL
2a670 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 ITE_TEXT.#else.#
2a680 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 define SQLITE_T
2a690 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 EXT 3.#endif
2a6a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 .#define SQLITE3
2a6b0 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a _TEXT 3../*.
2a6c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 ** CAPI3REF: Res
2a6d0 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 ult Values From
2a6e0 41 20 51 75 65 72 79 20 7b 48 31 33 38 30 30 7d A Query {H13800}
2a6f0 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 <S10700>.** KEY
2a700 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 WORDS: {column a
2a710 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d ccess functions}
2a720 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
2a730 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 tines form the "
2a740 72 65 73 75 6c 74 20 73 65 74 20 71 75 65 72 79 result set query
2a750 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a " interface..**.
2a760 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
2a770 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 s return informa
2a780 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e tion about a sin
2a790 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 gle column of th
2a7a0 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 e current.** res
2a7b0 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 ult row of a que
2a7c0 72 79 2e 20 20 49 6e 20 65 76 65 72 79 20 63 61 ry. In every ca
2a7d0 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 se the first arg
2a7e0 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 ument is a point
2a7f0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 er.** to the [pr
2a800 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2a810 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 ] that is being
2a820 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b evaluated (the [
2a830 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a sqlite3_stmt*].*
2a840 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 * that was retur
2a850 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ned from [sqlite
2a860 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
2a870 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 or one of its va
2a880 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 riants).** and t
2a890 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
2a8a0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 nt is the index
2a8b0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f of the column fo
2a8c0 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 r which informat
2a8d0 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 ion.** should be
2a8e0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 returned. The
2a8f0 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 leftmost column
2a900 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 of the result se
2a910 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 t has the index
2a920 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 0..**.** If the
2a930 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f SQL statement do
2a940 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 es not currently
2a950 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 point to a vali
2a960 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 d row, or if the
2a970 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 .** column index
2a980 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 is out of range
2a990 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 , the result is
2a9a0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 undefined..** Th
2a9b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 ese routines may
2a9c0 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 only be called
2a9d0 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 when the most re
2a9e0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 cent call to.**
2a9f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
2aa00 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 has returned [S
2aa10 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e QLITE_ROW] and n
2aa20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 either.** [sqlit
2aa30 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 e3_reset()] nor
2aa40 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
2aa50 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 e()] have been c
2aa60 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 alled subsequent
2aa70 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 ly..** If any of
2aa80 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
2aa90 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 are called after
2aaa0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2aab0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
2aac0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 3_finalize()] or
2aad0 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f after [sqlite3_
2aae0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 step()] has retu
2aaf0 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e rned.** somethin
2ab00 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 g other than [SQ
2ab10 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 LITE_ROW], the r
2ab20 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 esults are undef
2ab30 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c ined..** If [sql
2ab40 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 ite3_step()] or
2ab50 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
2ab60 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 ] or [sqlite3_fi
2ab70 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 nalize()].** are
2ab80 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 called from a d
2ab90 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 ifferent thread
2aba0 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 while any of the
2abb0 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 se routines.** a
2abc0 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e re pending, then
2abd0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 the results are
2abe0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
2abf0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f * The sqlite3_co
2ac00 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 lumn_type() rout
2ac10 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a ine returns the.
2ac20 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 ** [SQLITE_INTEG
2ac30 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f ER | datatype co
2ac40 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 de] for the init
2ac50 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a ial data type.**
2ac60 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 of the result c
2ac70 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65 74 75 olumn. The retu
2ac80 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e rned value is on
2ac90 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 e of [SQLITE_INT
2aca0 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 EGER],.** [SQLIT
2acb0 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 E_FLOAT], [SQLIT
2acc0 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 E_TEXT], [SQLITE
2acd0 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 _BLOB], or [SQLI
2ace0 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 TE_NULL]. The v
2acf0 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 alue.** returned
2ad00 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by sqlite3_colu
2ad10 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c mn_type() is onl
2ad20 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 y meaningful if
2ad30 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 no type.** conve
2ad40 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 rsions have occu
2ad50 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65 rred as describe
2ad60 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 d below. After
2ad70 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f a type conversio
2ad80 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 n,.** the value
2ad90 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
2ada0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
2adb0 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 ) is undefined.
2adc0 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 Future.** versi
2add0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 ons of SQLite ma
2ade0 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 y change the beh
2adf0 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 avior of sqlite3
2ae00 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a _column_type().*
2ae10 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 * following a ty
2ae20 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a pe conversion..*
2ae30 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 *.** If the resu
2ae40 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 lt is a BLOB or
2ae50 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 UTF-8 string the
2ae60 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f n the sqlite3_co
2ae70 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 lumn_bytes().**
2ae80 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
2ae90 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
2aea0 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 tes in that BLOB
2aeb0 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 or string..** I
2aec0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
2aed0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c a UTF-16 string,
2aee0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f then sqlite3_co
2aef0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e lumn_bytes() con
2af00 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 verts.** the str
2af10 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 ing to UTF-8 and
2af20 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 then returns th
2af30 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
2af40 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 s..** If the res
2af50 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 ult is a numeric
2af60 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 value then sqli
2af70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2af80 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 () uses.** [sqli
2af90 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 te3_snprintf()]
2afa0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 to convert that
2afb0 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 value to a UTF-8
2afc0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 string and retu
2afd0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 rns.** the numbe
2afe0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
2aff0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 at string..** Th
2b000 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
2b010 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 does not includ
2b020 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 e the zero termi
2b030 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64 nator at the end
2b040 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e .** of the strin
2b050 67 2e 20 20 46 6f 72 20 63 6c 61 72 69 74 79 3a g. For clarity:
2b060 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
2b070 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 ned is the numbe
2b080 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e r of.** bytes in
2b090 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 the string, not
2b0a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 the number of c
2b0b0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a haracters..**.**
2b0c0 20 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 Strings returne
2b0d0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c d by sqlite3_col
2b0e0 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 umn_text() and s
2b0f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
2b100 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 xt16(),.** even
2b110 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 empty strings, a
2b120 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74 re always zero t
2b130 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 erminated. The
2b140 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 return.** value
2b150 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c from sqlite3_col
2b160 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 umn_blob() for a
2b170 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f zero-length BLO
2b180 42 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 B is an arbitrar
2b190 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f y.** pointer, po
2b1a0 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20 4e 55 ssibly even a NU
2b1b0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
2b1c0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f * The sqlite3_co
2b1d0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 lumn_bytes16() r
2b1e0 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 outine is simila
2b1f0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c r to sqlite3_col
2b200 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62 umn_bytes().** b
2b210 75 74 20 6c 65 61 76 65 73 20 74 68 65 20 72 65 ut leaves the re
2b220 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 36 20 69 sult in UTF-16 i
2b230 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 n native byte or
2b240 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 55 der instead of U
2b250 54 46 2d 38 2e 0a 2a 2a 20 54 68 65 20 7a 65 72 TF-8..** The zer
2b260 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 o terminator is
2b270 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 not included in
2b280 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a this count..**.*
2b290 2a 20 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 * The object ret
2b2a0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 urned by [sqlite
2b2b0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 3_column_value()
2b2c0 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 ] is an.** [unpr
2b2d0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
2b2e0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 value] object.
2b2f0 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 An unprotected s
2b300 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
2b310 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 ect.** may only
2b320 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 be used with [sq
2b330 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 lite3_bind_value
2b340 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
2b350 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d _result_value()]
2b360 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 ..** If the [unp
2b370 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
2b380 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 _value] object r
2b390 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 eturned by.** [s
2b3a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 qlite3_column_va
2b3b0 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 lue()] is used i
2b3c0 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c n any other way,
2b3d0 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 including calls
2b3e0 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 .** to routines
2b3f0 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 like [sqlite3_va
2b400 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c lue_int()], [sql
2b410 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 ite3_value_text(
2b420 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 )],.** or [sqlit
2b430 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 e3_value_bytes()
2b440 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 ], then the beha
2b450 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 vior is undefine
2b460 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 d..**.** These r
2b470 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 outines attempt
2b480 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 to convert the v
2b490 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f alue where appro
2b4a0 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20 priate. For.**
2b4b0 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 example, if the
2b4c0 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 internal represe
2b4d0 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 ntation is FLOAT
2b4e0 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 and a text resu
2b4f0 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 lt.** is request
2b500 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 ed, [sqlite3_snp
2b510 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 rintf()] is used
2b520 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 internally to p
2b530 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f erform the.** co
2b540 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 nversion automat
2b550 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c ically. The fol
2b560 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 lowing table det
2b570 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 ails the convers
2b580 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 ions.** that are
2b590 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 applied:.**.**
2b5a0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 <blockquote>.**
2b5b0 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 <table border="1
2b5c0 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 ">.** <tr><th> I
2b5d0 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 nternal<br>Type
2b5e0 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 <th> Requested<b
2b5f0 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e r>Type <th> Con
2b600 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 version.**.** <t
2b610 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 r><td> NULL
2b620 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c <td> INTEGER <
2b630 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a td> Result is 0.
2b640 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c ** <tr><td> NUL
2b650 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 L <td> FLOAT
2b660 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 <td> Result
2b670 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 is 0.0.** <tr><t
2b680 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e d> NULL <td>
2b690 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 TEXT <td>
2b6a0 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 Result is NULL p
2b6b0 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 ointer.** <tr><t
2b6c0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e d> NULL <td>
2b6d0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 BLOB <td>
2b6e0 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 Result is NULL p
2b6f0 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 ointer.** <tr><t
2b700 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e d> INTEGER <td>
2b710 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 FLOAT <td>
2b720 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 Convert from int
2b730 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a eger to float.**
2b740 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 <tr><td> INTEGE
2b750 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 R <td> TEXT
2b760 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e <td> ASCII ren
2b770 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e dering of the in
2b780 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 teger.** <tr><td
2b790 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 > INTEGER <td>
2b7a0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 BLOB <td> S
2b7b0 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e ame as INTEGER->
2b7c0 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e TEXT.** <tr><td>
2b7d0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 FLOAT <td> I
2b7e0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f NTEGER <td> Co
2b7f0 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 nvert from float
2b800 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c to integer.** <
2b810 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 tr><td> FLOAT
2b820 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 <td> TEXT
2b830 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 <td> ASCII rende
2b840 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 ring of the floa
2b850 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 t.** <tr><td> F
2b860 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c LOAT <td> BL
2b870 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 OB <td> Same
2b880 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a as FLOAT->TEXT.*
2b890 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 * <tr><td> TEXT
2b8a0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 <td> INTEGER
2b8b0 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 <td> Use atoi
2b8c0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 ().** <tr><td>
2b8d0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c TEXT <td> FL
2b8e0 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 OAT <td> Use
2b8f0 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 atof().** <tr><t
2b900 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e d> TEXT <td>
2b910 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 BLOB <td>
2b920 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 No change.** <tr
2b930 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c ><td> BLOB <
2b940 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 td> INTEGER <t
2b950 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 d> Convert to TE
2b960 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 XT then use atoi
2b970 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 ().** <tr><td>
2b980 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c BLOB <td> FL
2b990 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 OAT <td> Conv
2b9a0 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e ert to TEXT then
2b9b0 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c use atof().** <
2b9c0 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 tr><td> BLOB
2b9d0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 <td> TEXT
2b9e0 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 <td> Add a zero
2b9f0 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 terminator if ne
2ba00 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e eded.** </table>
2ba10 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 .** </blockquote
2ba20 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c >.**.** The tabl
2ba30 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 e above makes re
2ba40 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 ference to stand
2ba50 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 ard C library fu
2ba60 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a nctions atoi().*
2ba70 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 * and atof(). S
2ba80 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 QLite does not r
2ba90 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 eally use these
2baa0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 functions. It h
2bab0 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 as its.** own eq
2bac0 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 uivalent interna
2bad0 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 l routines. The
2bae0 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 atoi() and atof
2baf0 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 () names are.**
2bb00 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c used in the tabl
2bb10 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e e for brevity an
2bb20 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61 d because they a
2bb30 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d re familiar to m
2bb40 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d ost.** C program
2bb50 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 mers..**.** Note
2bb60 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 that when type
2bb70 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 conversions occu
2bb80 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 r, pointers retu
2bb90 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a rned by prior.**
2bba0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 calls to sqlite
2bbb0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 3_column_blob(),
2bbc0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2bbd0 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a text(), and/or.*
2bbe0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e * sqlite3_column
2bbf0 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 _text16() may be
2bc00 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a invalidated..**
2bc10 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e Type conversion
2bc20 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e s and pointer in
2bc30 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 validations migh
2bc40 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 t occur.** in th
2bc50 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 e following case
2bc60 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a s:.**.** <ul>.**
2bc70 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 <li> The initia
2bc80 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 l content is a B
2bc90 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f LOB and sqlite3_
2bca0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 column_text() or
2bcb0 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 .** sqlite3
2bcc0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
2bcd0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a is called. A z
2bce0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d ero-terminator m
2bcf0 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 ight.** nee
2bd00 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f d to be added to
2bd10 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 the string.</li
2bd20 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e >.** <li> The in
2bd30 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 itial content is
2bd40 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 UTF-8 text and
2bd50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2bd60 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 ytes16() or.**
2bd70 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 sqlite3_colu
2bd80 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 mn_text16() is c
2bd90 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 alled. The cont
2bda0 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 ent must be conv
2bdb0 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f erted.** to
2bdc0 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a UTF-16.</li>.**
2bdd0 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 <li> The initia
2bde0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 l content is UTF
2bdf0 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c -16 text and sql
2be00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2be10 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 s() or.** s
2be20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
2be30 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 xt() is called.
2be40 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 The content mus
2be50 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a t be converted.*
2be60 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e * to UTF-8.
2be70 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a </li>.** </ul>.*
2be80 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73 *.** Conversions
2be90 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 between UTF-16b
2bea0 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 e and UTF-16le a
2beb0 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 re always done i
2bec0 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a n place and do.*
2bed0 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 * not invalidate
2bee0 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 a prior pointer
2bef0 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 , though of cour
2bf00 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f se the content o
2bf10 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 f the buffer.**
2bf20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 that the prior p
2bf30 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f ointer points to
2bf40 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 will have been
2bf50 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 modified. Other
2bf60 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e kinds.** of con
2bf70 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 version are done
2bf80 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 in place when i
2bf90 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 t is possible, b
2bfa0 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 ut sometimes the
2bfb0 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 y.** are not pos
2bfc0 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f sible and in tho
2bfd0 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 se cases prior p
2bfe0 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 ointers are inva
2bff0 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 lidated..**.** T
2c000 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 he safest and ea
2c010 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 siest to remembe
2c020 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 r policy is to i
2c030 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 nvoke these rout
2c040 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f ines.** in one o
2c050 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 f the following
2c060 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ways:.**.** <ul>
2c070 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 .** <li>sqlite3
2c080 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 _column_text() f
2c090 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 ollowed by sqlit
2c0a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2c0b0 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 )</li>.** <li>s
2c0c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
2c0d0 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 ob() followed by
2c0e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2c0f0 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 bytes()</li>.**
2c100 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c <li>sqlite3_col
2c110 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c umn_text16() fol
2c120 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 lowed by sqlite3
2c130 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
2c140 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a )</li>.** </ul>.
2c150 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 **.** In other w
2c160 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 ords, you should
2c170 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f call sqlite3_co
2c180 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 lumn_text(),.**
2c190 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2c1a0 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 lob(), or sqlite
2c1b0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
2c1c0 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 ) first to force
2c1d0 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 the result.** i
2c1e0 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 nto the desired
2c1f0 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 format, then inv
2c200 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 oke sqlite3_colu
2c210 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a mn_bytes() or.**
2c220 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2c230 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e bytes16() to fin
2c240 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 d the size of th
2c250 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f e result. Do no
2c260 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 t mix calls.** t
2c270 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e o sqlite3_column
2c280 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 _text() or sqlit
2c290 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 e3_column_blob()
2c2a0 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a with calls to.*
2c2b0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e * sqlite3_column
2c2c0 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 _bytes16(), and
2c2d0 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 do not mix calls
2c2e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to sqlite3_colu
2c2f0 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 mn_text16().** w
2c300 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c ith calls to sql
2c310 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2c320 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 s()..**.** The p
2c330 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 ointers returned
2c340 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c are valid until
2c350 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 a type conversi
2c360 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 on occurs as.**
2c370 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c described above,
2c380 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 or until [sqlit
2c390 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 e3_step()] or [s
2c3a0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
2c3b0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 or.** [sqlite3_f
2c3c0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 inalize()] is ca
2c3d0 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65 6d 6f 72 lled. The memor
2c3e0 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 y space used to
2c3f0 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 hold strings.**
2c400 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 and BLOBs is fre
2c410 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ed automatically
2c420 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e . Do <b>not</b>
2c430 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 pass the pointe
2c440 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b rs returned.** [
2c450 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2c460 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 lob()], [sqlite3
2c470 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c _column_text()],
2c480 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 etc. into.** [s
2c490 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a qlite3_free()]..
2c4a0 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f 72 **.** If a memor
2c4b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 y allocation err
2c4c0 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 or occurs during
2c4d0 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 the evaluation
2c4e0 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 of any.** of the
2c4f0 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 se routines, a d
2c500 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 efault value is
2c510 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 returned. The d
2c520 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 efault value.**
2c530 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e is either the in
2c540 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f teger 0, the flo
2c550 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 ating point numb
2c560 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c er 0.0, or a NUL
2c570 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 L.** pointer. S
2c580 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 ubsequent calls
2c590 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 to [sqlite3_errc
2c5a0 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 ode()] will retu
2c5b0 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f rn.** [SQLITE_NO
2c5c0 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 MEM]..**.** INVA
2c5d0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
2c5e0 31 33 38 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 13803} The [sqli
2c5f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
2c600 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 S,N)] interface
2c610 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 converts the.**
2c620 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c Nth col
2c630 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 umn in the curre
2c640 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 nt row of the re
2c650 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 sult set for.**
2c660 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 the [pr
2c670 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2c680 5d 20 53 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 ] S into a BLOB
2c690 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 and then returns
2c6a0 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 a.** p
2c6b0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f ointer to the co
2c6c0 6e 76 65 72 74 65 64 20 76 61 6c 75 65 2e 0a 2a nverted value..*
2c6d0 2a 0a 2a 2a 20 7b 48 31 33 38 30 36 7d 20 54 68 *.** {H13806} Th
2c6e0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d e [sqlite3_colum
2c6f0 6e 5f 62 79 74 65 73 28 53 2c 4e 29 5d 20 69 6e n_bytes(S,N)] in
2c700 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
2c710 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
2c720 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
2c730 69 6e 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 in the BLOB or s
2c740 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 tring (exclusive
2c750 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 of the.**
2c760 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 zero termina
2c770 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e tor on the strin
2c780 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75 g) that was retu
2c790 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 rned by the.**
2c7a0 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 most rec
2c7b0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ent call to [sql
2c7c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 ite3_column_blob
2c7d0 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 (S,N)] or.**
2c7e0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 [sqlite3_c
2c7f0 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d olumn_text(S,N)]
2c800 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 39 7d ..**.** {H13809}
2c810 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f The [sqlite3_co
2c820 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 53 2c 4e lumn_bytes16(S,N
2c830 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
2c840 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 urns the.**
2c850 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 number of b
2c860 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 ytes in the stri
2c870 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66 ng (exclusive of
2c880 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
2c890 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 zero terminator
2c8a0 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20 on the string)
2c8b0 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 that was returne
2c8c0 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 d by the.**
2c8d0 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 most recent
2c8e0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
2c8f0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
2c900 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 S,N)]..**.** {H1
2c910 33 38 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 3812} The [sqlit
2c920 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 e3_column_double
2c930 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 (S,N)] interface
2c940 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a converts the.**
2c950 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f Nth co
2c960 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 lumn in the curr
2c970 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 ent row of the r
2c980 65 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68 esult set for th
2c990 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 e.** [p
2c9a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2c9b0 74 5d 20 53 20 69 6e 74 6f 20 61 20 66 6c 6f 61 t] S into a floa
2c9c0 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 ting point value
2c9d0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 and.**
2c9e0 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 returns a copy
2c9f0 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a of that value..*
2ca00 2a 0a 2a 2a 20 7b 48 31 33 38 31 35 7d 20 54 68 *.** {H13815} Th
2ca10 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d e [sqlite3_colum
2ca20 6e 5f 69 6e 74 28 53 2c 4e 29 5d 20 69 6e 74 65 n_int(S,N)] inte
2ca30 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 rface converts t
2ca40 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e he.** N
2ca50 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 th column in the
2ca60 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 current row of
2ca70 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 the result set f
2ca80 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 or the.**
2ca90 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 [prepared sta
2caa0 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 tement] S into a
2cab0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 64-bit signed i
2cac0 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 nteger and.**
2cad0 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 74 returns t
2cae0 68 65 20 6c 6f 77 65 72 20 33 32 20 62 69 74 73 he lower 32 bits
2caf0 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 of that integer
2cb00 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31 38 7d ..**.** {H13818}
2cb10 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f The [sqlite3_co
2cb20 6c 75 6d 6e 5f 69 6e 74 36 34 28 53 2c 4e 29 5d lumn_int64(S,N)]
2cb30 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 interface conve
2cb40 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 rts the.**
2cb50 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 Nth column i
2cb60 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f n the current ro
2cb70 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 w of the result
2cb80 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 set for the.**
2cb90 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 [prepare
2cba0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 d statement] S i
2cbb0 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 nto a 64-bit sig
2cbc0 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a ned integer and.
2cbd0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 ** retu
2cbe0 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 rns a copy of th
2cbf0 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a at integer..**.*
2cc00 2a 20 7b 48 31 33 38 32 31 7d 20 54 68 65 20 5b * {H13821} The [
2cc10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2cc20 65 78 74 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 ext(S,N)] interf
2cc30 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 ace converts the
2cc40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 .** Nth
2cc50 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 column in the c
2cc60 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 urrent row of th
2cc70 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 e result set for
2cc80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
2cc90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2cca0 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 7a ment] S into a z
2ccb0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 ero-terminated U
2ccc0 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 TF-8.**
2ccd0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 string and retu
2cce0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
2ccf0 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a that string..**
2cd00 0a 2a 2a 20 7b 48 31 33 38 32 34 7d 20 54 68 65 .** {H13824} The
2cd10 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
2cd20 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d 20 69 6e _text16(S,N)] in
2cd30 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 terface converts
2cd40 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 the.**
2cd50 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 Nth column in t
2cd60 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f he current row o
2cd70 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 f the result set
2cd80 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 for the.**
2cd90 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 [prepared s
2cda0 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f tatement] S into
2cdb0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
2cdc0 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 ed 2-byte.**
2cdd0 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 aligned UT
2cde0 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 F-16 native byte
2cdf0 20 6f 72 64 65 72 20 73 74 72 69 6e 67 20 61 6e order string an
2ce00 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 d returns.**
2ce10 20 20 20 20 20 20 61 20 70 6f 69 6e 74 65 72 20 a pointer
2ce20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a to that string..
2ce30 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 37 7d 20 54 **.** {H13827} T
2ce40 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 he [sqlite3_colu
2ce50 6d 6e 5f 74 79 70 65 28 53 2c 4e 29 5d 20 69 6e mn_type(S,N)] in
2ce60 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a terface returns.
2ce70 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 65 20 ** one
2ce80 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d of [SQLITE_NULL]
2ce90 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 , [SQLITE_INTEGE
2cea0 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 R], [SQLITE_FLOA
2ceb0 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 T],.**
2cec0 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f [SQLITE_TEXT], o
2ced0 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 r [SQLITE_BLOB]
2cee0 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 as appropriate f
2cef0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 or.** t
2cf00 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e he Nth column in
2cf10 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 the current row
2cf20 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 of the result s
2cf30 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 et for.**
2cf40 20 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 the [prepared
2cf50 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a statement] S..*
2cf60 2a 0a 2a 2a 20 7b 48 31 33 38 33 30 7d 20 54 68 *.** {H13830} Th
2cf70 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d e [sqlite3_colum
2cf80 6e 5f 76 61 6c 75 65 28 53 2c 4e 29 5d 20 69 6e n_value(S,N)] in
2cf90 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
2cfa0 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f a.** po
2cfb0 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 75 6e 70 inter to an [unp
2cfc0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
2cfd0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 _value] object f
2cfe0 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 or the.**
2cff0 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e Nth column in
2d000 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 the current row
2d010 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 of the result s
2d020 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 et for.**
2d030 20 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 the [prepared
2d040 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a statement] S..*
2d050 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 /.const void *sq
2d060 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
2d070 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c b(sqlite3_stmt*,
2d080 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 int iCol);.int
2d090 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2d0a0 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d ytes(sqlite3_stm
2d0b0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 t*, int iCol);.i
2d0c0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nt sqlite3_colum
2d0d0 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 n_bytes16(sqlite
2d0e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
2d0f0 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 l);.double sqlit
2d100 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 e3_column_double
2d110 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2d120 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 int iCol);.int s
2d130 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e qlite3_column_in
2d140 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c t(sqlite3_stmt*,
2d150 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 int iCol);.sqli
2d160 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 te3_int64 sqlite
2d170 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 3_column_int64(s
2d180 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
2d190 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 t iCol);.const u
2d1a0 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 nsigned char *sq
2d1b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
2d1c0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c t(sqlite3_stmt*,
2d1d0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 int iCol);.cons
2d1e0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
2d1f0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 column_text16(sq
2d200 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2d210 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 iCol);.int sqli
2d220 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
2d230 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2d240 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 nt iCol);.sqlite
2d250 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 3_value *sqlite3
2d260 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 _column_value(sq
2d270 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2d280 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 iCol);../*.** C
2d290 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 API3REF: Destroy
2d2a0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 A Prepared Stat
2d2b0 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 ement Object {H1
2d2c0 33 33 30 30 7d 20 3c 53 37 30 33 30 30 3e 3c 53 3300} <S70300><S
2d2d0 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 30100>.**.** The
2d2e0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a sqlite3_finaliz
2d2f0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 e() function is
2d300 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 called to delete
2d310 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
2d320 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 tement]..** If t
2d330 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 he statement was
2d340 20 65 78 65 63 75 74 65 64 20 73 75 63 63 65 73 executed succes
2d350 73 66 75 6c 6c 79 20 6f 72 20 6e 6f 74 20 65 78 sfully or not ex
2d360 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 ecuted at all, t
2d370 68 65 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b hen.** SQLITE_OK
2d380 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 49 66 is returned. If
2d390 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 execution of th
2d3a0 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c e statement fail
2d3b0 65 64 20 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 ed then an.** [e
2d3c0 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 rror code] or [e
2d3d0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f xtended error co
2d3e0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e de] is returned.
2d3f0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 .**.** This rout
2d400 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 ine can be calle
2d410 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 d at any point d
2d420 75 72 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 uring the execut
2d430 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 ion of the.** [p
2d440 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2d450 74 5d 2e 20 20 49 66 20 74 68 65 20 76 69 72 74 t]. If the virt
2d460 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20 ual machine has
2d470 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 not.** completed
2d480 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 execution when
2d490 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 this routine is
2d4a0 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20 called, that is
2d4b0 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 like.** encounte
2d4c0 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 ring an error or
2d4d0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 an [sqlite3_int
2d4e0 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 errupt | interru
2d4f0 70 74 5d 2e 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 pt]..** Incomple
2d500 74 65 20 75 70 64 61 74 65 73 20 6d 61 79 20 62 te updates may b
2d510 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e e rolled back an
2d520 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 d transactions c
2d530 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 anceled,.** depe
2d540 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 nding on the cir
2d550 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 cumstances, and
2d560 74 68 65 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f the.** [error co
2d570 64 65 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c de] returned wil
2d580 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f l be [SQLITE_ABO
2d590 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 RT]..**.** INVAR
2d5a0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
2d5b0 31 33 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 1302} The [sqlit
2d5c0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 e3_finalize(S)]
2d5d0 69 6e 74 65 72 66 61 63 65 20 64 65 73 74 72 6f interface destro
2d5e0 79 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 ys the.**
2d5f0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 [prepared sta
2d600 74 65 6d 65 6e 74 5d 20 53 20 61 6e 64 20 72 65 tement] S and re
2d610 6c 65 61 73 65 73 20 61 6c 6c 0a 2a 2a 20 20 20 leases all.**
2d620 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 61 6e memory an
2d630 64 20 66 69 6c 65 20 72 65 73 6f 75 72 63 65 73 d file resources
2d640 20 68 65 6c 64 20 62 79 20 74 68 61 74 20 6f 62 held by that ob
2d650 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 ject..**.** {H11
2d660 33 30 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 304} If the most
2d670 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 recent call to
2d680 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
2d690 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 ] for the.**
2d6a0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 [prepared
2d6b0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 statement] S ret
2d6c0 75 72 6e 65 64 20 61 6e 20 65 72 72 6f 72 2c 0a urned an error,.
2d6d0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e ** then
2d6e0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
2d6f0 7a 65 28 53 29 5d 20 72 65 74 75 72 6e 73 20 74 ze(S)] returns t
2d700 68 61 74 20 73 61 6d 65 20 65 72 72 6f 72 2e 0a hat same error..
2d710 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 */.int sqlite3_f
2d720 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f inalize(sqlite3_
2d730 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f stmt *pStmt);../
2d740 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
2d750 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 eset A Prepared
2d760 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 Statement Object
2d770 20 7b 48 31 33 33 33 30 7d 20 3c 53 37 30 33 30 {H13330} <S7030
2d780 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 0>.**.** The sql
2d790 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e ite3_reset() fun
2d7a0 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 ction is called
2d7b0 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 to reset a [prep
2d7c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a ared statement].
2d7d0 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 ** object back t
2d7e0 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 o its initial st
2d7f0 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 ate, ready to be
2d800 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a re-executed..**
2d810 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 Any SQL stateme
2d820 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 nt variables tha
2d830 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 t had values bou
2d840 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 nd to them using
2d850 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 .** the [sqlite3
2d860 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c _bind_blob | sql
2d870 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 ite3_bind_*() AP
2d880 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 I] retain their
2d890 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b values..** Use [
2d8a0 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 sqlite3_clear_bi
2d8b0 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 ndings()] to res
2d8c0 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e et the bindings.
2d8d0 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 32 7d 20 .**.** {H11332}
2d8e0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 The [sqlite3_res
2d8f0 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 et(S)] interface
2d900 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 resets the [pre
2d910 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2d920 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 S.** b
2d930 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e ack to the begin
2d940 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 ning of its prog
2d950 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 ram..**.** {H113
2d960 33 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 34} If the most
2d970 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b recent call to [
2d980 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d sqlite3_step(S)]
2d990 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 for the.**
2d9a0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 [prepared s
2d9b0 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 tatement] S retu
2d9c0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 rned [SQLITE_ROW
2d9d0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e ] or [SQLITE_DON
2d9e0 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 E],.**
2d9f0 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 or if [sqlite3_s
2da00 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 tep(S)] has neve
2da10 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 r before been ca
2da20 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20 lled on S,.**
2da30 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c then [sql
2da40 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 ite3_reset(S)] r
2da50 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
2da60 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 K]..**.** {H1133
2da70 36 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 6} If the most r
2da80 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 ecent call to [s
2da90 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 qlite3_step(S)]
2daa0 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 for the.**
2dab0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 [prepared st
2dac0 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 atement] S indic
2dad0 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 ated an error, t
2dae0 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 hen.**
2daf0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 [sqlite3_reset(S
2db00 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 )] returns an ap
2db10 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 propriate [error
2db20 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 code]..**.** {H
2db30 31 31 33 33 38 7d 20 54 68 65 20 5b 73 71 6c 69 11338} The [sqli
2db40 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e te3_reset(S)] in
2db50 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 terface does not
2db60 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 change the valu
2db70 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f es.** o
2db80 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 f any [sqlite3_b
2db90 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 ind_blob|binding
2dba0 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 s] on the [prepa
2dbb0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
2dbc0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
2dbd0 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 _reset(sqlite3_s
2dbe0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
2dbf0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 .** CAPI3REF: Cr
2dc00 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 eate Or Redefine
2dc10 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b SQL Functions {
2dc20 48 31 36 31 30 30 7d 20 3c 53 32 30 32 30 30 3e H16100} <S20200>
2dc30 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 .** KEYWORDS: {f
2dc40 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e unction creation
2dc50 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 routines}.** KE
2dc60 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 YWORDS: {applica
2dc70 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c tion-defined SQL
2dc80 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 function}.** KE
2dc90 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 YWORDS: {applica
2dca0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c tion-defined SQL
2dcb0 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a functions}.**.*
2dcc0 2a 20 54 68 65 73 65 20 74 77 6f 20 66 75 6e 63 * These two func
2dcd0 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 tions (collectiv
2dce0 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 ely known as "fu
2dcf0 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 nction creation
2dd00 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 routines").** ar
2dd10 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 e used to add SQ
2dd20 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 L functions or a
2dd30 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 ggregates or to
2dd40 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 redefine the beh
2dd50 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 avior.** of exis
2dd60 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f ting SQL functio
2dd70 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 ns or aggregates
2dd80 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 . The only diff
2dd90 65 72 65 6e 63 65 20 62 65 74 77 65 65 6e 20 74 erence between t
2dda0 68 65 0a 2a 2a 20 74 77 6f 20 69 73 20 74 68 61 he.** two is tha
2ddb0 74 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 t the second par
2ddc0 61 6d 65 74 65 72 2c 20 74 68 65 20 6e 61 6d 65 ameter, the name
2ddd0 20 6f 66 20 74 68 65 20 28 73 63 61 6c 61 72 29 of the (scalar)
2dde0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 function or.**
2ddf0 61 67 67 72 65 67 61 74 65 2c 20 69 73 20 65 6e aggregate, is en
2de00 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 20 66 coded in UTF-8 f
2de10 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 or sqlite3_creat
2de20 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64 e_function() and
2de30 20 55 54 46 2d 31 36 0a 2a 2a 20 66 6f 72 20 73 UTF-16.** for s
2de40 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
2de50 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a nction16()..**.*
2de60 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 * The first para
2de70 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 meter is the [da
2de80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2de90 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 n] to which the
2dea0 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 SQL.** function
2deb0 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 is to be added.
2dec0 20 49 66 20 61 20 73 69 6e 67 6c 65 20 70 72 6f If a single pro
2ded0 67 72 61 6d 20 75 73 65 73 20 6d 6f 72 65 20 74 gram uses more t
2dee0 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 han one database
2def0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 .** connection i
2df00 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 nternally, then
2df10 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 SQL functions mu
2df20 73 74 20 62 65 20 61 64 64 65 64 20 69 6e 64 69 st be added indi
2df30 76 69 64 75 61 6c 6c 79 20 74 6f 0a 2a 2a 20 65 vidually to.** e
2df40 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e ach database con
2df50 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 nection..**.** T
2df60 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
2df70 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 ter is the name
2df80 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 of the SQL funct
2df90 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 ion to be create
2dfa0 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 d or.** redefine
2dfb0 64 2e 20 20 54 68 65 20 6c 65 6e 67 74 68 20 6f d. The length o
2dfc0 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 f the name is li
2dfd0 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 mited to 255 byt
2dfe0 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 es, exclusive of
2dff0 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 .** the zero-ter
2e000 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 minator. Note t
2e010 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e hat the name len
2e020 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 gth limit is in
2e030 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 bytes, not.** ch
2e040 61 72 61 63 74 65 72 73 2e 20 20 41 6e 79 20 61 aracters. Any a
2e050 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 ttempt to create
2e060 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 a function with
2e070 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a a longer name.*
2e080 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e * will result in
2e090 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
2e0a0 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a being returned..
2e0b0 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 **.** The third
2e0c0 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 parameter (nArg)
2e0d0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 .** is the numbe
2e0e0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 r of arguments t
2e0f0 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 hat the SQL func
2e100 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 tion or.** aggre
2e110 67 61 74 65 20 74 61 6b 65 73 2e 20 49 66 20 74 gate takes. If t
2e120 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 his parameter is
2e130 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 negative, then
2e140 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
2e150 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 or.** aggregate
2e160 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 may take any nu
2e170 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 mber of argument
2e180 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 s..**.** The fou
2e190 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 rth parameter, e
2e1a0 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 TextRep, specifi
2e1b0 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 es what.** [SQLI
2e1c0 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 TE_UTF8 | text e
2e1d0 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 ncoding] this SQ
2e1e0 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 L function prefe
2e1f0 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 rs for.** its pa
2e200 72 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 53 rameters. Any S
2e210 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c QL function impl
2e220 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c ementation shoul
2e230 64 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 d be able to wor
2e240 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 k.** work with U
2e250 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 TF-8, UTF-16le,
2e260 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 or UTF-16be. Bu
2e270 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 t some implement
2e280 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a ations may be.**
2e290 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 more efficient
2e2a0 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e with one encodin
2e2b0 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 g than another.
2e2c0 20 49 74 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 It is allowed t
2e2d0 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 o.** invoke sqli
2e2e0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
2e2f0 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ion() or sqlite3
2e300 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
2e310 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 16() multiple.**
2e320 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 times with the
2e330 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 same function bu
2e340 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 t with different
2e350 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 values of eText
2e360 52 65 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c Rep..** When mul
2e370 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 tiple implementa
2e380 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d tions of the sam
2e390 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 e function are a
2e3a0 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 vailable, SQLite
2e3b0 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 .** will pick th
2e3c0 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c e one that invol
2e3d0 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d ves the least am
2e3e0 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e ount of data con
2e3f0 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 version..** If t
2e400 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 here is only a s
2e410 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 ingle implementa
2e420 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 tion which does
2e430 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20 74 65 not care what te
2e440 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 xt.** encoding i
2e450 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 s used, then the
2e460 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 fourth argument
2e470 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 should be [SQLI
2e480 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 TE_ANY]..**.** T
2e490 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 he fifth paramet
2e4a0 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 er is an arbitra
2e4b0 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 ry pointer. The
2e4c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
2e4d0 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 of the.** functi
2e4e0 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 on can gain acce
2e4f0 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 ss to this point
2e500 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 er using [sqlite
2e510 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 0a 3_user_data()]..
2e520 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e 74 **.** The sevent
2e530 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20 6e 69 h, eighth and ni
2e540 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 nth parameters,
2e550 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 xFunc, xStep and
2e560 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 xFinal, are.**
2e570 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 pointers to C-la
2e580 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 nguage functions
2e590 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 that implement
2e5a0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
2e5b0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 or.** aggregate
2e5c0 2e 20 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 . A scalar SQL f
2e5d0 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 unction requires
2e5e0 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 an implementati
2e5f0 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a on of the xFunc.
2e600 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 ** callback only
2e610 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 , NULL pointers
2e620 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 should be passed
2e630 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e as the xStep an
2e640 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 d xFinal.** para
2e650 6d 65 74 65 72 73 2e 20 41 6e 20 61 67 67 72 65 meters. An aggre
2e660 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f gate SQL functio
2e670 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d n requires an im
2e680 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
2e690 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 xStep.** and xFi
2e6a0 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f nal and NULL sho
2e6b0 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 66 6f uld be passed fo
2e6c0 72 20 78 46 75 6e 63 2e 20 54 6f 20 64 65 6c 65 r xFunc. To dele
2e6d0 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a te an existing.*
2e6e0 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f * SQL function o
2e6f0 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 r aggregate, pas
2e700 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 s NULL for all t
2e710 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 20 63 61 hree function ca
2e720 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 49 llbacks..**.** I
2e730 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 t is permitted t
2e740 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 o register multi
2e750 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ple implementati
2e760 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a ons of the same.
2e770 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 ** functions wit
2e780 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 h the same name
2e790 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 but with either
2e7a0 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 differing number
2e7b0 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 s of.** argument
2e7c0 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 s or differing p
2e7d0 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e referred text en
2e7e0 63 6f 64 69 6e 67 73 2e 20 20 53 51 4c 69 74 65 codings. SQLite
2e7f0 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 will use.** the
2e800 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
2e810 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 most closely mat
2e820 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 ches the way in
2e830 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c which the.** SQL
2e840 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 function is use
2e850 64 2e 20 20 41 20 66 75 6e 63 74 69 6f 6e 20 69 d. A function i
2e860 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 mplementation wi
2e870 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 th a non-negativ
2e880 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 e.** nArg parame
2e890 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20 ter is a better
2e8a0 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e match than a fun
2e8b0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 ction implementa
2e8c0 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e tion with.** a n
2e8d0 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 41 egative nArg. A
2e8e0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 function where
2e8f0 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65 the preferred te
2e900 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d xt encoding.** m
2e910 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62 atches the datab
2e920 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 ase encoding is
2e930 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 a better.** matc
2e940 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f h than a functio
2e950 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f n where the enco
2e960 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e ding is differen
2e970 74 2e 20 20 0a 2a 2a 20 41 20 66 75 6e 63 74 69 t. .** A functi
2e980 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 on where the enc
2e990 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 oding difference
2e9a0 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 is between UTF1
2e9b0 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 6le and UTF16be.
2e9c0 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d ** is a closer m
2e9d0 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 atch than a func
2e9e0 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 tion where the e
2e9f0 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e ncoding differen
2ea00 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e ce is.** between
2ea10 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e UTF8 and UTF16.
2ea20 0a 2a 2a 0a 2a 2a 20 42 75 69 6c 74 2d 69 6e 20 .**.** Built-in
2ea30 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 functions may be
2ea40 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e overloaded by n
2ea50 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 ew application-d
2ea60 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 efined functions
2ea70 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 ..** The first a
2ea80 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
2ea90 65 64 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 ed function with
2eaa0 20 61 20 67 69 76 65 6e 20 6e 61 6d 65 20 6f 76 a given name ov
2eab0 65 72 72 69 64 65 73 20 61 6c 6c 0a 2a 2a 20 62 errides all.** b
2eac0 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e uilt-in function
2ead0 73 20 69 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 s in the same [d
2eae0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2eaf0 6f 6e 5d 20 77 69 74 68 20 74 68 65 20 73 61 6d on] with the sam
2eb00 65 20 6e 61 6d 65 2e 0a 2a 2a 20 53 75 62 73 65 e name..** Subse
2eb10 71 75 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f quent applicatio
2eb20 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
2eb30 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 ons of the same
2eb40 6e 61 6d 65 20 6f 6e 6c 79 20 6f 76 65 72 72 69 name only overri
2eb50 64 65 20 0a 2a 2a 20 70 72 69 6f 72 20 61 70 70 de .** prior app
2eb60 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
2eb70 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 functions that
2eb80 61 72 65 20 61 6e 20 65 78 61 63 74 20 6d 61 74 are an exact mat
2eb90 63 68 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6e 75 ch for the.** nu
2eba0 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 mber of paramete
2ebb0 72 73 20 61 6e 64 20 70 72 65 66 65 72 72 65 64 rs and preferred
2ebc0 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a encoding..**.**
2ebd0 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d An application-
2ebe0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
2ebf0 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f is permitted to
2ec00 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 call other.** S
2ec10 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 QLite interfaces
2ec20 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 . However, such
2ec30 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a calls must not.
2ec40 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 ** close the dat
2ec50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2ec60 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 nor finalize or
2ec70 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 reset the prepa
2ec80 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 red.** statement
2ec90 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 in which the fu
2eca0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e nction is runnin
2ecb0 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 g..**.** INVARIA
2ecc0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 NTS:.**.** {H161
2ecd0 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 03} The [sqlite3
2ece0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
2ecf0 31 36 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 74 16(D,X,...)] int
2ed00 65 72 66 61 63 65 20 73 68 61 6c 6c 20 62 65 68 erface shall beh
2ed10 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ave.**
2ed20 61 73 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 as [sqlite3_crea
2ed30 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c te_function(D,X,
2ed40 2e 2e 2e 29 5d 20 69 6e 20 65 76 65 72 79 20 77 ...)] in every w
2ed50 61 79 20 65 78 63 65 70 74 20 74 68 61 74 20 69 ay except that i
2ed60 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e t.** in
2ed70 74 65 72 70 72 65 74 73 20 74 68 65 20 58 20 61 terprets the X a
2ed80 72 67 75 6d 65 6e 74 20 61 73 20 7a 65 72 6f 2d rgument as zero-
2ed90 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 terminated UTF-1
2eda0 36 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61 6.** na
2edb0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 tive byte order
2edc0 69 6e 73 74 65 61 64 20 6f 66 20 61 73 20 7a 65 instead of as ze
2edd0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 ro-terminated UT
2ede0 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 F-8..**.** {H161
2edf0 30 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 06} A successful
2ee00 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 invocation of t
2ee10 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b he.** [
2ee20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
2ee30 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c unction(D,X,N,E,
2ee40 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 ...)] interface
2ee50 73 68 61 6c 6c 20 72 65 67 69 73 74 65 72 0a 2a shall register.*
2ee60 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 72 65 * or re
2ee70 70 6c 61 63 65 73 20 63 61 6c 6c 62 61 63 6b 20 places callback
2ee80 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68 65 functions in the
2ee90 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
2eea0 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 ction] D.**
2eeb0 20 20 20 20 20 75 73 65 64 20 74 6f 20 69 6d 70 used to imp
2eec0 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 lement the SQL f
2eed0 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 64 20 58 20 unction named X
2eee0 77 69 74 68 20 4e 20 70 61 72 61 6d 65 74 65 72 with N parameter
2eef0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e s.** an
2ef00 64 20 68 61 76 69 6e 67 20 61 20 70 72 65 66 65 d having a prefe
2ef10 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 rred text encodi
2ef20 6e 67 20 6f 66 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b ng of E..**.** {
2ef30 48 31 36 31 30 39 7d 20 41 20 73 75 63 63 65 73 H16109} A succes
2ef40 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 sful call to [sq
2ef50 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
2ef60 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c ction(D,X,N,E,P,
2ef70 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 F,S,L)].**
2ef80 20 20 20 20 73 68 61 6c 6c 20 72 65 70 6c 61 63 shall replac
2ef90 65 20 74 68 65 20 50 2c 20 46 2c 20 53 2c 20 61 e the P, F, S, a
2efa0 6e 64 20 4c 20 76 61 6c 75 65 73 20 66 72 6f 6d nd L values from
2efb0 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 any prior calls
2efc0 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 with.**
2efd0 20 20 74 68 65 20 73 61 6d 65 20 44 2c 20 58 2c the same D, X,
2efe0 20 4e 2c 20 61 6e 64 20 45 20 76 61 6c 75 65 73 N, and E values
2eff0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 31 32 7d ..**.** {H16112}
2f000 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 The [sqlite3_cr
2f010 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c eate_function(D,
2f020 58 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 X,...)] interfac
2f030 65 20 73 68 61 6c 6c 20 66 61 69 6c 0a 2a 2a 20 e shall fail.**
2f040 20 20 20 20 20 20 20 20 20 69 66 20 74 68 65 20 if the
2f050 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d SQL function nam
2f060 65 20 58 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 e X is.**
2f070 20 20 20 6c 6f 6e 67 65 72 20 74 68 61 6e 20 32 longer than 2
2f080 35 35 20 62 79 74 65 73 20 65 78 63 6c 75 73 69 55 bytes exclusi
2f090 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 20 74 ve of the zero t
2f0a0 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a erminator..**.**
2f0b0 20 7b 48 31 36 31 31 38 7d 20 54 68 65 20 5b 73 {H16118} The [s
2f0c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
2f0d0 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 nction(D,X,N,E,P
2f0e0 2c 46 2c 53 2c 4c 29 5d 20 69 6e 74 65 72 66 61 ,F,S,L)] interfa
2f0f0 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 ce.** s
2f100 68 61 6c 6c 20 66 61 69 6c 20 75 6e 6c 65 73 73 hall fail unless
2f110 20 65 69 74 68 65 72 20 46 20 69 73 20 4e 55 4c either F is NUL
2f120 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72 L and S and L ar
2f130 65 20 6e 6f 6e 2d 4e 55 4c 4c 20 6f 72 0a 2a 2a e non-NULL or.**
2f140 2a 20 20 20 20 20 20 20 20 20 46 20 69 73 20 6e * F is n
2f150 6f 6e 2d 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e on-NULL and S an
2f160 64 20 4c 20 61 72 65 20 4e 55 4c 4c 2e 0a 2a 2a d L are NULL..**
2f170 0a 2a 2a 20 7b 48 31 36 31 32 31 7d 20 54 68 65 .** {H16121} The
2f180 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
2f190 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 2e 2e 2e 29 _function(D,...)
2f1a0 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c ] interface shal
2f1b0 6c 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a l fails with an.
2f1c0 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72 72 6f ** erro
2f1d0 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 r code of [SQLIT
2f1e0 45 5f 42 55 53 59 5d 20 69 66 20 74 68 65 72 65 E_BUSY] if there
2f1f0 20 65 78 69 73 74 20 5b 70 72 65 70 61 72 65 64 exist [prepared
2f200 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20 statements].**
2f210 20 20 20 20 20 20 20 20 20 61 73 73 6f 63 69 61 associa
2f220 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 ted with the [da
2f230 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2f240 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 n] D..**.** {H16
2f250 31 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 124} The [sqlite
2f260 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
2f270 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 20 69 6e n(D,X,N,...)] in
2f280 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 66 61 terface shall fa
2f290 69 6c 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 il with.**
2f2a0 20 20 20 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 an error cod
2f2b0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45 52 52 e of [SQLITE_ERR
2f2c0 4f 52 5d 20 69 66 20 70 61 72 61 6d 65 74 65 72 OR] if parameter
2f2d0 20 4e 20 69 73 20 6c 65 73 73 0a 2a 2a 20 20 20 N is less.**
2f2e0 20 20 20 20 20 20 20 74 68 61 6e 20 2d 31 20 6f than -1 o
2f2f0 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 r greater than 1
2f300 32 37 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 27..**.** {H1612
2f310 37 7d 20 57 68 65 6e 20 4e 20 69 73 20 6e 6f 6e 7} When N is non
2f320 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 5b -negative, the [
2f330 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
2f340 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e unction(D,X,N,..
2f350 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 .)].**
2f360 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 interface shall
2f370 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 register callbac
2f380 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 ks to be invoked
2f390 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 for the.**
2f3a0 20 20 20 20 20 53 51 4c 20 66 75 6e 63 74 69 6f SQL functio
2f3b0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61 n.** na
2f3c0 6d 65 64 20 58 20 77 68 65 6e 20 74 68 65 20 6e med X when the n
2f3d0 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e umber of argumen
2f3e0 74 73 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 ts to the SQL fu
2f3f0 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 nction is.**
2f400 20 20 20 20 20 20 65 78 61 63 74 6c 79 20 4e 2e exactly N.
2f410 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 30 7d 20 .**.** {H16130}
2f420 57 68 65 6e 20 4e 20 69 73 20 2d 31 2c 20 74 68 When N is -1, th
2f430 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 e [sqlite3_creat
2f440 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e e_function(D,X,N
2f450 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 ,...)].**
2f460 20 20 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 interface sha
2f470 6c 6c 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c ll register call
2f480 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f backs to be invo
2f490 6b 65 64 20 66 6f 72 20 74 68 65 20 53 51 4c 0a ked for the SQL.
2f4a0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 ** func
2f4b0 74 69 6f 6e 20 6e 61 6d 65 64 20 58 20 77 69 74 tion named X wit
2f4c0 68 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 h any number of
2f4d0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a arguments..**.**
2f4e0 20 7b 48 31 36 31 33 33 7d 20 57 68 65 6e 20 63 {H16133} When c
2f4f0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
2f500 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
2f510 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 (D,X,N,...)].**
2f520 20 20 20 20 20 20 20 20 20 73 70 65 63 69 66 79 specify
2f530 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d multiple implem
2f540 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 entations of the
2f550 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58 same function X
2f560 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 .** and
2f570 20 77 68 65 6e 20 6f 6e 65 20 69 6d 70 6c 65 6d when one implem
2f580 65 6e 74 61 74 69 6f 6e 20 68 61 73 20 4e 3e 3d entation has N>=
2f590 30 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 0 and the other
2f5a0 68 61 73 20 4e 3d 28 2d 31 29 0a 2a 2a 20 20 20 has N=(-1).**
2f5b0 20 20 20 20 20 20 20 74 68 65 20 69 6d 70 6c 65 the imple
2f5c0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 mentation with a
2f5d0 20 6e 6f 6e 2d 7a 65 72 6f 20 4e 20 73 68 61 6c non-zero N shal
2f5e0 6c 20 62 65 20 70 72 65 66 65 72 72 65 64 2e 0a l be preferred..
2f5f0 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 36 7d 20 57 **.** {H16136} W
2f600 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 hen calls to [sq
2f610 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
2f620 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e ction(D,X,N,E,..
2f630 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 .)].**
2f640 73 70 65 63 69 66 79 20 6d 75 6c 74 69 70 6c 65 specify multiple
2f650 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
2f660 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e of the same fun
2f670 63 74 69 6f 6e 20 58 20 77 69 74 68 0a 2a 2a 20 ction X with.**
2f680 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d the sam
2f690 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 e number of argu
2f6a0 6d 65 6e 74 73 20 4e 20 62 75 74 20 77 69 74 68 ments N but with
2f6b0 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 20 20 different.**
2f6c0 20 20 20 20 20 20 20 65 6e 63 6f 64 69 6e 67 73 encodings
2f6d0 20 45 2c 20 74 68 65 6e 20 74 68 65 20 69 6d 70 E, then the imp
2f6e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 72 lementation wher
2f6f0 65 20 45 20 6d 61 74 63 68 65 73 20 74 68 65 0a e E matches the.
2f700 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61 ** data
2f710 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 73 68 base encoding sh
2f720 61 6c 6c 20 70 72 65 66 65 72 72 65 64 2e 0a 2a all preferred..*
2f730 2a 0a 2a 2a 20 7b 48 31 36 31 33 39 7d 20 46 6f *.** {H16139} Fo
2f740 72 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 53 r an aggregate S
2f750 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 QL function crea
2f760 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 ted using.**
2f770 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 [sqlite3_c
2f780 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 reate_function(D
2f790 2c 58 2c 4e 2c 45 2c 50 2c 30 2c 53 2c 4c 29 5d ,X,N,E,P,0,S,L)]
2f7a0 20 74 68 65 20 66 69 6e 61 6c 69 7a 65 72 0a 2a the finalizer.*
2f7b0 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 * funct
2f7c0 69 6f 6e 20 4c 20 73 68 61 6c 6c 20 61 6c 77 61 ion L shall alwa
2f7d0 79 73 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 78 ys be invoked ex
2f7e0 61 63 74 6c 79 20 6f 6e 63 65 20 69 66 20 74 68 actly once if th
2f7f0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 e.** st
2f800 65 70 20 66 75 6e 63 74 69 6f 6e 20 53 20 69 73 ep function S is
2f810 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d called one or m
2f820 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 0a 2a 2a ore times..**.**
2f830 20 7b 48 31 36 31 34 32 7d 20 57 68 65 6e 20 53 {H16142} When S
2f840 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 65 69 QLite invokes ei
2f850 74 68 65 72 20 74 68 65 20 78 46 75 6e 63 20 6f ther the xFunc o
2f860 72 20 78 53 74 65 70 20 66 75 6e 63 74 69 6f 6e r xStep function
2f870 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 of.**
2f880 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 an application-d
2f890 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
2f8a0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 ion or aggregate
2f8b0 20 63 72 65 61 74 65 64 0a 2a 2a 20 20 20 20 20 created.**
2f8c0 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 by [sqlite3
2f8d0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
2f8e0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
2f8f0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
2f900 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 6()],.**
2f910 20 20 74 68 65 6e 20 74 68 65 20 61 72 72 61 79 then the array
2f920 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c of [sqlite3_val
2f930 75 65 5d 20 6f 62 6a 65 63 74 73 20 70 61 73 73 ue] objects pass
2f940 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 20 20 20 ed as the.**
2f950 20 20 20 20 20 20 74 68 69 72 64 20 70 61 72 61 third para
2f960 6d 65 74 65 72 20 73 68 61 6c 6c 20 62 65 20 5b meter shall be [
2f970 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
2f980 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 3_value] objects
2f990 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
2f9a0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
2f9b0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
2f9c0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
2f9d0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 FunctionName,.
2f9e0 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 int nArg,. int
2f9f0 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 eTextRep,. void
2fa00 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 *pApp,. void (
2fa10 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f *xFunc)(sqlite3_
2fa20 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c context*,int,sql
2fa30 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 ite3_value**),.
2fa40 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 void (*xStep)(s
2fa50 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
2fa60 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 int,sqlite3_valu
2fa70 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 e**),. void (*x
2fa80 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 Final)(sqlite3_c
2fa90 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 ontext*).);.int
2faa0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
2fab0 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c unction16(. sql
2fac0 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 ite3 *db,. cons
2fad0 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f t void *zFunctio
2fae0 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 nName,. int nAr
2faf0 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 g,. int eTextRe
2fb00 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c p,. void *pApp,
2fb10 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 . void (*xFunc)
2fb20 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
2fb30 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
2fb40 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
2fb50 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f *xStep)(sqlite3_
2fb60 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c context*,int,sql
2fb70 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 ite3_value**),.
2fb80 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 void (*xFinal)(
2fb90 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
2fba0 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ).);../*.** CAPI
2fbb0 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 3REF: Text Encod
2fbc0 69 6e 67 73 20 7b 48 31 30 32 36 37 7d 20 3c 53 ings {H10267} <S
2fbd0 35 30 32 30 30 3e 20 3c 48 31 36 31 30 30 3e 0a 50200> <H16100>.
2fbe0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
2fbf0 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 tant define inte
2fc00 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 ger codes that r
2fc10 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 epresent the var
2fc20 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 ious.** text enc
2fc30 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 odings supported
2fc40 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 by SQLite..*/.#
2fc50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 define SQLITE_UT
2fc60 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 F8 1.#
2fc70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 define SQLITE_UT
2fc80 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 F16LE 2.#
2fc90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 define SQLITE_UT
2fca0 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 F16BE 3.#
2fcb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 define SQLITE_UT
2fcc0 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20 F16 4
2fcd0 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 /* Use native
2fce0 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 byte order */.#d
2fcf0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 efine SQLITE_ANY
2fd00 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 5
2fd10 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 /* sqlite3_crea
2fd20 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 te_function only
2fd30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
2fd40 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 TE_UTF16_ALIGNED
2fd50 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 8 /* sqlite
2fd60 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
2fd70 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a on only */../*.*
2fd80 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 * CAPI3REF: Depr
2fd90 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 ecated Functions
2fda0 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a .** DEPRECATED.*
2fdb0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 *.** These funct
2fdc0 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 ions are [deprec
2fdd0 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 ated]. In order
2fde0 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 to maintain.**
2fdf0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 backwards compat
2fe00 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 ibility with old
2fe10 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 er code, these f
2fe20 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 unctions continu
2fe30 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 e .** to be supp
2fe40 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c orted. However,
2fe50 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e new application
2fe60 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a s should avoid.*
2fe70 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 * the use of the
2fe80 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 se functions. T
2fe90 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 o help encourage
2fea0 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 people to avoid
2feb0 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 .** using these
2fec0 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 functions, we ar
2fed0 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 e not going to t
2fee0 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 ell you what the
2fef0 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 y do..*/.#ifndef
2ff00 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 SQLITE_OMIT_DEP
2ff10 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 RECATED.SQLITE_D
2ff20 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 EPRECATED int sq
2ff30 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
2ff40 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f count(sqlite3_co
2ff50 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f ntext*);.SQLITE_
2ff60 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 DEPRECATED int s
2ff70 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 qlite3_expired(s
2ff80 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 qlite3_stmt*);.S
2ff90 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 QLITE_DEPRECATED
2ffa0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 int sqlite3_tra
2ffb0 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 nsfer_bindings(s
2ffc0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 qlite3_stmt*, sq
2ffd0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 lite3_stmt*);.SQ
2ffe0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
2fff0 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 int sqlite3_glob
30000 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 al_recover(void)
30010 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 ;.SQLITE_DEPRECA
30020 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 TED void sqlite3
30030 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 _thread_cleanup(
30040 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 void);.SQLITE_DE
30050 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c PRECATED int sql
30060 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 ite3_memory_alar
30070 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c m(void(*)(void*,
30080 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e sqlite3_int64,in
30090 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 t),void*,sqlite3
300a0 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a _int64);.#endif.
300b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
300c0 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 Obtaining SQL F
300d0 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 unction Paramete
300e0 72 20 56 61 6c 75 65 73 20 7b 48 31 35 31 30 30 r Values {H15100
300f0 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a } <S20200>.**.**
30100 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 The C-language
30110 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
30120 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 f SQL functions
30130 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75 and aggregates u
30140 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 ses.** this set
30150 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 of interface rou
30160 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 tines to access
30170 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 the parameter va
30180 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 lues on.** the f
30190 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 unction or aggre
301a0 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 gate..**.** The
301b0 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 xFunc (for scala
301c0 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 r functions) or
301d0 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 xStep (for aggre
301e0 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 gates) parameter
301f0 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 s.** to [sqlite3
30200 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
30210 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
30220 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
30230 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 16()].** define
30240 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 callbacks that i
30250 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c mplement the SQL
30260 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 functions and a
30270 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 ggregates..** Th
30280 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 4th parameter
30290 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 to these callbac
302a0 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f ks is an array o
302b0 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a f pointers to.**
302c0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 [protected sqli
302d0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
302e0 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e ts. There is on
302f0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
30300 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 ] object for.**
30310 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 each parameter t
30320 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 o the SQL functi
30330 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 on. These routi
30340 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a nes are used to.
30350 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 ** extract value
30360 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 s from the [sqli
30370 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
30380 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ts..**.** These
30390 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e routines work on
303a0 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 ly with [protect
303b0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
303c0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e ] objects..** An
303d0 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 y attempt to use
303e0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
303f0 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 on an [unprotect
30400 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
30410 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 ].** object resu
30420 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 lts in undefined
30430 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a behavior..**.**
30440 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
30450 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 work just like t
30460 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
30470 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 [column access
30480 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 functions].** ex
30490 63 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65 cept that these
304a0 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 routines take a
304b0 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 single [protect
304c0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
304d0 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e ] object.** poin
304e0 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 ter instead of a
304f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d [sqlite3_stmt*]
30500 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 pointer and an
30510 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e integer column n
30520 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 umber..**.** The
30530 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
30540 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 ext16() interfac
30550 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 e extracts a UTF
30560 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e -16 string.** in
30570 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 the native byte
30580 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f -order of the ho
30590 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 54 68 65 st machine. The
305a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 .** sqlite3_valu
305b0 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 e_text16be() and
305c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
305d0 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 ext16le() interf
305e0 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 aces.** extract
305f0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 UTF-16 strings a
30600 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 s big-endian and
30610 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 little-endian r
30620 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a espectively..**.
30630 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 ** The sqlite3_v
30640 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 alue_numeric_typ
30650 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 e() interface at
30660 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a tempts to apply.
30670 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e ** numeric affin
30680 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 ity to the value
30690 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 . This means th
306a0 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 at an attempt is
306b0 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 .** made to conv
306c0 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f ert the value to
306d0 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 an integer or f
306e0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 loating point.
306f0 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e If.** such a con
30700 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 version is possi
30710 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 ble without loss
30720 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 of information
30730 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 (in other.** wor
30740 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 ds, if the value
30750 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 is a string tha
30760 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e t looks like a n
30770 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 umber).** then t
30780 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 he conversion is
30790 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 performed. Oth
307a0 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 erwise no conver
307b0 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 sion occurs..**
307c0 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 The [SQLITE_INTE
307d0 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 GER | datatype]
307e0 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e after conversion
307f0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
30800 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 .** Please pay p
30810 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 articular attent
30820 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 ion to the fact
30830 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 that the pointer
30840 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f returned.** fro
30850 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 m [sqlite3_value
30860 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 _blob()], [sqlit
30870 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d e3_value_text()]
30880 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 , or.** [sqlite3
30890 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d _value_text16()]
308a0 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 can be invalida
308b0 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 ted by a subsequ
308c0 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b ent call to.** [
308d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
308e0 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 tes()], [sqlite3
308f0 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 _value_bytes16()
30900 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ], [sqlite3_valu
30910 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 e_text()],.** or
30920 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
30930 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a text16()]..**.**
30940 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
30950 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 must be called f
30960 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 rom the same thr
30970 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 ead as.** the SQ
30980 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 L function that
30990 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 supplied the [sq
309a0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 lite3_value*] pa
309b0 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 rameters..**.**
309c0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
309d0 2a 20 7b 48 31 35 31 30 33 7d 20 54 68 65 20 5b * {H15103} The [
309e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c sqlite3_value_bl
309f0 6f 62 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 ob(V)] interface
30a00 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a converts the.**
30a10 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 [prote
30a20 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
30a30 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 ue] object V int
30a40 6f 20 61 20 42 4c 4f 42 20 61 6e 64 20 74 68 65 o a BLOB and the
30a50 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 n.** re
30a60 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
30a70 74 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 65 64 to the converted
30a80 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 value..**.** {H
30a90 31 35 31 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 15106} The [sqli
30aa0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 te3_value_bytes(
30ab0 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 V)] interface re
30ac0 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 turns the.**
30ad0 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 number of
30ae0 62 79 74 65 73 20 69 6e 20 74 68 65 20 42 4c 4f bytes in the BLO
30af0 42 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63 B or string (exc
30b00 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a lusive of the.**
30b10 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 zero t
30b20 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 erminator on the
30b30 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 string) that wa
30b40 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 s returned by th
30b50 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f e.** mo
30b60 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 st recent call t
30b70 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 o [sqlite3_value
30b80 5f 62 6c 6f 62 28 56 29 5d 20 6f 72 0a 2a 2a 20 _blob(V)] or.**
30b90 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
30ba0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 56 29 5d 3_value_text(V)]
30bb0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 39 7d ..**.** {H15109}
30bc0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 The [sqlite3_va
30bd0 6c 75 65 5f 62 79 74 65 73 31 36 28 56 29 5d 20 lue_bytes16(V)]
30be0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
30bf0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 s the.**
30c00 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 number of byte
30c10 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 s in the string
30c20 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 (exclusive of th
30c30 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 e.** ze
30c40 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e ro terminator on
30c50 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61 the string) tha
30c60 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62 t was returned b
30c70 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 y the.**
30c80 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 most recent ca
30c90 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76 ll to [sqlite3_v
30ca0 61 6c 75 65 5f 74 65 78 74 31 36 28 56 29 5d 2c alue_text16(V)],
30cb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
30cc0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
30cd0 31 36 62 65 28 56 29 5d 2c 20 6f 72 20 5b 73 71 16be(V)], or [sq
30ce0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
30cf0 31 36 6c 65 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 16le(V)]..**.**
30d00 7b 48 31 35 31 31 32 7d 20 54 68 65 20 5b 73 71 {H15112} The [sq
30d10 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 lite3_value_doub
30d20 6c 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 le(V)] interface
30d30 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a converts the.**
30d40 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 [prote
30d50 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
30d60 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 ue] object V int
30d70 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 o a floating poi
30d80 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 nt value and.**
30d90 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 returns
30da0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 a copy of that
30db0 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 value..**.** {H1
30dc0 35 31 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 5115} The [sqlit
30dd0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 56 29 5d e3_value_int(V)]
30de0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 interface conve
30df0 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 rts the.**
30e00 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 [protected s
30e10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
30e20 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 36 34 ject V into a 64
30e30 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 -bit signed inte
30e40 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 ger and.**
30e50 20 20 20 20 72 65 74 75 72 6e 73 20 74 68 65 20 returns the
30e60 6c 6f 77 65 72 20 33 32 20 62 69 74 73 20 6f 66 lower 32 bits of
30e70 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a that integer..*
30e80 2a 0a 2a 2a 20 7b 48 31 35 31 31 38 7d 20 54 68 *.** {H15118} Th
30e90 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
30ea0 5f 69 6e 74 36 34 28 56 29 5d 20 69 6e 74 65 72 _int64(V)] inter
30eb0 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 face converts th
30ec0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 e.** [p
30ed0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
30ee0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 _value] object V
30ef0 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 into a 64-bit s
30f00 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e igned integer an
30f10 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 d.** re
30f20 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 turns a copy of
30f30 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a that integer..**
30f40 0a 2a 2a 20 7b 48 31 35 31 32 31 7d 20 54 68 65 .** {H15121} The
30f50 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
30f60 74 65 78 74 28 56 29 5d 20 69 6e 74 65 72 66 61 text(V)] interfa
30f70 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a ce converts the.
30f80 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f ** [pro
30f90 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
30fa0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 alue] object V i
30fb0 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 nto a zero-termi
30fc0 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 20 nated UTF-8.**
30fd0 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 string a
30fe0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 nd returns a poi
30ff0 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 nter to that str
31000 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 ing..**.** {H151
31010 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 24} The [sqlite3
31020 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 56 29 _value_text16(V)
31030 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 ] interface conv
31040 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 erts the.**
31050 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 [protected
31060 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
31070 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a bject V into a z
31080 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 ero-terminated 2
31090 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 -byte.**
310a0 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 aligned UTF-16
310b0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
310c0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 er.** s
310d0 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e tring and return
310e0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 s a pointer to t
310f0 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a hat string..**.*
31100 2a 20 7b 48 31 35 31 32 37 7d 20 54 68 65 20 5b * {H15127} The [
31110 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
31120 78 74 31 36 62 65 28 56 29 5d 20 69 6e 74 65 72 xt16be(V)] inter
31130 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 face converts th
31140 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 e.** [p
31150 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
31160 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 _value] object V
31170 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 into a zero-ter
31180 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a minated 2-byte.*
31190 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e * align
311a0 65 64 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e ed UTF-16 big-en
311b0 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 dian.**
311c0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 string and retu
311d0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
311e0 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a that string..**
311f0 0a 2a 2a 20 7b 48 31 35 31 33 30 7d 20 54 68 65 .** {H15130} The
31200 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
31210 74 65 78 74 31 36 6c 65 28 56 29 5d 20 69 6e 74 text16le(V)] int
31220 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 erface converts
31230 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
31240 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 [protected sqlit
31250 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
31260 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 V into a zero-t
31270 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 erminated 2-byte
31280 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 .** ali
31290 67 6e 65 64 20 55 54 46 2d 31 36 20 6c 69 74 74 gned UTF-16 litt
312a0 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 le-endian.**
312b0 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 string and
312c0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
312d0 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e er to that strin
312e0 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 33 g..**.** {H15133
312f0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 } The [sqlite3_v
31300 61 6c 75 65 5f 74 79 70 65 28 56 29 5d 20 69 6e alue_type(V)] in
31310 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a terface returns.
31320 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 65 20 ** one
31330 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d of [SQLITE_NULL]
31340 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 , [SQLITE_INTEGE
31350 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 R], [SQLITE_FLOA
31360 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 T],.**
31370 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f [SQLITE_TEXT], o
31380 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 r [SQLITE_BLOB]
31390 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 as appropriate f
313a0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 or.** t
313b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 he [sqlite3_valu
313c0 65 5d 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a e] object V..**.
313d0 2a 2a 20 7b 48 31 35 31 33 36 7d 20 54 68 65 20 ** {H15136} The
313e0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e [sqlite3_value_n
313f0 75 6d 65 72 69 63 5f 74 79 70 65 28 56 29 5d 20 umeric_type(V)]
31400 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 interface conver
31410 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 ts.** t
31420 68 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 he [protected sq
31430 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
31440 65 63 74 20 56 20 69 6e 74 6f 20 65 69 74 68 65 ect V into eithe
31450 72 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 0a r an integer or.
31460 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 66 6c ** a fl
31470 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c oating point val
31480 75 65 20 69 66 20 69 74 20 63 61 6e 20 64 6f 20 ue if it can do
31490 73 6f 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 so without loss
314a0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 of.** i
314b0 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20 61 6e 64 20 nformation, and
314c0 72 65 74 75 72 6e 73 20 6f 6e 65 20 6f 66 20 5b returns one of [
314d0 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 0a 2a 2a SQLITE_NULL],.**
314e0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 [SQLIT
314f0 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c E_INTEGER], [SQL
31500 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c ITE_FLOAT], [SQL
31510 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 0a 2a 2a ITE_TEXT], or.**
31520 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 [SQLIT
31530 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f E_BLOB] as appro
31540 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 0a 2a priate for the.*
31550 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 * [prot
31560 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
31570 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 61 66 lue] object V af
31580 74 65 72 20 74 68 65 20 63 6f 6e 76 65 72 73 69 ter the conversi
31590 6f 6e 20 61 74 74 65 6d 70 74 2e 0a 2a 2f 0a 63 on attempt..*/.c
315a0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
315b0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 e3_value_blob(sq
315c0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 lite3_value*);.i
315d0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt sqlite3_value
315e0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 _bytes(sqlite3_v
315f0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 alue*);.int sqli
31600 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 te3_value_bytes1
31610 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 6(sqlite3_value*
31620 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 );.double sqlite
31630 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 3_value_double(s
31640 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
31650 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 int sqlite3_valu
31660 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 e_int(sqlite3_va
31670 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 lue*);.sqlite3_i
31680 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c nt64 sqlite3_val
31690 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 ue_int64(sqlite3
316a0 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 _value*);.const
316b0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 unsigned char *s
316c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
316d0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t(sqlite3_value*
316e0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
316f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
31700 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 t16(sqlite3_valu
31710 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 e*);.const void
31720 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 *sqlite3_value_t
31730 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f ext16le(sqlite3_
31740 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 value*);.const v
31750 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c oid *sqlite3_val
31760 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 ue_text16be(sqli
31770 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 te3_value*);.int
31780 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
31790 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 ype(sqlite3_valu
317a0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 e*);.int sqlite3
317b0 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 _value_numeric_t
317c0 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 ype(sqlite3_valu
317d0 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 e*);../*.** CAPI
317e0 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 3REF: Obtain Agg
317f0 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 regate Function
31800 43 6f 6e 74 65 78 74 20 7b 48 31 36 32 31 30 7d Context {H16210}
31810 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S20200>.**.**
31820 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 The implementati
31830 6f 6e 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 on of aggregate
31840 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 SQL functions us
31850 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 e this routine t
31860 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 20 o allocate.** a
31870 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 73 74 structure for st
31880 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 oring their stat
31890 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 e..**.** The fir
318a0 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 st time the sqli
318b0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
318c0 6e 74 65 78 74 28 29 20 72 6f 75 74 69 6e 65 20 ntext() routine
318d0 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 0a is called for a.
318e0 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 ** particular ag
318f0 67 72 65 67 61 74 65 2c 20 53 51 4c 69 74 65 20 gregate, SQLite
31900 61 6c 6c 6f 63 61 74 65 73 20 6e 42 79 74 65 73 allocates nBytes
31910 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f of memory, zero
31920 65 73 20 6f 75 74 20 74 68 61 74 0a 2a 2a 20 6d es out that.** m
31930 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 emory, and retur
31940 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
31950 69 74 2e 20 4f 6e 20 73 65 63 6f 6e 64 20 61 6e it. On second an
31960 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c d subsequent cal
31970 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 ls to.** sqlite3
31980 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
31990 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d xt() for the sam
319a0 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 e aggregate func
319b0 74 69 6f 6e 20 69 6e 64 65 78 2c 0a 2a 2a 20 74 tion index,.** t
319c0 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 he same buffer i
319d0 73 20 72 65 74 75 72 6e 65 64 2e 20 54 68 65 20 s returned. The
319e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
319f0 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 f the aggregate
31a00 63 61 6e 20 75 73 65 0a 2a 2a 20 74 68 65 20 72 can use.** the r
31a10 65 74 75 72 6e 65 64 20 62 75 66 66 65 72 20 74 eturned buffer t
31a20 6f 20 61 63 63 75 6d 75 6c 61 74 65 20 64 61 74 o accumulate dat
31a30 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 a..**.** SQLite
31a40 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 automatically fr
31a50 65 65 73 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 ees the allocate
31a60 64 20 62 75 66 66 65 72 20 77 68 65 6e 20 74 68 d buffer when th
31a70 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 71 e aggregate.** q
31a80 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a uery concludes..
31a90 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
31aa0 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 parameter should
31ab0 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 be a copy of th
31ac0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f e.** [sqlite3_co
31ad0 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 ntext | SQL func
31ae0 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 tion context] th
31af0 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 at is the first
31b00 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 parameter.** to
31b10 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 the callback rou
31b20 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d tine that implem
31b30 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 ents the aggrega
31b40 74 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a te function..**.
31b50 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
31b60 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 must be called f
31b70 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 rom the same thr
31b80 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 ead in which.**
31b90 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51 the aggregate SQ
31ba0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 L function is ru
31bb0 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 nning..**.** INV
31bc0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
31bd0 48 31 36 32 31 31 7d 20 54 68 65 20 66 69 72 73 H16211} The firs
31be0 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 t invocation of
31bf0 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 [sqlite3_aggrega
31c00 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d te_context(C,N)]
31c10 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 for.**
31c20 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 69 6e a particular in
31c30 73 74 61 6e 63 65 20 6f 66 20 61 6e 20 61 67 67 stance of an agg
31c40 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 regate function
31c50 28 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 (for a particula
31c60 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f r.** co
31c70 6e 74 65 78 74 20 43 29 20 63 61 75 73 65 73 20 ntext C) causes
31c80 53 51 4c 69 74 65 20 74 6f 20 61 6c 6c 6f 63 61 SQLite to alloca
31c90 74 65 20 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 te N bytes of me
31ca0 6d 6f 72 79 2c 0a 2a 2a 20 20 20 20 20 20 20 20 mory,.**
31cb0 20 20 7a 65 72 6f 20 74 68 61 74 20 6d 65 6d 6f zero that memo
31cc0 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 20 61 ry, and return a
31cd0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
31ce0 61 6c 6c 6f 63 61 74 65 64 20 6d 65 6d 6f 72 79 allocated memory
31cf0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 33 7d ..**.** {H16213}
31d00 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c If a memory all
31d10 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 ocation error oc
31d20 63 75 72 73 20 64 75 72 69 6e 67 0a 2a 2a 20 20 curs during.**
31d30 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 [sqlite3
31d40 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
31d50 78 74 28 43 2c 4e 29 5d 20 74 68 65 6e 20 74 68 xt(C,N)] then th
31d60 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 e function retur
31d70 6e 73 20 30 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 ns 0..**.** {H16
31d80 32 31 35 7d 20 53 65 63 6f 6e 64 20 61 6e 64 20 215} Second and
31d90 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 subsequent invoc
31da0 61 74 69 6f 6e 73 20 6f 66 0a 2a 2a 20 20 20 20 ations of.**
31db0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 61 [sqlite3_a
31dc0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
31dd0 28 43 2c 4e 29 5d 20 66 6f 72 20 74 68 65 20 73 (C,N)] for the s
31de0 61 6d 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e ame context poin
31df0 74 65 72 20 43 0a 2a 2a 20 20 20 20 20 20 20 20 ter C.**
31e00 20 20 69 67 6e 6f 72 65 20 74 68 65 20 4e 20 70 ignore the N p
31e10 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 arameter and ret
31e20 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f urn a pointer to
31e30 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 the same.**
31e40 20 20 20 20 20 20 62 6c 6f 63 6b 20 6f 66 20 6d block of m
31e50 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 emory returned b
31e60 79 20 74 68 65 20 66 69 72 73 74 20 69 6e 76 6f y the first invo
31e70 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 cation..**.** {H
31e80 31 36 32 31 37 7d 20 54 68 65 20 6d 65 6d 6f 72 16217} The memor
31e90 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 5b y allocated by [
31ea0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
31eb0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 e_context(C,N)]
31ec0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 is.** a
31ed0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 utomatically fre
31ee0 65 64 20 6f 6e 20 74 68 65 20 6e 65 78 74 20 63 ed on the next c
31ef0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
31f00 72 65 73 65 74 28 29 5d 0a 2a 2a 20 20 20 20 20 reset()].**
31f10 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 or [sqlite3
31f20 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 66 6f 72 _finalize()] for
31f30 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
31f40 74 61 74 65 6d 65 6e 74 5d 20 63 6f 6e 74 61 69 tatement] contai
31f50 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 ning.**
31f60 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 the aggregate f
31f70 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 unction associat
31f80 65 64 20 77 69 74 68 20 63 6f 6e 74 65 78 74 20 ed with context
31f90 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 C..*/.void *sqli
31fa0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
31fb0 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f ntext(sqlite3_co
31fc0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 ntext*, int nByt
31fd0 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 es);../*.** CAPI
31fe0 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 3REF: User Data
31ff0 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 For Functions {H
32000 31 36 32 34 30 7d 20 3c 53 32 30 32 30 30 3e 0a 16240} <S20200>.
32010 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
32020 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 3_user_data() in
32030 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
32040 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 a copy of.** the
32050 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 pointer that wa
32060 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 s the pUserData
32070 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 parameter (the 5
32080 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a th parameter).**
32090 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
320a0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
320b0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 ()].** and [sqli
320c0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
320d0 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 ion16()] routine
320e0 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c s that originall
320f0 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 y.** registered
32100 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
32110 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
32120 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 . {END}.**.** Th
32130 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 is routine must
32140 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 be called from t
32150 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 he same thread i
32160 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 n which.** the a
32170 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
32180 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 ed function is r
32190 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e unning..**.** IN
321a0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 VARIANTS:.**.**
321b0 7b 48 31 36 32 34 33 7d 20 54 68 65 20 5b 73 71 {H16243} The [sq
321c0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 lite3_user_data(
321d0 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 C)] interface re
321e0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 turns a copy of
321f0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
32200 50 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d 20 74 P pointer from t
32210 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 he [sqlite3_crea
32220 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c te_function(D,X,
32230 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a N,E,P,F,S,L)].**
32240 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 or [sq
32250 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
32260 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c ction16(D,X,N,E,
32270 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 P,F,S,L)] call t
32280 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 hat.**
32290 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 53 registered the S
322a0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f QL function asso
322b0 63 69 61 74 65 64 20 77 69 74 68 20 5b 73 71 6c ciated with [sql
322c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e ite3_context] C.
322d0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 .*/.void *sqlite
322e0 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 3_user_data(sqli
322f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a te3_context*);..
32300 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
32310 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 Database Connect
32320 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e ion For Function
32330 73 20 7b 48 31 36 32 35 30 7d 20 3c 53 36 30 36 s {H16250} <S606
32340 30 30 3e 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 00><S20200>.**.*
32350 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f * The sqlite3_co
32360 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 ntext_db_handle(
32370 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
32380 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a rns a copy of.**
32390 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 the pointer to
323a0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
323b0 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 nnection] (the 1
323c0 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a st parameter).**
323d0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
323e0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
323f0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 ()].** and [sqli
32400 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
32410 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 ion16()] routine
32420 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c s that originall
32430 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 y.** registered
32440 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
32450 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
32460 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
32470 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 35 TS:.**.** {H1625
32480 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 3} The [sqlite3_
32490 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c context_db_handl
324a0 65 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 e(C)] interface
324b0 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f returns a copy o
324c0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 f the.**
324d0 20 20 44 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d D pointer from
324e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 the [sqlite3_cr
324f0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c eate_function(D,
32500 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a X,N,E,P,F,S,L)].
32510 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b ** or [
32520 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
32530 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c unction16(D,X,N,
32540 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c E,P,F,S,L)] call
32550 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 that.**
32560 20 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 registered the
32570 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73 SQL function as
32580 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 5b 73 sociated with [s
32590 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 qlite3_context]
325a0 43 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 C..*/.sqlite3 *s
325b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 qlite3_context_d
325c0 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 b_handle(sqlite3
325d0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a _context*);../*.
325e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e ** CAPI3REF: Fun
325f0 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 ction Auxiliary
32600 44 61 74 61 20 7b 48 31 36 32 37 30 7d 20 3c 53 Data {H16270} <S
32610 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20200>.**.** The
32620 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 following two f
32630 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 unctions may be
32640 75 73 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 used by scalar S
32650 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a QL functions to.
32660 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 ** associate met
32670 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d adata with argum
32680 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 ent values. If t
32690 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 he same value is
326a0 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 passed to.** mu
326b0 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f ltiple invocatio
326c0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 ns of the same S
326d0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 QL function duri
326e0 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69 ng query executi
326f0 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d on, under.** som
32700 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 e circumstances
32710 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d the associated m
32720 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 etadata may be p
32730 72 65 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d reserved. This m
32740 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 ay.** be used, f
32750 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 or example, to a
32760 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 dd a regular-exp
32770 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 ression matching
32780 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 scalar.** funct
32790 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 ion. The compile
327a0 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 d version of the
327b0 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 regular express
327c0 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73 ion is stored as
327d0 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 .** metadata ass
327e0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 ociated with the
327f0 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65 SQL value passe
32800 64 20 61 73 20 74 68 65 20 72 65 67 75 6c 61 72 d as the regular
32810 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 expression.** p
32820 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d attern. The com
32830 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 piled regular ex
32840 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 pression can be
32850 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 reused on multip
32860 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e le.** invocation
32870 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 s of the same fu
32880 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 nction so that t
32890 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 he original patt
328a0 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f ern string.** do
328b0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 es not need to b
328c0 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 e recompiled on
328d0 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e each invocation.
328e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
328f0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 e3_get_auxdata()
32900 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
32910 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
32920 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 the metadata.**
32930 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 associated by th
32940 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 e sqlite3_set_au
32950 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e xdata() function
32960 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 with the Nth ar
32970 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 gument.** value
32980 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 to the applicati
32990 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
329a0 69 6f 6e 2e 20 49 66 20 6e 6f 20 6d 65 74 61 64 ion. If no metad
329b0 61 74 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 ata has been eve
329c0 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f r.** been set fo
329d0 72 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 r the Nth argume
329e0 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 nt of the functi
329f0 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f on, or if the co
32a00 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 rresponding.** f
32a10 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 unction paramete
32a20 72 20 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 r has changed si
32a30 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 nce the meta-dat
32a40 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 a was set,.** th
32a50 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 en sqlite3_get_a
32a60 75 78 64 61 74 61 28 29 20 72 65 74 75 72 6e 73 uxdata() returns
32a70 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
32a80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
32a90 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 e3_set_auxdata()
32aa0 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 interface saves
32ab0 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a the metadata.**
32ac0 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 pointed to by i
32ad0 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 ts 3rd parameter
32ae0 20 61 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 as the metadata
32af0 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a for the N-th.**
32b00 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 argument of the
32b10 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
32b20 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 ined function.
32b30 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 Subsequent.** ca
32b40 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 lls to sqlite3_g
32b50 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 et_auxdata() mig
32b60 68 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 ht return this d
32b70 61 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a ata, if it has.*
32b80 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 * not been destr
32b90 6f 79 65 64 2e 0a 2a 2a 20 49 66 20 69 74 20 69 oyed..** If it i
32ba0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 s not NULL, SQLi
32bb0 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 te will invoke t
32bc0 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a he destructor.**
32bd0 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 function given
32be0 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d by the 4th param
32bf0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
32c00 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e set_auxdata() on
32c10 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 .** the metadata
32c20 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 when the corres
32c30 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e ponding function
32c40 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 parameter chang
32c50 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 es.** or when th
32c60 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
32c70 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 completes, which
32c80 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 ever comes first
32c90 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 ..**.** SQLite i
32ca0 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 s free to call t
32cb0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e he destructor an
32cc0 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 d drop metadata
32cd0 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 on any.** parame
32ce0 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 ter of any funct
32cf0 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e ion at any time.
32d00 20 20 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 The only guara
32d10 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 ntee is that.**
32d20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 the destructor w
32d30 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 ill be called be
32d40 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 fore the metadat
32d50 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a a is dropped..**
32d60 0a 2a 2a 20 49 6e 20 70 72 61 63 74 69 63 65 2c .** In practice,
32d70 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65 metadata is pre
32d80 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 served between f
32d90 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f unction calls fo
32da0 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 r.** expressions
32db0 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 that are consta
32dc0 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 nt at compile ti
32dd0 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 me. This include
32de0 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c s literal.** val
32df0 75 65 73 20 61 6e 64 20 53 51 4c 20 76 61 72 69 ues and SQL vari
32e00 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ables..**.** The
32e10 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 se routines must
32e20 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 be called from
32e30 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 the same thread
32e40 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 in which.** the
32e50 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 SQL function is
32e60 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 running..**.** I
32e70 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
32e80 20 7b 48 31 36 32 37 32 7d 20 54 68 65 20 5b 73 {H16272} The [s
32e90 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 qlite3_get_auxda
32ea0 74 61 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66 61 ta(C,N)] interfa
32eb0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ce returns a poi
32ec0 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 nter.**
32ed0 20 74 6f 20 6d 65 74 61 64 61 74 61 20 61 73 73 to metadata ass
32ee0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 ociated with the
32ef0 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f Nth parameter o
32f00 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 f the SQL functi
32f10 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 on.** w
32f20 68 6f 73 65 20 63 6f 6e 74 65 78 74 20 69 73 20 hose context is
32f30 43 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 C, or NULL if th
32f40 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 ere is no metada
32f50 74 61 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a ta associated.**
32f60 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20 74 with t
32f70 68 61 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a hat parameter..*
32f80 2a 0a 2a 2a 20 7b 48 31 36 32 37 34 7d 20 54 68 *.** {H16274} Th
32f90 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 e [sqlite3_set_a
32fa0 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d uxdata(C,N,P,D)]
32fb0 20 69 6e 74 65 72 66 61 63 65 20 61 73 73 69 67 interface assig
32fc0 6e 73 20 61 20 6d 65 74 61 64 61 74 61 0a 2a 2a ns a metadata.**
32fd0 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 pointe
32fe0 72 20 50 20 74 6f 20 74 68 65 20 4e 74 68 20 70 r P to the Nth p
32ff0 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 arameter of the
33000 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 SQL function wit
33010 68 20 63 6f 6e 74 65 78 74 20 43 2e 0a 2a 2a 0a h context C..**.
33020 2a 2a 20 7b 48 31 36 32 37 36 7d 20 53 51 4c 69 ** {H16276} SQLi
33030 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 te will invoke t
33040 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 he destructor D
33050 77 69 74 68 20 61 20 73 69 6e 67 6c 65 20 61 72 with a single ar
33060 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 gument.**
33070 20 20 20 77 68 69 63 68 20 69 73 20 74 68 65 20 which is the
33080 6d 65 74 61 64 61 74 61 20 70 6f 69 6e 74 65 72 metadata pointer
33090 20 50 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 P following a c
330a0 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 all to.**
330b0 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f [sqlite3_set_
330c0 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 auxdata(C,N,P,D)
330d0 5d 20 77 68 65 6e 20 53 51 4c 69 74 65 20 63 65 ] when SQLite ce
330e0 61 73 65 73 20 74 6f 20 68 6f 6c 64 0a 2a 2a 20 ases to hold.**
330f0 20 20 20 20 20 20 20 20 20 74 68 65 20 6d 65 74 the met
33100 61 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 adata..**.** {H1
33110 36 32 37 37 7d 20 53 51 4c 69 74 65 20 63 65 61 6277} SQLite cea
33120 73 65 73 20 74 6f 20 68 6f 6c 64 20 6d 65 74 61 ses to hold meta
33130 64 61 74 61 20 66 6f 72 20 61 6e 20 53 51 4c 20 data for an SQL
33140 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 function paramet
33150 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 er.** w
33160 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 hen the value of
33170 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 that parameter
33180 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b changes..**.** {
33190 48 31 36 32 37 38 7d 20 57 68 65 6e 20 5b 73 71 H16278} When [sq
331a0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 lite3_set_auxdat
331b0 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69 73 20 69 a(C,N,P,D)] is i
331c0 6e 76 6f 6b 65 64 2c 20 74 68 65 20 64 65 73 74 nvoked, the dest
331d0 72 75 63 74 6f 72 0a 2a 2a 20 20 20 20 20 20 20 ructor.**
331e0 20 20 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 is called for
331f0 20 61 6e 79 20 70 72 69 6f 72 20 6d 65 74 61 64 any prior metad
33200 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 ata associated w
33210 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e ith the same fun
33220 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 ction.**
33230 20 20 63 6f 6e 74 65 78 74 20 43 20 61 6e 64 20 context C and
33240 70 61 72 61 6d 65 74 65 72 20 4e 2e 0a 2a 2a 0a parameter N..**.
33250 2a 2a 20 7b 48 31 36 32 37 39 7d 20 53 51 4c 69 ** {H16279} SQLi
33260 74 65 20 77 69 6c 6c 20 63 61 6c 6c 20 64 65 73 te will call des
33270 74 72 75 63 74 6f 72 73 20 66 6f 72 20 61 6e 79 tructors for any
33280 20 6d 65 74 61 64 61 74 61 20 69 74 20 69 73 20 metadata it is
33290 68 6f 6c 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 holding.**
332a0 20 20 20 20 69 6e 20 61 20 70 61 72 74 69 63 75 in a particu
332b0 6c 61 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 lar [prepared st
332c0 61 74 65 6d 65 6e 74 5d 20 53 20 77 68 65 6e 20 atement] S when
332d0 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 either.**
332e0 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 [sqlite3_rese
332f0 74 28 53 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 t(S)] or [sqlite
33300 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 3_finalize(S)] i
33310 73 20 63 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 s called..*/.voi
33320 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 d *sqlite3_get_a
33330 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 uxdata(sqlite3_c
33340 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b ontext*, int N);
33350 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 .void sqlite3_se
33360 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 t_auxdata(sqlite
33370 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 3_context*, int
33380 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 N, void*, void (
33390 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a *)(void*));.../*
333a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
333b0 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 nstants Defining
333c0 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 Special Destruc
333d0 74 6f 72 20 42 65 68 61 76 69 6f 72 20 7b 48 31 tor Behavior {H1
333e0 30 32 38 30 7d 20 3c 53 33 30 31 30 30 3e 0a 2a 0280} <S30100>.*
333f0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 *.** These are s
33400 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f pecial values fo
33410 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 r the destructor
33420 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 that is passed
33430 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e in as the.** fin
33440 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 al argument to r
33450 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 outines like [sq
33460 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f lite3_result_blo
33470 62 28 29 5d 2e 20 20 49 66 20 74 68 65 20 64 65 b()]. If the de
33480 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 structor.** argu
33490 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 ment is SQLITE_S
334a0 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 TATIC, it means
334b0 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 that the content
334c0 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 pointer is cons
334d0 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c tant.** and will
334e0 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 never change.
334f0 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 It does not need
33500 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 to be destroyed
33510 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 . The.** SQLITE
33520 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 _TRANSIENT value
33530 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 means that the
33540 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b content will lik
33550 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a ely change in.**
33560 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 the near future
33570 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 and that SQLite
33580 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 should make its
33590 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 own private cop
335a0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 y of.** the cont
335b0 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 ent before retur
335c0 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ning..**.** The
335d0 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 typedef is neces
335e0 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f sary to work aro
335f0 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 und problems in
33600 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 certain.** C++ c
33610 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 ompilers. See t
33620 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a icket #2191..*/.
33630 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 typedef void (*s
33640 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f qlite3_destructo
33650 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a r_type)(void*);.
33660 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
33670 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c TATIC ((sql
33680 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f ite3_destructor_
33690 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 type)0).#define
336a0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 SQLITE_TRANSIENT
336b0 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 ((sqlite3_des
336c0 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 tructor_type)-1)
336d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
336e0 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 : Setting The Re
336f0 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 sult Of An SQL F
33700 75 6e 63 74 69 6f 6e 20 7b 48 31 36 34 30 30 7d unction {H16400}
33710 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S20200>.**.**
33720 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
33730 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78 re used by the x
33740 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 Func or xFinal c
33750 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a allbacks that.**
33760 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 implement SQL f
33770 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 unctions and agg
33780 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a regates. See.**
33790 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
337a0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 _function()] and
337b0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
337c0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a _function16()].*
337d0 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c * for additional
337e0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a information..**
337f0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 .** These functi
33800 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 ons work very mu
33810 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 ch like the [par
33820 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 ameter binding]
33830 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e family of.** fun
33840 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 ctions used to b
33850 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f ind values to ho
33860 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e st parameters in
33870 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
33880 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 ents..** Refer t
33890 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d o the [SQL param
338a0 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 eter] documentat
338b0 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e ion for addition
338c0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a al information..
338d0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
338e0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 3_result_blob()
338f0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 interface sets t
33900 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a he result from.*
33910 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e * an application
33920 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
33930 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 n to be the BLOB
33940 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 whose content i
33950 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 s pointed.** to
33960 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 by the second pa
33970 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 rameter and whic
33980 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e h is N bytes lon
33990 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 g where N is the
339a0 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 .** third parame
339b0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ter..**.** The s
339c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 qlite3_result_ze
339d0 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 roblob() interfa
339e0 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 ces set the resu
339f0 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 lt of.** the app
33a00 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
33a10 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
33a20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e a BLOB containin
33a30 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 g all zero.** by
33a40 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 tes and N bytes
33a50 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e in size, where N
33a60 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 is the value of
33a70 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
33a80 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 er..**.** The sq
33a90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 lite3_result_dou
33aa0 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 ble() interface
33ab0 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 sets the result
33ac0 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 from.** an appli
33ad0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
33ae0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 unction to be a
33af0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 floating point v
33b00 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a alue specified.*
33b10 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 * by its 2nd arg
33b20 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ument..**.** The
33b30 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
33b40 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 error() and sqli
33b50 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
33b60 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 16() functions.*
33b70 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c * cause the impl
33b80 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 emented SQL func
33b90 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e tion to throw an
33ba0 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53 exception..** S
33bb0 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 QLite uses the s
33bc0 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f tring pointed to
33bd0 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 by the.** 2nd p
33be0 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 arameter of sqli
33bf0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
33c00 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 () or sqlite3_re
33c10 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a sult_error16().*
33c20 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 * as the text of
33c30 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 an error messag
33c40 65 2e 20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 e. SQLite inter
33c50 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a prets the error.
33c60 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e ** message strin
33c70 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 g from sqlite3_r
33c80 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 esult_error() as
33c90 20 55 54 46 2d 38 2e 20 53 51 4c 69 74 65 0a 2a UTF-8. SQLite.*
33ca0 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 * interprets the
33cb0 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c string from sql
33cc0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
33cd0 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 r16() as UTF-16
33ce0 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 in native.** byt
33cf0 65 20 6f 72 64 65 72 2e 20 20 49 66 20 74 68 65 e order. If the
33d00 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
33d10 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 to sqlite3_resu
33d20 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 lt_error().** or
33d30 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
33d40 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 error16() is neg
33d50 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 ative then SQLit
33d60 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 e takes as the e
33d70 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 rror.** message
33d80 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f all text up thro
33d90 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 ugh the first ze
33da0 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a ro character..**
33db0 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 If the third pa
33dc0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
33dd0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
33de0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ) or.** sqlite3_
33df0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 result_error16()
33e00 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 is non-negative
33e10 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b then SQLite tak
33e20 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 es that many.**
33e30 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 bytes (not chara
33e40 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 cters) from the
33e50 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 2nd parameter as
33e60 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
33e70 67 65 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 ge..** The sqlit
33e80 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
33e90 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 ) and sqlite3_re
33ea0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a sult_error16().*
33eb0 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 * routines make
33ec0 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f a private copy o
33ed0 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 f the error mess
33ee0 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a age text before.
33ef0 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 ** they return.
33f00 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c Hence, the call
33f10 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e ing function can
33f20 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a deallocate or.*
33f30 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 * modify the tex
33f40 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74 t after they ret
33f50 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d urn without harm
33f60 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 ..** The sqlite3
33f70 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f _result_error_co
33f80 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 de() function ch
33f90 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 anges the error
33fa0 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 code.** returned
33fb0 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 by SQLite as a
33fc0 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 result of an err
33fd0 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e or in a function
33fe0 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a . By default,.*
33ff0 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 * the error code
34000 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 is SQLITE_ERROR
34010 2e 20 20 41 20 73 75 62 73 65 71 75 65 6e 74 20 . A subsequent
34020 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
34030 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a result_error().*
34040 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 * or sqlite3_res
34050 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 ult_error16() re
34060 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 sets the error c
34070 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 ode to SQLITE_ER
34080 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ROR..**.** The s
34090 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f qlite3_result_to
340a0 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 obig() interface
340b0 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 causes SQLite t
340c0 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 o throw an error
340d0 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 .** indicating t
340e0 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 hat a string or
340f0 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67 20 BLOB is to long
34100 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a to represent..**
34110 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
34120 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 result_nomem() i
34130 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 nterface causes
34140 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 SQLite to throw
34150 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 an error.** indi
34160 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 cating that a me
34170 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
34180 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 failed..**.** Th
34190 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
341a0 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 _int() interface
341b0 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e sets the return
341c0 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 value.** of the
341d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
341e0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f ined function to
341f0 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 be the 32-bit s
34200 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a igned integer.**
34210 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 value given in
34220 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 the 2nd argument
34230 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 ..** The sqlite3
34240 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 _result_int64()
34250 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 interface sets t
34260 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a he return value.
34270 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 ** of the applic
34280 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
34290 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 nction to be the
342a0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 64-bit signed i
342b0 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 nteger.** value
342c0 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 given in the 2nd
342d0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
342e0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 The sqlite3_res
342f0 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 ult_null() inter
34300 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 face sets the re
34310 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 turn value.** of
34320 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
34330 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
34340 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a n to be NULL..**
34350 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
34360 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 result_text(), s
34370 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
34380 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 xt16(),.** sqlit
34390 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
343a0 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 le(), and sqlite
343b0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 3_result_text16b
343c0 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a e() interfaces.*
343d0 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e * set the return
343e0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 value of the ap
343f0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
34400 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 d function to be
34410 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e .** a text strin
34420 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 g which is repre
34430 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c sented as UTF-8,
34440 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 UTF-16 native b
34450 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 yte order,.** UT
34460 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 F-16 little endi
34470 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 an, or UTF-16 bi
34480 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 g endian, respec
34490 74 69 76 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74 tively..** SQLit
344a0 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 e takes the text
344b0 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 result from the
344c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f application fro
344d0 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 m.** the 2nd par
344e0 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 ameter of the sq
344f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
34500 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a t* interfaces..*
34510 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 * If the 3rd par
34520 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
34530 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
34540 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a t* interfaces.**
34550 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 is negative, th
34560 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 en SQLite takes
34570 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d result text from
34580 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
34590 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 er.** through th
345a0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 e first zero cha
345b0 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 racter..** If th
345c0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 e 3rd parameter
345d0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 to the sqlite3_r
345e0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 esult_text* inte
345f0 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e rfaces.** is non
34600 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 -negative, then
34610 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e as many bytes (n
34620 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f ot characters) o
34630 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f f the text.** po
34640 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 inted to by the
34650 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 2nd parameter ar
34660 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 e taken as the a
34670 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
34680 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 ed.** function r
34690 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 esult..** If the
346a0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 4th parameter t
346b0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 o the sqlite3_re
346c0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 sult_text* inter
346d0 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 faces.** or sqli
346e0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 te3_result_blob
346f0 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f is a non-NULL po
34700 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 inter, then SQLi
34710 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a te calls that.**
34720 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 function as the
34730 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 destructor on t
34740 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 he text or BLOB
34750 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 result when it h
34760 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 as.** finished u
34770 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 sing that result
34780 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 ..** If the 4th
34790 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
347a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
347b0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 text* interfaces
347c0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 or.** sqlite3_r
347d0 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 esult_blob is th
347e0 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 e special consta
347f0 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 nt SQLITE_STATIC
34800 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a , then SQLite.**
34810 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 assumes that th
34820 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 e text or BLOB r
34830 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 esult is in cons
34840 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 tant space and d
34850 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 oes not.** copy
34860 74 68 65 20 69 74 20 6f 72 20 63 61 6c 6c 20 61 the it or call a
34870 20 64 65 73 74 72 75 63 74 6f 72 20 77 68 65 6e destructor when
34880 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 it has finished
34890 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 using that resu
348a0 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 lt..** If the 4t
348b0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
348c0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
348d0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 t_text* interfac
348e0 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 es.** or sqlite3
348f0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 _result_blob is
34900 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 the special cons
34910 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e tant SQLITE_TRAN
34920 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 SIENT.** then SQ
34930 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 Lite makes a cop
34940 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 y of the result
34950 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 into space obtai
34960 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d ned from.** from
34970 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
34980 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 ()] before it re
34990 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 turns..**.** The
349a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
349b0 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 value() interfac
349c0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c e sets the resul
349d0 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c t of.** the appl
349e0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
349f0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 function to be a
34a00 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e copy the.** [un
34a10 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
34a20 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
34a30 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 specified by the
34a40 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 2nd parameter.
34a50 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f The.** sqlite3_
34a60 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 result_value() i
34a70 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 nterface makes a
34a80 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 copy of the [sq
34a90 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 lite3_value].**
34aa0 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c so that the [sql
34ab0 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 ite3_value] spec
34ac0 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 ified in the par
34ad0 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 ameter may chang
34ae0 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c e or.** be deall
34af0 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c ocated after sql
34b00 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 ite3_result_valu
34b10 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 e() returns with
34b20 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 41 20 5b out harm..** A [
34b30 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
34b40 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
34b50 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 may always be us
34b60 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b ed where an.** [
34b70 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
34b80 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
34b90 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 t is required, s
34ba0 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 o either.** kind
34bb0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c of [sqlite3_val
34bc0 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 ue] object can b
34bd0 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73 e used with this
34be0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a interface..**.*
34bf0 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 * If these routi
34c00 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 nes are called f
34c10 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 rom within the d
34c20 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a ifferent thread.
34c30 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 ** than the one
34c40 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 containing the a
34c50 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
34c60 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 ed function that
34c70 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 received.** the
34c80 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 [sqlite3_contex
34c90 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 t] pointer, the
34ca0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 results are unde
34cb0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 fined..**.** INV
34cc0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
34cd0 48 31 36 34 30 33 7d 20 54 68 65 20 64 65 66 61 H16403} The defa
34ce0 75 6c 74 20 72 65 74 75 72 6e 20 76 61 6c 75 65 ult return value
34cf0 20 66 72 6f 6d 20 61 6e 79 20 53 51 4c 20 66 75 from any SQL fu
34d00 6e 63 74 69 6f 6e 20 69 73 20 4e 55 4c 4c 2e 0a nction is NULL..
34d10 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 36 7d 20 54 **.** {H16406} T
34d20 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 he [sqlite3_resu
34d30 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 lt_blob(C,V,N,D)
34d40 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e ] interface chan
34d50 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 ges the.**
34d60 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 return value
34d70 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 of function C t
34d80 6f 20 62 65 20 61 20 42 4c 4f 42 20 74 68 61 74 o be a BLOB that
34d90 20 69 73 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20 is N bytes.**
34da0 20 20 20 20 20 20 20 20 69 6e 20 6c 65 6e 67 74 in lengt
34db0 68 20 61 6e 64 20 77 69 74 68 20 63 6f 6e 74 65 h and with conte
34dc0 6e 74 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 nt pointed to by
34dd0 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 V..**.** {H1640
34de0 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 9} The [sqlite3_
34df0 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 43 2c result_double(C,
34e00 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 V)] interface ch
34e10 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 anges the.**
34e20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c return val
34e30 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 ue of function C
34e40 20 74 6f 20 62 65 20 74 68 65 20 66 6c 6f 61 74 to be the float
34e50 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 ing point value
34e60 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 32 V..**.** {H16412
34e70 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 } The [sqlite3_r
34e80 65 73 75 6c 74 5f 65 72 72 6f 72 28 43 2c 56 2c esult_error(C,V,
34e90 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 N)] interface ch
34ea0 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e anges the return
34eb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c .** val
34ec0 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 ue of function C
34ed0 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 to be an except
34ee0 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 ion with error c
34ef0 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ode.**
34f00 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61 [SQLITE_ERROR] a
34f10 6e 64 20 61 20 55 54 46 2d 38 20 65 72 72 6f 72 nd a UTF-8 error
34f20 20 6d 65 73 73 61 67 65 20 63 6f 70 69 65 64 20 message copied
34f30 66 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 68 65 from V up to the
34f40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 72 .** fir
34f50 73 74 20 7a 65 72 6f 20 62 79 74 65 20 6f 72 20 st zero byte or
34f60 75 6e 74 69 6c 20 4e 20 62 79 74 65 73 20 61 72 until N bytes ar
34f70 65 20 72 65 61 64 20 69 66 20 4e 20 69 73 20 70 e read if N is p
34f80 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b ositive..**.** {
34f90 48 31 36 34 31 35 7d 20 54 68 65 20 5b 73 71 6c H16415} The [sql
34fa0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
34fb0 72 31 36 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 r16(C,V,N)] inte
34fc0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 rface changes th
34fd0 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 e return.**
34fe0 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 66 75 value of fu
34ff0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 nction C to be a
35000 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 n exception with
35010 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 error code.**
35020 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f [SQLITE_
35030 45 52 52 4f 52 5d 20 61 6e 64 20 61 20 55 54 46 ERROR] and a UTF
35040 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 -16 native byte
35050 6f 72 64 65 72 20 65 72 72 6f 72 20 6d 65 73 73 order error mess
35060 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 age.**
35070 63 6f 70 69 65 64 20 66 72 6f 6d 20 56 20 75 70 copied from V up
35080 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 to the first ze
35090 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 72 ro terminator or
350a0 20 75 6e 74 69 6c 20 4e 20 62 79 74 65 73 0a 2a until N bytes.*
350b0 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20 72 * are r
350c0 65 61 64 20 69 66 20 4e 20 69 73 20 70 6f 73 69 ead if N is posi
350d0 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 tive..**.** {H16
350e0 34 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 418} The [sqlite
350f0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 3_result_error_t
35100 6f 6f 62 69 67 28 43 29 5d 20 69 6e 74 65 72 66 oobig(C)] interf
35110 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 ace changes the
35120 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 return.**
35130 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 value of the
35140 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 function C to be
35150 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 an exception wi
35160 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a th error code.**
35170 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 [SQLIT
35180 45 5f 54 4f 4f 42 49 47 5d 20 61 6e 64 20 61 6e E_TOOBIG] and an
35190 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 appropriate err
351a0 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a or message..**.*
351b0 2a 20 7b 48 31 36 34 32 31 7d 20 54 68 65 20 5b * {H16421} The [
351c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
351d0 72 72 6f 72 5f 6e 6f 6d 65 6d 28 43 29 5d 20 69 rror_nomem(C)] i
351e0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 nterface changes
351f0 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 the return.**
35200 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 value of
35210 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 the function C
35220 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 to be an excepti
35230 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f on with error co
35240 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b de.** [
35250 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 61 6e SQLITE_NOMEM] an
35260 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 d an appropriate
35270 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a error message..
35280 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32 34 7d 20 54 **.** {H16424} T
35290 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 he [sqlite3_resu
352a0 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 43 2c lt_error_code(C,
352b0 45 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 E)] interface ch
352c0 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e anges the return
352d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c .** val
352e0 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 ue of the functi
352f0 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 on C to be an ex
35300 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 ception with err
35310 6f 72 20 63 6f 64 65 20 45 2e 0a 2a 2a 20 20 20 or code E..**
35320 20 20 20 20 20 20 20 54 68 65 20 65 72 72 6f 72 The error
35330 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 69 73 message text is
35340 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a unchanged..**.*
35350 2a 20 7b 48 31 36 34 32 37 7d 20 54 68 65 20 5b * {H16427} The [
35360 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 sqlite3_result_i
35370 6e 74 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 nt(C,V)] interfa
35380 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a ce changes the.*
35390 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 * retur
353a0 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 n value of funct
353b0 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 ion C to be the
353c0 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72 20 76 32-bit integer v
353d0 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 alue V..**.** {H
353e0 31 36 34 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 16430} The [sqli
353f0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 te3_result_int64
35400 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 (C,V)] interface
35410 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 changes the.**
35420 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 return
35430 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f value of functio
35440 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 36 34 n C to be the 64
35450 2d 62 69 74 20 69 6e 74 65 67 65 72 20 76 61 6c -bit integer val
35460 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 ue V..**.** {H16
35470 34 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 433} The [sqlite
35480 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 43 29 3_result_null(C)
35490 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e ] interface chan
354a0 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 ges the.**
354b0 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 return value
354c0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 of function C t
354d0 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a o be NULL..**.**
354e0 20 7b 48 31 36 34 33 36 7d 20 54 68 65 20 5b 73 {H16436} The [s
354f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
35500 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 xt(C,V,N,D)] int
35510 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 erface changes t
35520 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 he.** r
35530 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 eturn value of f
35540 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 unction C to be
35550 74 68 65 20 55 54 46 2d 38 20 73 74 72 69 6e 67 the UTF-8 string
35560 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 56 20 75 .** V u
35570 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a p to the first z
35580 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61 ero if N is nega
35590 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 tive.**
355a0 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 or the first N
355b0 62 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20 bytes of V if N
355c0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e is non-negative.
355d0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 39 7d 20 .**.** {H16439}
355e0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 The [sqlite3_res
355f0 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e ult_text16(C,V,N
35600 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 ,D)] interface c
35610 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 hanges the.**
35620 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 return va
35630 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 lue of function
35640 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d C to be the UTF-
35650 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 16 native byte o
35660 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 rder.**
35670 20 73 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20 string V up to
35680 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 the first zero i
35690 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a f N is negative.
356a0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 ** or t
356b0 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 he first N bytes
356c0 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f of V if N is no
356d0 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a n-negative..**.*
356e0 2a 20 7b 48 31 36 34 34 32 7d 20 54 68 65 20 5b * {H16442} The [
356f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
35700 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 ext16be(C,V,N,D)
35710 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e ] interface chan
35720 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 ges the.**
35730 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 return value
35740 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 of function C t
35750 6f 20 62 65 20 74 68 65 20 55 54 46 2d 31 36 20 o be the UTF-16
35760 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 big-endian.**
35770 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 56 20 string V
35780 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 up to the first
35790 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 zero if N is neg
357a0 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 ative.**
357b0 20 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e or the first N
357c0 20 62 79 74 65 73 20 6f 72 20 56 20 69 66 20 4e bytes or V if N
357d0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 is non-negative
357e0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 35 7d ..**.** {H16445}
357f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 The [sqlite3_re
35800 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c sult_text16le(C,
35810 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 V,N,D)] interfac
35820 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a e changes the.**
35830 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e return
35840 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 value of functi
35850 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 on C to be the U
35860 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 TF-16 little-end
35870 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ian.**
35880 73 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 string V up to t
35890 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 he first zero if
358a0 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a N is negative.*
358b0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 * or th
358c0 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 e first N bytes
358d0 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e of V if N is non
358e0 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a -negative..**.**
358f0 20 7b 48 31 36 34 34 38 7d 20 54 68 65 20 5b 73 {H16448} The [s
35900 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 qlite3_result_va
35910 6c 75 65 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 lue(C,V)] interf
35920 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a ace changes the.
35930 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 ** retu
35940 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 rn value of func
35950 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 tion C to be the
35960 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 [unprotected sq
35970 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 lite3_value].**
35980 20 20 20 20 20 20 20 20 20 6f 62 6a 65 63 74 20 object
35990 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35 31 V..**.** {H16451
359a0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 } The [sqlite3_r
359b0 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 43 esult_zeroblob(C
359c0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 ,N)] interface c
359d0 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 hanges the.**
359e0 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 return va
359f0 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 lue of function
35a00 43 20 74 6f 20 62 65 20 61 6e 20 4e 2d 62 79 74 C to be an N-byt
35a10 65 20 42 4c 4f 42 20 6f 66 20 61 6c 6c 20 7a 65 e BLOB of all ze
35a20 72 6f 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 ros..**.** {H164
35a30 35 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 54} The [sqlite3
35a40 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 5d _result_error()]
35a50 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 and [sqlite3_re
35a60 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 5d 0a sult_error16()].
35a70 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 ** inte
35a80 72 66 61 63 65 73 20 6d 61 6b 65 20 61 20 63 6f rfaces make a co
35a90 70 79 20 6f 66 20 74 68 65 69 72 20 65 72 72 6f py of their erro
35aa0 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 r message string
35ab0 73 20 62 65 66 6f 72 65 0a 2a 2a 20 20 20 20 20 s before.**
35ac0 20 20 20 20 20 72 65 74 75 72 6e 69 6e 67 2e 0a returning..
35ad0 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35 37 7d 20 49 **.** {H16457} I
35ae0 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63 74 f the D destruct
35af0 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 or parameter to
35b00 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
35b10 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a blob(C,V,N,D)],.
35b20 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
35b30 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
35b40 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c (C,V,N,D)], [sql
35b50 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
35b60 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 16(C,V,N,D)],.**
35b70 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
35b80 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
35b90 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 be(C,V,N,D)], or
35ba0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
35bb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
35bc0 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 t16le(C,V,N,D)]
35bd0 69 73 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 20 is the constant
35be0 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 0a [SQLITE_STATIC].
35bf0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e ** then
35c00 20 6e 6f 20 64 65 73 74 72 75 63 74 6f 72 20 69 no destructor i
35c10 73 20 65 76 65 72 20 63 61 6c 6c 65 64 20 6f 6e s ever called on
35c20 20 74 68 65 20 70 6f 69 6e 74 65 72 20 56 20 61 the pointer V a
35c30 6e 64 20 53 51 4c 69 74 65 0a 2a 2a 20 20 20 20 nd SQLite.**
35c40 20 20 20 20 20 20 61 73 73 75 6d 65 73 20 74 68 assumes th
35c50 61 74 20 56 20 69 73 20 69 6d 6d 75 74 61 62 6c at V is immutabl
35c60 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 36 30 e..**.** {H16460
35c70 7d 20 49 66 20 74 68 65 20 44 20 64 65 73 74 72 } If the D destr
35c80 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20 uctor parameter
35c90 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 to [sqlite3_resu
35ca0 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 lt_blob(C,V,N,D)
35cb0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b ],.** [
35cc0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
35cd0 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b ext(C,V,N,D)], [
35ce0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
35cf0 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c ext16(C,V,N,D)],
35d00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
35d10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
35d20 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c t16be(C,V,N,D)],
35d30 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 or.**
35d40 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
35d50 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 text16le(C,V,N,D
35d60 29 5d 20 69 73 20 74 68 65 20 63 6f 6e 73 74 61 )] is the consta
35d70 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b nt.** [
35d80 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 SQLITE_TRANSIENT
35d90 5d 20 74 68 65 6e 20 74 68 65 20 69 6e 74 65 72 ] then the inter
35da0 66 61 63 65 73 20 6d 61 6b 65 73 20 61 20 63 6f faces makes a co
35db0 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 py of the.**
35dc0 20 20 20 20 20 20 63 6f 6e 74 65 6e 74 20 6f 66 content of
35dd0 20 56 20 61 6e 64 20 72 65 74 61 69 6e 73 20 74 V and retains t
35de0 68 65 20 63 6f 70 79 2e 0a 2a 2a 0a 2a 2a 20 7b he copy..**.** {
35df0 48 31 36 34 36 33 7d 20 49 66 20 74 68 65 20 44 H16463} If the D
35e00 20 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61 destructor para
35e10 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 meter to [sqlite
35e20 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 3_result_blob(C,
35e30 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 V,N,D)],.**
35e40 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 [sqlite3_re
35e50 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c sult_text(C,V,N,
35e60 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 D)], [sqlite3_re
35e70 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c sult_text16(C,V,
35e80 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 N,D)],.**
35e90 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 [sqlite3_resu
35ea0 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c lt_text16be(C,V,
35eb0 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 N,D)], or.**
35ec0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 [sqlite3_r
35ed0 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 esult_text16le(C
35ee0 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 73 6f 6d 65 ,V,N,D)] is some
35ef0 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 value other tha
35f00 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 n.** th
35f10 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c e constants [SQL
35f20 49 54 45 5f 53 54 41 54 49 43 5d 20 61 6e 64 20 ITE_STATIC] and
35f30 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e [SQLITE_TRANSIEN
35f40 54 5d 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 T] then.**
35f50 20 20 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 SQLite will
35f60 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 invoke the destr
35f70 75 63 74 6f 72 20 44 20 77 69 74 68 20 56 20 61 uctor D with V a
35f80 73 20 69 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d s its only argum
35f90 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ent.**
35fa0 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 when it has fini
35fb0 73 68 65 64 20 77 69 74 68 20 74 68 65 20 56 20 shed with the V
35fc0 76 61 6c 75 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 value..*/.void s
35fd0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
35fe0 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ob(sqlite3_conte
35ff0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a xt*, const void*
36000 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 , int, void(*)(v
36010 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c oid*));.void sql
36020 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 ite3_result_doub
36030 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 le(sqlite3_conte
36040 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f xt*, double);.vo
36050 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
36060 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f t_error(sqlite3_
36070 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
36080 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 char*, int);.voi
36090 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
360a0 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 _error16(sqlite3
360b0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 _context*, const
360c0 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f void*, int);.vo
360d0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
360e0 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 t_error_toobig(s
360f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
36100 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
36110 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 esult_error_nome
36120 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 m(sqlite3_contex
36130 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 t*);.void sqlite
36140 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 3_result_error_c
36150 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ode(sqlite3_cont
36160 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 ext*, int);.void
36170 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
36180 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 int(sqlite3_cont
36190 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 ext*, int);.void
361a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
361b0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f int64(sqlite3_co
361c0 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f ntext*, sqlite3_
361d0 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c int64);.void sql
361e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c ite3_result_null
361f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
36200 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 *);.void sqlite3
36210 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c _result_text(sql
36220 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 ite3_context*, c
36230 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c onst char*, int,
36240 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 void(*)(void*))
36250 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
36260 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c esult_text16(sql
36270 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 ite3_context*, c
36280 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c onst void*, int,
36290 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 void(*)(void*))
362a0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
362b0 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 esult_text16le(s
362c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
362d0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
362e0 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 t,void(*)(void*)
362f0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
36300 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 result_text16be(
36310 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
36320 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 , const void*, i
36330 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a nt,void(*)(void*
36340 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 ));.void sqlite3
36350 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 _result_value(sq
36360 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
36370 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
36380 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
36390 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 sult_zeroblob(sq
363a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
363b0 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 int n);../*.** C
363c0 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 API3REF: Define
363d0 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 New Collating Se
363e0 71 75 65 6e 63 65 73 20 7b 48 31 36 36 30 30 7d quences {H16600}
363f0 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S20300>.**.**
36400 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 These functions
36410 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 are used to add
36420 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 new collation se
36430 71 75 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a quences to the.*
36440 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
36450 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 ection] specifie
36460 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 d as the first a
36470 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 rgument..**.** T
36480 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e he name of the n
36490 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 ew collation seq
364a0 75 65 6e 63 65 20 69 73 20 73 70 65 63 69 66 69 uence is specifi
364b0 65 64 20 61 73 20 61 20 55 54 46 2d 38 20 73 74 ed as a UTF-8 st
364c0 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 ring.** for sqli
364d0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
364e0 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 tion() and sqlit
364f0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
36500 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 ion_v2().** and
36510 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 a UTF-16 string
36520 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 for sqlite3_crea
36530 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 te_collation16()
36540 2e 20 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a . In all cases.*
36550 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61 * the name is pa
36560 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f ssed as the seco
36570 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 nd function argu
36580 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ment..**.** The
36590 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d third argument m
365a0 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 ay be one of the
365b0 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 constants [SQLI
365c0 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 TE_UTF8],.** [SQ
365d0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 6f 72 LITE_UTF16LE] or
365e0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 [SQLITE_UTF16BE
365f0 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 ], indicating th
36600 61 74 20 74 68 65 20 75 73 65 72 2d 73 75 70 70 at the user-supp
36610 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 lied.** routine
36620 65 78 70 65 63 74 73 20 74 6f 20 62 65 20 70 61 expects to be pa
36630 73 73 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f ssed pointers to
36640 20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 strings encoded
36650 20 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a using UTF-8,.**
36660 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 UTF-16 little-e
36670 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 ndian, or UTF-16
36680 20 62 69 67 2d 65 6e 64 69 61 6e 2c 20 72 65 73 big-endian, res
36690 70 65 63 74 69 76 65 6c 79 2e 20 54 68 65 0a 2a pectively. The.*
366a0 2a 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 * third argument
366b0 20 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20 5b might also be [
366c0 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 SQLITE_UTF16_ALI
366d0 47 4e 45 44 5d 20 74 6f 20 69 6e 64 69 63 61 74 GNED] to indicat
366e0 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 72 6f e that.** the ro
366f0 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 70 6f utine expects po
36700 69 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 69 74 inters to 16-bit
36710 20 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 73 74 word aligned st
36720 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46 2d rings.** of UTF-
36730 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 16 in the native
36740 20 62 79 74 65 20 6f 72 64 65 72 20 6f 66 20 74 byte order of t
36750 68 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 he host computer
36760 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 ..**.** A pointe
36770 72 20 74 6f 20 74 68 65 20 75 73 65 72 20 73 75 r to the user su
36780 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d pplied routine m
36790 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 ust be passed as
367a0 20 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 the fifth.** ar
367b0 67 75 6d 65 6e 74 2e 20 20 49 66 20 69 74 20 69 gument. If it i
367c0 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 s NULL, this is
367d0 74 68 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65 the same as dele
367e0 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 ting the collati
367f0 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 on.** sequence (
36800 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 so that SQLite c
36810 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e annot call it an
36820 79 6d 6f 72 65 29 2e 0a 2a 2a 20 45 61 63 68 20 ymore)..** Each
36830 74 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63 61 time the applica
36840 74 69 6f 6e 20 73 75 70 70 6c 69 65 64 20 66 75 tion supplied fu
36850 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 nction is invoke
36860 64 2c 20 69 74 20 69 73 20 70 61 73 73 65 64 0a d, it is passed.
36870 2a 2a 20 61 73 20 69 74 73 20 66 69 72 73 74 20 ** as its first
36880 70 61 72 61 6d 65 74 65 72 20 61 20 63 6f 70 79 parameter a copy
36890 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 61 of the void* pa
368a0 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 ssed as the four
368b0 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 th argument.** t
368c0 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 o sqlite3_create
368d0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20 _collation() or
368e0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
368f0 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a ollation16()..**
36900 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e .** The remainin
36910 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 g arguments to t
36920 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 he application-s
36930 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 upplied routine
36940 61 72 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c are two strings,
36950 0a 2a 2a 20 65 61 63 68 20 72 65 70 72 65 73 65 .** each represe
36960 6e 74 65 64 20 62 79 20 61 20 28 6c 65 6e 67 74 nted by a (lengt
36970 68 2c 20 64 61 74 61 29 20 70 61 69 72 20 61 6e h, data) pair an
36980 64 20 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 d encoded in the
36990 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 encoding.** tha
369a0 74 20 77 61 73 20 70 61 73 73 65 64 20 61 73 20 t was passed as
369b0 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 the third argume
369c0 6e 74 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c nt when the coll
369d0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 ation sequence w
369e0 61 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 as.** registered
369f0 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20 61 70 70 . {END} The app
36a00 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 lication defined
36a10 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 collation routi
36a20 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 ne should.** ret
36a30 75 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 urn negative, ze
36a40 72 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69 ro or positive i
36a50 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69 f the first stri
36a60 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c ng is less than,
36a70 0a 2a 2a 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 .** equal to, or
36a80 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 greater than th
36a90 65 20 73 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e e second string.
36aa0 20 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d i.e. (STRING1 -
36ab0 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a STRING2)..**.**
36ac0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 The sqlite3_cre
36ad0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 ate_collation_v2
36ae0 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 () works like sq
36af0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
36b00 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 lation().** exce
36b10 70 74 20 74 68 61 74 20 69 74 20 74 61 6b 65 73 pt that it takes
36b20 20 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d 65 an extra argume
36b30 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 64 65 nt which is a de
36b40 73 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 structor for.**
36b50 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 the collation.
36b60 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 The destructor i
36b70 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 s called when th
36b80 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a e collation is.*
36b90 2a 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 * destroyed and
36ba0 69 73 20 70 61 73 73 65 64 20 61 20 63 6f 70 79 is passed a copy
36bb0 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 of the fourth p
36bc0 61 72 61 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 arameter void* p
36bd0 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 ointer.** of the
36be0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
36bf0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a collation_v2()..
36c00 2a 2a 20 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 ** Collations ar
36c10 65 20 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e e destroyed when
36c20 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 they are overri
36c30 64 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61 dden by later ca
36c40 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 63 6f lls to the.** co
36c50 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e llation creation
36c60 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 functions or wh
36c70 65 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 en the [database
36c80 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 connection] is
36c90 63 6c 6f 73 65 64 0a 2a 2a 20 75 73 69 6e 67 20 closed.** using
36ca0 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 [sqlite3_close()
36cb0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 ]..**.** INVARIA
36cc0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 NTS:.**.** {H166
36cd0 30 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 03} A successful
36ce0 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 call to the.**
36cf0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
36d00 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
36d10 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c on_v2(B,X,E,P,F,
36d20 44 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a D)] interface.**
36d30 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74 regist
36d40 65 72 73 20 66 75 6e 63 74 69 6f 6e 20 46 20 61 ers function F a
36d50 73 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e s the comparison
36d60 20 66 75 6e 63 74 69 6f 6e 20 75 73 65 64 20 74 function used t
36d70 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6d o.** im
36d80 70 6c 65 6d 65 6e 74 20 63 6f 6c 6c 61 74 69 6f plement collatio
36d90 6e 20 58 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 n X on the [data
36da0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
36db0 20 42 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 B for.**
36dc0 20 20 20 64 61 74 61 62 61 73 65 73 20 68 61 76 databases hav
36dd0 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20 45 2e 0a ing encoding E..
36de0 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 34 7d 20 53 **.** {H16604} S
36df0 51 4c 69 74 65 20 75 6e 64 65 72 73 74 61 6e 64 QLite understand
36e00 73 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 s the X paramete
36e10 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 r to.**
36e20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
36e30 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c _collation_v2(B,
36e40 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 61 73 20 61 X,E,P,F,D)] as a
36e50 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
36e60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 .** UTF
36e70 2d 38 20 73 74 72 69 6e 67 20 69 6e 20 77 68 69 -8 string in whi
36e80 63 68 20 63 61 73 65 20 69 73 20 69 67 6e 6f 72 ch case is ignor
36e90 65 64 20 66 6f 72 20 41 53 43 49 49 20 63 68 61 ed for ASCII cha
36ea0 72 61 63 74 65 72 73 20 61 6e 64 0a 2a 2a 20 20 racters and.**
36eb0 20 20 20 20 20 20 20 20 69 73 20 73 69 67 6e 69 is signi
36ec0 66 69 63 61 6e 74 20 66 6f 72 20 6e 6f 6e 2d 41 ficant for non-A
36ed0 53 43 49 49 20 63 68 61 72 61 63 74 65 72 73 2e SCII characters.
36ee0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 36 7d 20 .**.** {H16606}
36ef0 53 75 63 63 65 73 73 69 76 65 20 63 61 6c 6c 73 Successive calls
36f00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 to [sqlite3_cre
36f10 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 ate_collation_v2
36f20 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a (B,X,E,P,F,D)].*
36f30 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20 * with
36f40 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 73 20 the same values
36f50 66 6f 72 20 42 2c 20 58 2c 20 61 6e 64 20 45 2c for B, X, and E,
36f60 20 6f 76 65 72 72 69 64 65 20 70 72 69 6f 72 20 override prior
36f70 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 values.**
36f80 20 20 20 6f 66 20 50 2c 20 46 2c 20 61 6e 64 20 of P, F, and
36f90 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 39 D..**.** {H16609
36fa0 7d 20 49 66 20 74 68 65 20 64 65 73 74 72 75 63 } If the destruc
36fb0 74 6f 72 20 44 20 69 6e 20 5b 73 71 6c 69 74 65 tor D in [sqlite
36fc0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
36fd0 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c on_v2(B,X,E,P,F,
36fe0 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 D)].**
36ff0 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e is not NULL then
37000 20 69 74 20 69 73 20 63 61 6c 6c 65 64 20 77 69 it is called wi
37010 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 th argument P wh
37020 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 en the.**
37030 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e collating fun
37040 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 ction is dropped
37050 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a by SQLite..**.*
37060 2a 20 7b 48 31 36 36 31 32 7d 20 41 20 63 6f 6c * {H16612} A col
37070 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 lating function
37080 69 73 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20 is dropped when
37090 69 74 20 69 73 20 6f 76 65 72 6c 6f 61 64 65 64 it is overloaded
370a0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 35 7d ..**.** {H16615}
370b0 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e A collating fun
370c0 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 ction is dropped
370d0 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 when the databa
370e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
370f0 20 20 20 20 20 20 20 20 20 20 69 73 20 63 6c 6f is clo
37100 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 sed using [sqlit
37110 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a e3_close()]..**.
37120 2a 2a 20 7b 48 31 36 36 31 38 7d 20 54 68 65 20 ** {H16618} The
37130 70 6f 69 6e 74 65 72 20 50 20 69 6e 20 5b 73 71 pointer P in [sq
37140 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
37150 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c lation_v2(B,X,E,
37160 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 P,F,D)].**
37170 20 20 20 20 69 73 20 70 61 73 73 65 64 20 74 68 is passed th
37180 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 rough as the fir
37190 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
371a0 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a the comparison.*
371b0 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 * funct
371c0 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c 20 73 75 ion F for all su
371d0 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 bsequent invocat
371e0 69 6f 6e 73 20 6f 66 20 46 2e 0a 2a 2a 0a 2a 2a ions of F..**.**
371f0 20 7b 48 31 36 36 32 31 7d 20 41 20 63 61 6c 6c {H16621} A call
37200 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 to [sqlite3_cre
37210 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c ate_collation(B,
37220 58 2c 45 2c 50 2c 46 29 5d 20 69 73 20 65 78 61 X,E,P,F)] is exa
37230 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 ctly.**
37240 20 74 68 65 20 73 61 6d 65 20 61 73 20 61 20 63 the same as a c
37250 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
37260 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
37270 5f 76 32 28 29 5d 20 77 69 74 68 0a 2a 2a 20 20 _v2()] with.**
37280 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 the same
37290 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 parameters and
372a0 61 20 4e 55 4c 4c 20 64 65 73 74 72 75 63 74 6f a NULL destructo
372b0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 34 r..**.** {H16624
372c0 7d 20 46 6f 6c 6c 6f 77 69 6e 67 20 61 20 5b 73 } Following a [s
372d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
372e0 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 llation_v2(B,X,E
372f0 2c 50 2c 46 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 ,P,F,D)],.**
37300 20 20 20 20 20 20 53 51 4c 69 74 65 20 75 73 65 SQLite use
37310 73 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e s the comparison
37320 20 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 function F for
37330 61 6c 6c 20 74 65 78 74 20 63 6f 6d 70 61 72 69 all text compari
37340 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 son.**
37350 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 operations on th
37360 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
37370 65 63 74 69 6f 6e 5d 20 42 20 6f 6e 20 74 65 78 ection] B on tex
37380 74 20 76 61 6c 75 65 73 20 74 68 61 74 0a 2a 2a t values that.**
37390 20 20 20 20 20 20 20 20 20 20 75 73 65 20 74 68 use th
373a0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 e collating sequ
373b0 65 6e 63 65 20 6e 61 6d 65 64 20 58 2e 0a 2a 2a ence named X..**
373c0 0a 2a 2a 20 7b 48 31 36 36 32 37 7d 20 54 68 65 .** {H16627} The
373d0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
373e0 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 42 2c 58 _collation16(B,X
373f0 2c 45 2c 50 2c 46 29 5d 20 77 6f 72 6b 73 20 74 ,E,P,F)] works t
37400 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 he same.**
37410 20 20 20 20 61 73 20 5b 73 71 6c 69 74 65 33 5f as [sqlite3_
37420 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
37430 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 65 78 63 (B,X,E,P,F)] exc
37440 65 70 74 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 ept that the.**
37450 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 collati
37460 6f 6e 20 6e 61 6d 65 20 58 20 69 73 20 75 6e 64 on name X is und
37470 65 72 73 74 6f 6f 64 20 61 73 20 55 54 46 2d 31 erstood as UTF-1
37480 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 6 in native byte
37490 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 order.**
374a0 20 20 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54 instead of UT
374b0 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 F-8..**.** {H166
374c0 33 30 7d 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 30} When multipl
374d0 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e e comparison fun
374e0 63 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c ctions are avail
374f0 61 62 6c 65 20 66 6f 72 20 74 68 65 20 73 61 6d able for the sam
37500 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f e.** co
37510 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 llating sequence
37520 2c 20 53 51 4c 69 74 65 20 63 68 6f 6f 73 65 73 , SQLite chooses
37530 20 74 68 65 20 6f 6e 65 20 77 68 6f 73 65 20 74 the one whose t
37540 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 ext encoding.**
37550 20 20 20 20 20 20 20 20 20 72 65 71 75 69 72 65 require
37560 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 s the least amou
37570 6e 74 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e nt of conversion
37580 20 66 72 6f 6d 20 74 68 65 20 64 65 66 61 75 6c from the defaul
37590 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65 t.** te
375a0 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 xt encoding of t
375b0 68 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a he database..*/.
375c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 int sqlite3_crea
375d0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 te_collation(.
375e0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e sqlite3*, . con
375f0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
37600 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c . int eTextRep,
37610 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 . void*,. int
37620 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 (*xCompare)(void
37630 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 *,int,const void
37640 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 *,int,const void
37650 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 *).);.int sqlite
37660 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
37670 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 on_v2(. sqlite3
37680 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 *, . const char
37690 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 *zName, . int
376a0 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 eTextRep, . voi
376b0 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 d*,. int(*xComp
376c0 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 are)(void*,int,c
376d0 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 onst void*,int,c
376e0 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 onst void*),. v
376f0 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 oid(*xDestroy)(v
37700 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c oid*).);.int sql
37710 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
37720 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 ation16(. sqlit
37730 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f e3*, . const vo
37740 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 id *zName,. int
37750 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f eTextRep, . vo
37760 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d id*,. int(*xCom
37770 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c pare)(void*,int,
37780 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c const void*,int,
37790 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a const void*).);.
377a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
377b0 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 Collation Neede
377c0 64 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 36 d Callbacks {H16
377d0 37 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 700} <S20300>.**
377e0 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 68 61 76 .** To avoid hav
377f0 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 ing to register
37800 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 all collation se
37810 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 quences before a
37820 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e database.** can
37830 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 be used, a sing
37840 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 le callback func
37850 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 tion may be regi
37860 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a stered with the.
37870 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
37880 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 63 nection] to be c
37890 61 6c 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61 alled whenever a
378a0 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c n undefined coll
378b0 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 ation.** sequenc
378c0 65 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a e is required..*
378d0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 75 6e 63 *.** If the func
378e0 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 tion is register
378f0 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c ed using the sql
37900 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
37910 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 eeded() API,.**
37920 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 then it is passe
37930 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 d the names of u
37940 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 ndefined collati
37950 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 on sequences as
37960 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 strings.** encod
37970 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 7b 48 31 ed in UTF-8. {H1
37980 36 37 30 33 7d 20 49 66 20 73 71 6c 69 74 65 33 6703} If sqlite3
37990 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 _collation_neede
379a0 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a d16() is used,.*
379b0 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 * the names are
379c0 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 passed as UTF-16
379d0 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 in machine nati
379e0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a ve byte order..*
379f0 2a 20 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 * A call to eith
37a00 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c er function repl
37a10 61 63 65 73 20 61 6e 79 20 65 78 69 73 74 69 6e aces any existin
37a20 67 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a g callback..**.*
37a30 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 * When the callb
37a40 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 ack is invoked,
37a50 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
37a60 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 nt passed is a c
37a70 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 opy.** of the se
37a80 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
37a90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 sqlite3_collati
37aa0 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a on_needed() or.*
37ab0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 * sqlite3_collat
37ac0 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 ion_needed16().
37ad0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 The second argu
37ae0 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 ment is the data
37af0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 base.** connecti
37b00 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 on. The third a
37b10 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f rgument is one o
37b20 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c f [SQLITE_UTF8],
37b30 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 [SQLITE_UTF16BE
37b40 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 ],.** or [SQLITE
37b50 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 _UTF16LE], indic
37b60 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 ating the most d
37b70 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 esirable form of
37b80 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a the collation.*
37b90 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 * sequence funct
37ba0 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 ion required. T
37bb0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
37bc0 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 ter is the name
37bd0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 of the.** requir
37be0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 ed collation seq
37bf0 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 uence..**.** The
37c00 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
37c10 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 on should regist
37c20 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63 er the desired c
37c30 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a ollation using.*
37c40 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 * [sqlite3_creat
37c50 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 e_collation()],
37c60 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
37c70 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 collation16()],
37c80 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 or.** [sqlite3_c
37c90 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f reate_collation_
37ca0 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 v2()]..**.** INV
37cb0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b ARIANTS:.**.** {
37cc0 48 31 36 37 30 32 7d 20 41 20 73 75 63 63 65 73 H16702} A succes
37cd0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 sful call to [sq
37ce0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
37cf0 6e 65 65 64 65 64 28 44 2c 50 2c 46 29 5d 0a 2a needed(D,P,F)].*
37d00 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 * or [s
37d10 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
37d20 5f 6e 65 65 64 65 64 31 36 28 44 2c 50 2c 46 29 _needed16(D,P,F)
37d30 5d 20 63 61 75 73 65 73 0a 2a 2a 20 20 20 20 20 ] causes.**
37d40 20 20 20 20 20 74 68 65 20 5b 64 61 74 61 62 61 the [databa
37d50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
37d60 20 74 6f 20 69 6e 76 6f 6b 65 20 63 61 6c 6c 62 to invoke callb
37d70 61 63 6b 20 46 20 77 69 74 68 20 66 69 72 73 74 ack F with first
37d80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 .** par
37d90 61 6d 65 74 65 72 20 50 20 77 68 65 6e 65 76 65 ameter P wheneve
37da0 72 20 69 74 20 6e 65 65 64 73 20 61 20 63 6f 6d r it needs a com
37db0 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e parison function
37dc0 20 66 6f 72 20 61 0a 2a 2a 20 20 20 20 20 20 20 for a.**
37dd0 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 collating seq
37de0 75 65 6e 63 65 20 74 68 61 74 20 69 74 20 64 6f uence that it do
37df0 65 73 20 6e 6f 74 20 6b 6e 6f 77 20 61 62 6f 75 es not know abou
37e00 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 34 t..**.** {H16704
37e10 7d 20 45 61 63 68 20 73 75 63 63 65 73 73 66 75 } Each successfu
37e20 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 l call to [sqlit
37e30 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 e3_collation_nee
37e40 64 65 64 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 ded()] or.**
37e50 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 [sqlite3_c
37e60 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 ollation_needed1
37e70 36 28 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74 6()] overrides t
37e80 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 67 69 he callback regi
37e90 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 stered.**
37ea0 20 20 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b on the same [
37eb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
37ec0 69 6f 6e 5d 20 62 79 20 70 72 69 6f 72 20 63 61 ion] by prior ca
37ed0 6c 6c 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a lls to either.**
37ee0 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 interf
37ef0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 ace..**.** {H167
37f00 30 36 7d 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 06} The name of
37f10 74 68 65 20 72 65 71 75 65 73 74 65 64 20 63 6f the requested co
37f20 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e llating function
37f30 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 0a 2a passed in the.*
37f40 2a 20 20 20 20 20 20 20 20 20 20 34 74 68 20 70 * 4th p
37f50 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
37f60 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 20 55 callback is in U
37f70 54 46 2d 38 20 69 66 20 74 68 65 20 63 61 6c 6c TF-8 if the call
37f80 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 back.**
37f90 20 77 61 73 20 72 65 67 69 73 74 65 72 65 64 20 was registered
37fa0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 using [sqlite3_c
37fb0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 ollation_needed(
37fc0 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 )] and.**
37fd0 20 20 20 69 73 20 69 6e 20 55 54 46 2d 31 36 20 is in UTF-16
37fe0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
37ff0 72 20 69 66 20 74 68 65 20 63 61 6c 6c 62 61 63 r if the callbac
38000 6b 20 77 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 k was.**
38010 20 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 registered usi
38020 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c ng [sqlite3_coll
38030 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 ation_needed16()
38040 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 ]..*/.int sqlite
38050 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 3_collation_need
38060 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 ed(. sqlite3*,
38070 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 . void*, . voi
38080 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 d(*)(void*,sqlit
38090 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 e3*,int eTextRep
380a0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b ,const char*).);
380b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c .int sqlite3_col
380c0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 lation_needed16(
380d0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 . sqlite3*, .
380e0 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 void*,. void(*)
380f0 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c (void*,sqlite3*,
38100 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e int eTextRep,con
38110 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a st void*).);../*
38120 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 .** Specify the
38130 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 key for an encry
38140 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 pted database.
38150 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f This routine sho
38160 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 uld be.** called
38170 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c right after sql
38180 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a ite3_open()..**.
38190 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 ** The code to i
381a0 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 mplement this AP
381b0 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 I is not availab
381c0 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 le in the public
381d0 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 release.** of S
381e0 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 QLite..*/.int sq
381f0 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c lite3_key(. sql
38200 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
38210 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 /* D
38220 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 atabase to be re
38230 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 keyed */. const
38240 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 void *pKey, int
38250 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 nKey /* The
38260 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a key */.);../*.*
38270 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 * Change the key
38280 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 on an open data
38290 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 base. If the cu
382a0 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 rrent database i
382b0 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 s not.** encrypt
382c0 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 ed, this routine
382d0 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 will encrypt it
382e0 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 . If pNew==0 or
382f0 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a nNew==0, the.**
38300 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63 database is dec
38310 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 rypted..**.** Th
38320 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d e code to implem
38330 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 ent this API is
38340 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e not available in
38350 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 the public rele
38360 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 ase.** of SQLite
38370 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
38380 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 _rekey(. sqlite
38390 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
383a0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
383b0 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 base to be rekey
383c0 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f ed */. const vo
383d0 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b id *pKey, int nK
383e0 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 ey /* The ne
383f0 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a w key */.);../*.
38400 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 ** CAPI3REF: Sus
38410 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 pend Execution F
38420 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 20 or A Short Time
38430 7b 48 31 30 35 33 30 7d 20 3c 53 34 30 34 31 30 {H10530} <S40410
38440 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 >.**.** The sqli
38450 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 te3_sleep() func
38460 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 tion causes the
38470 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 current thread t
38480 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 o suspend execut
38490 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 ion.** for at le
384a0 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 ast a number of
384b0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 milliseconds spe
384c0 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 cified in its pa
384d0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 rameter..**.** I
384e0 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 f the operating
384f0 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 system does not
38500 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 support sleep re
38510 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d quests with.** m
38520 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 illisecond time
38530 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e resolution, then
38540 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 the time will b
38550 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a e rounded up to.
38560 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 ** the nearest s
38570 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 econd. The numbe
38580 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 r of millisecond
38590 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 s of sleep actua
385a0 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 lly.** requested
385b0 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 from the operat
385c0 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 ing system is re
385d0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 turned..**.** SQ
385e0 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 Lite implements
385f0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 this interface b
38600 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 y calling the xS
38610 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 leep().** method
38620 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 of the default
38630 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
38640 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 ject..**.** INVA
38650 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
38660 31 30 35 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 10533} The [sqli
38670 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d 20 69 6e te3_sleep(M)] in
38680 74 65 72 66 61 63 65 20 69 6e 76 6f 6b 65 73 20 terface invokes
38690 74 68 65 20 78 53 6c 65 65 70 0a 2a 2a 20 20 20 the xSleep.**
386a0 20 20 20 20 20 20 20 6d 65 74 68 6f 64 20 6f 66 method of
386b0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 the default [sq
386c0 6c 69 74 65 33 5f 76 66 73 7c 56 46 53 5d 20 69 lite3_vfs|VFS] i
386d0 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 20 20 n order to.**
386e0 20 20 20 20 20 20 20 73 75 73 70 65 6e 64 20 65 suspend e
386f0 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 xecution of the
38700 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 66 current thread f
38710 6f 72 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 20 or at least.**
38720 20 20 20 20 20 20 20 20 4d 20 6d 69 6c 6c 69 73 M millis
38730 65 63 6f 6e 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 econds..**.** {H
38740 31 30 35 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 10536} The [sqli
38750 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d 20 69 6e te3_sleep(M)] in
38760 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
38770 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a the number of.**
38780 20 20 20 20 20 20 20 20 20 20 6d 69 6c 6c 69 73 millis
38790 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 econds of sleep
387a0 61 63 74 75 61 6c 6c 79 20 72 65 71 75 65 73 74 actually request
387b0 65 64 20 6f 66 20 74 68 65 20 6f 70 65 72 61 74 ed of the operat
387c0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ing.**
387d0 73 79 73 74 65 6d 2c 20 77 68 69 63 68 20 6d 69 system, which mi
387e0 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 ght be larger th
387f0 61 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 an the parameter
38800 20 4d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 M..*/.int sqlit
38810 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a e3_sleep(int);..
38820 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
38830 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 Name Of The Fold
38840 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f er Holding Tempo
38850 72 61 72 79 20 46 69 6c 65 73 20 7b 48 31 30 33 rary Files {H103
38860 31 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 10} <S20000>.**.
38870 2a 2a 20 49 66 20 74 68 69 73 20 67 6c 6f 62 61 ** If this globa
38880 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 l variable is ma
38890 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 de to point to a
388a0 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 string which is
388b0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 .** the name of
388c0 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e a folder (a.k.a.
388d0 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 directory), the
388e0 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 n all temporary
388f0 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 files.** created
38900 20 62 79 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 by SQLite will
38910 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 be placed in tha
38920 74 20 64 69 72 65 63 74 6f 72 79 2e 20 20 49 66 t directory. If
38930 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a this variable.*
38940 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e * is a NULL poin
38950 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 ter, then SQLite
38960 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 performs a sear
38970 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 ch for an approp
38980 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 riate.** tempora
38990 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 ry file director
389a0 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e y..**.** It is n
389b0 6f 74 20 73 61 66 65 20 74 6f 20 6d 6f 64 69 66 ot safe to modif
389c0 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 y this variable
389d0 6f 6e 63 65 20 61 20 5b 64 61 74 61 62 61 73 65 once a [database
389e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 connection].**
389f0 68 61 73 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e has been opened.
38a00 20 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 It is intended
38a10 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 that this varia
38a20 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a ble be set once.
38a30 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 ** as part of pr
38a40 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 ocess initializa
38a50 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 tion and before
38a60 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 any SQLite inter
38a70 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 face.** routines
38a80 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 20 have been call
38a90 61 6e 64 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 and remain uncha
38aa0 6e 67 65 64 20 74 68 65 72 65 61 66 74 65 72 2e nged thereafter.
38ab0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 .*/.SQLITE_EXTER
38ac0 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f N char *sqlite3_
38ad0 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a temp_directory;.
38ae0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
38af0 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 Test For Auto-C
38b00 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b 48 31 32 39 ommit Mode {H129
38b10 33 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 30} <S60200>.**
38b20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 KEYWORDS: {autoc
38b30 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a ommit mode}.**.*
38b40 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 * The sqlite3_ge
38b50 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 t_autocommit() i
38b60 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
38b70 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 non-zero or.**
38b80 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 zero if the give
38b90 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 n database conne
38ba0 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e ction is or is n
38bb0 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 ot in autocommit
38bc0 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 mode,.** respec
38bd0 74 69 76 65 6c 79 2e 20 20 41 75 74 6f 63 6f 6d tively. Autocom
38be0 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 mit mode is on b
38bf0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 41 75 y default..** Au
38c00 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 tocommit mode is
38c10 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b disabled by a [
38c20 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 BEGIN] statement
38c30 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 ..** Autocommit
38c40 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c mode is re-enabl
38c50 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d ed by a [COMMIT]
38c60 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a or [ROLLBACK]..
38c70 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e **.** If certain
38c80 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 kinds of errors
38c90 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74 occur on a stat
38ca0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d ement within a m
38cb0 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a ulti-statement.*
38cc0 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 * transaction (e
38cd0 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 rrors including
38ce0 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b [SQLITE_FULL], [
38cf0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a SQLITE_IOERR],.*
38d00 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d * [SQLITE_NOMEM]
38d10 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c , [SQLITE_BUSY],
38d20 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 and [SQLITE_INT
38d30 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68 ERRUPT]) then th
38d40 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e e.** transaction
38d50 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 might be rolled
38d60 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 back automatica
38d70 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 lly. The only w
38d80 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 ay to.** find ou
38d90 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74 65 t whether SQLite
38da0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 automatically r
38db0 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74 olled back the t
38dc0 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72 ransaction after
38dd0 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20 .** an error is
38de0 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63 to use this func
38df0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 tion..**.** INVA
38e00 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 RIANTS:.**.** {H
38e10 31 32 39 33 31 7d 20 54 68 65 20 5b 73 71 6c 69 12931} The [sqli
38e20 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d te3_get_autocomm
38e30 69 74 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65 it(D)] interface
38e40 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 returns non-zer
38e50 6f 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 o or.**
38e60 20 7a 65 72 6f 20 69 66 20 74 68 65 20 5b 64 61 zero if the [da
38e70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
38e80 6e 5d 20 44 20 69 73 20 6f 72 20 69 73 20 6e 6f n] D is or is no
38e90 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 0a t in autocommit.
38ea0 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 64 65 ** mode
38eb0 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a , respectively..
38ec0 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33 32 7d 20 41 **.** {H12932} A
38ed0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 utocommit mode i
38ee0 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e s on by default.
38ef0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33 33 7d 20 .**.** {H12933}
38f00 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 Autocommit mode
38f10 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 is disabled by a
38f20 20 73 75 63 63 65 73 73 66 75 6c 20 5b 42 45 47 successful [BEG
38f30 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a IN] statement..*
38f40 2a 0a 2a 2a 20 7b 48 31 32 39 33 34 7d 20 41 75 *.** {H12934} Au
38f50 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 tocommit mode is
38f60 20 65 6e 61 62 6c 65 64 20 62 79 20 61 20 73 75 enabled by a su
38f70 63 63 65 73 73 66 75 6c 20 5b 43 4f 4d 4d 49 54 ccessful [COMMIT
38f80 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 0a ] or [ROLLBACK].
38f90 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 61 74 ** stat
38fa0 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 ement..**.** ASS
38fb0 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 UMPTIONS:.**.**
38fc0 7b 41 31 32 39 33 36 7d 20 49 66 20 61 6e 6f 74 {A12936} If anot
38fd0 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 her thread chang
38fe0 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 es the autocommi
38ff0 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 t status of the
39000 64 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 20 20 database.**
39010 20 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 connection
39020 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 while this routi
39030 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 ne is running, t
39040 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 hen the return v
39050 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 alue.**
39060 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
39070 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 /.int sqlite3_ge
39080 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c t_autocommit(sql
39090 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ite3*);../*.** C
390a0 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 API3REF: Find Th
390b0 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c e Database Handl
390c0 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 e Of A Prepared
390d0 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 31 32 Statement {H1312
390e0 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a 0} <S60600>.**.*
390f0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 * The sqlite3_db
39100 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 _handle interfac
39110 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64 e returns the [d
39120 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
39130 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f on] handle.** to
39140 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 72 which a [prepar
39150 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 ed statement] be
39160 6c 6f 6e 67 73 2e 20 20 54 68 65 20 64 61 74 61 longs. The data
39170 62 61 73 65 20 68 61 6e 64 6c 65 20 72 65 74 75 base handle retu
39180 72 6e 65 64 20 62 79 0a 2a 2a 20 73 71 6c 69 74 rned by.** sqlit
39190 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 e3_db_handle is
391a0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
391b0 65 20 68 61 6e 64 6c 65 20 74 68 61 74 20 77 61 e handle that wa
391c0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 s the first argu
391d0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b ment.** to the [
391e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
391f0 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 v2()] call (or i
39200 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 61 ts variants) tha
39210 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a t was used to.**
39220 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74 create the stat
39230 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 ement in the fir
39240 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 st place..**.**
39250 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a INVARIANTS:.**.*
39260 2a 20 7b 48 31 33 31 32 33 7d 20 54 68 65 20 5b * {H13123} The [
39270 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c sqlite3_db_handl
39280 65 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 e(S)] interface
39290 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
392a0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f r.** to
392b0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
392c0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f 63 onnection] assoc
392d0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 0a 2a iated with the.*
392e0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 * [prep
392f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
39300 53 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 S..*/.sqlite3 *s
39310 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 qlite3_db_handle
39320 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b (sqlite3_stmt*);
39330 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
39340 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20 : Find the next
39350 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
39360 6e 74 20 7b 48 31 33 31 34 30 7d 20 3c 53 36 30 nt {H13140} <S60
39370 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 600>.**.** This
39380 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
39390 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 s a pointer to t
393a0 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 he next [prepare
393b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 d statement] aft
393c0 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f er.** pStmt asso
393d0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 ciated with the
393e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
393f0 74 69 6f 6e 5d 20 70 44 62 2e 20 20 49 66 20 70 tion] pDb. If p
39400 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 Stmt is NULL.**
39410 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66 then this interf
39420 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f ace returns a po
39430 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72 inter to the fir
39440 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 st prepared stat
39450 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 ement.** associa
39460 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74 ted with the dat
39470 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
39480 20 70 44 62 2e 20 20 49 66 20 6e 6f 20 70 72 65 pDb. If no pre
39490 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a pared statement.
394a0 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68 65 ** satisfies the
394b0 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 conditions of t
394c0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 his routine, it
394d0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a returns NULL..**
394e0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
394f0 2a 2a 0a 2a 2a 20 7b 48 31 33 31 34 33 7d 20 49 **.** {H13143} I
39500 66 20 44 20 69 73 20 61 20 5b 64 61 74 61 62 61 f D is a [databa
39510 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 se connection] t
39520 68 61 74 20 68 6f 6c 64 73 20 6f 6e 65 20 6f 72 hat holds one or
39530 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 more.**
39540 20 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 5b 70 unfinalized [p
39550 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
39560 74 73 5d 20 61 6e 64 20 53 20 69 73 20 61 20 4e ts] and S is a N
39570 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 0a 2a 2a 20 ULL pointer,.**
39580 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 then [s
39590 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 qlite3_next_stmt
395a0 28 44 2c 20 53 29 5d 20 72 6f 75 74 69 6e 65 20 (D, S)] routine
395b0 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 61 20 70 shall return a p
395c0 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 ointer.**
395d0 20 20 20 74 6f 20 6f 6e 65 20 6f 66 20 74 68 65 to one of the
395e0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
395f0 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 ents associated
39600 77 69 74 68 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 with D..**.** {H
39610 31 33 31 34 36 7d 20 49 66 20 44 20 69 73 20 61 13146} If D is a
39620 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
39630 63 74 69 6f 6e 5d 20 74 68 61 74 20 68 6f 6c 64 ction] that hold
39640 73 20 6e 6f 20 75 6e 66 69 6e 61 6c 69 7a 65 64 s no unfinalized
39650 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 .** [pr
39660 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
39670 73 5d 20 61 6e 64 20 53 20 69 73 20 61 20 4e 55 s] and S is a NU
39680 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e LL pointer, then
39690 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 .** [sq
396a0 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 lite3_next_stmt(
396b0 44 2c 20 53 29 5d 20 72 6f 75 74 69 6e 65 20 73 D, S)] routine s
396c0 68 61 6c 6c 20 72 65 74 75 72 6e 20 61 20 4e 55 hall return a NU
396d0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
396e0 2a 20 7b 48 31 33 31 34 39 7d 20 49 66 20 53 20 * {H13149} If S
396f0 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 is a [prepared s
39700 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 74 68 65 tatement] in the
39710 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
39720 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 ction] D.**
39730 20 20 20 20 20 61 6e 64 20 53 20 69 73 20 6e 6f and S is no
39740 74 20 74 68 65 20 6c 61 73 74 20 70 72 65 70 61 t the last prepa
39750 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 6e red statement in
39760 20 44 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 D, then.**
39770 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6e 65 [sqlite3_ne
39780 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20 72 xt_stmt(D, S)] r
39790 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 outine shall ret
397a0 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a urn a pointer.**
397b0 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 to the
397c0 20 6e 65 78 74 20 70 72 65 70 61 72 65 64 20 73 next prepared s
397d0 74 61 74 65 6d 65 6e 74 20 69 6e 20 44 20 61 66 tatement in D af
397e0 74 65 72 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 ter S..**.** {H1
397f0 33 31 35 32 7d 20 49 66 20 53 20 69 73 20 74 68 3152} If S is th
39800 65 20 6c 61 73 74 20 5b 70 72 65 70 61 72 65 64 e last [prepared
39810 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 74 statement] in t
39820 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b he.** [
39830 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
39840 69 6f 6e 5d 20 44 20 74 68 65 6e 20 74 68 65 20 ion] D then the
39850 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 [sqlite3_next_st
39860 6d 74 28 44 2c 20 53 29 5d 0a 2a 2a 20 20 20 20 mt(D, S)].**
39870 20 20 20 20 20 20 72 6f 75 74 69 6e 65 20 73 68 routine sh
39880 61 6c 6c 20 72 65 74 75 72 6e 20 61 20 4e 55 4c all return a NUL
39890 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a L pointer..**.**
398a0 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a ASSUMPTIONS:.**
398b0 0a 2a 2a 20 7b 41 31 33 31 35 34 7d 20 54 68 65 .** {A13154} The
398c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
398d0 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44 ction] pointer D
398e0 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a in a call to.**
398f0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
39900 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 e3_next_stmt(D,S
39910 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f )] must refer to
39920 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 an open databas
39930 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f e.** co
39940 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 nnection and in
39950 70 61 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20 particular must
39960 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f not be a NULL po
39970 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 inter..*/.sqlite
39980 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 3_stmt *sqlite3_
39990 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 next_stmt(sqlite
399a0 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 3 *pDb, sqlite3_
399b0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f stmt *pStmt);../
399c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
399d0 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 ommit And Rollba
399e0 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 ck Notification
399f0 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 35 Callbacks {H1295
39a00 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 0} <S60400>.**.*
39a10 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f * The sqlite3_co
39a20 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 mmit_hook() inte
39a30 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 rface registers
39a40 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 a callback.** fu
39a50 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 nction to be inv
39a60 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 oked whenever a
39a70 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 transaction is c
39a80 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 ommitted..** Any
39a90 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 callback set by
39aa0 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c a previous call
39ab0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d to sqlite3_comm
39ac0 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 it_hook().** for
39ad0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
39ae0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
39af0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 overridden..**
39b00 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c The sqlite3_roll
39b10 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 back_hook() inte
39b20 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 rface registers
39b30 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 a callback.** fu
39b40 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 nction to be inv
39b50 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 oked whenever a
39b60 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 transaction is c
39b70 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 ommitted..** Any
39b80 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 callback set by
39b90 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c a previous call
39ba0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d to sqlite3_comm
39bb0 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 it_hook().** for
39bc0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
39bd0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
39be0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 overridden..**
39bf0 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e The pArg argumen
39c00 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f t is passed thro
39c10 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 ugh to the callb
39c20 61 63 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 ack..** If the c
39c30 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d allback on a com
39c40 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f mit hook functio
39c50 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 n returns non-ze
39c60 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 ro,.** then the
39c70 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 commit is conver
39c80 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 ted into a rollb
39c90 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e ack..**.** If an
39ca0 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 other function w
39cb0 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 as previously re
39cc0 67 69 73 74 65 72 65 64 2c 20 69 74 73 0a 2a 2a gistered, its.**
39cd0 20 70 41 72 67 20 76 61 6c 75 65 20 69 73 20 72 pArg value is r
39ce0 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 eturned. Otherw
39cf0 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 ise NULL is retu
39d00 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 rned..**.** The
39d10 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 callback impleme
39d20 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 ntation must not
39d30 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 do anything tha
39d40 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a t will modify.**
39d50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
39d60 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e nnection that in
39d70 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61 voked the callba
39d80 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 ck. Any actions
39d90 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 .** to modify th
39da0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
39db0 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 ction must be de
39dc0 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 ferred until aft
39dd0 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 er the.** comple
39de0 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c tion of the [sql
39df0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c ite3_step()] cal
39e00 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 l that triggered
39e10 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f the commit.** o
39e20 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 r rollback hook
39e30 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 in the first pla
39e40 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 ce..** Note that
39e50 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
39e60 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c e_v2()] and [sql
39e70 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 ite3_step()] bot
39e80 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a h modify their.*
39e90 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
39ea0 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d ctions for the m
39eb0 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 eaning of "modif
39ec0 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 y" in this parag
39ed0 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 raph..**.** Regi
39ee0 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 stering a NULL f
39ef0 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 unction disables
39f00 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a the callback..*
39f10 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 *.** For the pur
39f20 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 poses of this AP
39f30 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e I, a transaction
39f40 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 is said to have
39f50 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 been.** rolled
39f60 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 back if an expli
39f70 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 cit "ROLLBACK" s
39f80 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 tatement is exec
39f90 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 uted, or.** an e
39fa0 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 rror or constrai
39fb0 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 nt causes an imp
39fc0 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 licit rollback t
39fd0 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 54 68 65 20 o occur..** The
39fe0 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 rollback callbac
39ff0 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 k is not invoked
3a000 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f if a transactio
3a010 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 n is.** automati
3a020 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 cally rolled bac
3a030 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 64 61 k because the da
3a040 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
3a050 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 n is closed..**
3a060 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c The rollback cal
3a070 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 lback is not inv
3a080 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 oked if a transa
3a090 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c 6c ction is.** roll
3a0a0 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 ed back because
3a0b0 61 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63 a commit callbac
3a0c0 6b 20 72 65 74 75 72 6e 65 64 20 6e 6f 6e 2d 7a k returned non-z
3a0d0 65 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20 43 ero..** <todo> C
3a0e0 68 65 63 6b 20 6f 6e 20 74 68 69 73 20 3c 2f 74 heck on this </t
3a0f0 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 odo>.**.** INVAR
3a100 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
3a110 32 39 35 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 2951} The [sqlit
3a120 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 e3_commit_hook(D
3a130 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 ,F,P)] interface
3a140 20 72 65 67 69 73 74 65 72 73 20 74 68 65 0a 2a registers the.*
3a150 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 * callb
3a160 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20 74 ack function F t
3a170 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 o be invoked wit
3a180 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 h argument P whe
3a190 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 never.**
3a1a0 20 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 a transaction
3a1b0 63 6f 6d 6d 69 74 73 20 6f 6e 20 74 68 65 20 5b commits on the [
3a1c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3a1d0 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ion] D..**.** {H
3a1e0 31 32 39 35 32 7d 20 54 68 65 20 5b 73 71 6c 69 12952} The [sqli
3a1f0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 te3_commit_hook(
3a200 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 D,F,P)] interfac
3a210 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 e returns the P
3a220 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 argument.**
3a230 20 20 20 20 20 66 72 6f 6d 20 74 68 65 20 70 72 from the pr
3a240 65 76 69 6f 75 73 20 63 61 6c 6c 20 77 69 74 68 evious call with
3a250 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 the same [datab
3a260 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
3a270 44 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f D,.** o
3a280 72 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69 r NULL on the fi
3a290 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 61 20 70 rst call for a p
3a2a0 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 articular databa
3a2b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e se connection D.
3a2c0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 33 7d 20 .**.** {H12953}
3a2d0 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 Each call to [sq
3a2e0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f lite3_commit_hoo
3a2f0 6b 28 29 5d 20 6f 76 65 72 77 72 69 74 65 73 20 k()] overwrites
3a300 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 the callback.**
3a310 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 registe
3a320 72 65 64 20 62 79 20 70 72 69 6f 72 20 63 61 6c red by prior cal
3a330 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 ls..**.** {H1295
3a340 34 7d 20 49 66 20 74 68 65 20 46 20 61 72 67 75 4} If the F argu
3a350 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 ment to [sqlite3
3a360 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 _commit_hook(D,F
3a370 2c 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 ,P)] is NULL.**
3a380 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 then th
3a390 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 e commit hook ca
3a3a0 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e 63 65 6c llback is cancel
3a3b0 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62 61 ed and no callba
3a3c0 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 ck.** i
3a3d0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 s invoked when a
3a3e0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d transaction com
3a3f0 6d 69 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 mits..**.** {H12
3a400 39 35 35 7d 20 49 66 20 74 68 65 20 63 6f 6d 6d 955} If the comm
3a410 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 it callback retu
3a420 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 74 68 65 rns non-zero the
3a430 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 0a n the commit is.
3a440 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 76 ** conv
3a450 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c erted into a rol
3a460 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 lback..**.** {H1
3a470 32 39 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 2961} The [sqlit
3a480 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b e3_rollback_hook
3a490 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 (D,F,P)] interfa
3a4a0 63 65 20 72 65 67 69 73 74 65 72 73 20 74 68 65 ce registers the
3a4b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c .** cal
3a4c0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46 lback function F
3a4d0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 to be invoked w
3a4e0 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 ith argument P w
3a4f0 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 henever.**
3a500 20 20 20 20 61 20 74 72 61 6e 73 61 63 74 69 6f a transactio
3a510 6e 20 72 6f 6c 6c 73 20 62 61 63 6b 20 6f 6e 20 n rolls back on
3a520 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
3a530 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a nnection] D..**.
3a540 2a 2a 20 7b 48 31 32 39 36 32 7d 20 54 68 65 20 ** {H12962} The
3a550 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 [sqlite3_rollbac
3a560 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 k_hook(D,F,P)] i
3a570 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
3a580 20 74 68 65 20 50 0a 2a 2a 20 20 20 20 20 20 20 the P.**
3a590 20 20 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d argument from
3a5a0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 the previous ca
3a5b0 6c 6c 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 ll with the same
3a5c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 .** [da
3a5d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
3a5e0 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 6f 6e n] D, or NULL on
3a5f0 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 0a the first call.
3a600 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 ** for
3a610 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 a particular dat
3a620 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
3a630 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36 D..**.** {H1296
3a640 33 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 3} Each call to
3a650 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 [sqlite3_rollbac
3a660 6b 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77 72 k_hook()] overwr
3a670 69 74 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 ites the callbac
3a680 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 k.** re
3a690 67 69 73 74 65 72 65 64 20 62 79 20 70 72 69 6f gistered by prio
3a6a0 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b r calls..**.** {
3a6b0 48 31 32 39 36 34 7d 20 49 66 20 74 68 65 20 46 H12964} If the F
3a6c0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 argument to [sq
3a6d0 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 lite3_rollback_h
3a6e0 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20 4e ook(D,F,P)] is N
3a6f0 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ULL.**
3a700 74 68 65 6e 20 74 68 65 20 72 6f 6c 6c 62 61 63 then the rollbac
3a710 6b 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 k hook callback
3a720 69 73 20 63 61 6e 63 65 6c 65 64 20 61 6e 64 20 is canceled and
3a730 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 no callback.**
3a740 20 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b is invok
3a750 65 64 20 77 68 65 6e 20 61 20 74 72 61 6e 73 61 ed when a transa
3a760 63 74 69 6f 6e 20 72 6f 6c 6c 73 20 62 61 63 6b ction rolls back
3a770 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 ..*/.void *sqlit
3a780 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 e3_commit_hook(s
3a790 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 qlite3*, int(*)(
3a7a0 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a void*), void*);.
3a7b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f void *sqlite3_ro
3a7c0 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 llback_hook(sqli
3a7d0 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f te3*, void(*)(vo
3a7e0 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a id *), void*);..
3a7f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
3a800 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 Data Change Noti
3a810 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 fication Callbac
3a820 6b 73 20 7b 48 31 32 39 37 30 7d 20 3c 53 36 30 ks {H12970} <S60
3a830 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 400>.**.** The s
3a840 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f qlite3_update_ho
3a850 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 ok() interface r
3a860 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 egisters a callb
3a870 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 ack function.**
3a880 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 with the [databa
3a890 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 se connection] i
3a8a0 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 dentified by the
3a8b0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a first argument.
3a8c0 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 ** to be invoked
3a8d0 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 whenever a row
3a8e0 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 is updated, inse
3a8f0 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e rted or deleted.
3a900 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b .** Any callback
3a910 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f set by a previo
3a920 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 us call to this
3a930 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 function.** for
3a940 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
3a950 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
3a960 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a overridden..**.*
3a970 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 * The second arg
3a980 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 ument is a point
3a990 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 er to the functi
3a9a0 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 on to invoke whe
3a9b0 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 n a.** row is up
3a9c0 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 dated, inserted
3a9d0 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 54 or deleted..** T
3a9e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
3a9f0 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 t to the callbac
3aa00 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 k is a copy of t
3aa10 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
3aa20 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f t.** to sqlite3_
3aa30 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a update_hook()..*
3aa40 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c * The second cal
3aa50 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 lback argument i
3aa60 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 s one of [SQLITE
3aa70 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 _INSERT], [SQLIT
3aa80 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 E_DELETE],.** or
3aa90 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d [SQLITE_UPDATE]
3aaa0 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 , depending on t
3aab0 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 he operation tha
3aac0 74 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c t caused the cal
3aad0 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 lback.** to be i
3aae0 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 74 nvoked..** The t
3aaf0 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 hird and fourth
3ab00 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 arguments to the
3ab10 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 callback contai
3ab20 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 n pointers to th
3ab30 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e e.** database an
3ab40 64 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e d table name con
3ab50 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 taining the affe
3ab60 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 54 68 65 cted row..** The
3ab70 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 final callback
3ab80 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
3ab90 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 [rowid] of the
3aba0 72 6f 77 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 63 row..** In the c
3abb0 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65 ase of an update
3abc0 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 5b 72 , this is the [r
3abd0 6f 77 69 64 5d 20 61 66 74 65 72 20 74 68 65 20 owid] after the
3abe0 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c 61 update takes pla
3abf0 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 ce..**.** The up
3ac00 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 date hook is not
3ac10 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e invoked when in
3ac20 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 ternal system ta
3ac30 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 bles are.** modi
3ac40 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 fied (i.e. sqlit
3ac50 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c e_master and sql
3ac60 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 0a 2a ite_sequence)..*
3ac70 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20 *.** The update
3ac80 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 hook implementat
3ac90 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 ion must not do
3aca0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 anything that wi
3acb0 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 ll modify.** the
3acc0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
3acd0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 tion that invoke
3ace0 64 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f d the update hoo
3acf0 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a k. Any actions.
3ad00 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 ** to modify the
3ad10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
3ad20 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 tion must be def
3ad30 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 erred until afte
3ad40 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 r the.** complet
3ad50 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 ion of the [sqli
3ad60 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c te3_step()] call
3ad70 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 that triggered
3ad80 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e the update hook.
3ad90 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 .** Note that [s
3ada0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
3adb0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 2()] and [sqlite
3adc0 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 3_step()] both m
3add0 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 odify their.** d
3ade0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
3adf0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e ons for the mean
3ae00 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 ing of "modify"
3ae10 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 in this paragrap
3ae20 68 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 h..**.** If anot
3ae30 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 her function was
3ae40 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 previously regi
3ae50 73 74 65 72 65 64 2c 20 69 74 73 20 70 41 72 67 stered, its pArg
3ae60 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 72 65 74 value.** is ret
3ae70 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 urned. Otherwis
3ae80 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e e NULL is return
3ae90 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 ed..**.** INVARI
3aea0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 ANTS:.**.** {H12
3aeb0 39 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 971} The [sqlite
3aec0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 3_update_hook(D,
3aed0 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 F,P)] interface
3aee0 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 causes the callb
3aef0 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ack.**
3af00 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 function F to be
3af10 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 69 invoked with fi
3af20 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 50 20 rst parameter P
3af30 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 whenever.**
3af40 20 20 20 20 20 61 20 74 61 62 6c 65 20 72 6f 77 a table row
3af50 20 69 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e is modified, in
3af60 73 65 72 74 65 64 2c 20 6f 72 20 64 65 6c 65 74 serted, or delet
3af70 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 ed on.**
3af80 20 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 the [database
3af90 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a connection] D..*
3afa0 2a 0a 2a 2a 20 7b 48 31 32 39 37 33 7d 20 54 68 *.** {H12973} Th
3afb0 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 e [sqlite3_updat
3afc0 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 e_hook(D,F,P)] i
3afd0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
3afe0 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20 the value.**
3aff0 20 20 20 20 20 20 20 6f 66 20 50 20 66 6f 72 20 of P for
3b000 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c the previous cal
3b010 6c 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 l on the same [d
3b020 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
3b030 6f 6e 5d 20 44 2c 0a 2a 2a 20 20 20 20 20 20 20 on] D,.**
3b040 20 20 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 20 74 or NULL for t
3b050 68 65 20 66 69 72 73 74 20 63 61 6c 6c 2e 0a 2a he first call..*
3b060 2a 0a 2a 2a 20 7b 48 31 32 39 37 35 7d 20 49 66 *.** {H12975} If
3b070 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b the update hook
3b080 20 63 61 6c 6c 62 61 63 6b 20 46 20 69 6e 20 5b callback F in [
3b090 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 sqlite3_update_h
3b0a0 6f 6f 6b 28 44 2c 46 2c 50 29 5d 0a 2a 2a 20 20 ook(D,F,P)].**
3b0b0 20 20 20 20 20 20 20 20 69 73 20 4e 55 4c 4c 20 is NULL
3b0c0 74 68 65 6e 20 74 68 65 20 6e 6f 20 75 70 64 61 then the no upda
3b0d0 74 65 20 63 61 6c 6c 62 61 63 6b 73 20 61 72 65 te callbacks are
3b0e0 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 made..**.** {H1
3b0f0 32 39 37 37 7d 20 45 61 63 68 20 63 61 6c 6c 20 2977} Each call
3b100 74 6f 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 to [sqlite3_upda
3b110 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 te_hook(D,F,P)]
3b120 6f 76 65 72 72 69 64 65 73 20 70 72 69 6f 72 20 overrides prior
3b130 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20 calls.**
3b140 20 20 74 6f 20 74 68 65 20 73 61 6d 65 20 69 6e to the same in
3b150 74 65 72 66 61 63 65 20 6f 6e 20 74 68 65 20 73 terface on the s
3b160 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f ame [database co
3b170 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a nnection] D..**.
3b180 2a 2a 20 7b 48 31 32 39 37 39 7d 20 54 68 65 20 ** {H12979} The
3b190 75 70 64 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c update hook call
3b1a0 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f back is not invo
3b1b0 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 ked when interna
3b1c0 6c 20 73 79 73 74 65 6d 0a 2a 2a 20 20 20 20 20 l system.**
3b1d0 20 20 20 20 20 74 61 62 6c 65 73 20 73 75 63 68 tables such
3b1e0 20 61 73 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 as sqlite_maste
3b1f0 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 r and sqlite_seq
3b200 75 65 6e 63 65 20 61 72 65 20 6d 6f 64 69 66 69 uence are modifi
3b210 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 38 ed..**.** {H1298
3b220 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 1} The second pa
3b230 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 75 rameter to the u
3b240 70 64 61 74 65 20 63 61 6c 6c 62 61 63 6b 0a 2a pdate callback.*
3b250 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6f 6e * is on
3b260 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 e of [SQLITE_INS
3b270 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 ERT], [SQLITE_DE
3b280 4c 45 54 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 LETE] or [SQLITE
3b290 5f 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 20 20 20 _UPDATE],.**
3b2a0 20 20 20 20 20 20 64 65 70 65 6e 64 69 6e 67 20 depending
3b2b0 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e on the operation
3b2c0 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65 that caused the
3b2d0 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 callback to be
3b2e0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b invoked..**.** {
3b2f0 48 31 32 39 38 33 7d 20 54 68 65 20 74 68 69 72 H12983} The thir
3b300 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67 d and fourth arg
3b310 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 uments to the ca
3b320 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 llback contain p
3b330 6f 69 6e 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 ointers.**
3b340 20 20 20 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d to zero-term
3b350 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 inated UTF-8 str
3b360 69 6e 67 73 20 77 68 69 63 68 20 61 72 65 20 74 ings which are t
3b370 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a he names of the.
3b380 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61 ** data
3b390 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 74 base and table t
3b3a0 68 61 74 20 69 73 20 62 65 69 6e 67 20 75 70 64 hat is being upd
3b3b0 61 74 65 64 2e 0a 0a 2a 2a 20 7b 48 31 32 39 38 ated...** {H1298
3b3c0 35 7d 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 5} The final cal
3b3d0 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 lback parameter
3b3e0 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f is the [rowid] o
3b3f0 66 20 74 68 65 20 72 6f 77 20 61 66 74 65 72 0a f the row after.
3b400 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
3b410 63 68 61 6e 67 65 20 6f 63 63 75 72 73 2e 0a 2a change occurs..*
3b420 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f /.void *sqlite3_
3b430 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 update_hook(. s
3b440 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 qlite3*, . void
3b450 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c (*)(void *,int ,
3b460 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 char const *,cha
3b470 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 r const *,sqlite
3b480 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 3_int64),. void
3b490 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 *.);../*.** CAPI
3b4a0 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 3REF: Enable Or
3b4b0 44 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 Disable Shared P
3b4c0 61 67 65 72 20 43 61 63 68 65 20 7b 48 31 30 33 ager Cache {H103
3b4d0 33 30 7d 20 3c 53 33 30 39 30 30 3e 0a 2a 2a 20 30} <S30900>.**
3b4e0 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 KEYWORDS: {share
3b4f0 64 20 63 61 63 68 65 7d 20 7b 73 68 61 72 65 64 d cache} {shared
3b500 20 63 61 63 68 65 20 6d 6f 64 65 7d 0a 2a 2a 0a cache mode}.**.
3b510 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
3b520 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 enables or disab
3b530 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 les the sharing
3b540 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 of the database
3b550 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 cache.** and sch
3b560 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75 ema data structu
3b570 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 res between [dat
3b580 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
3b590 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a | connections].
3b5a0 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 ** to the same d
3b5b0 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 atabase. Sharing
3b5c0 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 is enabled if t
3b5d0 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 he argument is t
3b5e0 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 rue.** and disab
3b5f0 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d led if the argum
3b600 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a ent is false..**
3b610 0a 2a 2a 20 43 61 63 68 65 20 73 68 61 72 69 6e .** Cache sharin
3b620 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 g is enabled and
3b630 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e disabled for an
3b640 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e entire process.
3b650 20 7b 45 4e 44 7d 0a 2a 2a 20 54 68 69 73 20 69 {END}.** This i
3b660 73 20 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66 s a change as of
3b670 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
3b680 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 3.5.0. In prior
3b690 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
3b6a0 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 te,.** sharing w
3b6b0 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 as enabled or di
3b6c0 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20 sabled for each
3b6d0 74 68 72 65 61 64 20 73 65 70 61 72 61 74 65 6c thread separatel
3b6e0 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 63 y..**.** The cac
3b6f0 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 he sharing mode
3b700 73 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 set by this inte
3b710 72 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c rface effects al
3b720 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 l subsequent.**
3b730 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
3b740 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 3_open()], [sqli
3b750 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 te3_open_v2()],
3b760 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 and [sqlite3_ope
3b770 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 n16()]..** Exist
3b780 69 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e ing database con
3b790 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 nections continu
3b7a0 65 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e e use the sharin
3b7b0 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 g mode.** that w
3b7c0 61 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 as in effect at
3b7d0 74 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 the time they we
3b7e0 72 65 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a re opened..**.**
3b7f0 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 Virtual tables
3b800 63 61 6e 6e 6f 74 20 62 65 20 75 73 65 64 20 77 cannot be used w
3b810 69 74 68 20 61 20 73 68 61 72 65 64 20 63 61 63 ith a shared cac
3b820 68 65 2e 20 20 57 68 65 6e 20 73 68 61 72 65 64 he. When shared
3b830 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 .** cache is ena
3b840 62 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 bled, the [sqlit
3b850 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 e3_create_module
3b860 28 29 5d 20 41 50 49 20 75 73 65 64 20 74 6f 20 ()] API used to
3b870 72 65 67 69 73 74 65 72 0a 2a 2a 20 76 69 72 74 register.** virt
3b880 75 61 6c 20 74 61 62 6c 65 73 20 77 69 6c 6c 20 ual tables will
3b890 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 61 6e always return an
3b8a0 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 error..**.** Th
3b8b0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 is routine retur
3b8c0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 ns [SQLITE_OK] i
3b8d0 66 20 73 68 61 72 65 64 20 63 61 63 68 65 20 77 f shared cache w
3b8e0 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 as enabled or di
3b8f0 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65 73 sabled.** succes
3b900 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 sfully. An [err
3b910 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 or code] is retu
3b920 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a rned otherwise..
3b930 2a 2a 0a 2a 2a 20 53 68 61 72 65 64 20 63 61 63 **.** Shared cac
3b940 68 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 he is disabled b
3b950 79 20 64 65 66 61 75 6c 74 2e 20 42 75 74 20 74 y default. But t
3b960 68 69 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65 his might change
3b970 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 in.** future re
3b980 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
3b990 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 . Applications
3b9a0 74 68 61 74 20 63 61 72 65 20 61 62 6f 75 74 20 that care about
3b9b0 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 shared.** cache
3b9c0 73 65 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 setting should s
3b9d0 65 74 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79 et it explicitly
3b9e0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e ..**.** INVARIAN
3b9f0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 33 33 TS:.**.** {H1033
3ba00 31 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 1} A successful
3ba10 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 invocation of [s
3ba20 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 qlite3_enable_sh
3ba30 61 72 65 64 5f 63 61 63 68 65 28 42 29 5d 0a 2a ared_cache(B)].*
3ba40 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20 * will
3ba50 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c enable or disabl
3ba60 65 20 73 68 61 72 65 64 20 63 61 63 68 65 20 6d e shared cache m
3ba70 6f 64 65 20 66 6f 72 20 61 6e 79 20 73 75 62 73 ode for any subs
3ba80 65 71 75 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 equently.**
3ba90 20 20 20 20 20 63 72 65 61 74 65 64 20 5b 64 61 created [da
3baa0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
3bab0 6e 5d 20 69 6e 20 74 68 65 20 73 61 6d 65 20 70 n] in the same p
3bac0 72 6f 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 rocess..**.** {H
3bad0 31 30 33 33 36 7d 20 57 68 65 6e 20 73 68 61 72 10336} When shar
3bae0 65 64 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 ed cache is enab
3baf0 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 led, the [sqlite
3bb00 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 3_create_module(
3bb10 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 )].** i
3bb20 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 61 6c nterface will al
3bb30 77 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65 ways return an e
3bb40 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 rror..**.** {H10
3bb50 33 33 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 337} The [sqlite
3bb60 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 3_enable_shared_
3bb70 63 61 63 68 65 28 42 29 5d 20 69 6e 74 65 72 66 cache(B)] interf
3bb80 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 ace returns.**
3bb90 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f [SQLITE_
3bba0 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 OK] if shared ca
3bbb0 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 che was enabled
3bbc0 6f 72 20 64 69 73 61 62 6c 65 64 20 73 75 63 63 or disabled succ
3bbd0 65 73 73 66 75 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 essfully..**.**
3bbe0 7b 48 31 30 33 33 39 7d 20 53 68 61 72 65 64 20 {H10339} Shared
3bbf0 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c 65 cache is disable
3bc00 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2f d by default..*/
3bc10 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 .int sqlite3_ena
3bc20 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 ble_shared_cache
3bc30 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 (int);../*.** CA
3bc40 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70 74 20 PI3REF: Attempt
3bc50 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d To Free Heap Mem
3bc60 6f 72 79 20 7b 48 31 37 33 34 30 7d 20 3c 53 33 ory {H17340} <S3
3bc70 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 0220>.**.** The
3bc80 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f sqlite3_release_
3bc90 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61 memory() interfa
3bca0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66 ce attempts to f
3bcb0 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f ree N bytes.** o
3bcc0 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 f heap memory by
3bcd0 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f deallocating no
3bce0 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f n-essential memo
3bcf0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a ry allocations.*
3bd00 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 * held by the da
3bd10 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e 20 tabase library.
3bd20 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72 79 20 75 73 {END} Memory us
3bd30 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 ed to cache data
3bd40 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f base.** pages to
3bd50 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d improve perform
3bd60 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70 ance is an examp
3bd70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 le of non-essent
3bd80 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 73 ial memory..** s
3bd90 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d qlite3_release_m
3bda0 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20 emory() returns
3bdb0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
3bdc0 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 tes actually fre
3bdd0 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 ed,.** which mig
3bde0 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 ht be more or le
3bdf0 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 ss than the amou
3be00 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a nt requested..**
3be10 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a .** INVARIANTS:.
3be20 2a 2a 0a 2a 2a 20 7b 48 31 37 33 34 31 7d 20 54 **.** {H17341} T
3be30 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 he [sqlite3_rele
3be40 61 73 65 5f 6d 65 6d 6f 72 79 28 4e 29 5d 20 69 ase_memory(N)] i
3be50 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 nterface attempt
3be60 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 s to.**
3be70 20 66 72 65 65 20 4e 20 62 79 74 65 73 20 6f 66 free N bytes of
3be80 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 heap memory by
3be90 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e deallocating non
3bea0 2d 65 73 73 65 6e 74 69 61 6c 0a 2a 2a 20 20 20 -essential.**
3beb0 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 61 6c memory al
3bec0 6c 6f 63 61 74 69 6f 6e 73 20 68 65 6c 64 20 62 locations held b
3bed0 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c y the database l
3bee0 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 ibrary..**.** {H
3bef0 31 36 33 34 32 7d 20 54 68 65 20 5b 73 71 6c 69 16342} The [sqli
3bf00 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f te3_release_memo
3bf10 72 79 28 4e 29 5d 20 72 65 74 75 72 6e 73 20 74 ry(N)] returns t
3bf20 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 he number.**
3bf30 20 20 20 20 20 20 6f 66 20 62 79 74 65 73 20 61 of bytes a
3bf40 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 20 77 ctually freed, w
3bf50 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f hich might be mo
3bf60 72 65 20 6f 72 20 6c 65 73 73 0a 2a 2a 20 20 20 re or less.**
3bf70 20 20 20 20 20 20 20 74 68 61 6e 20 74 68 65 20 than the
3bf80 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 amount requested
3bf90 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
3bfa0 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 _release_memory(
3bfb0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 int);../*.** CAP
3bfc0 49 33 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 I3REF: Impose A
3bfd0 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69 Limit On Heap Si
3bfe0 7a 65 20 7b 48 31 37 33 35 30 7d 20 3c 53 33 30 ze {H17350} <S30
3bff0 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 220>.**.** The s
3c000 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 qlite3_soft_heap
3c010 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65 72 66 61 _limit() interfa
3c020 63 65 20 70 6c 61 63 65 73 20 61 20 22 73 6f 66 ce places a "sof
3c030 74 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 t" limit.** on t
3c040 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 he amount of hea
3c050 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 p memory that ma
3c060 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 y be allocated b
3c070 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 49 66 20 y SQLite..** If
3c080 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f an internal allo
3c090 63 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 cation is reques
3c0a0 74 65 64 20 74 68 61 74 20 77 6f 75 6c 64 20 65 ted that would e
3c0b0 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 73 6f 66 xceed the.** sof
3c0c0 74 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73 t heap limit, [s
3c0d0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d qlite3_release_m
3c0e0 65 6d 6f 72 79 28 29 5d 20 69 73 20 69 6e 76 6f emory()] is invo
3c0f0 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f ked one or.** mo
3c100 72 65 20 74 69 6d 65 73 20 74 6f 20 66 72 65 65 re times to free
3c110 20 75 70 20 73 6f 6d 65 20 73 70 61 63 65 20 62 up some space b
3c120 65 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63 61 efore the alloca
3c130 74 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 tion is performe
3c140 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 6d d..**.** The lim
3c150 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73 6f it is called "so
3c160 66 74 22 2c 20 62 65 63 61 75 73 65 20 69 66 20 ft", because if
3c170 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 [sqlite3_release
3c180 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63 61 _memory()].** ca
3c190 6e 6e 6f 74 20 66 72 65 65 20 73 75 66 66 69 63 nnot free suffic
3c1a0 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70 ient memory to p
3c1b0 72 65 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74 revent the limit
3c1c0 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65 from being exce
3c1d0 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d eded,.** the mem
3c1e0 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 ory is allocated
3c1f0 20 61 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20 anyway and the
3c200 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f current operatio
3c210 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a n proceeds..**.*
3c220 2a 20 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20 * A negative or
3c230 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e zero value for N
3c240 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 72 means that ther
3c250 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65 61 e is no soft hea
3c260 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b p limit and.** [
3c270 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f sqlite3_release_
3c280 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f memory()] will o
3c290 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 nly be called wh
3c2a0 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78 68 en memory is exh
3c2b0 61 75 73 74 65 64 2e 0a 2a 2a 20 54 68 65 20 64 austed..** The d
3c2c0 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 efault value for
3c2d0 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c the soft heap l
3c2e0 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a imit is zero..**
3c2f0 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 .** SQLite makes
3c300 20 61 20 62 65 73 74 20 65 66 66 6f 72 74 20 74 a best effort t
3c310 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f 66 74 o honor the soft
3c320 20 68 65 61 70 20 6c 69 6d 69 74 2e 0a 2a 2a 20 heap limit..**
3c330 42 75 74 20 69 66 20 74 68 65 20 73 6f 66 74 20 But if the soft
3c340 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e 6e 6f heap limit canno
3c350 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c 20 65 78 t be honored, ex
3c360 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 ecution will.**
3c370 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f 75 74 continue without
3c380 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69 error or notifi
3c390 63 61 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 73 cation. This is
3c3a0 20 77 68 79 20 74 68 65 20 6c 69 6d 69 74 20 69 why the limit i
3c3b0 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 61 20 22 73 s.** called a "s
3c3c0 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20 49 74 20 oft" limit. It
3c3d0 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 is advisory only
3c3e0 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f ..**.** Prior to
3c3f0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
3c400 33 2e 35 2e 30 2c 20 74 68 69 73 20 72 6f 75 74 3.5.0, this rout
3c410 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 ine only constra
3c420 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f 72 79 0a ined the memory.
3c430 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 ** allocated by
3c440 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 20 a single thread
3c450 2d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 - the same threa
3c460 64 20 69 6e 20 77 68 69 63 68 20 74 68 69 73 20 d in which this
3c470 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e routine.** runs.
3c480 20 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 Beginning with
3c490 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
3c4a0 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f 66 74 20 3.5.0, the soft
3c4b0 68 65 61 70 20 6c 69 6d 69 74 20 69 73 0a 2a 2a heap limit is.**
3c4c0 20 61 70 70 6c 69 65 64 20 74 6f 20 61 6c 6c 20 applied to all
3c4d0 74 68 72 65 61 64 73 2e 20 54 68 65 20 76 61 6c threads. The val
3c4e0 75 65 20 73 70 65 63 69 66 69 65 64 20 66 6f 72 ue specified for
3c4f0 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c the soft heap l
3c500 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e 20 75 70 imit.** is an up
3c510 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 per bound on the
3c520 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79 20 61 6c total memory al
3c530 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 6c 6c location for all
3c540 20 74 68 72 65 61 64 73 2e 20 49 6e 0a 2a 2a 20 threads. In.**
3c550 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 74 68 version 3.5.0 th
3c560 65 72 65 20 69 73 20 6e 6f 20 6d 65 63 68 61 6e ere is no mechan
3c570 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74 69 6e 67 ism for limiting
3c580 20 74 68 65 20 68 65 61 70 20 75 73 61 67 65 20 the heap usage
3c590 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64 75 61 for.** individua
3c5a0 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a l threads..**.**
3c5b0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
3c5c0 2a 2a 20 7b 48 31 36 33 35 31 7d 20 54 68 65 20 ** {H16351} The
3c5d0 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 [sqlite3_soft_he
3c5e0 61 70 5f 6c 69 6d 69 74 28 4e 29 5d 20 69 6e 74 ap_limit(N)] int
3c5f0 65 72 66 61 63 65 20 70 6c 61 63 65 73 20 61 20 erface places a
3c600 73 6f 66 74 20 6c 69 6d 69 74 0a 2a 2a 20 20 20 soft limit.**
3c610 20 20 20 20 20 20 20 6f 66 20 4e 20 62 79 74 65 of N byte
3c620 73 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 s on the amount
3c630 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 of heap memory t
3c640 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 hat may be alloc
3c650 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 ated.**
3c660 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
3c670 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 malloc()] or [sq
3c680 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d lite3_realloc()]
3c690 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 0a 2a 2a at any point.**
3c6a0 20 20 20 20 20 20 20 20 20 20 69 6e 20 74 69 6d in tim
3c6b0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 33 35 32 e..**.** {H16352
3c6c0 7d 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b } If a call to [
3c6d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
3c6e0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ] or [sqlite3_re
3c6f0 61 6c 6c 6f 63 28 29 5d 20 77 6f 75 6c 64 0a 2a alloc()] would.*
3c700 2a 20 20 20 20 20 20 20 20 20 20 63 61 75 73 65 * cause
3c710 20 74 68 65 20 74 6f 74 61 6c 20 61 6d 6f 75 6e the total amoun
3c720 74 20 6f 66 20 61 6c 6c 6f 63 61 74 65 64 20 6d t of allocated m
3c730 65 6d 6f 72 79 20 74 6f 20 65 78 63 65 65 64 20 emory to exceed
3c740 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
3c750 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c soft heap limit,
3c760 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 then [sqlite3_r
3c770 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d elease_memory()]
3c780 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 is invoked.**
3c790 20 20 20 20 20 20 20 20 69 6e 20 61 6e 20 61 74 in an at
3c7a0 74 65 6d 70 74 20 74 6f 20 72 65 64 75 63 65 20 tempt to reduce
3c7b0 74 68 65 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 the memory usage
3c7c0 20 70 72 69 6f 72 20 74 6f 20 70 72 6f 63 65 65 prior to procee
3c7d0 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 ding.**
3c7e0 20 77 69 74 68 20 74 68 65 20 6d 65 6d 6f 72 79 with the memory
3c7f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 74 74 65 allocation atte
3c800 6d 70 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 33 mpt..**.** {H163
3c810 35 33 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 53} Calls to [sq
3c820 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
3c830 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c or [sqlite3_real
3c840 6c 6f 63 28 29 5d 20 74 68 61 74 20 74 72 69 67 loc()] that trig
3c850 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ger.**
3c860 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 64 75 attempts to redu
3c870 63 65 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 ce memory usage
3c880 74 68 72 6f 75 67 68 20 74 68 65 20 73 6f 66 74 through the soft
3c890 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 20 heap limit.**
3c8a0 20 20 20 20 20 20 20 20 6d 65 63 68 61 6e 69 73 mechanis
3c8b0 6d 20 63 6f 6e 74 69 6e 75 65 20 65 76 65 6e 20 m continue even
3c8c0 69 66 20 74 68 65 20 61 74 74 65 6d 70 74 20 74 if the attempt t
3c8d0 6f 20 72 65 64 75 63 65 20 6d 65 6d 6f 72 79 0a o reduce memory.
3c8e0 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73 61 67 ** usag
3c8f0 65 20 69 73 20 75 6e 73 75 63 63 65 73 73 66 75 e is unsuccessfu
3c900 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 33 35 34 l..**.** {H16354
3c910 7d 20 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20 } A negative or
3c920 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e zero value for N
3c930 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a in a call to.**
3c940 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
3c950 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d e3_soft_heap_lim
3c960 69 74 28 4e 29 5d 20 6d 65 61 6e 73 20 74 68 61 it(N)] means tha
3c970 74 20 74 68 65 72 65 20 69 73 20 6e 6f 20 73 6f t there is no so
3c980 66 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 ft.** h
3c990 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 20 5b 73 eap limit and [s
3c9a0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d qlite3_release_m
3c9b0 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e emory()] will on
3c9c0 6c 79 20 62 65 0a 2a 2a 20 20 20 20 20 20 20 20 ly be.**
3c9d0 20 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 called when me
3c9e0 6d 6f 72 79 20 69 73 20 63 6f 6d 70 6c 65 74 65 mory is complete
3c9f0 6c 79 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a ly exhausted..**
3ca00 0a 2a 2a 20 7b 48 31 36 33 35 35 7d 20 54 68 65 .** {H16355} The
3ca10 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 default value f
3ca20 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 or the soft heap
3ca30 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a limit is zero..
3ca40 2a 2a 0a 2a 2a 20 7b 48 31 36 33 35 38 7d 20 45 **.** {H16358} E
3ca50 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ach call to [sql
3ca60 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c ite3_soft_heap_l
3ca70 69 6d 69 74 28 4e 29 5d 20 6f 76 65 72 72 69 64 imit(N)] overrid
3ca80 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 es the.**
3ca90 20 20 20 76 61 6c 75 65 73 20 73 65 74 20 62 79 values set by
3caa0 20 61 6c 6c 20 70 72 69 6f 72 20 63 61 6c 6c 73 all prior calls
3cab0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 ..*/.void sqlite
3cac0 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 3_soft_heap_limi
3cad0 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 t(int);../*.** C
3cae0 41 50 49 33 52 45 46 3a 20 45 78 74 72 61 63 74 API3REF: Extract
3caf0 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74 20 Metadata About
3cb00 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 A Column Of A Ta
3cb10 62 6c 65 20 7b 48 31 32 38 35 30 7d 20 3c 53 36 ble {H12850} <S6
3cb20 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 0300>.**.** This
3cb30 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
3cb40 20 6d 65 74 61 64 61 74 61 20 61 62 6f 75 74 20 metadata about
3cb50 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d a specific colum
3cb60 6e 20 6f 66 20 61 20 73 70 65 63 69 66 69 63 0a n of a specific.
3cb70 2a 2a 20 64 61 74 61 62 61 73 65 20 74 61 62 6c ** database tabl
3cb80 65 20 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 e accessible usi
3cb90 6e 67 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 ng the [database
3cba0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e connection] han
3cbb0 64 6c 65 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 dle.** passed as
3cbc0 20 74 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 the first funct
3cbd0 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a ion argument..**
3cbe0 0a 2a 2a 20 54 68 65 20 63 6f 6c 75 6d 6e 20 69 .** The column i
3cbf0 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 s identified by
3cc00 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 the second, thir
3cc10 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 d and fourth par
3cc20 61 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 ameters to.** th
3cc30 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 is function. The
3cc40 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
3cc50 72 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 r is either the
3cc60 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 name of the data
3cc70 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d base.** (i.e. "m
3cc80 61 69 6e 22 2c 20 22 74 65 6d 70 22 20 6f 72 20 ain", "temp" or
3cc90 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 61 an attached data
3cca0 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 base) containing
3ccb0 20 74 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a the specified.*
3ccc0 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e * table or NULL.
3ccd0 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 If it is NULL,
3cce0 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 then all attache
3ccf0 64 20 64 61 74 61 62 61 73 65 73 20 61 72 65 20 d databases are
3cd00 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 searched.** for
3cd10 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20 the table using
3cd20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 the same algorit
3cd30 68 6d 20 75 73 65 64 20 62 79 20 74 68 65 20 64 hm used by the d
3cd40 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 74 atabase engine t
3cd50 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 o.** resolve unq
3cd60 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72 ualified table r
3cd70 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a eferences..**.**
3cd80 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 The third and f
3cd90 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 ourth parameters
3cda0 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f to this functio
3cdb0 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 n are the table
3cdc0 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 and column.** na
3cdd0 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 me of the desire
3cde0 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 d column, respec
3cdf0 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 tively. Neither
3ce00 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 of these paramet
3ce10 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 ers.** may be NU
3ce20 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74 61 64 61 LL..**.** Metada
3ce30 74 61 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 ta is returned b
3ce40 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 y writing to the
3ce50 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e memory location
3ce60 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 s passed as the
3ce70 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 5th.** and subse
3ce80 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 quent parameters
3ce90 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f to this functio
3cea0 6e 2e 20 41 6e 79 20 6f 66 20 74 68 65 73 65 20 n. Any of these
3ceb0 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 arguments may be
3cec0 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 .** NULL, in whi
3ced0 63 68 20 63 61 73 65 20 74 68 65 20 63 6f 72 72 ch case the corr
3cee0 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e esponding elemen
3cef0 74 20 6f 66 20 6d 65 74 61 64 61 74 61 20 69 73 t of metadata is
3cf00 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 omitted..**.**
3cf10 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 <blockquote>.**
3cf20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 <table border="1
3cf30 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 ">.** <tr><th> P
3cf40 61 72 61 6d 65 74 65 72 20 3c 74 68 3e 20 4f 75 arameter <th> Ou
3cf50 74 70 75 74 3c 62 72 3e 54 79 70 65 20 3c 74 68 tput<br>Type <th
3cf60 3e 20 20 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a > Description.*
3cf70 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 35 74 *.** <tr><td> 5t
3cf80 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 h <td> const cha
3cf90 72 2a 20 3c 74 64 3e 20 44 61 74 61 20 74 79 70 r* <td> Data typ
3cfa0 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 36 74 e.** <tr><td> 6t
3cfb0 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 h <td> const cha
3cfc0 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f 66 20 r* <td> Name of
3cfd0 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f default collatio
3cfe0 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 n sequence.** <t
3cff0 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74 64 3e 20 r><td> 7th <td>
3d000 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e int <td>
3d010 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 True if column
3d020 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 has a NOT NULL c
3d030 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 onstraint.** <tr
3d040 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64 3e 20 69 ><td> 8th <td> i
3d050 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 nt <td>
3d060 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 True if column i
3d070 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 50 52 s part of the PR
3d080 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 IMARY KEY.** <tr
3d090 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64 3e 20 69 ><td> 9th <td> i
3d0a0 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 nt <td>
3d0b0 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 True if column i
3d0c0 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 s [AUTOINCREMENT
3d0d0 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a ].** </table>.**
3d0e0 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a </blockquote>.*
3d0f0 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 *.** The memory
3d100 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 pointed to by th
3d110 65 20 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e e character poin
3d120 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f ters returned fo
3d130 72 20 74 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61 r the.** declara
3d140 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f tion type and co
3d150 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 llation sequence
3d160 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 is valid only u
3d170 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a ntil the next.**
3d180 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c call to any SQL
3d190 69 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e ite API function
3d1a0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 ..**.** If the s
3d1b0 70 65 63 69 66 69 65 64 20 74 61 62 6c 65 20 69 pecified table i
3d1c0 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76 69 65 s actually a vie
3d1d0 77 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 w, an [error cod
3d1e0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a e] is returned..
3d1f0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65 **.** If the spe
3d200 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 cified column is
3d210 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 "rowid", "oid"
3d220 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 or "_rowid_" and
3d230 20 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45 52 20 an.** [INTEGER
3d240 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c PRIMARY KEY] col
3d250 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70 umn has been exp
3d260 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 licitly declared
3d270 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 , then the outpu
3d280 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 t.** parameters
3d290 61 72 65 20 73 65 74 20 66 6f 72 20 74 68 65 20 are set for the
3d2a0 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 explicitly decla
3d2b0 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 49 66 20 74 red column. If t
3d2c0 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 here is no.** ex
3d2d0 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 plicitly declare
3d2e0 64 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 d [INTEGER PRIMA
3d2f0 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 RY KEY] column,
3d300 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a then the output.
3d310 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 ** parameters ar
3d320 65 20 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 e set as follows
3d330 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a :.**.** <pre>.**
3d340 20 20 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 data type:
3d350 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 "INTEGER".**
3d360 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 collation seque
3d370 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a nce: "BINARY".**
3d380 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 not null: 0
3d390 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 .** primary
3d3a0 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 key: 1.** au
3d3b0 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a to increment: 0.
3d3c0 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 ** </pre>.**.**
3d3d0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 This function ma
3d3e0 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f y load one or mo
3d3f0 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 re schemas from
3d400 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20 database files.
3d410 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f If an.** error o
3d420 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 69 ccurs during thi
3d430 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 s process, or if
3d440 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 74 the requested t
3d450 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a able or column.*
3d460 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e * cannot be foun
3d470 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 d, an [error cod
3d480 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 e] is returned a
3d490 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 nd an error mess
3d4a0 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 age left.** in t
3d4b0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
3d4c0 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 nection] (to be
3d4d0 72 65 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 retrieved using
3d4e0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
3d4f0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 )..**.** This AP
3d500 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 I is only availa
3d510 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 ble if the libra
3d520 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 ry was compiled
3d530 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c with the.** [SQL
3d540 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d ITE_ENABLE_COLUM
3d550 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 N_METADATA] C-pr
3d560 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f eprocessor symbo
3d570 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e l defined..*/.in
3d580 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f t sqlite3_table_
3d590 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 column_metadata(
3d5a0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
3d5b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
3d5c0 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e * Connection han
3d5d0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 dle */. const c
3d5e0 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 har *zDbName,
3d5f0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
3d600 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f name or NULL */
3d610 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
3d620 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f TableName, /
3d630 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a * Table name */.
3d640 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 const char *zC
3d650 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a olumnName, /*
3d660 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a Column name */.
3d670 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 char const **p
3d680 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a zDataType, /*
3d690 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65 OUTPUT: Declare
3d6a0 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 d data type */.
3d6b0 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a char const **pz
3d6c0 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 CollSeq, /*
3d6d0 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f OUTPUT: Collatio
3d6e0 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 n sequence name
3d6f0 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 */. int *pNotNu
3d700 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 ll,
3d710 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 /* OUTPUT: True
3d720 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e if NOT NULL con
3d730 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a straint exists *
3d740 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 /. int *pPrimar
3d750 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20 20 yKey,
3d760 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 /* OUTPUT: True
3d770 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f if column part o
3d780 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 f PK */. int *p
3d790 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20 Autoinc
3d7a0 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a /* OUTPUT:
3d7b0 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 True if column
3d7c0 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e is auto-incremen
3d7d0 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 t */.);../*.** C
3d7e0 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e API3REF: Load An
3d7f0 20 45 78 74 65 6e 73 69 6f 6e 20 7b 48 31 32 36 Extension {H126
3d800 30 30 7d 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 00} <S20500>.**.
3d810 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 ** This interfac
3d820 65 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74 e loads an SQLit
3d830 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 e extension libr
3d840 61 72 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d ary from the nam
3d850 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b ed file..**.** {
3d860 48 31 32 36 30 31 7d 20 54 68 65 20 73 71 6c 69 H12601} The sqli
3d870 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 te3_load_extensi
3d880 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 on() interface a
3d890 74 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 ttempts to load
3d8a0 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 an.** S
3d8b0 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 QLite extension
3d8c0 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 library containe
3d8d0 64 20 69 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 d in the file zF
3d8e0 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 ile..**.** {H126
3d8f0 30 32 7d 20 54 68 65 20 65 6e 74 72 79 20 70 6f 02} The entry po
3d900 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a int is zProc..**
3d910 0a 2a 2a 20 7b 48 31 32 36 30 33 7d 20 7a 50 72 .** {H12603} zPr
3d920 6f 63 20 6d 61 79 20 62 65 20 30 2c 20 69 6e 20 oc may be 0, in
3d930 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e which case the n
3d940 61 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79 ame of the entry
3d950 20 70 6f 69 6e 74 0a 2a 2a 20 20 20 20 20 20 20 point.**
3d960 20 20 20 64 65 66 61 75 6c 74 73 20 74 6f 20 22 defaults to "
3d970 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 73 69 6f sqlite3_extensio
3d980 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 0a 2a 2a 20 7b n_init"..**.** {
3d990 48 31 32 36 30 34 7d 20 54 68 65 20 73 71 6c 69 H12604} The sqli
3d9a0 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 te3_load_extensi
3d9b0 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 on() interface s
3d9c0 68 61 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 hall return.**
3d9d0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f [SQLITE_
3d9e0 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 OK] on success a
3d9f0 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 nd [SQLITE_ERROR
3da00 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 ] if something g
3da10 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 0a 2a 2a oes wrong..**.**
3da20 20 7b 48 31 32 36 30 35 7d 20 49 66 20 61 6e 20 {H12605} If an
3da30 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 error occurs and
3da40 20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 pzErrMsg is not
3da50 20 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 0, then the.**
3da60 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
3da70 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 3_load_extension
3da80 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 ()] interface sh
3da90 61 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a all attempt to.*
3daa0 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 6c 20 * fill
3dab0 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20 65 *pzErrMsg with e
3dac0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 rror message tex
3dad0 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f t stored in memo
3dae0 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f ry.** o
3daf0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
3db00 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e lite3_malloc()].
3db10 20 7b 45 4e 44 7d 20 20 54 68 65 20 63 61 6c 6c {END} The call
3db20 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 ing function.**
3db30 20 20 20 20 20 20 20 20 20 73 68 6f 75 6c 64 20 should
3db40 66 72 65 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 free this memory
3db50 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c by calling [sql
3db60 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a ite3_free()]..**
3db70 0a 2a 2a 20 7b 48 31 32 36 30 36 7d 20 45 78 74 .** {H12606} Ext
3db80 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d ension loading m
3db90 75 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75 ust be enabled u
3dba0 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 sing.**
3dbb0 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 [sqlite3_enable
3dbc0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 _load_extension(
3dbd0 29 5d 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c )] prior to call
3dbe0 69 6e 67 20 74 68 69 73 20 41 50 49 2c 0a 2a 2a ing this API,.**
3dbf0 20 20 20 20 20 20 20 20 20 20 6f 74 68 65 72 77 otherw
3dc00 69 73 65 20 61 6e 20 65 72 72 6f 72 20 77 69 6c ise an error wil
3dc10 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a l be returned..*
3dc20 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f /.int sqlite3_lo
3dc30 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 ad_extension(.
3dc40 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
3dc50 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 /* Load th
3dc60 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f e extension into
3dc70 20 74 68 69 73 20 64 61 74 61 62 61 73 65 20 63 this database c
3dc80 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 onnection */. c
3dc90 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 onst char *zFile
3dca0 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 , /* Name of
3dcb0 74 68 65 20 73 68 61 72 65 64 20 6c 69 62 72 61 the shared libra
3dcc0 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 ry containing ex
3dcd0 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e tension */. con
3dce0 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 st char *zProc,
3dcf0 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e /* Entry poin
3dd00 74 2e 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d t. Derived from
3dd10 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 zFile if 0 */.
3dd20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 char **pzErrMsg
3dd30 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72 /* Put er
3dd40 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65 72 65 ror message here
3dd50 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a if not 0 */.);.
3dd60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
3dd70 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 Enable Or Disab
3dd80 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 le Extension Loa
3dd90 64 69 6e 67 20 7b 48 31 32 36 32 30 7d 20 3c 53 ding {H12620} <S
3dda0 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 6f 20 20500>.**.** So
3ddb0 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 as not to open s
3ddc0 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e ecurity holes in
3ddd0 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69 older applicati
3dde0 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 ons that are.**
3ddf0 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64 65 unprepared to de
3de00 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f al with extensio
3de10 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 n loading, and a
3de20 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 s a means of dis
3de30 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 abling.** extens
3de40 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c ion loading whil
3de50 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65 e evaluating use
3de60 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 r-entered SQL, t
3de70 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 he following API
3de80 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 64 20 .** is provided
3de90 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c to turn the [sql
3dea0 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 ite3_load_extens
3deb0 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d ion()] mechanism
3dec0 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a on and off..**.
3ded0 2a 2a 20 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 ** Extension loa
3dee0 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79 20 64 ding is off by d
3def0 65 66 61 75 6c 74 2e 20 53 65 65 20 74 69 63 6b efault. See tick
3df00 65 74 20 23 31 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 et #1863..**.**
3df10 7b 48 31 32 36 32 31 7d 20 43 61 6c 6c 20 74 68 {H12621} Call th
3df20 65 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 e sqlite3_enable
3df30 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 _load_extension(
3df40 29 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 6f ) routine with o
3df50 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 20 20 20 20 20 noff==1.**
3df60 20 20 20 20 74 6f 20 74 75 72 6e 20 65 78 74 65 to turn exte
3df70 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e nsion loading on
3df80 20 61 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 and call it wit
3df90 68 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 h onoff==0 to tu
3dfa0 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 rn.** i
3dfb0 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69 6e t back off again
3dfc0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 32 32 7d ..**.** {H12622}
3dfd0 20 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 Extension loadi
3dfe0 6e 67 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 ng is off by def
3dff0 61 75 6c 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c ault..*/.int sql
3e000 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 ite3_enable_load
3e010 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 _extension(sqlit
3e020 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 e3 *db, int onof
3e030 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 f);../*.** CAPI3
3e040 52 45 46 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c REF: Automatical
3e050 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e ly Load An Exten
3e060 73 69 6f 6e 73 20 7b 48 31 32 36 34 30 7d 20 3c sions {H12640} <
3e070 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S20500>.**.** Th
3e080 69 73 20 41 50 49 20 63 61 6e 20 62 65 20 69 6e is API can be in
3e090 76 6f 6b 65 64 20 61 74 20 70 72 6f 67 72 61 6d voked at program
3e0a0 20 73 74 61 72 74 75 70 20 69 6e 20 6f 72 64 65 startup in orde
3e0b0 72 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a r to register.**
3e0c0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 one or more sta
3e0d0 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 tically linked e
3e0e0 78 74 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 xtensions that w
3e0f0 69 6c 6c 20 62 65 20 61 76 61 69 6c 61 62 6c 65 ill be available
3e100 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 5b .** to all new [
3e110 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3e120 69 6f 6e 73 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a ions]. {END}.**.
3e130 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
3e140 73 74 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72 stores a pointer
3e150 20 74 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f to the extensio
3e160 6e 20 69 6e 20 61 6e 20 61 72 72 61 79 20 74 68 n in an array th
3e170 61 74 20 69 73 0a 2a 2a 20 6f 62 74 61 69 6e 65 at is.** obtaine
3e180 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
3e190 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 49 66 20 79 malloc()]. If y
3e1a0 6f 75 20 72 75 6e 20 61 20 6d 65 6d 6f 72 79 20 ou run a memory
3e1b0 6c 65 61 6b 20 63 68 65 63 6b 65 72 0a 2a 2a 20 leak checker.**
3e1c0 6f 6e 20 79 6f 75 72 20 70 72 6f 67 72 61 6d 20 on your program
3e1d0 61 6e 64 20 69 74 20 72 65 70 6f 72 74 73 20 61 and it reports a
3e1e0 20 6c 65 61 6b 20 62 65 63 61 75 73 65 20 6f 66 leak because of
3e1f0 20 74 68 69 73 20 61 72 72 61 79 2c 20 69 6e 76 this array, inv
3e200 6f 6b 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f oke.** [sqlite3_
3e210 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e reset_auto_exten
3e220 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f sion()] prior to
3e230 20 73 68 75 74 64 6f 77 6e 20 74 6f 20 66 72 65 shutdown to fre
3e240 65 20 74 68 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a e the memory..**
3e250 0a 2a 2a 20 7b 48 31 32 36 34 31 7d 20 54 68 69 .** {H12641} Thi
3e260 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 s function regis
3e270 74 65 72 73 20 61 6e 20 65 78 74 65 6e 73 69 6f ters an extensio
3e280 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 74 68 n entry point th
3e290 61 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 at is.**
3e2a0 20 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 automatically
3e2b0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 invoked whenever
3e2c0 20 61 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 a new [database
3e2d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 connection].**
3e2e0 20 20 20 20 20 20 20 20 20 69 73 20 6f 70 65 6e is open
3e2f0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ed using [sqlite
3e300 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 3_open()], [sqli
3e310 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a te3_open16()],.*
3e320 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 * or [s
3e330 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
3e340 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 32 ]..**.** {H12642
3e350 7d 20 44 75 70 6c 69 63 61 74 65 20 65 78 74 65 } Duplicate exte
3e360 6e 73 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63 nsions are detec
3e370 74 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 ted so calling t
3e380 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 20 his routine.**
3e390 20 20 20 20 20 20 20 20 6d 75 6c 74 69 70 6c 65 multiple
3e3a0 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 times with the
3e3b0 73 61 6d 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 same extension i
3e3c0 73 20 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a s harmless..**.*
3e3d0 2a 20 7b 48 31 32 36 34 33 7d 20 54 68 69 73 20 * {H12643} This
3e3e0 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61 routine stores a
3e3f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
3e400 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 extension in an
3e410 61 72 72 61 79 0a 2a 2a 20 20 20 20 20 20 20 20 array.**
3e420 20 20 74 68 61 74 20 69 73 20 6f 62 74 61 69 6e that is obtain
3e430 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
3e440 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a _malloc()]..**.*
3e450 2a 20 7b 48 31 32 36 34 34 7d 20 41 75 74 6f 6d * {H12644} Autom
3e460 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 atic extensions
3e470 61 70 70 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c apply across all
3e480 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 69 6e 74 threads..*/.int
3e490 20 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 sqlite3_auto_ex
3e4a0 74 65 6e 73 69 6f 6e 28 76 6f 69 64 20 28 2a 78 tension(void (*x
3e4b0 45 6e 74 72 79 50 6f 69 6e 74 29 28 76 6f 69 64 EntryPoint)(void
3e4c0 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 ));../*.** CAPI3
3e4d0 52 45 46 3a 20 52 65 73 65 74 20 41 75 74 6f 6d REF: Reset Autom
3e4e0 61 74 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c atic Extension L
3e4f0 6f 61 64 69 6e 67 20 7b 48 31 32 36 36 30 7d 20 oading {H12660}
3e500 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <S20500>.**.** T
3e510 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 his function dis
3e520 61 62 6c 65 73 20 61 6c 6c 20 70 72 65 76 69 6f ables all previo
3e530 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 20 usly registered
3e540 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 65 78 74 automatic.** ext
3e550 65 6e 73 69 6f 6e 73 2e 20 7b 45 4e 44 7d 20 20 ensions. {END}
3e560 49 74 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 It undoes the ef
3e570 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f fect of all prio
3e580 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 75 r.** [sqlite3_au
3e590 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 to_extension()]
3e5a0 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 calls..**.** {H1
3e5b0 32 36 36 31 7d 20 54 68 69 73 20 66 75 6e 63 74 2661} This funct
3e5c0 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 6c 6c ion disables all
3e5d0 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 previously regi
3e5e0 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 stered.**
3e5f0 20 20 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74 automatic ext
3e600 65 6e 73 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b ensions..**.** {
3e610 48 31 32 36 36 32 7d 20 54 68 69 73 20 66 75 6e H12662} This fun
3e620 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 ction disables a
3e630 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 utomatic extensi
3e640 6f 6e 73 20 69 6e 20 61 6c 6c 20 74 68 72 65 61 ons in all threa
3e650 64 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 ds..*/.void sqli
3e660 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 te3_reset_auto_e
3e670 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a xtension(void);.
3e680 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 ./*.****** EXPER
3e690 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 IMENTAL - subjec
3e6a0 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 t to change with
3e6b0 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a out notice *****
3e6c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 *********.**.**
3e6d0 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f The interface to
3e6e0 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 the virtual-tab
3e6f0 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 le mechanism is
3e700 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 currently consid
3e710 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 ered.** to be ex
3e720 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 perimental. The
3e730 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 interface might
3e740 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d change in incom
3e750 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a patible ways..**
3e760 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72 If this is a pr
3e770 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 oblem for you, d
3e780 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e o not use the in
3e790 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20 terface at this
3e7a0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e time..**.** When
3e7b0 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 the virtual-tab
3e7c0 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 le mechanism sta
3e7d0 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c bilizes, we will
3e7e0 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 declare the.**
3e7f0 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c interface fixed,
3e800 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 support it inde
3e810 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 finitely, and re
3e820 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e move this commen
3e830 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 t..*/../*.** Str
3e840 75 63 74 75 72 65 73 20 75 73 65 64 20 62 79 20 uctures used by
3e850 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c the virtual tabl
3e860 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 e interface.*/.t
3e870 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
3e880 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69 74 lite3_vtab sqlit
3e890 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 66 e3_vtab;.typedef
3e8a0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
3e8b0 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 index_info sqlit
3e8c0 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 e3_index_info;.t
3e8d0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
3e8e0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f lite3_vtab_curso
3e8f0 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 r sqlite3_vtab_c
3e900 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 ursor;.typedef s
3e910 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f truct sqlite3_mo
3e920 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 dule sqlite3_mod
3e930 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ule;../*.** CAPI
3e940 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 3REF: Virtual Ta
3e950 62 6c 65 20 4f 62 6a 65 63 74 20 7b 48 31 38 30 ble Object {H180
3e960 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 00} <S20400>.**
3e970 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 KEYWORDS: sqlite
3e980 33 5f 6d 6f 64 75 6c 65 0a 2a 2a 20 45 58 50 45 3_module.** EXPE
3e990 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 RIMENTAL.**.** A
3e9a0 20 6d 6f 64 75 6c 65 20 69 73 20 61 20 63 6c 61 module is a cla
3e9b0 73 73 20 6f 66 20 76 69 72 74 75 61 6c 20 74 61 ss of virtual ta
3e9c0 62 6c 65 73 2e 20 20 45 61 63 68 20 6d 6f 64 75 bles. Each modu
3e9d0 6c 65 20 69 73 20 64 65 66 69 6e 65 64 0a 2a 2a le is defined.**
3e9e0 20 62 79 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 by an instance
3e9f0 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 of the following
3ea00 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 69 structure. Thi
3ea10 73 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73 s structure cons
3ea20 69 73 74 73 0a 2a 2a 20 6d 6f 73 74 6c 79 20 6f ists.** mostly o
3ea30 66 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 f methods for th
3ea40 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 e module..**.**
3ea50 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 This interface i
3ea60 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 s experimental a
3ea70 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f nd is subject to
3ea80 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 change or.** re
3ea90 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20 moval in future
3eaa0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 releases of SQLi
3eab0 74 65 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 te..*/.struct sq
3eac0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 lite3_module {.
3ead0 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 int iVersion;.
3eae0 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28 int (*xCreate)(
3eaf0 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a sqlite3*, void *
3eb00 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 pAux,.
3eb10 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 int argc, c
3eb20 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 onst char *const
3eb30 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 *argv,.
3eb40 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 sqlite3_vt
3eb50 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 ab **ppVTab, cha
3eb60 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 r**);. int (*xC
3eb70 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a onnect)(sqlite3*
3eb80 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 , void *pAux,.
3eb90 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 int
3eba0 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 argc, const cha
3ebb0 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 r *const*argv,.
3ebc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 sq
3ebd0 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 lite3_vtab **ppV
3ebe0 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 Tab, char**);.
3ebf0 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78 int (*xBestIndex
3ec00 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a )(sqlite3_vtab *
3ec10 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 pVTab, sqlite3_i
3ec20 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 ndex_info*);. i
3ec30 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 nt (*xDisconnect
3ec40 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a )(sqlite3_vtab *
3ec50 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a pVTab);. int (*
3ec60 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65 xDestroy)(sqlite
3ec70 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 3_vtab *pVTab);.
3ec80 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 int (*xOpen)(s
3ec90 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 qlite3_vtab *pVT
3eca0 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62 ab, sqlite3_vtab
3ecb0 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 _cursor **ppCurs
3ecc0 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c or);. int (*xCl
3ecd0 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 ose)(sqlite3_vta
3ece0 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e b_cursor*);. in
3ecf0 74 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c t (*xFilter)(sql
3ed00 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 ite3_vtab_cursor
3ed10 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 *, int idxNum, c
3ed20 6f 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53 74 onst char *idxSt
3ed30 72 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 r,.
3ed40 20 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c int argc, sql
3ed50 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 ite3_value **arg
3ed60 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 v);. int (*xNex
3ed70 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f t)(sqlite3_vtab_
3ed80 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 cursor*);. int
3ed90 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f (*xEof)(sqlite3_
3eda0 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 vtab_cursor*);.
3edb0 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 int (*xColumn)(
3edc0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 sqlite3_vtab_cur
3edd0 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f sor*, sqlite3_co
3ede0 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 ntext*, int);.
3edf0 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71 int (*xRowid)(sq
3ee00 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f lite3_vtab_curso
3ee10 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 r*, sqlite3_int6
3ee20 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 4 *pRowid);. in
3ee30 74 20 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c t (*xUpdate)(sql
3ee40 69 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 ite3_vtab *, int
3ee50 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 , sqlite3_value
3ee60 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 **, sqlite3_int6
3ee70 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 4 *);. int (*xB
3ee80 65 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 egin)(sqlite3_vt
3ee90 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e ab *pVTab);. in
3eea0 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 t (*xSync)(sqlit
3eeb0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b e3_vtab *pVTab);
3eec0 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 . int (*xCommit
3eed0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a )(sqlite3_vtab *
3eee0 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a pVTab);. int (*
3eef0 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 xRollback)(sqlit
3ef00 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b e3_vtab *pVTab);
3ef10 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 . int (*xFindFu
3ef20 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f nction)(sqlite3_
3ef30 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 vtab *pVtab, int
3ef40 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 nArg, const cha
3ef50 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 r *zName,.
3ef60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3ef70 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 void (**pxFunc)
3ef80 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
3ef90 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
3efa0 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 lue**),.
3efb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 v
3efc0 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20 oid **ppArg);.
3efd0 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 int (*xRename)(s
3efe0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 qlite3_vtab *pVt
3eff0 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a ab, const char *
3f000 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a zNew);.};../*.**
3f010 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 CAPI3REF: Virtu
3f020 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69 6e al Table Indexin
3f030 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 7b 48 g Information {H
3f040 31 38 31 30 30 7d 20 3c 53 32 30 34 30 30 3e 0a 18100} <S20400>.
3f050 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c ** KEYWORDS: sql
3f060 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a ite3_index_info.
3f070 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a ** EXPERIMENTAL.
3f080 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
3f090 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 3_index_info str
3f0a0 75 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 ucture and its s
3f0b0 75 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20 ubstructures is
3f0c0 75 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20 used to.** pass
3f0d0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f information into
3f0e0 20 61 6e 64 20 72 65 63 65 69 76 65 20 74 68 65 and receive the
3f0f0 20 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 reply from the
3f100 78 42 65 73 74 49 6e 64 65 78 0a 2a 2a 20 6d 65 xBestIndex.** me
3f110 74 68 6f 64 20 6f 66 20 61 6e 20 73 71 6c 69 74 thod of an sqlit
3f120 65 33 5f 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 e3_module. The
3f130 66 69 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 fields under **I
3f140 6e 70 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a nputs** are the.
3f150 2a 2a 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65 ** inputs to xBe
3f160 73 74 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20 stIndex and are
3f170 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 read-only. xBes
3f180 74 49 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69 tIndex inserts i
3f190 74 73 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e ts.** results in
3f1a0 74 6f 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 to the **Outputs
3f1b0 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a ** fields..**.**
3f1c0 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 The aConstraint
3f1d0 5b 5d 20 61 72 72 61 79 20 72 65 63 6f 72 64 73 [] array records
3f1e0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f WHERE clause co
3f1f0 6e 73 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65 nstraints of the
3f200 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 form:.**.** <pr
3f210 65 3e 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 e>column OP expr
3f220 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 </pre>.**.** whe
3f230 72 65 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b re OP is =, <
3f240 2c 20 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f , <=, >, o
3f250 72 20 26 67 74 3b 3d 2e 20 20 54 68 65 20 70 61 r >=. The pa
3f260 72 74 69 63 75 6c 61 72 20 6f 70 65 72 61 74 6f rticular operato
3f270 72 20 69 73 0a 2a 2a 20 73 74 6f 72 65 64 20 69 r is.** stored i
3f280 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e n aConstraint[].
3f290 6f 70 2e 20 20 54 68 65 20 69 6e 64 65 78 20 6f op. The index o
3f2a0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 f the column is
3f2b0 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61 43 6f stored in.** aCo
3f2c0 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 nstraint[].iColu
3f2d0 6d 6e 2e 20 20 61 43 6f 6e 73 74 72 61 69 6e 74 mn. aConstraint
3f2e0 5b 5d 2e 75 73 61 62 6c 65 20 69 73 20 54 52 55 [].usable is TRU
3f2f0 45 20 69 66 20 74 68 65 0a 2a 2a 20 65 78 70 72 E if the.** expr
3f300 20 6f 6e 20 74 68 65 20 72 69 67 68 74 2d 68 61 on the right-ha
3f310 6e 64 20 73 69 64 65 20 63 61 6e 20 62 65 20 65 nd side can be e
3f320 76 61 6c 75 61 74 65 64 20 28 61 6e 64 20 74 68 valuated (and th
3f330 75 73 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e us the constrain
3f340 74 0a 2a 2a 20 69 73 20 75 73 61 62 6c 65 29 20 t.** is usable)
3f350 61 6e 64 20 66 61 6c 73 65 20 69 66 20 69 74 20 and false if it
3f360 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 cannot..**.** Th
3f370 65 20 6f 70 74 69 6d 69 7a 65 72 20 61 75 74 6f e optimizer auto
3f380 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 65 72 74 matically invert
3f390 73 20 74 65 72 6d 73 20 6f 66 20 74 68 65 20 66 s terms of the f
3f3a0 6f 72 6d 20 22 65 78 70 72 20 4f 50 20 63 6f 6c orm "expr OP col
3f3b0 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 umn".** and make
3f3c0 73 20 6f 74 68 65 72 20 73 69 6d 70 6c 69 66 69 s other simplifi
3f3d0 63 61 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 57 cations to the W
3f3e0 48 45 52 45 20 63 6c 61 75 73 65 20 69 6e 20 61 HERE clause in a
3f3f0 6e 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 n attempt to.**
3f400 67 65 74 20 61 73 20 6d 61 6e 79 20 57 48 45 52 get as many WHER
3f410 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 E clause terms i
3f420 6e 74 6f 20 74 68 65 20 66 6f 72 6d 20 73 68 6f nto the form sho
3f430 77 6e 20 61 62 6f 76 65 20 61 73 20 70 6f 73 73 wn above as poss
3f440 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 20 61 43 6f ible..** The aCo
3f450 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 nstraint[] array
3f460 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 57 48 only reports WH
3f470 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 ERE clause terms
3f480 20 69 6e 20 74 68 65 20 63 6f 72 72 65 63 74 0a in the correct.
3f490 2a 2a 20 66 6f 72 6d 20 74 68 61 74 20 72 65 66 ** form that ref
3f4a0 65 72 20 74 6f 20 74 68 65 20 70 61 72 74 69 63 er to the partic
3f4b0 75 6c 61 72 20 76 69 72 74 75 61 6c 20 74 61 62 ular virtual tab
3f4c0 6c 65 20 62 65 69 6e 67 20 71 75 65 72 69 65 64 le being queried
3f4d0 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66 6f 72 6d 61 74 ..**.** Informat
3f4e0 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52 ion about the OR
3f4f0 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 DER BY clause is
3f500 20 73 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 stored in aOrde
3f510 72 42 79 5b 5d 2e 0a 2a 2a 20 45 61 63 68 20 74 rBy[]..** Each t
3f520 65 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20 erm of aOrderBy
3f530 72 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e records a column
3f540 20 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 of the ORDER BY
3f550 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 clause..**.** T
3f560 68 65 20 78 42 65 73 74 49 6e 64 65 78 20 6d 65 he xBestIndex me
3f570 74 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 thod must fill a
3f580 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b ConstraintUsage[
3f590 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 ] with informati
3f5a0 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 on.** about what
3f5b0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70 parameters to p
3f5c0 61 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 ass to xFilter.
3f5d0 20 49 66 20 61 72 67 76 49 6e 64 65 78 3e 30 20 If argvIndex>0
3f5e0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 then.** the righ
3f5f0 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74 t-hand side of t
3f600 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
3f610 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 aConstraint[] i
3f620 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 s evaluated.** a
3f630 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 61 nd becomes the a
3f640 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 rgvIndex-th entr
3f650 79 20 69 6e 20 61 72 67 76 2e 20 20 49 66 20 61 y in argv. If a
3f660 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b ConstraintUsage[
3f670 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75 ].omit.** is tru
3f680 65 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 e, then the cons
3f690 74 72 61 69 6e 74 20 69 73 20 61 73 73 75 6d 65 traint is assume
3f6a0 64 20 74 6f 20 62 65 20 66 75 6c 6c 79 20 68 61 d to be fully ha
3f6b0 6e 64 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 ndled by the.**
3f6c0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e virtual table an
3f6d0 64 20 69 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 d is not checked
3f6e0 20 61 67 61 69 6e 20 62 79 20 53 51 4c 69 74 65 again by SQLite
3f6f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 64 78 4e ..**.** The idxN
3f700 75 6d 20 61 6e 64 20 69 64 78 50 74 72 20 76 61 um and idxPtr va
3f710 6c 75 65 73 20 61 72 65 20 72 65 63 6f 72 64 65 lues are recorde
3f720 64 20 61 6e 64 20 70 61 73 73 65 64 20 69 6e 74 d and passed int
3f730 6f 20 78 46 69 6c 74 65 72 2e 0a 2a 2a 20 73 71 o xFilter..** sq
3f740 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 lite3_free() is
3f750 75 73 65 64 20 74 6f 20 66 72 65 65 20 69 64 78 used to free idx
3f760 50 74 72 20 69 66 20 6e 65 65 64 54 6f 46 72 65 Ptr if needToFre
3f770 65 49 64 78 50 74 72 20 69 73 20 74 72 75 65 2e eIdxPtr is true.
3f780 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 72 64 65 72 .**.** The order
3f790 42 79 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73 ByConsumed means
3f7a0 20 74 68 61 74 20 6f 75 74 70 75 74 20 66 72 6f that output fro
3f7b0 6d 20 78 46 69 6c 74 65 72 20 77 69 6c 6c 20 6f m xFilter will o
3f7c0 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20 63 ccur in.** the c
3f7d0 6f 72 72 65 63 74 20 6f 72 64 65 72 20 74 6f 20 orrect order to
3f7e0 73 61 74 69 73 66 79 20 74 68 65 20 4f 52 44 45 satisfy the ORDE
3f7f0 52 20 42 59 20 63 6c 61 75 73 65 20 73 6f 20 74 R BY clause so t
3f800 68 61 74 20 6e 6f 20 73 65 70 61 72 61 74 65 0a hat no separate.
3f810 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74 65 70 20 ** sorting step
3f820 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a is required..**.
3f830 2a 2a 20 54 68 65 20 65 73 74 69 6d 61 74 65 64 ** The estimated
3f840 43 6f 73 74 20 76 61 6c 75 65 20 69 73 20 61 6e Cost value is an
3f850 20 65 73 74 69 6d 61 74 65 20 6f 66 20 74 68 65 estimate of the
3f860 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e 67 20 74 cost of doing t
3f870 68 65 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 he.** particular
3f880 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66 75 6c 6c lookup. A full
3f890 20 73 63 61 6e 20 6f 66 20 61 20 74 61 62 6c 65 scan of a table
3f8a0 20 77 69 74 68 20 4e 20 65 6e 74 72 69 65 73 20 with N entries
3f8b0 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 61 should have.** a
3f8c0 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20 41 20 62 cost of N. A b
3f8d0 69 6e 61 72 79 20 73 65 61 72 63 68 20 6f 66 20 inary search of
3f8e0 61 20 74 61 62 6c 65 20 6f 66 20 4e 20 65 6e 74 a table of N ent
3f8f0 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 ries should have
3f900 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 61 70 a.** cost of ap
3f910 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c 6f 67 28 proximately log(
3f920 4e 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 N)..**.** This i
3f930 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65 nterface is expe
3f940 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 rimental and is
3f950 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 subject to chang
3f960 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 e or.** removal
3f970 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
3f980 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f es of SQLite..*/
3f990 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
3f9a0 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f index_info {. /
3f9b0 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20 69 6e * Inputs */. in
3f9c0 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 t nConstraint;
3f9d0 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 /* Numb
3f9e0 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20 69 6e er of entries in
3f9f0 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a aConstraint */.
3fa00 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 struct sqlite3
3fa10 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e _index_constrain
3fa20 74 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f t {. int iCo
3fa30 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 lumn;
3fa40 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 /* Column on
3fa50 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f left-hand side o
3fa60 66 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a f constraint */.
3fa70 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 unsigned ch
3fa80 61 72 20 6f 70 3b 20 20 20 20 20 20 20 20 20 2f ar op; /
3fa90 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65 * Constraint ope
3faa0 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e rator */. un
3fab0 73 69 67 6e 65 64 20 63 68 61 72 20 75 73 61 62 signed char usab
3fac0 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72 75 65 20 le; /* True
3fad0 69 66 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 if this constrai
3fae0 6e 74 20 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a nt is usable */.
3faf0 20 20 20 20 20 69 6e 74 20 69 54 65 72 6d 4f 66 int iTermOf
3fb00 66 73 65 74 3b 20 20 20 20 20 20 20 20 20 20 2f fset; /
3fb10 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c * Used internall
3fb20 79 20 2d 20 78 42 65 73 74 49 6e 64 65 78 20 73 y - xBestIndex s
3fb30 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a hould ignore */.
3fb40 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 } *aConstraint
3fb50 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 ; /*
3fb60 54 61 62 6c 65 20 6f 66 20 57 48 45 52 45 20 63 Table of WHERE c
3fb70 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 lause constraint
3fb80 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72 64 65 s */. int nOrde
3fb90 72 42 79 3b 20 20 20 20 20 20 20 20 20 20 20 20 rBy;
3fba0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74 /* Number of t
3fbb0 65 72 6d 73 20 69 6e 20 74 68 65 20 4f 52 44 45 erms in the ORDE
3fbc0 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 R BY clause */.
3fbd0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
3fbe0 69 6e 64 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a index_orderby {.
3fbf0 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e int iColumn
3fc00 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f ; /
3fc10 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 * Column number
3fc20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 */. unsigned
3fc30 20 63 68 61 72 20 64 65 73 63 3b 20 20 20 20 20 char desc;
3fc40 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 20 44 45 /* True for DE
3fc50 53 43 2e 20 20 46 61 6c 73 65 20 66 6f 72 20 41 SC. False for A
3fc60 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64 SC. */. } *aOrd
3fc70 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20 20 erBy;
3fc80 20 20 20 20 2f 2a 20 54 68 65 20 4f 52 44 45 52 /* The ORDER
3fc90 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 BY clause */.
3fca0 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20 /* Outputs */.
3fcb0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 struct sqlite3_i
3fcc0 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f ndex_constraint_
3fcd0 75 73 61 67 65 20 7b 0a 20 20 20 20 69 6e 74 20 usage {. int
3fce0 61 72 67 76 49 6e 64 65 78 3b 20 20 20 20 20 20 argvIndex;
3fcf0 20 20 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63 /* if >0, c
3fd00 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 70 61 72 onstraint is par
3fd10 74 20 6f 66 20 61 72 67 76 20 74 6f 20 78 46 69 t of argv to xFi
3fd20 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69 lter */. unsi
3fd30 67 6e 65 64 20 63 68 61 72 20 6f 6d 69 74 3b 20 gned char omit;
3fd40 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 /* Do not c
3fd50 6f 64 65 20 61 20 74 65 73 74 20 66 6f 72 20 74 ode a test for t
3fd60 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a his constraint *
3fd70 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 /. } *aConstrai
3fd80 6e 74 55 73 61 67 65 3b 0a 20 20 69 6e 74 20 69 ntUsage;. int i
3fd90 64 78 4e 75 6d 3b 20 20 20 20 20 20 20 20 20 20 dxNum;
3fda0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 /* Number
3fdb0 75 73 65 64 20 74 6f 20 69 64 65 6e 74 69 66 79 used to identify
3fdc0 20 74 68 65 20 69 6e 64 65 78 20 2a 2f 0a 20 20 the index */.
3fdd0 63 68 61 72 20 2a 69 64 78 53 74 72 3b 20 20 20 char *idxStr;
3fde0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 /* St
3fdf0 72 69 6e 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f ring, possibly o
3fe00 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c btained from sql
3fe10 69 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 ite3_malloc */.
3fe20 20 69 6e 74 20 6e 65 65 64 54 6f 46 72 65 65 49 int needToFreeI
3fe30 64 78 53 74 72 3b 20 20 20 20 20 20 2f 2a 20 46 dxStr; /* F
3fe40 72 65 65 20 69 64 78 53 74 72 20 75 73 69 6e 67 ree idxStr using
3fe50 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 sqlite3_free()
3fe60 69 66 20 74 72 75 65 20 2a 2f 0a 20 20 69 6e 74 if true */. int
3fe70 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 orderByConsumed
3fe80 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20 ; /* True
3fe90 69 66 20 6f 75 74 70 75 74 20 69 73 20 61 6c 72 if output is alr
3fea0 65 61 64 79 20 6f 72 64 65 72 65 64 20 2a 2f 0a eady ordered */.
3feb0 20 20 64 6f 75 62 6c 65 20 65 73 74 69 6d 61 74 double estimat
3fec0 65 64 43 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20 edCost; /*
3fed0 45 73 74 69 6d 61 74 65 64 20 63 6f 73 74 20 6f Estimated cost o
3fee0 66 20 75 73 69 6e 67 20 74 68 69 73 20 69 6e 64 f using this ind
3fef0 65 78 20 2a 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65 ex */.};.#define
3ff00 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f SQLITE_INDEX_CO
3ff10 4e 53 54 52 41 49 4e 54 5f 45 51 20 20 20 20 32 NSTRAINT_EQ 2
3ff20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3ff30 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 INDEX_CONSTRAINT
3ff40 5f 47 54 20 20 20 20 34 0a 23 64 65 66 69 6e 65 _GT 4.#define
3ff50 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f SQLITE_INDEX_CO
3ff60 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20 20 20 38 NSTRAINT_LE 8
3ff70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3ff80 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 INDEX_CONSTRAINT
3ff90 5f 4c 54 20 20 20 20 31 36 0a 23 64 65 66 69 6e _LT 16.#defin
3ffa0 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 e SQLITE_INDEX_C
3ffb0 4f 4e 53 54 52 41 49 4e 54 5f 47 45 20 20 20 20 ONSTRAINT_GE
3ffc0 33 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 32.#define SQLIT
3ffd0 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 E_INDEX_CONSTRAI
3ffe0 4e 54 5f 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a NT_MATCH 64../*.
3fff0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 ** CAPI3REF: Reg
40000 69 73 74 65 72 20 41 20 56 69 72 74 75 61 6c 20 ister A Virtual
40010 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 Table Implementa
40020 74 69 6f 6e 20 7b 48 31 38 32 30 30 7d 20 3c 53 tion {H18200} <S
40030 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 20400>.** EXPERI
40040 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 MENTAL.**.** Thi
40050 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 65 s routine is use
40060 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 20 d to register a
40070 6e 65 77 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 new module name
40080 77 69 74 68 20 61 0a 2a 2a 20 5b 64 61 74 61 62 with a.** [datab
40090 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e ase connection].
400a0 20 20 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d Module names m
400b0 75 73 74 20 62 65 20 72 65 67 69 73 74 65 72 65 ust be registere
400c0 64 20 62 65 66 6f 72 65 0a 2a 2a 20 63 72 65 61 d before.** crea
400d0 74 69 6e 67 20 6e 65 77 20 76 69 72 74 75 61 6c ting new virtual
400e0 20 74 61 62 6c 65 73 20 6f 6e 20 74 68 65 20 6d tables on the m
400f0 6f 64 75 6c 65 2c 20 6f 72 20 62 65 66 6f 72 65 odule, or before
40100 20 75 73 69 6e 67 0a 2a 2a 20 70 72 65 65 78 69 using.** preexi
40110 73 74 69 6e 67 20 76 69 72 74 75 61 6c 20 74 61 sting virtual ta
40120 62 6c 65 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 bles of the modu
40130 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 le..**.** This i
40140 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65 nterface is expe
40150 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 rimental and is
40160 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 subject to chang
40170 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20 e or.** removal
40180 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
40190 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f es of SQLite..*/
401a0 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 .SQLITE_EXPERIME
401b0 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 NTAL int sqlite3
401c0 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a _create_module(.
401d0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
401e0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
401f0 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f SQLite connectio
40200 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f n to register mo
40210 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 dule with */. c
40220 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
40230 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d , /* Nam
40240 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 e of the module
40250 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 */. const sqlit
40260 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 20 20 e3_module *,
40270 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 /* Methods for t
40280 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 he module */. v
40290 6f 69 64 20 2a 20 20 20 20 20 20 20 20 20 20 20 oid *
402a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 /* Cli
402b0 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 ent data for xCr
402c0 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f eate/xConnect */
402d0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
402e0 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 REF: Register A
402f0 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6d Virtual Table Im
40300 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 7b 48 31 plementation {H1
40310 38 32 31 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 8210} <S20400>.*
40320 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
40330 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
40340 65 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 e is identical t
40350 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 o the [sqlite3_c
40360 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 reate_module()]
40370 6d 65 74 68 6f 64 20 61 62 6f 76 65 2c 0a 2a 2a method above,.**
40380 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 except that it
40390 61 6c 6c 6f 77 73 20 61 20 64 65 73 74 72 75 63 allows a destruc
403a0 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 tor function to
403b0 62 65 20 73 70 65 63 69 66 69 65 64 2e 20 49 74 be specified. It
403c0 20 69 73 0a 2a 2a 20 65 76 65 6e 20 6d 6f 72 65 is.** even more
403d0 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 74 68 experimental th
403e0 61 6e 20 74 68 65 20 72 65 73 74 20 6f 66 20 74 an the rest of t
403f0 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 he virtual table
40400 73 20 41 50 49 2e 0a 2a 2f 0a 53 51 4c 49 54 45 s API..*/.SQLITE
40410 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e _EXPERIMENTAL in
40420 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
40430 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73 71 _module_v2(. sq
40440 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
40450 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 /* SQLi
40460 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f te connection to
40470 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 register module
40480 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 with */. const
40490 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 char *zName,
404a0 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 /* Name of
404b0 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 the module */.
404c0 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d const sqlite3_m
404d0 6f 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d odule *, /* M
404e0 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d ethods for the m
404f0 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 odule */. void
40500 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 *,
40510 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 /* Client
40520 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 data for xCreate
40530 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 76 /xConnect */. v
40540 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 oid(*xDestroy)(v
40550 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f 64 oid*) /* Mod
40560 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 ule destructor f
40570 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f unction */.);../
40580 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 *.** CAPI3REF: V
40590 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 73 irtual Table Ins
405a0 74 61 6e 63 65 20 4f 62 6a 65 63 74 20 7b 48 31 tance Object {H1
405b0 38 30 31 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 8010} <S20400>.*
405c0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 * KEYWORDS: sqli
405d0 74 65 33 5f 76 74 61 62 0a 2a 2a 20 45 58 50 45 te3_vtab.** EXPE
405e0 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 RIMENTAL.**.** E
405f0 76 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c very module impl
40600 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 ementation uses
40610 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 a subclass of th
40620 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 e following stru
40630 63 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63 cture.** to desc
40640 72 69 62 65 20 61 20 70 61 72 74 69 63 75 6c 61 ribe a particula
40650 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 r instance of th
40660 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 e module. Each
40670 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a subclass will.**
40680 20 62 65 20 74 61 69 6c 6f 72 65 64 20 74 6f 20 be tailored to
40690 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 the specific nee
406a0 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 ds of the module
406b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e implementation.
406c0 0a 2a 2a 20 54 68 65 20 70 75 72 70 6f 73 65 20 .** The purpose
406d0 6f 66 20 74 68 69 73 20 73 75 70 65 72 63 6c 61 of this supercla
406e0 73 73 20 69 73 20 74 6f 20 64 65 66 69 6e 65 20 ss is to define
406f0 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73 20 74 certain fields t
40700 68 61 74 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f hat are.** commo
40710 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 n to all module
40720 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e implementations.
40730 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 .**.** Virtual t
40740 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 20 63 61 ables methods ca
40750 6e 20 73 65 74 20 61 6e 20 65 72 72 6f 72 20 6d n set an error m
40760 65 73 73 61 67 65 20 62 79 20 61 73 73 69 67 6e essage by assign
40770 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20 ing a.** string
40780 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 obtained from [s
40790 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 qlite3_mprintf()
407a0 5d 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 ] to zErrMsg. T
407b0 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 he method should
407c0 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 74 68 .** take care th
407d0 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73 74 72 at any prior str
407e0 69 6e 67 20 69 73 20 66 72 65 65 64 20 62 79 20 ing is freed by
407f0 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 a call to [sqlit
40800 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 70 72 e3_free()].** pr
40810 69 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 ior to assigning
40820 20 61 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f a new string to
40830 20 7a 45 72 72 4d 73 67 2e 20 20 41 66 74 65 72 zErrMsg. After
40840 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
40850 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 ge.** is deliver
40860 65 64 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69 ed up to the cli
40870 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c ent application,
40880 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c the string will
40890 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c be automaticall
408a0 79 0a 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71 y.** freed by sq
408b0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64 lite3_free() and
408c0 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 the zErrMsg fie
408d0 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 ld will be zeroe
408e0 64 2e 20 20 4e 6f 74 65 0a 2a 2a 20 74 68 61 74 d. Note.** that
408f0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 sqlite3_mprintf
40900 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 66 () and sqlite3_f
40910 72 65 65 28 29 20 61 72 65 20 75 73 65 64 20 6f ree() are used o
40920 6e 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 n the zErrMsg fi
40930 65 6c 64 0a 2a 2a 20 73 69 6e 63 65 20 76 69 72 eld.** since vir
40940 74 75 61 6c 20 74 61 62 6c 65 73 20 61 72 65 20 tual tables are
40950 63 6f 6d 6d 6f 6e 6c 79 20 69 6d 70 6c 65 6d 65 commonly impleme
40960 6e 74 65 64 20 69 6e 20 6c 6f 61 64 61 62 6c 65 nted in loadable
40970 20 65 78 74 65 6e 73 69 6f 6e 73 20 77 68 69 63 extensions whic
40980 68 0a 2a 2a 20 64 6f 20 6e 6f 74 20 68 61 76 65 h.** do not have
40990 20 61 63 63 65 73 73 20 74 6f 20 73 71 6c 69 74 access to sqlit
409a0 65 33 4d 50 72 69 6e 74 66 28 29 20 6f 72 20 73 e3MPrintf() or s
409b0 71 6c 69 74 65 33 46 72 65 65 28 29 2e 0a 2a 2a qlite3Free()..**
409c0 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 .** This interfa
409d0 63 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 ce is experiment
409e0 61 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 al and is subjec
409f0 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a t to change or.*
40a00 2a 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 * removal in fut
40a10 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 ure releases of
40a20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 73 74 72 75 63 SQLite..*/.struc
40a30 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 7b t sqlite3_vtab {
40a40 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 . const sqlite3
40a50 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 _module *pModule
40a60 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65 ; /* The module
40a70 20 66 6f 72 20 74 68 69 73 20 76 69 72 74 75 61 for this virtua
40a80 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 l table */. int
40a90 20 6e 52 65 66 3b 20 20 20 20 20 20 20 20 20 20 nRef;
40aa0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
40ab0 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 Used internally
40ac0 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72 72 4d */. char *zErrM
40ad0 73 67 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 sg;
40ae0 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65 /* Error me
40af0 73 73 61 67 65 20 66 72 6f 6d 20 73 71 6c 69 74 ssage from sqlit
40b00 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a e3_mprintf() */.
40b10 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 /* Virtual tab
40b20 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
40b30 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c ns will typicall
40b40 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c y add additional
40b50 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f fields */.};../
40b60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 *.** CAPI3REF: V
40b70 69 72 74 75 61 6c 20 54 61 62 6c 65 20 43 75 72 irtual Table Cur
40b80 73 6f 72 20 4f 62 6a 65 63 74 20 20 7b 48 31 38 sor Object {H18
40b90 30 32 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 020} <S20400>.**
40ba0 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 KEYWORDS: sqlit
40bb0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 0a 2a e3_vtab_cursor.*
40bc0 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
40bd0 2a 0a 2a 2a 20 45 76 65 72 79 20 6d 6f 64 75 6c *.** Every modul
40be0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
40bf0 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 uses a subclass
40c00 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e of the followin
40c10 67 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 74 g structure.** t
40c20 6f 20 64 65 73 63 72 69 62 65 20 63 75 72 73 6f o describe curso
40c30 72 73 20 74 68 61 74 20 70 6f 69 6e 74 20 69 6e rs that point in
40c40 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 to the virtual t
40c50 61 62 6c 65 20 61 6e 64 20 61 72 65 20 75 73 65 able and are use
40c60 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68 72 d.** to loop thr
40c70 6f 75 67 68 20 74 68 65 20 76 69 72 74 75 61 6c ough the virtual
40c80 20 74 61 62 6c 65 2e 20 20 43 75 72 73 6f 72 73 table. Cursors
40c90 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69 are created usi
40ca0 6e 67 20 74 68 65 0a 2a 2a 20 78 4f 70 65 6e 20 ng the.** xOpen
40cb0 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f method of the mo
40cc0 64 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 dule. Each modu
40cd0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
40ce0 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a n will define.**
40cf0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
40d00 61 20 63 75 72 73 6f 72 20 73 74 72 75 63 74 75 a cursor structu
40d10 72 65 20 74 6f 20 73 75 69 74 20 69 74 73 20 6f re to suit its o
40d20 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 wn needs..**.**
40d30 54 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 This superclass
40d40 65 78 69 73 74 73 20 69 6e 20 6f 72 64 65 72 20 exists in order
40d50 74 6f 20 64 65 66 69 6e 65 20 66 69 65 6c 64 73 to define fields
40d60 20 6f 66 20 74 68 65 20 63 75 72 73 6f 72 20 74 of the cursor t
40d70 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f hat.** are commo
40d80 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 n to all impleme
40d90 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 ntations..**.**
40da0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 This interface i
40db0 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 s experimental a
40dc0 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f nd is subject to
40dd0 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 change or.** re
40de0 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20 moval in future
40df0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 releases of SQLi
40e00 74 65 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 te..*/.struct sq
40e10 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f lite3_vtab_curso
40e20 72 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 74 r {. sqlite3_vt
40e30 61 62 20 2a 70 56 74 61 62 3b 20 20 20 20 20 20 ab *pVtab;
40e40 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 /* Virtual table
40e50 20 6f 66 20 74 68 69 73 20 63 75 72 73 6f 72 20 of this cursor
40e60 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 */. /* Virtual
40e70 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 table implementa
40e80 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 tions will typic
40e90 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f ally add additio
40ea0 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b nal fields */.};
40eb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
40ec0 3a 20 44 65 63 6c 61 72 65 20 54 68 65 20 53 63 : Declare The Sc
40ed0 68 65 6d 61 20 4f 66 20 41 20 56 69 72 74 75 61 hema Of A Virtua
40ee0 6c 20 54 61 62 6c 65 20 7b 48 31 38 32 38 30 7d l Table {H18280}
40ef0 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50 <S20400>.** EXP
40f00 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 ERIMENTAL.**.**
40f10 54 68 65 20 78 43 72 65 61 74 65 20 61 6e 64 20 The xCreate and
40f20 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 73 xConnect methods
40f30 20 6f 66 20 61 20 6d 6f 64 75 6c 65 20 75 73 65 of a module use
40f40 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 the following A
40f50 50 49 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65 PI.** to declare
40f60 20 74 68 65 20 66 6f 72 6d 61 74 20 28 74 68 65 the format (the
40f70 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61 74 names and datat
40f80 79 70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 ypes of the colu
40f90 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76 mns) of.** the v
40fa0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 74 68 irtual tables th
40fb0 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2a ey implement..**
40fc0 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 .** This interfa
40fd0 63 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 ce is experiment
40fe0 61 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 al and is subjec
40ff0 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a t to change or.*
41000 2a 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 * removal in fut
41010 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 ure releases of
41020 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 SQLite..*/.SQLIT
41030 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 E_EXPERIMENTAL i
41040 6e 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 nt sqlite3_decla
41050 72 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a re_vtab(sqlite3*
41060 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 , const char *zC
41070 72 65 61 74 65 54 61 62 6c 65 29 3b 0a 0a 2f 2a reateTable);../*
41080 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 76 .** CAPI3REF: Ov
41090 65 72 6c 6f 61 64 20 41 20 46 75 6e 63 74 69 6f erload A Functio
410a0 6e 20 46 6f 72 20 41 20 56 69 72 74 75 61 6c 20 n For A Virtual
410b0 54 61 62 6c 65 20 7b 48 31 38 33 30 30 7d 20 3c Table {H18300} <
410c0 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 S20400>.** EXPER
410d0 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 56 69 IMENTAL.**.** Vi
410e0 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e rtual tables can
410f0 20 70 72 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 provide alterna
41100 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 tive implementat
41110 69 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e ions of function
41120 73 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 78 s.** using the x
41130 46 69 6e 64 46 75 6e 63 74 69 6f 6e 20 6d 65 74 FindFunction met
41140 68 6f 64 2e 20 20 42 75 74 20 67 6c 6f 62 61 6c hod. But global
41150 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f versions of tho
41160 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 se functions.**
41170 6d 75 73 74 20 65 78 69 73 74 20 69 6e 20 6f 72 must exist in or
41180 64 65 72 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f der to be overlo
41190 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 aded..**.** This
411a0 20 41 50 49 20 6d 61 6b 65 73 20 73 75 72 65 20 API makes sure
411b0 61 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e a global version
411c0 20 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 of a function w
411d0 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 ith a particular
411e0 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d .** name and num
411f0 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 ber of parameter
41200 73 20 65 78 69 73 74 73 2e 20 20 49 66 20 6e 6f s exists. If no
41210 20 73 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 65 such function e
41220 78 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20 xists.** before
41230 74 68 69 73 20 41 50 49 20 69 73 20 63 61 6c 6c this API is call
41240 65 64 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 69 ed, a new functi
41250 6f 6e 20 69 73 20 63 72 65 61 74 65 64 2e 20 20 on is created.
41260 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 The implementati
41270 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65 77 on.** of the new
41280 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79 73 function always
41290 20 63 61 75 73 65 73 20 61 6e 20 65 78 63 65 70 causes an excep
412a0 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f 77 tion to be throw
412b0 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 n. So.** the ne
412c0 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f w function is no
412d0 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74 68 t good for anyth
412e0 69 6e 67 20 62 79 20 69 74 73 65 6c 66 2e 20 20 ing by itself.
412f0 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 Its only.** purp
41300 6f 73 65 20 69 73 20 74 6f 20 62 65 20 61 20 70 ose is to be a p
41310 6c 61 63 65 68 6f 6c 64 65 72 20 66 75 6e 63 74 laceholder funct
41320 69 6f 6e 20 74 68 61 74 20 63 61 6e 20 62 65 20 ion that can be
41330 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 overloaded.** by
41340 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 2e virtual tables.
41350 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 .**.** This API
41360 73 68 6f 75 6c 64 20 62 65 20 63 6f 6e 73 69 64 should be consid
41370 65 72 65 64 20 70 61 72 74 20 6f 66 20 74 68 65 ered part of the
41380 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 virtual table i
41390 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 77 68 69 nterface,.** whi
413a0 63 68 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 ch is experiment
413b0 61 6c 20 61 6e 64 20 73 75 62 6a 65 63 74 20 74 al and subject t
413c0 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c o change..*/.SQL
413d0 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c ITE_EXPERIMENTAL
413e0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76 65 int sqlite3_ove
413f0 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28 73 rload_function(s
41400 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 qlite3*, const c
41410 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 har *zFuncName,
41420 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a int nArg);../*.*
41430 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 * The interface
41440 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 to the virtual-t
41450 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 64 able mechanism d
41460 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28 62 61 efined above (ba
41470 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63 6f ck up.** to a co
41480 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c 79 mment remarkably
41490 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 69 73 similar to this
414a0 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65 6e 74 one) is current
414b0 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a ly considered.**
414c0 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e to be experimen
414d0 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 tal. The interf
414e0 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 ace might change
414f0 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 in incompatible
41500 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 ways..** If thi
41510 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 s is a problem f
41520 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 or you, do not u
41530 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 se the interface
41540 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a at this time..*
41550 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 *.** When the vi
41560 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 rtual-table mech
41570 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 anism stabilizes
41580 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 , we will declar
41590 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 e the.** interfa
415a0 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 ce fixed, suppor
415b0 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c t it indefinitel
415c0 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 y, and remove th
415d0 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a is comment..**.*
415e0 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 ***** EXPERIMENT
415f0 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 AL - subject to
41600 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e change without n
41610 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a otice **********
41620 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 ****.*/../*.** C
41630 41 50 49 33 52 45 46 3a 20 41 20 48 61 6e 64 6c API3REF: A Handl
41640 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c 4f e To An Open BLO
41650 42 20 7b 48 31 37 38 30 30 7d 20 3c 53 33 30 32 B {H17800} <S302
41660 33 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 30>.** KEYWORDS:
41670 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 7d 20 7b {BLOB handle} {
41680 42 4c 4f 42 20 68 61 6e 64 6c 65 73 7d 0a 2a 2a BLOB handles}.**
41690 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 .** An instance
416a0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 of this object r
416b0 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 epresents an ope
416c0 6e 20 42 4c 4f 42 20 6f 6e 20 77 68 69 63 68 0a n BLOB on which.
416d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 ** [sqlite3_blob
416e0 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e _open | incremen
416f0 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 63 61 tal BLOB I/O] ca
41700 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 2e 0a n be performed..
41710 2a 2a 20 4f 62 6a 65 63 74 73 20 6f 66 20 74 68 ** Objects of th
41720 69 73 20 74 79 70 65 20 61 72 65 20 63 72 65 61 is type are crea
41730 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ted by [sqlite3_
41740 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 blob_open()].**
41750 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20 62 79 and destroyed by
41760 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 [sqlite3_blob_c
41770 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 lose()]..** The
41780 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 [sqlite3_blob_re
41790 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ad()] and [sqlit
417a0 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d e3_blob_write()]
417b0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 63 interfaces.** c
417c0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 an be used to re
417d0 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61 6c ad or write smal
417e0 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f 66 l subsections of
417f0 20 74 68 65 20 42 4c 4f 42 2e 0a 2a 2a 20 54 68 the BLOB..** Th
41800 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f e [sqlite3_blob_
41810 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 bytes()] interfa
41820 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 ce returns the s
41830 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 ize of the BLOB
41840 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 in bytes..*/.typ
41850 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
41860 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74 65 33 te3_blob sqlite3
41870 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 _blob;../*.** CA
41880 50 49 33 52 45 46 3a 20 4f 70 65 6e 20 41 20 42 PI3REF: Open A B
41890 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d 65 6e LOB For Incremen
418a0 74 61 6c 20 49 2f 4f 20 7b 48 31 37 38 31 30 7d tal I/O {H17810}
418b0 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 <S30230>.**.**
418c0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 73 20 This interfaces
418d0 6f 70 65 6e 73 20 61 20 5b 42 4c 4f 42 20 68 61 opens a [BLOB ha
418e0 6e 64 6c 65 20 7c 20 68 61 6e 64 6c 65 5d 20 74 ndle | handle] t
418f0 6f 20 74 68 65 20 42 4c 4f 42 20 6c 6f 63 61 74 o the BLOB locat
41900 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 20 69 52 6f ed.** in row iRo
41910 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d w, column zColum
41920 6e 2c 20 74 61 62 6c 65 20 7a 54 61 62 6c 65 20 n, table zTable
41930 69 6e 20 64 61 74 61 62 61 73 65 20 7a 44 62 3b in database zDb;
41940 0a 2a 2a 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 .** in other wor
41950 64 73 2c 20 74 68 65 20 73 61 6d 65 20 42 4c 4f ds, the same BLO
41960 42 20 74 68 61 74 20 77 6f 75 6c 64 20 62 65 20 B that would be
41970 73 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a selected by:.**.
41980 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 ** <pre>.**
41990 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 SELECT zColumn F
419a0 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57 ROM zDb.zTable W
419b0 48 45 52 45 20 5b 72 6f 77 69 64 5d 20 3d 20 69 HERE [rowid] = i
419c0 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 20 7b Row;.** </pre> {
419d0 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 END}.**.** If th
419e0 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 e flags paramete
419f0 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 r is non-zero, t
41a00 68 65 20 74 68 65 20 42 4c 4f 42 20 69 73 20 6f he the BLOB is o
41a10 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 0a 2a pened for read.*
41a20 2a 20 61 6e 64 20 77 72 69 74 65 20 61 63 63 65 * and write acce
41a30 73 73 2e 20 49 66 20 69 74 20 69 73 20 7a 65 72 ss. If it is zer
41a40 6f 2c 20 74 68 65 20 42 4c 4f 42 20 69 73 20 6f o, the BLOB is o
41a50 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 20 61 pened for read a
41a60 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 ccess..**.** Not
41a70 65 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 e that the datab
41a80 61 73 65 20 6e 61 6d 65 20 69 73 20 6e 6f 74 20 ase name is not
41a90 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 74 68 61 the filename tha
41aa0 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 t contains.** th
41ab0 65 20 64 61 74 61 62 61 73 65 20 62 75 74 20 72 e database but r
41ac0 61 74 68 65 72 20 74 68 65 20 73 79 6d 62 6f 6c ather the symbol
41ad0 69 63 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 ic name of the d
41ae0 61 74 61 62 61 73 65 20 74 68 61 74 0a 2a 2a 20 atabase that.**
41af0 69 73 20 61 73 73 69 67 6e 65 64 20 77 68 65 6e is assigned when
41b00 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 the database is
41b10 20 63 6f 6e 6e 65 63 74 65 64 20 75 73 69 6e 67 connected using
41b20 20 5b 41 54 54 41 43 48 5d 2e 0a 2a 2a 20 46 6f [ATTACH]..** Fo
41b30 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 r the main datab
41b40 61 73 65 20 66 69 6c 65 2c 20 74 68 65 20 64 61 ase file, the da
41b50 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22 tabase name is "
41b60 6d 61 69 6e 22 2e 0a 2a 2a 20 46 6f 72 20 54 45 main"..** For TE
41b70 4d 50 20 74 61 62 6c 65 73 2c 20 74 68 65 20 64 MP tables, the d
41b80 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 atabase name is
41b90 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 4f 6e "temp"..**.** On
41ba0 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 success, [SQLIT
41bb0 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 E_OK] is returne
41bc0 64 20 61 6e 64 20 74 68 65 20 6e 65 77 20 5b 42 d and the new [B
41bd0 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 LOB handle] is w
41be0 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70 ritten.** to *pp
41bf0 42 6c 6f 62 2e 20 4f 74 68 65 72 77 69 73 65 20 Blob. Otherwise
41c00 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 an [error code]
41c10 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 is returned and
41c20 61 6e 79 20 76 61 6c 75 65 20 77 72 69 74 74 65 any value writte
41c30 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c 6f 62 20 n.** to *ppBlob
41c40 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 should not be us
41c50 65 64 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72 ed by the caller
41c60 2e 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 ..** This functi
41c70 6f 6e 20 73 65 74 73 20 74 68 65 20 5b 64 61 74 on sets the [dat
41c80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
41c90 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 ] error code and
41ca0 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61 63 63 65 message.** acce
41cb0 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 ssible via [sqli
41cc0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 61 te3_errcode()] a
41cd0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d nd [sqlite3_errm
41ce0 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 sg()]..**.** If
41cf0 74 68 65 20 72 6f 77 20 74 68 61 74 20 61 20 42 the row that a B
41d00 4c 4f 42 20 68 61 6e 64 6c 65 20 70 6f 69 6e 74 LOB handle point
41d10 73 20 74 6f 20 69 73 20 6d 6f 64 69 66 69 65 64 s to is modified
41d20 20 62 79 20 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 by an.** [UPDAT
41d30 45 5d 2c 20 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 E], [DELETE], or
41d40 20 62 79 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 by [ON CONFLICT
41d50 5d 20 73 69 64 65 2d 65 66 66 65 63 74 73 0a 2a ] side-effects.*
41d60 2a 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 * then the BLOB
41d70 68 61 6e 64 6c 65 20 69 73 20 6d 61 72 6b 65 64 handle is marked
41d80 20 61 73 20 22 65 78 70 69 72 65 64 22 2e 0a 2a as "expired"..*
41d90 2a 20 54 68 69 73 20 69 73 20 74 72 75 65 20 69 * This is true i
41da0 66 20 61 6e 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 f any column of
41db0 74 68 65 20 72 6f 77 20 69 73 20 63 68 61 6e 67 the row is chang
41dc0 65 64 2c 20 65 76 65 6e 20 61 20 63 6f 6c 75 6d ed, even a colum
41dd0 6e 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 n.** other than
41de0 74 68 65 20 6f 6e 65 20 74 68 65 20 42 4c 4f 42 the one the BLOB
41df0 20 68 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e 20 handle is open
41e00 6f 6e 2e 0a 2a 2a 20 43 61 6c 6c 73 20 74 6f 20 on..** Calls to
41e10 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 [sqlite3_blob_re
41e20 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ad()] and [sqlit
41e30 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d e3_blob_write()]
41e40 20 66 6f 72 0a 2a 2a 20 61 20 65 78 70 69 72 65 for.** a expire
41e50 64 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 66 61 d BLOB handle fa
41e60 69 6c 20 77 69 74 68 20 61 6e 20 72 65 74 75 72 il with an retur
41e70 6e 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 n code of [SQLIT
41e80 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20 43 68 61 E_ABORT]..** Cha
41e90 6e 67 65 73 20 77 72 69 74 74 65 6e 20 69 6e 74 nges written int
41ea0 6f 20 61 20 42 4c 4f 42 20 70 72 69 6f 72 20 74 o a BLOB prior t
41eb0 6f 20 74 68 65 20 42 4c 4f 42 20 65 78 70 69 72 o the BLOB expir
41ec0 69 6e 67 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 ing are not.** r
41ed0 6f 6c 6c 62 61 63 6b 20 62 79 20 74 68 65 20 65 ollback by the e
41ee0 78 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 xpiration of the
41ef0 20 42 4c 4f 42 2e 20 20 53 75 63 68 20 63 68 61 BLOB. Such cha
41f00 6e 67 65 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 nges will eventu
41f10 61 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d 69 74 20 69 ally.** commit i
41f20 66 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f f the transactio
41f30 6e 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 n continues to c
41f40 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a ompletion..**.**
41f50 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a INVARIANTS:.**.
41f60 2a 2a 20 7b 48 31 37 38 31 33 7d 20 41 20 73 75 ** {H17813} A su
41f70 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 ccessful invocat
41f80 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 ion of the [sqli
41f90 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 44 2c te3_blob_open(D,
41fa0 42 2c 54 2c 43 2c 52 2c 46 2c 50 29 5d 0a 2a 2a B,T,C,R,F,P)].**
41fb0 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 interf
41fc0 61 63 65 20 73 68 61 6c 6c 20 6f 70 65 6e 20 61 ace shall open a
41fd0 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d n [sqlite3_blob]
41fe0 20 6f 62 6a 65 63 74 20 50 20 6f 6e 20 74 68 65 object P on the
41ff0 20 42 4c 4f 42 0a 2a 2a 20 20 20 20 20 20 20 20 BLOB.**
42000 20 20 69 6e 20 63 6f 6c 75 6d 6e 20 43 20 6f 66 in column C of
42010 20 74 68 65 20 74 61 62 6c 65 20 54 20 69 6e 20 the table T in
42020 74 68 65 20 64 61 74 61 62 61 73 65 20 42 20 6f the database B o
42030 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 n.** th
42040 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
42050 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a ection] D..**.**
42060 20 7b 48 31 37 38 31 34 7d 20 41 20 73 75 63 63 {H17814} A succ
42070 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f essful invocatio
42080 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 62 6c n of [sqlite3_bl
42090 6f 62 5f 6f 70 65 6e 28 44 2c 2e 2e 2e 29 5d 20 ob_open(D,...)]
420a0 73 68 61 6c 6c 20 73 74 61 72 74 0a 2a 2a 20 20 shall start.**
420b0 20 20 20 20 20 20 20 20 61 20 6e 65 77 20 74 72 a new tr
420c0 61 6e 73 61 63 74 69 6f 6e 20 6f 6e 20 74 68 65 ansaction on the
420d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
420e0 63 74 69 6f 6e 5d 20 44 20 69 66 20 74 68 61 74 ction] D if that
420f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e .** con
42100 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 nection is not a
42110 6c 72 65 61 64 79 20 69 6e 20 61 20 74 72 61 6e lready in a tran
42120 73 61 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b saction..**.** {
42130 48 31 37 38 31 36 7d 20 54 68 65 20 5b 73 71 6c H17816} The [sql
42140 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 44 ite3_blob_open(D
42150 2c 42 2c 54 2c 43 2c 52 2c 46 2c 50 29 5d 20 69 ,B,T,C,R,F,P)] i
42160 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 6f nterface shall o
42170 70 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 pen.**
42180 74 68 65 20 42 4c 4f 42 20 66 6f 72 20 72 65 61 the BLOB for rea
42190 64 20 61 6e 64 20 77 72 69 74 65 20 61 63 63 65 d and write acce
421a0 73 73 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 ss if and only i
421b0 66 20 74 68 65 20 46 0a 2a 2a 20 20 20 20 20 20 f the F.**
421c0 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 69 73 parameter is
421d0 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a non-zero..**.**
421e0 20 7b 48 31 37 38 31 39 7d 20 54 68 65 20 5b 73 {H17819} The [s
421f0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e qlite3_blob_open
42200 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 ()] interface sh
42210 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 all return [SQLI
42220 54 45 5f 4f 4b 5d 20 6f 6e 0a 2a 2a 20 20 20 20 TE_OK] on.**
42230 20 20 20 20 20 20 73 75 63 63 65 73 73 20 61 6e success an
42240 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 d an appropriate
42250 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e [error code] on
42260 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 failure..**.**
42270 7b 48 31 37 38 32 31 7d 20 49 66 20 61 6e 20 65 {H17821} If an e
42280 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 rror occurs duri
42290 6e 67 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 ng evaluation of
422a0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f [sqlite3_blob_o
422b0 70 65 6e 28 44 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 pen(D,...)].**
422c0 20 20 20 20 20 20 20 20 74 68 65 6e 20 73 75 62 then sub
422d0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f sequent calls to
422e0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 [sqlite3_errcod
422f0 65 28 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 e(D)],.**
42300 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 [sqlite3_exte
42310 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d 2c nded_errcode()],
42320 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 .** [s
42330 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 44 29 qlite3_errmsg(D)
42340 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ], and [sqlite3_
42350 65 72 72 6d 73 67 31 36 28 44 29 5d 20 73 68 61 errmsg16(D)] sha
42360 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 ll return.**
42370 20 20 20 20 20 20 69 6e 66 6f 72 6d 61 74 69 6f informatio
42380 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f n appropriate fo
42390 72 20 74 68 61 74 20 65 72 72 6f 72 2e 0a 2a 2a r that error..**
423a0 0a 2a 2a 20 7b 48 31 37 38 32 34 7d 20 49 66 20 .** {H17824} If
423b0 61 6e 79 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 any column in th
423c0 65 20 72 6f 77 20 74 68 61 74 20 61 20 5b 73 71 e row that a [sq
423d0 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 68 61 73 20 lite3_blob] has
423e0 6f 70 65 6e 20 69 73 0a 2a 2a 20 20 20 20 20 20 open is.**
423f0 20 20 20 20 63 68 61 6e 67 65 64 20 62 79 20 61 changed by a
42400 20 73 65 70 61 72 61 74 65 20 5b 55 50 44 41 54 separate [UPDAT
42410 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 E] or [DELETE] s
42420 74 61 74 65 6d 65 6e 74 20 6f 72 20 62 79 0a 2a tatement or by.*
42430 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20 5b 4f * an [O
42440 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64 65 N CONFLICT] side
42450 20 65 66 66 65 63 74 2c 20 74 68 65 6e 20 74 68 effect, then th
42460 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d e [sqlite3_blob]
42470 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 shall.**
42480 20 20 20 62 65 20 6d 61 72 6b 65 64 20 61 73 20 be marked as
42490 69 6e 76 61 6c 69 64 2e 0a 2a 2f 0a 69 6e 74 20 invalid..*/.int
424a0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 sqlite3_blob_ope
424b0 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 n(. sqlite3*,.
424c0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 const char *zDb
424d0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a ,. const char *
424e0 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 zTable,. const
424f0 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 char *zColumn,.
42500 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 sqlite3_int64 i
42510 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73 Row,. int flags
42520 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 ,. sqlite3_blob
42530 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a **ppBlob.);../*
42540 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c .** CAPI3REF: Cl
42550 6f 73 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c ose A BLOB Handl
42560 65 20 7b 48 31 37 38 33 30 7d 20 3c 53 33 30 32 e {H17830} <S302
42570 33 30 3e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 73 30>.**.** Closes
42580 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 an open [BLOB h
42590 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 43 6c andle]..**.** Cl
425a0 6f 73 69 6e 67 20 61 20 42 4c 4f 42 20 73 68 61 osing a BLOB sha
425b0 6c 6c 20 63 61 75 73 65 20 74 68 65 20 63 75 72 ll cause the cur
425c0 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e rent transaction
425d0 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66 to commit.** if
425e0 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 6f 74 there are no ot
425f0 68 65 72 20 42 4c 4f 42 73 2c 20 6e 6f 20 70 65 her BLOBs, no pe
42600 6e 64 69 6e 67 20 70 72 65 70 61 72 65 64 20 73 nding prepared s
42610 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 74 tatements, and t
42620 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 he.** database c
42630 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20 onnection is in
42640 5b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 [autocommit mode
42650 5d 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 77 72 69 ]..** If any wri
42660 74 65 73 20 77 65 72 65 20 6d 61 64 65 20 74 6f tes were made to
42670 20 74 68 65 20 42 4c 4f 42 2c 20 74 68 65 79 20 the BLOB, they
42680 6d 69 67 68 74 20 62 65 20 68 65 6c 64 20 69 6e might be held in
42690 20 63 61 63 68 65 0a 2a 2a 20 75 6e 74 69 6c 20 cache.** until
426a0 74 68 65 20 63 6c 6f 73 65 20 6f 70 65 72 61 74 the close operat
426b0 69 6f 6e 20 69 66 20 74 68 65 79 20 77 69 6c 6c ion if they will
426c0 20 66 69 74 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a fit. {END}.**.*
426d0 2a 20 43 6c 6f 73 69 6e 67 20 74 68 65 20 42 4c * Closing the BL
426e0 4f 42 20 6f 66 74 65 6e 20 66 6f 72 63 65 73 20 OB often forces
426f0 74 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f the changes.** o
42700 75 74 20 74 6f 20 64 69 73 6b 20 61 6e 64 20 73 ut to disk and s
42710 6f 20 69 66 20 61 6e 79 20 49 2f 4f 20 65 72 72 o if any I/O err
42720 6f 72 73 20 6f 63 63 75 72 2c 20 74 68 65 79 20 ors occur, they
42730 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63 75 will likely occu
42740 72 0a 2a 2a 20 61 74 20 74 68 65 20 74 69 6d 65 r.** at the time
42750 20 77 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 when the BLOB i
42760 73 20 63 6c 6f 73 65 64 2e 20 20 7b 48 31 37 38 s closed. {H178
42770 33 33 7d 20 41 6e 79 20 65 72 72 6f 72 73 20 74 33} Any errors t
42780 68 61 74 20 6f 63 63 75 72 20 64 75 72 69 6e 67 hat occur during
42790 0a 2a 2a 20 63 6c 6f 73 69 6e 67 20 61 72 65 20 .** closing are
427a0 72 65 70 6f 72 74 65 64 20 61 73 20 61 20 6e 6f reported as a no
427b0 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 76 61 n-zero return va
427c0 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 42 lue..**.** The B
427d0 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 20 75 6e LOB is closed un
427e0 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e 20 20 conditionally.
427f0 45 76 65 6e 20 69 66 20 74 68 69 73 20 72 6f 75 Even if this rou
42800 74 69 6e 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 tine returns.**
42810 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 74 an error code, t
42820 68 65 20 42 4c 4f 42 20 69 73 20 73 74 69 6c 6c he BLOB is still
42830 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 closed..**.** I
42840 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
42850 20 7b 48 31 37 38 33 33 7d 20 54 68 65 20 5b 73 {H17833} The [s
42860 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 qlite3_blob_clos
42870 65 28 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 e(P)] interface
42880 63 6c 6f 73 65 73 20 61 6e 20 5b 73 71 6c 69 74 closes an [sqlit
42890 65 33 5f 62 6c 6f 62 5d 0a 2a 2a 20 20 20 20 20 e3_blob].**
428a0 20 20 20 20 20 6f 62 6a 65 63 74 20 50 20 70 72 object P pr
428b0 65 76 69 6f 75 73 6c 79 20 6f 70 65 6e 65 64 20 eviously opened
428c0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 using [sqlite3_b
428d0 6c 6f 62 5f 6f 70 65 6e 28 29 5d 2e 0a 2a 2a 0a lob_open()]..**.
428e0 2a 2a 20 7b 48 31 37 38 33 36 7d 20 43 6c 6f 73 ** {H17836} Clos
428f0 69 6e 67 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f ing an [sqlite3_
42900 62 6c 6f 62 5d 20 6f 62 6a 65 63 74 20 75 73 69 blob] object usi
42910 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b ng.** [
42920 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f sqlite3_blob_clo
42930 73 65 28 29 5d 20 73 68 61 6c 6c 20 63 61 75 73 se()] shall caus
42940 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 72 e the current tr
42950 61 6e 73 61 63 74 69 6f 6e 20 74 6f 0a 2a 2a 20 ansaction to.**
42960 20 20 20 20 20 20 20 20 20 63 6f 6d 6d 69 74 20 commit
42970 69 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 if there are no
42980 6f 74 68 65 72 20 6f 70 65 6e 20 5b 73 71 6c 69 other open [sqli
42990 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63 74 te3_blob] object
429a0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 s.** or
429b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
429c0 6d 65 6e 74 73 5d 20 6f 6e 20 74 68 65 20 73 61 ments] on the sa
429d0 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e me [database con
429e0 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 0a 2a 2a 20 nection] and.**
429f0 20 20 20 20 20 20 20 20 20 74 68 65 20 64 61 74 the dat
42a00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
42a10 20 69 73 20 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d is in [autocomm
42a20 69 74 20 6d 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 it mode]..**.**
42a30 7b 48 31 37 38 33 39 7d 20 54 68 65 20 5b 73 71 {H17839} The [sq
42a40 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 lite3_blob_close
42a50 28 50 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 (P)] interfaces
42a60 73 68 61 6c 6c 20 63 6c 6f 73 65 20 74 68 65 0a shall close the.
42a70 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c ** [sql
42a80 69 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63 ite3_blob] objec
42a90 74 20 50 20 75 6e 63 6f 6e 64 69 74 69 6f 6e 61 t P unconditiona
42aa0 6c 6c 79 2c 20 65 76 65 6e 20 69 66 0a 2a 2a 20 lly, even if.**
42ab0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
42ac0 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 50 29 5d 3_blob_close(P)]
42ad0 20 72 65 74 75 72 6e 73 20 73 6f 6d 65 74 68 69 returns somethi
42ae0 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 ng other than [S
42af0 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2f 0a 69 6e QLITE_OK]..*/.in
42b00 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 t sqlite3_blob_c
42b10 6c 6f 73 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f lose(sqlite3_blo
42b20 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 b *);../*.** CAP
42b30 49 33 52 45 46 3a 20 52 65 74 75 72 6e 20 54 68 I3REF: Return Th
42b40 65 20 53 69 7a 65 20 4f 66 20 41 6e 20 4f 70 65 e Size Of An Ope
42b50 6e 20 42 4c 4f 42 20 7b 48 31 37 38 34 30 7d 20 n BLOB {H17840}
42b60 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 52 <S30230>.**.** R
42b70 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 eturns the size
42b80 69 6e 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 in bytes of the
42b90 42 4c 4f 42 20 61 63 63 65 73 73 69 62 6c 65 20 BLOB accessible
42ba0 76 69 61 20 74 68 65 20 6f 70 65 6e 0a 2a 2a 20 via the open.**
42bb0 5b 5d 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 []BLOB handle] i
42bc0 6e 20 69 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d n its only argum
42bd0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 ent..**.** INVAR
42be0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 IANTS:.**.** {H1
42bf0 37 38 34 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 7843} The [sqlit
42c00 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 50 29 e3_blob_bytes(P)
42c10 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ] interface retu
42c20 72 6e 73 20 74 68 65 20 73 69 7a 65 0a 2a 2a 20 rns the size.**
42c30 20 20 20 20 20 20 20 20 20 69 6e 20 62 79 74 65 in byte
42c40 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 74 68 s of the BLOB th
42c50 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f at the [sqlite3_
42c60 62 6c 6f 62 5d 20 6f 62 6a 65 63 74 20 50 0a 2a blob] object P.*
42c70 2a 20 20 20 20 20 20 20 20 20 20 72 65 66 65 72 * refer
42c80 73 20 74 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c s to..*/.int sql
42c90 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 ite3_blob_bytes(
42ca0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b sqlite3_blob *);
42cb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
42cc0 3a 20 52 65 61 64 20 44 61 74 61 20 46 72 6f 6d : Read Data From
42cd0 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e A BLOB Incremen
42ce0 74 61 6c 6c 79 20 7b 48 31 37 38 35 30 7d 20 3c tally {H17850} <
42cf0 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 S30230>.**.** Th
42d00 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 is function is u
42d10 73 65 64 20 74 6f 20 72 65 61 64 20 64 61 74 61 sed to read data
42d20 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 5b 42 from an open [B
42d30 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 74 6f LOB handle] into
42d40 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 a.** caller-sup
42d50 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20 4e 20 plied buffer. N
42d60 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72 bytes of data ar
42d70 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 62 75 e copied into bu
42d80 66 66 65 72 20 5a 0a 2a 2a 20 66 72 6f 6d 20 74 ffer Z.** from t
42d90 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74 he open BLOB, st
42da0 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74 arting at offset
42db0 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 iOffset..**.**
42dc0 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 If offset iOffse
42dd0 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 4e t is less than N
42de0 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20 bytes from the
42df0 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f 42 2c end of the BLOB,
42e00 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f .** [SQLITE_ERRO
42e10 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 R] is returned a
42e20 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65 nd no data is re
42e30 61 64 2e 20 20 49 66 20 4e 20 6f 72 20 69 4f 66 ad. If N or iOf
42e40 66 73 65 74 20 69 73 0a 2a 2a 20 6c 65 73 73 20 fset is.** less
42e50 74 68 61 6e 20 7a 65 72 6f 2c 20 5b 53 51 4c 49 than zero, [SQLI
42e60 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 TE_ERROR] is ret
42e70 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 urned and no dat
42e80 61 20 69 73 20 72 65 61 64 2e 0a 2a 2a 0a 2a 2a a is read..**.**
42e90 20 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 72 An attempt to r
42ea0 65 61 64 20 66 72 6f 6d 20 61 6e 20 65 78 70 69 ead from an expi
42eb0 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 red [BLOB handle
42ec0 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a ] fails with an.
42ed0 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 ** error code of
42ee0 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e [SQLITE_ABORT].
42ef0 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 .**.** On succes
42f00 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 s, SQLITE_OK is
42f10 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 returned..** Oth
42f20 65 72 77 69 73 65 2c 20 61 6e 20 5b 65 72 72 6f erwise, an [erro
42f30 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 r code] or an [e
42f40 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f xtended error co
42f50 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e de] is returned.
42f60 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 .**.** INVARIANT
42f70 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 35 33 S:.**.** {H17853
42f80 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 } A successful i
42f90 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 nvocation of [sq
42fa0 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 lite3_blob_read(
42fb0 50 2c 5a 2c 4e 2c 58 29 5d 20 0a 2a 2a 20 20 20 P,Z,N,X)] .**
42fc0 20 20 20 20 20 20 20 73 68 61 6c 6c 20 72 65 61 shall rea
42fd0 64 73 20 4e 20 62 79 74 65 73 20 6f 66 20 64 61 ds N bytes of da
42fe0 74 61 20 6f 75 74 20 6f 66 20 74 68 65 20 42 4c ta out of the BL
42ff0 4f 42 20 72 65 66 65 72 65 6e 63 65 64 20 62 79 OB referenced by
43000 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 42 4c .** [BL
43010 4f 42 20 68 61 6e 64 6c 65 5d 20 50 20 62 65 67 OB handle] P beg
43020 69 6e 6e 69 6e 67 20 61 74 20 6f 66 66 73 65 74 inning at offset
43030 20 58 20 61 6e 64 20 73 74 6f 72 65 20 74 68 6f X and store tho
43040 73 65 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 se bytes.**
43050 20 20 20 20 20 69 6e 74 6f 20 62 75 66 66 65 72 into buffer
43060 20 5a 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 35 Z..**.** {H1785
43070 36 7d 20 49 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6} In [sqlite3_b
43080 6c 6f 62 5f 72 65 61 64 28 50 2c 5a 2c 4e 2c 58 lob_read(P,Z,N,X
43090 29 5d 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f )] if the size o
430a0 66 20 74 68 65 20 42 4c 4f 42 0a 2a 2a 20 20 20 f the BLOB.**
430b0 20 20 20 20 20 20 20 69 73 20 6c 65 73 73 20 74 is less t
430c0 68 61 6e 20 4e 2b 58 20 62 79 74 65 73 2c 20 74 han N+X bytes, t
430d0 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e hen the function
430e0 20 73 68 61 6c 6c 20 6c 65 61 76 65 20 74 68 65 shall leave the
430f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5a 20 62 .** Z b
43100 75 66 66 65 72 20 75 6e 63 68 61 6e 67 65 64 20 uffer unchanged
43110 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 and return [SQLI
43120 54 45 5f 45 52 52 4f 52 5d 2e 0a 2a 2a 0a 2a 2a TE_ERROR]..**.**
43130 20 7b 48 31 37 38 35 39 7d 20 49 6e 20 5b 73 71 {H17859} In [sq
43140 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 lite3_blob_read(
43150 50 2c 5a 2c 4e 2c 58 29 5d 20 69 66 20 58 20 6f P,Z,N,X)] if X o
43160 72 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e r N is less than
43170 20 7a 65 72 6f 0a 2a 2a 20 20 20 20 20 20 20 20 zero.**
43180 20 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 then the funct
43190 69 6f 6e 20 73 68 61 6c 6c 20 6c 65 61 76 65 20 ion shall leave
431a0 74 68 65 20 5a 20 62 75 66 66 65 72 20 75 6e 63 the Z buffer unc
431b0 68 61 6e 67 65 64 0a 2a 2a 20 20 20 20 20 20 20 hanged.**
431c0 20 20 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 and return [S
431d0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 0a 2a 2a QLITE_ERROR]..**
431e0 0a 2a 2a 20 7b 48 31 37 38 36 32 7d 20 54 68 65 .** {H17862} The
431f0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 [sqlite3_blob_r
43200 65 61 64 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69 6e ead(P,Z,N,X)] in
43210 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 terface shall re
43220 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d turn [SQLITE_OK]
43230 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 .** if
43240 4e 20 62 79 74 65 73 20 61 72 65 20 73 75 63 63 N bytes are succ
43250 65 73 73 66 75 6c 6c 79 20 72 65 61 64 20 69 6e essfully read in
43260 74 6f 20 62 75 66 66 65 72 20 5a 2e 0a 2a 2a 0a to buffer Z..**.
43270 2a 2a 20 7b 48 31 37 38 36 33 7d 20 49 66 20 74 ** {H17863} If t
43280 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d he [BLOB handle]
43290 20 50 20 69 73 20 65 78 70 69 72 65 64 20 61 6e P is expired an
432a0 64 20 58 20 61 6e 64 20 4e 20 61 72 65 20 77 69 d X and N are wi
432b0 74 68 69 6e 20 62 6f 75 6e 64 73 0a 2a 2a 20 20 thin bounds.**
432c0 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 then [sq
432d0 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 lite3_blob_read(
432e0 50 2c 5a 2c 4e 2c 58 29 5d 20 73 68 61 6c 6c 20 P,Z,N,X)] shall
432f0 6c 65 61 76 65 20 74 68 65 20 5a 20 62 75 66 66 leave the Z buff
43300 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 er.** u
43310 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 nchanged and ret
43320 75 72 6e 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 urn [SQLITE_ABOR
43330 54 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 36 T]..**.** {H1786
43340 35 7d 20 49 66 20 74 68 65 20 72 65 71 75 65 73 5} If the reques
43350 74 65 64 20 72 65 61 64 20 63 6f 75 6c 64 20 6e ted read could n
43360 6f 74 20 62 65 20 63 6f 6d 70 6c 65 74 65 64 2c ot be completed,
43370 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
43380 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 [sqlite3_blob_r
43390 65 61 64 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69 6e ead(P,Z,N,X)] in
433a0 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 terface shall re
433b0 74 75 72 6e 20 61 6e 0a 2a 2a 20 20 20 20 20 20 turn an.**
433c0 20 20 20 20 61 70 70 72 6f 70 72 69 61 74 65 20 appropriate
433d0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 [error code] or
433e0 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 [extended error
433f0 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 code]..**.** {H1
43400 37 38 36 38 7d 20 49 66 20 61 6e 20 65 72 72 6f 7868} If an erro
43410 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 r occurs during
43420 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 5b 73 evaluation of [s
43430 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 qlite3_blob_read
43440 28 50 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 (P,...)].**
43450 20 20 20 20 20 74 68 65 6e 20 73 75 62 73 65 71 then subseq
43460 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 uent calls to [s
43470 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 qlite3_errcode(D
43480 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 )],.**
43490 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 [sqlite3_extende
434a0 64 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a d_errcode()],.**
434b0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 [sqlit
434c0 65 33 5f 65 72 72 6d 73 67 28 44 29 5d 2c 20 61 e3_errmsg(D)], a
434d0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d nd [sqlite3_errm
434e0 73 67 31 36 28 44 29 5d 20 73 68 61 6c 6c 20 72 sg16(D)] shall r
434f0 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 eturn.**
43500 20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 70 information ap
43510 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 propriate for th
43520 61 74 20 65 72 72 6f 72 2c 20 77 68 65 72 65 20 at error, where
43530 44 20 69 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 D is the.**
43540 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 [database c
43550 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 onnection] that
43560 77 61 73 20 75 73 65 64 20 74 6f 20 6f 70 65 6e was used to open
43570 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c the [BLOB handl
43580 65 5d 20 50 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c e] P..*/.int sql
43590 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 73 ite3_blob_read(s
435a0 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 76 qlite3_blob *, v
435b0 6f 69 64 20 2a 5a 2c 20 69 6e 74 20 4e 2c 20 69 oid *Z, int N, i
435c0 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a nt iOffset);../*
435d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 57 72 .** CAPI3REF: Wr
435e0 69 74 65 20 44 61 74 61 20 49 6e 74 6f 20 41 20 ite Data Into A
435f0 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c BLOB Incremental
43600 6c 79 20 7b 48 31 37 38 37 30 7d 20 3c 53 33 30 ly {H17870} <S30
43610 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 230>.**.** This
43620 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 function is used
43630 20 74 6f 20 77 72 69 74 65 20 64 61 74 61 20 69 to write data i
43640 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f nto an open [BLO
43650 42 20 68 61 6e 64 6c 65 5d 20 66 72 6f 6d 20 61 B handle] from a
43660 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c .** caller-suppl
43670 69 65 64 20 62 75 66 66 65 72 2e 20 4e 20 62 79 ied buffer. N by
43680 74 65 73 20 6f 66 20 64 61 74 61 20 61 72 65 20 tes of data are
43690 63 6f 70 69 65 64 20 66 72 6f 6d 20 74 68 65 20 copied from the
436a0 62 75 66 66 65 72 20 5a 0a 2a 2a 20 69 6e 74 6f buffer Z.** into
436b0 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 the open BLOB,
436c0 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73 starting at offs
436d0 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a et iOffset..**.*
436e0 2a 20 49 66 20 74 68 65 20 5b 42 4c 4f 42 20 68 * If the [BLOB h
436f0 61 6e 64 6c 65 5d 20 70 61 73 73 65 64 20 61 73 andle] passed as
43700 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
43710 65 6e 74 20 77 61 73 20 6e 6f 74 20 6f 70 65 6e ent was not open
43720 65 64 20 66 6f 72 0a 2a 2a 20 77 72 69 74 69 6e ed for.** writin
43730 67 20 28 74 68 65 20 66 6c 61 67 73 20 70 61 72 g (the flags par
43740 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 ameter to [sqlit
43750 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 e3_blob_open()]
43760 77 61 73 20 7a 65 72 6f 29 2c 0a 2a 2a 20 74 68 was zero),.** th
43770 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 is function retu
43780 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 rns [SQLITE_READ
43790 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 ONLY]..**.** Thi
437a0 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6f s function may o
437b0 6e 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 63 nly modify the c
437c0 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 65 20 42 ontents of the B
437d0 4c 4f 42 3b 20 69 74 20 69 73 0a 2a 2a 20 6e 6f LOB; it is.** no
437e0 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e t possible to in
437f0 63 72 65 61 73 65 20 74 68 65 20 73 69 7a 65 20 crease the size
43800 6f 66 20 61 20 42 4c 4f 42 20 75 73 69 6e 67 20 of a BLOB using
43810 74 68 69 73 20 41 50 49 2e 0a 2a 2a 20 49 66 20 this API..** If
43820 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 20 69 offset iOffset i
43830 73 20 6c 65 73 73 20 74 68 61 6e 20 4e 20 62 79 s less than N by
43840 74 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 tes from the end
43850 20 6f 66 20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a of the BLOB,.**
43860 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
43870 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 is returned and
43880 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69 74 74 no data is writt
43890 65 6e 2e 20 20 49 66 20 4e 20 69 73 0a 2a 2a 20 en. If N is.**
438a0 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 20 5b less than zero [
438b0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 SQLITE_ERROR] is
438c0 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f returned and no
438d0 20 64 61 74 61 20 69 73 20 77 72 69 74 74 65 6e data is written
438e0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 74 74 65 6d ..**.** An attem
438f0 70 74 20 74 6f 20 77 72 69 74 65 20 74 6f 20 61 pt to write to a
43900 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f 42 20 n expired [BLOB
43910 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77 69 handle] fails wi
43920 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 th an.** error c
43930 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 ode of [SQLITE_A
43940 42 4f 52 54 5d 2e 20 20 57 72 69 74 65 73 20 74 BORT]. Writes t
43950 6f 20 74 68 65 20 42 4c 4f 42 20 74 68 61 74 20 o the BLOB that
43960 6f 63 63 75 72 72 65 64 0a 2a 2a 20 62 65 66 6f occurred.** befo
43970 72 65 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e re the [BLOB han
43980 64 6c 65 5d 20 65 78 70 69 72 65 64 20 61 72 65 dle] expired are
43990 20 6e 6f 74 20 72 6f 6c 6c 65 64 20 62 61 63 6b not rolled back
439a0 20 62 79 20 74 68 65 0a 2a 2a 20 65 78 70 69 72 by the.** expir
439b0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 68 61 6e ation of the han
439c0 64 6c 65 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 dle, though of c
439d0 6f 75 72 73 65 20 74 68 6f 73 65 20 63 68 61 6e ourse those chan
439e0 67 65 73 20 6d 69 67 68 74 0a 2a 2a 20 68 61 76 ges might.** hav
439f0 65 20 62 65 65 6e 20 6f 76 65 72 77 72 69 74 74 e been overwritt
43a00 65 6e 20 62 79 20 74 68 65 20 73 74 61 74 65 6d en by the statem
43a10 65 6e 74 20 74 68 61 74 20 65 78 70 69 72 65 64 ent that expired
43a20 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 the BLOB handle
43a30 0a 2a 2a 20 6f 72 20 62 79 20 6f 74 68 65 72 20 .** or by other
43a40 69 6e 64 65 70 65 6e 64 65 6e 74 20 73 74 61 74 independent stat
43a50 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4f 6e ements..**.** On
43a60 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54 45 success, SQLITE
43a70 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e _OK is returned.
43a80 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 61 .** Otherwise, a
43a90 6e 20 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 n [error code]
43aa0 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 or an [extended
43ab0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 error code] is r
43ac0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 eturned..**.** I
43ad0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a NVARIANTS:.**.**
43ae0 20 7b 48 31 37 38 37 33 7d 20 41 20 73 75 63 63 {H17873} A succ
43af0 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f essful invocatio
43b00 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 62 6c n of [sqlite3_bl
43b10 6f 62 5f 77 72 69 74 65 28 50 2c 5a 2c 4e 2c 58 ob_write(P,Z,N,X
43b20 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 )].** s
43b30 68 61 6c 6c 20 77 72 69 74 65 20 4e 20 62 79 74 hall write N byt
43b40 65 73 20 6f 66 20 64 61 74 61 20 66 72 6f 6d 20 es of data from
43b50 62 75 66 66 65 72 20 5a 20 69 6e 74 6f 20 74 68 buffer Z into th
43b60 65 20 42 4c 4f 42 20 0a 2a 2a 20 20 20 20 20 20 e BLOB .**
43b70 20 20 20 20 72 65 66 65 72 65 6e 63 65 64 20 62 referenced b
43b80 79 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 y [BLOB handle]
43b90 50 20 62 65 67 69 6e 6e 69 6e 67 20 61 74 20 6f P beginning at o
43ba0 66 66 73 65 74 20 58 20 69 6e 74 6f 0a 2a 2a 20 ffset X into.**
43bb0 20 20 20 20 20 20 20 20 20 74 68 65 20 42 4c 4f the BLO
43bc0 42 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 37 34 B..**.** {H17874
43bd0 7d 20 49 6e 20 74 68 65 20 61 62 73 65 6e 63 65 } In the absence
43be0 20 6f 66 20 6f 74 68 65 72 20 6f 76 65 72 72 69 of other overri
43bf0 64 64 69 6e 67 20 63 68 61 6e 67 65 73 2c 20 74 dding changes, t
43c00 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 20 20 he changes.**
43c10 20 20 20 20 20 20 20 77 72 69 74 74 65 6e 20 74 written t
43c20 6f 20 61 20 42 4c 4f 42 20 62 79 20 5b 73 71 6c o a BLOB by [sql
43c30 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 ite3_blob_write(
43c40 29 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 )] shall.**
43c50 20 20 20 20 20 72 65 6d 61 69 6e 20 69 6e 20 65 remain in e
43c60 66 66 65 63 74 20 61 66 74 65 72 20 74 68 65 20 ffect after the
43c70 61 73 73 6f 63 69 61 74 65 64 20 5b 42 4c 4f 42 associated [BLOB
43c80 20 68 61 6e 64 6c 65 5d 20 65 78 70 69 72 65 73 handle] expires
43c90 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 37 35 7d ..**.** {H17875}
43ca0 20 49 66 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 If the [BLOB ha
43cb0 6e 64 6c 65 5d 20 50 20 77 61 73 20 6f 70 65 6e ndle] P was open
43cc0 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f ed for reading o
43cd0 6e 6c 79 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 nly then.**
43ce0 20 20 20 20 20 61 6e 20 69 6e 76 6f 63 61 74 69 an invocati
43cf0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 62 on of [sqlite3_b
43d00 6c 6f 62 5f 77 72 69 74 65 28 50 2c 5a 2c 4e 2c lob_write(P,Z,N,
43d10 58 29 5d 20 73 68 61 6c 6c 20 6c 65 61 76 65 0a X)] shall leave.
43d20 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 ** the
43d30 72 65 66 65 72 65 6e 63 65 64 20 42 4c 4f 42 20 referenced BLOB
43d40 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 unchanged and re
43d50 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 52 45 41 turn [SQLITE_REA
43d60 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 DONLY]..**.** {H
43d70 31 37 38 37 36 7d 20 49 66 20 74 68 65 20 73 69 17876} If the si
43d80 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 72 ze of the BLOB r
43d90 65 66 65 72 65 6e 63 65 64 20 62 79 20 5b 42 4c eferenced by [BL
43da0 4f 42 20 68 61 6e 64 6c 65 5d 20 50 20 69 73 0a OB handle] P is.
43db0 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 65 73 73 ** less
43dc0 20 74 68 61 6e 20 4e 2b 58 20 62 79 74 65 73 20 than N+X bytes
43dd0 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c then [sqlite3_bl
43de0 6f 62 5f 77 72 69 74 65 28 50 2c 5a 2c 4e 2c 58 ob_write(P,Z,N,X
43df0 29 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 )] shall.**
43e00 20 20 20 20 20 6c 65 61 76 65 20 74 68 65 20 42 leave the B
43e10 4c 4f 42 20 75 6e 63 68 61 6e 67 65 64 20 61 6e LOB unchanged an
43e20 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 d return [SQLITE
43e30 5f 45 52 52 4f 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b _ERROR]..**.** {
43e40 48 31 37 38 37 37 7d 20 49 66 20 74 68 65 20 5b H17877} If the [
43e50 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 50 20 69 BLOB handle] P i
43e60 73 20 65 78 70 69 72 65 64 20 61 6e 64 20 58 20 s expired and X
43e70 61 6e 64 20 4e 20 61 72 65 20 77 69 74 68 69 6e and N are within
43e80 20 62 6f 75 6e 64 73 0a 2a 2a 20 20 20 20 20 20 bounds.**
43e90 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 then [sqlite
43ea0 33 5f 62 6c 6f 62 5f 72 65 61 64 28 50 2c 5a 2c 3_blob_read(P,Z,
43eb0 4e 2c 58 29 5d 20 73 68 61 6c 6c 20 6c 65 61 76 N,X)] shall leav
43ec0 65 20 74 68 65 20 42 4c 4f 42 0a 2a 2a 20 20 20 e the BLOB.**
43ed0 20 20 20 20 20 20 20 75 6e 63 68 61 6e 67 65 64 unchanged
43ee0 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c and return [SQL
43ef0 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a ITE_ABORT]..**.*
43f00 2a 20 7b 48 31 37 38 37 39 7d 20 49 66 20 58 20 * {H17879} If X
43f10 6f 72 20 4e 20 61 72 65 20 6c 65 73 73 20 74 68 or N are less th
43f20 61 6e 20 7a 65 72 6f 20 74 68 65 6e 20 5b 73 71 an zero then [sq
43f30 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 lite3_blob_write
43f40 28 50 2c 5a 2c 4e 2c 58 29 5d 0a 2a 2a 20 20 20 (P,Z,N,X)].**
43f50 20 20 20 20 20 20 20 73 68 61 6c 6c 20 6c 65 61 shall lea
43f60 76 65 20 74 68 65 20 42 4c 4f 42 20 72 65 66 65 ve the BLOB refe
43f70 72 65 6e 63 65 64 20 62 79 20 5b 42 4c 4f 42 20 renced by [BLOB
43f80 68 61 6e 64 6c 65 5d 20 50 20 75 6e 63 68 61 6e handle] P unchan
43f90 67 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ged.**
43fa0 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 and return [SQLI
43fb0 54 45 5f 45 52 52 4f 52 5d 2e 0a 2a 2a 0a 2a 2a TE_ERROR]..**.**
43fc0 20 7b 48 31 37 38 38 32 7d 20 54 68 65 20 5b 73 {H17882} The [s
43fd0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 qlite3_blob_writ
43fe0 65 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69 6e 74 65 e(P,Z,N,X)] inte
43ff0 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 74 75 rface shall retu
44000 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b rn.** [
44010 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 4e 20 SQLITE_OK] if N
44020 62 79 74 65 73 20 77 68 65 72 65 20 73 75 63 63 bytes where succ
44030 65 73 73 66 75 6c 6c 79 20 77 72 69 74 74 65 6e essfully written
44040 20 69 6e 74 6f 20 74 68 65 20 42 4c 4f 42 2e 0a into the BLOB..
44050 2a 2a 0a 2a 2a 20 7b 48 31 37 38 38 35 7d 20 49 **.** {H17885} I
44060 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 f the requested
44070 77 72 69 74 65 20 63 6f 75 6c 64 20 6e 6f 74 20 write could not
44080 62 65 20 63 6f 6d 70 6c 65 74 65 64 2c 0a 2a 2a be completed,.**
44090 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 the [s
440a0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 qlite3_blob_writ
440b0 65 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69 6e 74 65 e(P,Z,N,X)] inte
440c0 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 74 75 rface shall retu
440d0 72 6e 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 rn an.**
440e0 20 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 appropriate [e
440f0 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 rror code] or [e
44100 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f xtended error co
44110 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 38 de]..**.** {H178
44120 38 38 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20 88} If an error
44130 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 65 76 occurs during ev
44140 61 6c 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c aluation of [sql
44150 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 ite3_blob_write(
44160 44 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 D,...)].**
44170 20 20 20 20 74 68 65 6e 20 73 75 62 73 65 71 75 then subsequ
44180 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 ent calls to [sq
44190 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 lite3_errcode(D)
441a0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b ],.** [
441b0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
441c0 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 _errcode()],.**
441d0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 [sqlite
441e0 33 5f 65 72 72 6d 73 67 28 44 29 5d 2c 20 61 6e 3_errmsg(D)], an
441f0 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 d [sqlite3_errms
44200 67 31 36 28 44 29 5d 20 73 68 61 6c 6c 20 72 65 g16(D)] shall re
44210 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 turn.**
44220 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 70 70 information app
44230 72 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 61 ropriate for tha
44240 74 20 65 72 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 t error..*/.int
44250 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 sqlite3_blob_wri
44260 74 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 te(sqlite3_blob
44270 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a *, const void *z
44280 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 , int n, int iOf
44290 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 fset);../*.** CA
442a0 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 PI3REF: Virtual
442b0 46 69 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 File System Obje
442c0 63 74 73 20 7b 48 31 31 32 30 30 7d 20 3c 53 32 cts {H11200} <S2
442d0 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 20 76 69 0100>.**.** A vi
442e0 72 74 75 61 6c 20 66 69 6c 65 73 79 73 74 65 6d rtual filesystem
442f0 20 28 56 46 53 29 20 69 73 20 61 6e 20 5b 73 71 (VFS) is an [sq
44300 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
44310 74 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 t.** that SQLite
44320 20 75 73 65 73 20 74 6f 20 69 6e 74 65 72 61 63 uses to interac
44330 74 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 75 6e t.** with the un
44340 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 derlying operati
44350 6e 67 20 73 79 73 74 65 6d 2e 20 20 4d 6f 73 74 ng system. Most
44360 20 53 51 4c 69 74 65 20 62 75 69 6c 64 73 20 63 SQLite builds c
44370 6f 6d 65 20 77 69 74 68 20 61 0a 2a 2a 20 73 69 ome with a.** si
44380 6e 67 6c 65 20 64 65 66 61 75 6c 74 20 56 46 53 ngle default VFS
44390 20 74 68 61 74 20 69 73 20 61 70 70 72 6f 70 72 that is appropr
443a0 69 61 74 65 20 66 6f 72 20 74 68 65 20 68 6f 73 iate for the hos
443b0 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e t computer..** N
443c0 65 77 20 56 46 53 65 73 20 63 61 6e 20 62 65 20 ew VFSes can be
443d0 72 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 65 registered and e
443e0 78 69 73 74 69 6e 67 20 56 46 53 65 73 20 63 61 xisting VFSes ca
443f0 6e 20 62 65 20 75 6e 72 65 67 69 73 74 65 72 65 n be unregistere
44400 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 d..** The follow
44410 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20 61 ing interfaces a
44420 72 65 20 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a re provided..**.
44430 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 ** The sqlite3_v
44440 66 73 5f 66 69 6e 64 28 29 20 69 6e 74 65 72 66 fs_find() interf
44450 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f ace returns a po
44460 69 6e 74 65 72 20 74 6f 20 61 20 56 46 53 20 67 inter to a VFS g
44470 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 0a 2a iven its name..*
44480 2a 20 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65 * Names are case
44490 20 73 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 4e sensitive..** N
444a0 61 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d 74 65 ames are zero-te
444b0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 rminated UTF-8 s
444c0 74 72 69 6e 67 73 2e 0a 2a 2a 20 49 66 20 74 68 trings..** If th
444d0 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c ere is no match,
444e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
444f0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 is returned..**
44500 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 20 4e If zVfsName is N
44510 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 65 66 ULL then the def
44520 61 75 6c 74 20 56 46 53 20 69 73 20 72 65 74 75 ault VFS is retu
44530 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 rned..**.** New
44540 56 46 53 65 73 20 61 72 65 20 72 65 67 69 73 74 VFSes are regist
44550 65 72 65 64 20 77 69 74 68 20 73 71 6c 69 74 65 ered with sqlite
44560 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 3_vfs_register()
44570 2e 0a 2a 2a 20 45 61 63 68 20 6e 65 77 20 56 46 ..** Each new VF
44580 53 20 62 65 63 6f 6d 65 73 20 74 68 65 20 64 65 S becomes the de
44590 66 61 75 6c 74 20 56 46 53 20 69 66 20 74 68 65 fault VFS if the
445a0 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 69 makeDflt flag i
445b0 73 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20 73 61 s set..** The sa
445c0 6d 65 20 56 46 53 20 63 61 6e 20 62 65 20 72 65 me VFS can be re
445d0 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c gistered multipl
445e0 65 20 74 69 6d 65 73 20 77 69 74 68 6f 75 74 20 e times without
445f0 69 6e 6a 75 72 79 2e 0a 2a 2a 20 54 6f 20 6d 61 injury..** To ma
44600 6b 65 20 61 6e 20 65 78 69 73 74 69 6e 67 20 56 ke an existing V
44610 46 53 20 69 6e 74 6f 20 74 68 65 20 64 65 66 61 FS into the defa
44620 75 6c 74 20 56 46 53 2c 20 72 65 67 69 73 74 65 ult VFS, registe
44630 72 20 69 74 20 61 67 61 69 6e 0a 2a 2a 20 77 69 r it again.** wi
44640 74 68 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 th the makeDflt
44650 66 6c 61 67 20 73 65 74 2e 20 20 49 66 20 74 77 flag set. If tw
44660 6f 20 64 69 66 66 65 72 65 6e 74 20 56 46 53 65 o different VFSe
44670 73 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 73 61 s with the.** sa
44680 6d 65 20 6e 61 6d 65 20 61 72 65 20 72 65 67 69 me name are regi
44690 73 74 65 72 65 64 2c 20 74 68 65 20 62 65 68 61 stered, the beha
446a0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 vior is undefine
446b0 64 2e 20 20 49 66 20 61 0a 2a 2a 20 56 46 53 20 d. If a.** VFS
446c0 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77 69 is registered wi
446d0 74 68 20 61 20 6e 61 6d 65 20 74 68 61 74 20 69 th a name that i
446e0 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 s NULL or an emp
446f0 74 79 20 73 74 72 69 6e 67 2c 0a 2a 2a 20 74 68 ty string,.** th
44700 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 en the behavior
44710 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a is undefined..**
44720 0a 2a 2a 20 55 6e 72 65 67 69 73 74 65 72 20 61 .** Unregister a
44730 20 56 46 53 20 77 69 74 68 20 74 68 65 20 73 71 VFS with the sq
44740 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 lite3_vfs_unregi
44750 73 74 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 ster() interface
44760 2e 0a 2a 2a 20 49 66 20 74 68 65 20 64 65 66 61 ..** If the defa
44770 75 6c 74 20 56 46 53 20 69 73 20 75 6e 72 65 67 ult VFS is unreg
44780 69 73 74 65 72 65 64 2c 20 61 6e 6f 74 68 65 72 istered, another
44790 20 56 46 53 20 69 73 20 63 68 6f 73 65 6e 20 61 VFS is chosen a
447a0 73 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 s.** the default
447b0 2e 20 20 54 68 65 20 63 68 6f 69 63 65 20 66 6f . The choice fo
447c0 72 20 74 68 65 20 6e 65 77 20 56 46 53 20 69 73 r the new VFS is
447d0 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a arbitrary..**.*
447e0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a * INVARIANTS:.**
447f0 0a 2a 2a 20 7b 48 31 31 32 30 33 7d 20 54 68 65 .** {H11203} The
44800 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 [sqlite3_vfs_fi
44810 6e 64 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 nd(N)] interface
44820 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
44830 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 er to the.**
44840 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64 registered
44850 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f [sqlite3_vfs] o
44860 62 6a 65 63 74 20 77 68 6f 73 65 20 6e 61 6d 65 bject whose name
44870 20 65 78 61 63 74 6c 79 20 6d 61 74 63 68 65 73 exactly matches
44880 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 .** the
44890 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
448a0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 4e 2c UTF-8 string N,
448b0 20 6f 72 20 69 74 20 72 65 74 75 72 6e 73 20 4e or it returns N
448c0 55 4c 4c 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 ULL if.**
448d0 20 20 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d there is no m
448e0 61 74 63 68 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 atch..**.** {H11
448f0 32 30 36 7d 20 49 66 20 74 68 65 20 4e 20 70 61 206} If the N pa
44900 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
44910 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 4e 29 5d te3_vfs_find(N)]
44920 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a is NULL then.**
44930 20 20 20 20 20 20 20 20 20 20 74 68 65 20 66 75 the fu
44940 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 nction returns a
44950 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
44960 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 default [sqlite3
44970 5f 76 66 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 _vfs].**
44980 20 20 6f 62 6a 65 63 74 20 69 66 20 74 68 65 72 object if ther
44990 65 20 69 73 20 6f 6e 65 2c 20 6f 72 20 4e 55 4c e is one, or NUL
449a0 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f L if there is no
449b0 20 64 65 66 61 75 6c 74 0a 2a 2a 20 20 20 20 20 default.**
449c0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 66 [sqlite3_vf
449d0 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a s] object..**.**
449e0 20 7b 48 31 31 32 30 39 7d 20 54 68 65 20 5b 73 {H11209} The [s
449f0 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 qlite3_vfs_regis
44a00 74 65 72 28 50 2c 46 29 5d 20 69 6e 74 65 72 66 ter(P,F)] interf
44a10 61 63 65 20 72 65 67 69 73 74 65 72 73 20 74 68 ace registers th
44a20 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 65 e.** we
44a30 6c 6c 2d 66 6f 72 6d 65 64 20 5b 73 71 6c 69 74 ll-formed [sqlit
44a40 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 50 e3_vfs] object P
44a50 20 75 73 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 using the name
44a60 67 69 76 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 given.**
44a70 20 20 62 79 20 74 68 65 20 7a 4e 61 6d 65 20 66 by the zName f
44a80 69 65 6c 64 20 6f 66 20 74 68 65 20 6f 62 6a 65 ield of the obje
44a90 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 32 31 ct..**.** {H1121
44aa0 32 7d 20 55 73 69 6e 67 20 74 68 65 20 5b 73 71 2} Using the [sq
44ab0 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 lite3_vfs_regist
44ac0 65 72 28 50 2c 46 29 5d 20 69 6e 74 65 72 66 61 er(P,F)] interfa
44ad0 63 65 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a ce to register.*
44ae0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73 * the s
44af0 61 6d 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 ame [sqlite3_vfs
44b00 5d 20 6f 62 6a 65 63 74 20 6d 75 6c 74 69 70 6c ] object multipl
44b10 65 20 74 69 6d 65 73 20 69 73 20 61 20 68 61 72 e times is a har
44b20 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a mless no-op..**.
44b30 2a 2a 20 7b 48 31 31 32 31 35 7d 20 54 68 65 20 ** {H11215} The
44b40 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 [sqlite3_vfs_reg
44b50 69 73 74 65 72 28 50 2c 46 29 5d 20 69 6e 74 65 ister(P,F)] inte
44b60 72 66 61 63 65 20 6d 61 6b 65 73 20 74 68 65 20 rface makes the
44b70 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 0a 2a 2a [sqlite3_vfs].**
44b80 20 20 20 20 20 20 20 20 20 20 6f 62 6a 65 63 74 object
44b90 20 50 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b P the default [
44ba0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
44bb0 65 63 74 20 69 66 20 46 20 69 73 20 6e 6f 6e 2d ect if F is non-
44bc0 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 zero..**.** {H11
44bd0 32 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 218} The [sqlite
44be0 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 3_vfs_unregister
44bf0 28 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 75 (P)] interface u
44c00 6e 72 65 67 69 73 74 65 72 73 20 74 68 65 0a 2a nregisters the.*
44c10 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 * [sqli
44c20 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 te3_vfs] object
44c30 50 20 73 6f 20 74 68 61 74 20 69 74 20 69 73 20 P so that it is
44c40 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 74 75 72 6e no longer return
44c50 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 ed by.**
44c60 20 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c subsequent cal
44c70 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76 ls to [sqlite3_v
44c80 66 73 5f 66 69 6e 64 28 29 5d 2e 0a 2a 2f 0a 73 fs_find()]..*/.s
44c90 71 6c 69 74 65 33 5f 76 66 73 20 2a 73 71 6c 69 qlite3_vfs *sqli
44ca0 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 63 6f 6e te3_vfs_find(con
44cb0 73 74 20 63 68 61 72 20 2a 7a 56 66 73 4e 61 6d st char *zVfsNam
44cc0 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f e);.int sqlite3_
44cd0 76 66 73 5f 72 65 67 69 73 74 65 72 28 73 71 6c vfs_register(sql
44ce0 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d ite3_vfs*, int m
44cf0 61 6b 65 44 66 6c 74 29 3b 0a 69 6e 74 20 73 71 akeDflt);.int sq
44d00 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 lite3_vfs_unregi
44d10 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73 ster(sqlite3_vfs
44d20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
44d30 52 45 46 3a 20 4d 75 74 65 78 65 73 20 7b 48 31 REF: Mutexes {H1
44d40 37 30 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 7000} <S20000>.*
44d50 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 *.** The SQLite
44d60 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 core uses these
44d70 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 74 68 72 routines for thr
44d80 65 61 64 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e 69 ead.** synchroni
44d90 7a 61 74 69 6f 6e 2e 20 54 68 6f 75 67 68 20 74 zation. Though t
44da0 68 65 79 20 61 72 65 20 69 6e 74 65 6e 64 65 64 hey are intended
44db0 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a for internal.**
44dc0 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 2c 20 use by SQLite,
44dd0 63 6f 64 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 code that links
44de0 61 67 61 69 6e 73 74 20 53 51 4c 69 74 65 20 69 against SQLite i
44df0 73 0a 2a 2a 20 70 65 72 6d 69 74 74 65 64 20 74 s.** permitted t
44e00 6f 20 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65 o use any of the
44e10 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a se routines..**.
44e20 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 73 6f ** The SQLite so
44e30 75 72 63 65 20 63 6f 64 65 20 63 6f 6e 74 61 69 urce code contai
44e40 6e 73 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c ns multiple impl
44e50 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6f ementations.** o
44e60 66 20 74 68 65 73 65 20 6d 75 74 65 78 20 72 6f f these mutex ro
44e70 75 74 69 6e 65 73 2e 20 20 41 6e 20 61 70 70 72 utines. An appr
44e80 6f 70 72 69 61 74 65 20 69 6d 70 6c 65 6d 65 6e opriate implemen
44e90 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c tation.** is sel
44ea0 65 63 74 65 64 20 61 75 74 6f 6d 61 74 69 63 61 ected automatica
44eb0 6c 6c 79 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 lly at compile-t
44ec0 69 6d 65 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 ime. The follow
44ed0 69 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 ing.** implement
44ee0 61 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c ations are avail
44ef0 61 62 6c 65 20 69 6e 20 74 68 65 20 53 51 4c 69 able in the SQLi
44f00 74 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c te core:.**.** <
44f10 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 ul>.** <li> SQ
44f20 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a LITE_MUTEX_OS2.*
44f30 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f * <li> SQLITE_
44f40 4d 55 54 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a MUTEX_PTHREAD.**
44f50 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d <li> SQLITE_M
44f60 55 54 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e UTEX_W32.** <li>
44f70 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f SQLITE_MUTEX_
44f80 4e 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a NOOP.** </ul>.**
44f90 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4d .** The SQLITE_M
44fa0 55 54 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d UTEX_NOOP implem
44fb0 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 20 73 65 entation is a se
44fc0 74 20 6f 66 20 72 6f 75 74 69 6e 65 73 0a 2a 2a t of routines.**
44fd0 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 20 72 65 that does no re
44fe0 61 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69 al locking and i
44ff0 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f s appropriate fo
45000 72 20 75 73 65 20 69 6e 0a 2a 2a 20 61 20 73 69 r use in.** a si
45010 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 20 61 70 ngle-threaded ap
45020 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 plication. The
45030 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 SQLITE_MUTEX_OS2
45040 2c 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 ,.** SQLITE_MUTE
45050 58 5f 50 54 48 52 45 41 44 2c 20 61 6e 64 20 53 X_PTHREAD, and S
45060 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 20 QLITE_MUTEX_W32
45070 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a implementations.
45080 2a 2a 20 61 72 65 20 61 70 70 72 6f 70 72 69 61 ** are appropria
45090 74 65 20 66 6f 72 20 75 73 65 20 6f 6e 20 4f 53 te for use on OS
450a0 2f 32 2c 20 55 6e 69 78 2c 20 61 6e 64 20 57 69 /2, Unix, and Wi
450b0 6e 64 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 ndows..**.** If
450c0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
450d0 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 ed with the SQLI
450e0 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 20 TE_MUTEX_APPDEF
450f0 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20 preprocessor.**
45100 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20 28 77 macro defined (w
45110 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55 ith "-DSQLITE_MU
45120 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29 2c 20 TEX_APPDEF=1"),
45130 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a then no mutex.**
45140 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
45150 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68 is included with
45160 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20 49 6e the library. In
45170 20 74 68 69 73 20 63 61 73 65 20 74 68 65 0a 2a this case the.*
45180 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 * application mu
45190 73 74 20 73 75 70 70 6c 79 20 61 20 63 75 73 74 st supply a cust
451a0 6f 6d 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 om mutex impleme
451b0 6e 74 61 74 69 6f 6e 20 75 73 69 6e 67 20 74 68 ntation using th
451c0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e e.** [SQLITE_CON
451d0 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f FIG_MUTEX] optio
451e0 6e 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 n of the sqlite3
451f0 5f 63 6f 6e 66 69 67 28 29 20 66 75 6e 63 74 69 _config() functi
45200 6f 6e 0a 2a 2a 20 62 65 66 6f 72 65 20 63 61 6c on.** before cal
45210 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 69 6e 69 ling sqlite3_ini
45220 74 69 61 6c 69 7a 65 28 29 20 6f 72 20 61 6e 79 tialize() or any
45230 20 6f 74 68 65 72 20 70 75 62 6c 69 63 20 73 71 other public sq
45240 6c 69 74 65 33 5f 0a 2a 2a 20 66 75 6e 63 74 69 lite3_.** functi
45250 6f 6e 20 74 68 61 74 20 63 61 6c 6c 73 20 73 71 on that calls sq
45260 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
45270 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 ()..**.** {H1701
45280 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 1} The sqlite3_m
45290 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 utex_alloc() rou
452a0 74 69 6e 65 20 61 6c 6c 6f 63 61 74 65 73 20 61 tine allocates a
452b0 20 6e 65 77 0a 2a 2a 20 6d 75 74 65 78 20 61 6e new.** mutex an
452c0 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e d returns a poin
452d0 74 65 72 20 74 6f 20 69 74 2e 20 7b 48 31 37 30 ter to it. {H170
452e0 31 32 7d 20 49 66 20 69 74 20 72 65 74 75 72 6e 12} If it return
452f0 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d s NULL.** that m
45300 65 61 6e 73 20 74 68 61 74 20 61 20 6d 75 74 65 eans that a mute
45310 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61 x could not be a
45320 6c 6c 6f 63 61 74 65 64 2e 20 7b 48 31 37 30 31 llocated. {H1701
45330 33 7d 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 3} SQLite.** wil
45340 6c 20 75 6e 77 69 6e 64 20 69 74 73 20 73 74 61 l unwind its sta
45350 63 6b 20 61 6e 64 20 72 65 74 75 72 6e 20 61 6e ck and return an
45360 20 65 72 72 6f 72 2e 20 7b 48 31 37 30 31 34 7d error. {H17014}
45370 20 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a The argument.**
45380 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 to sqlite3_mute
45390 78 5f 61 6c 6c 6f 63 28 29 20 69 73 20 6f 6e 65 x_alloc() is one
453a0 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 of these intege
453b0 72 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a r constants:.**.
453c0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
453d0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 SQLITE_MUTEX_FA
453e0 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 ST.** <li> SQLI
453f0 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 TE_MUTEX_RECURSI
45400 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 VE.** <li> SQLI
45410 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
45420 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20 MASTER.** <li>
45430 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 SQLITE_MUTEX_STA
45440 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 TIC_MEM.** <li>
45450 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 SQLITE_MUTEX_ST
45460 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 ATIC_MEM2.** <li
45470 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f > SQLITE_MUTEX_
45480 53 54 41 54 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c STATIC_PRNG.** <
45490 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 li> SQLITE_MUTE
454a0 58 5f 53 54 41 54 49 43 5f 4c 52 55 0a 2a 2a 20 X_STATIC_LRU.**
454b0 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 <li> SQLITE_MUT
454c0 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 0a 2a EX_STATIC_LRU2.*
454d0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 48 * </ul>.**.** {H
454e0 31 37 30 31 35 7d 20 54 68 65 20 66 69 72 73 74 17015} The first
454f0 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 63 two constants c
45500 61 75 73 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 ause sqlite3_mut
45510 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20 63 72 ex_alloc() to cr
45520 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20 6d 75 eate.** a new mu
45530 74 65 78 2e 20 20 54 68 65 20 6e 65 77 20 6d 75 tex. The new mu
45540 74 65 78 20 69 73 20 72 65 63 75 72 73 69 76 65 tex is recursive
45550 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 when SQLITE_MUT
45560 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 EX_RECURSIVE.**
45570 69 73 20 75 73 65 64 20 62 75 74 20 6e 6f 74 20 is used but not
45580 6e 65 63 65 73 73 61 72 69 6c 79 20 73 6f 20 77 necessarily so w
45590 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 hen SQLITE_MUTEX
455a0 5f 46 41 53 54 20 69 73 20 75 73 65 64 2e 20 7b _FAST is used. {
455b0 45 4e 44 7d 0a 2a 2a 20 54 68 65 20 6d 75 74 65 END}.** The mute
455c0 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e x implementation
455d0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 does not need t
455e0 6f 20 6d 61 6b 65 20 61 20 64 69 73 74 69 6e 63 o make a distinc
455f0 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 tion.** between
45600 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 SQLITE_MUTEX_REC
45610 55 52 53 49 56 45 20 61 6e 64 20 53 51 4c 49 54 URSIVE and SQLIT
45620 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 66 20 E_MUTEX_FAST if
45630 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 it does.** not w
45640 61 6e 74 20 74 6f 2e 20 20 7b 48 31 37 30 31 36 ant to. {H17016
45650 7d 20 42 75 74 20 53 51 4c 69 74 65 20 77 69 6c } But SQLite wil
45660 6c 20 6f 6e 6c 79 20 72 65 71 75 65 73 74 20 61 l only request a
45670 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 recursive mutex
45680 20 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77 68 65 in.** cases whe
45690 72 65 20 69 74 20 72 65 61 6c 6c 79 20 6e 65 65 re it really nee
456a0 64 73 20 6f 6e 65 2e 20 20 7b 45 4e 44 7d 20 49 ds one. {END} I
456b0 66 20 61 20 66 61 73 74 65 72 20 6e 6f 6e 2d 72 f a faster non-r
456c0 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 0a 2a ecursive mutex.*
456d0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
456e0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e is available on
456f0 20 74 68 65 20 68 6f 73 74 20 70 6c 61 74 66 6f the host platfo
45700 72 6d 2c 20 74 68 65 20 6d 75 74 65 78 20 73 75 rm, the mutex su
45710 62 73 79 73 74 65 6d 0a 2a 2a 20 6d 69 67 68 74 bsystem.** might
45720 20 72 65 74 75 72 6e 20 73 75 63 68 20 61 20 6d return such a m
45730 75 74 65 78 20 69 6e 20 72 65 73 70 6f 6e 73 65 utex in response
45740 20 74 6f 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 to SQLITE_MUTEX
45750 5f 46 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 _FAST..**.** {H1
45760 37 30 31 37 7d 20 54 68 65 20 6f 74 68 65 72 20 7017} The other
45770 61 6c 6c 6f 77 65 64 20 70 61 72 61 6d 65 74 65 allowed paramete
45780 72 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 rs to sqlite3_mu
45790 74 65 78 5f 61 6c 6c 6f 63 28 29 20 65 61 63 68 tex_alloc() each
457a0 20 72 65 74 75 72 6e 0a 2a 2a 20 61 20 70 6f 69 return.** a poi
457b0 6e 74 65 72 20 74 6f 20 61 20 73 74 61 74 69 63 nter to a static
457c0 20 70 72 65 65 78 69 73 74 69 6e 67 20 6d 75 74 preexisting mut
457d0 65 78 2e 20 7b 45 4e 44 7d 20 20 46 6f 75 72 20 ex. {END} Four
457e0 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 static mutexes a
457f0 72 65 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 68 re.** used by th
45800 65 20 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f e current versio
45810 6e 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 46 75 n of SQLite. Fu
45820 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 ture versions of
45830 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20 61 SQLite.** may a
45840 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 dd additional st
45850 61 74 69 63 20 6d 75 74 65 78 65 73 2e 20 20 53 atic mutexes. S
45860 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72 tatic mutexes ar
45870 65 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a e for internal.*
45880 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 20 * use by SQLite
45890 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 only. Applicati
458a0 6f 6e 73 20 74 68 61 74 20 75 73 65 20 53 51 4c ons that use SQL
458b0 69 74 65 20 6d 75 74 65 78 65 73 20 73 68 6f 75 ite mutexes shou
458c0 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20 74 ld.** use only t
458d0 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 he dynamic mutex
458e0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 es returned by S
458f0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 QLITE_MUTEX_FAST
45900 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 or.** SQLITE_MU
45910 54 45 58 5f 52 45 43 55 52 53 49 56 45 2e 0a 2a TEX_RECURSIVE..*
45920 2a 0a 2a 2a 20 7b 48 31 37 30 31 38 7d 20 4e 6f *.** {H17018} No
45930 74 65 20 74 68 61 74 20 69 66 20 6f 6e 65 20 6f te that if one o
45940 66 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 f the dynamic mu
45950 74 65 78 20 70 61 72 61 6d 65 74 65 72 73 20 28 tex parameters (
45960 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 SQLITE_MUTEX_FAS
45970 54 0a 2a 2a 20 6f 72 20 53 51 4c 49 54 45 5f 4d T.** or SQLITE_M
45980 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 29 20 UTEX_RECURSIVE)
45990 69 73 20 75 73 65 64 20 74 68 65 6e 20 73 71 6c is used then sql
459a0 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 ite3_mutex_alloc
459b0 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 ().** returns a
459c0 64 69 66 66 65 72 65 6e 74 20 6d 75 74 65 78 20 different mutex
459d0 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 2e 20 20 on every call.
459e0 7b 48 31 37 30 33 34 7d 20 42 75 74 20 66 6f 72 {H17034} But for
459f0 20 74 68 65 20 73 74 61 74 69 63 0a 2a 2a 20 6d the static.** m
45a00 75 74 65 78 20 74 79 70 65 73 2c 20 74 68 65 20 utex types, the
45a10 73 61 6d 65 20 6d 75 74 65 78 20 69 73 20 72 65 same mutex is re
45a20 74 75 72 6e 65 64 20 6f 6e 20 65 76 65 72 79 20 turned on every
45a30 63 61 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a 2a call that has.**
45a40 20 74 68 65 20 73 61 6d 65 20 74 79 70 65 20 6e the same type n
45a50 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 umber..**.** {H1
45a60 37 30 31 39 7d 20 54 68 65 20 73 71 6c 69 74 65 7019} The sqlite
45a70 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 20 72 3_mutex_free() r
45a80 6f 75 74 69 6e 65 20 64 65 61 6c 6c 6f 63 61 74 outine deallocat
45a90 65 73 20 61 20 70 72 65 76 69 6f 75 73 6c 79 0a es a previously.
45aa0 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 64 79 6e ** allocated dyn
45ab0 61 6d 69 63 20 6d 75 74 65 78 2e 20 7b 48 31 37 amic mutex. {H17
45ac0 30 32 30 7d 20 53 51 4c 69 74 65 20 69 73 20 63 020} SQLite is c
45ad0 61 72 65 66 75 6c 20 74 6f 20 64 65 61 6c 6c 6f areful to deallo
45ae0 63 61 74 65 20 65 76 65 72 79 0a 2a 2a 20 64 79 cate every.** dy
45af0 6e 61 6d 69 63 20 6d 75 74 65 78 20 74 68 61 74 namic mutex that
45b00 20 69 74 20 61 6c 6c 6f 63 61 74 65 73 2e 20 7b it allocates. {
45b10 41 31 37 30 32 31 7d 20 54 68 65 20 64 79 6e 61 A17021} The dyna
45b20 6d 69 63 20 6d 75 74 65 78 65 73 20 6d 75 73 74 mic mutexes must
45b30 20 6e 6f 74 20 62 65 20 69 6e 0a 2a 2a 20 75 73 not be in.** us
45b40 65 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 e when they are
45b50 64 65 61 6c 6c 6f 63 61 74 65 64 2e 20 7b 41 31 deallocated. {A1
45b60 37 30 32 32 7d 20 41 74 74 65 6d 70 74 69 6e 67 7022} Attempting
45b70 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 to deallocate a
45b80 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 static.** mutex
45b90 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 results in unde
45ba0 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 20 fined behavior.
45bb0 7b 48 31 37 30 32 33 7d 20 53 51 4c 69 74 65 20 {H17023} SQLite
45bc0 6e 65 76 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 never deallocate
45bd0 73 0a 2a 2a 20 61 20 73 74 61 74 69 63 20 6d 75 s.** a static mu
45be0 74 65 78 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a tex. {END}.**.**
45bf0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 The sqlite3_mut
45c00 65 78 5f 65 6e 74 65 72 28 29 20 61 6e 64 20 73 ex_enter() and s
45c10 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 qlite3_mutex_try
45c20 28 29 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 () routines atte
45c30 6d 70 74 0a 2a 2a 20 74 6f 20 65 6e 74 65 72 20 mpt.** to enter
45c40 61 20 6d 75 74 65 78 2e 20 7b 48 31 37 30 32 34 a mutex. {H17024
45c50 7d 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 } If another thr
45c60 65 61 64 20 69 73 20 61 6c 72 65 61 64 79 20 77 ead is already w
45c70 69 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78 2c ithin the mutex,
45c80 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 .** sqlite3_mute
45c90 78 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20 62 x_enter() will b
45ca0 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65 33 lock and sqlite3
45cb0 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69 6c _mutex_try() wil
45cc0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 l return.** SQLI
45cd0 54 45 5f 42 55 53 59 2e 20 7b 48 31 37 30 32 35 TE_BUSY. {H17025
45ce0 7d 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d } The sqlite3_m
45cf0 75 74 65 78 5f 74 72 79 28 29 20 69 6e 74 65 72 utex_try() inter
45d00 66 61 63 65 20 72 65 74 75 72 6e 73 20 5b 53 51 face returns [SQ
45d10 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e LITE_OK].** upon
45d20 20 73 75 63 63 65 73 73 66 75 6c 20 65 6e 74 72 successful entr
45d30 79 2e 20 20 7b 48 31 37 30 32 36 7d 20 4d 75 74 y. {H17026} Mut
45d40 65 78 65 73 20 63 72 65 61 74 65 64 20 75 73 69 exes created usi
45d50 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 ng.** SQLITE_MUT
45d60 45 58 5f 52 45 43 55 52 53 49 56 45 20 63 61 6e EX_RECURSIVE can
45d70 20 62 65 20 65 6e 74 65 72 65 64 20 6d 75 6c 74 be entered mult
45d80 69 70 6c 65 20 74 69 6d 65 73 20 62 79 20 74 68 iple times by th
45d90 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e 0a 2a e same thread..*
45da0 2a 20 7b 48 31 37 30 32 37 7d 20 49 6e 20 73 75 * {H17027} In su
45db0 63 68 20 63 61 73 65 73 20 74 68 65 2c 0a 2a 2a ch cases the,.**
45dc0 20 6d 75 74 65 78 20 6d 75 73 74 20 62 65 20 65 mutex must be e
45dd0 78 69 74 65 64 20 61 6e 20 65 71 75 61 6c 20 6e xited an equal n
45de0 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 62 umber of times b
45df0 65 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 74 68 efore another th
45e00 72 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74 65 read.** can ente
45e10 72 2e 20 20 7b 41 31 37 30 32 38 7d 20 49 66 20 r. {A17028} If
45e20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 the same thread
45e30 74 72 69 65 73 20 74 6f 20 65 6e 74 65 72 20 61 tries to enter a
45e40 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 ny other.** kind
45e50 20 6f 66 20 6d 75 74 65 78 20 6d 6f 72 65 20 74 of mutex more t
45e60 68 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20 62 65 han once, the be
45e70 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 havior is undefi
45e80 6e 65 64 2e 0a 2a 2a 20 7b 48 31 37 30 32 39 7d ned..** {H17029}
45e90 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 SQLite will nev
45ea0 65 72 20 65 78 68 69 62 69 74 0a 2a 2a 20 73 75 er exhibit.** su
45eb0 63 68 20 62 65 68 61 76 69 6f 72 20 69 6e 20 69 ch behavior in i
45ec0 74 73 20 6f 77 6e 20 75 73 65 20 6f 66 20 6d 75 ts own use of mu
45ed0 74 65 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d texes..**.** Som
45ee0 65 20 73 79 73 74 65 6d 73 20 28 66 6f 72 20 65 e systems (for e
45ef0 78 61 6d 70 6c 65 2c 20 57 69 6e 64 6f 77 73 20 xample, Windows
45f00 39 35 29 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 95) do not suppo
45f10 72 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e rt the operation
45f20 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 .** implemented
45f30 62 79 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 by sqlite3_mutex
45f40 5f 74 72 79 28 29 2e 20 20 4f 6e 20 74 68 6f 73 _try(). On thos
45f50 65 20 73 79 73 74 65 6d 73 2c 20 73 71 6c 69 74 e systems, sqlit
45f60 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 0a 2a e3_mutex_try().*
45f70 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 * will always re
45f80 74 75 72 6e 20 53 51 4c 49 54 45 5f 42 55 53 59 turn SQLITE_BUSY
45f90 2e 20 20 7b 48 31 37 30 33 30 7d 20 54 68 65 20 . {H17030} The
45fa0 53 51 4c 69 74 65 20 63 6f 72 65 20 6f 6e 6c 79 SQLite core only
45fb0 20 65 76 65 72 20 75 73 65 73 0a 2a 2a 20 73 71 ever uses.** sq
45fc0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 lite3_mutex_try(
45fd0 29 20 61 73 20 61 6e 20 6f 70 74 69 6d 69 7a 61 ) as an optimiza
45fe0 74 69 6f 6e 20 73 6f 20 74 68 69 73 20 69 73 20 tion so this is
45ff0 61 63 63 65 70 74 61 62 6c 65 20 62 65 68 61 76 acceptable behav
46000 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 ior..**.** {H170
46010 33 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 31} The sqlite3_
46020 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20 72 6f mutex_leave() ro
46030 75 74 69 6e 65 20 65 78 69 74 73 20 61 20 6d 75 utine exits a mu
46040 74 65 78 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 tex that was.**
46050 70 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 72 previously enter
46060 65 64 20 62 79 20 74 68 65 20 73 61 6d 65 20 74 ed by the same t
46070 68 72 65 61 64 2e 20 20 7b 41 31 37 30 33 32 7d hread. {A17032}
46080 20 54 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a The behavior.**
46090 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 69 66 is undefined if
460a0 20 74 68 65 20 6d 75 74 65 78 20 69 73 20 6e 6f the mutex is no
460b0 74 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 t currently ente
460c0 72 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 red by the.** ca
460d0 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 6f 72 20 lling thread or
460e0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 is not currently
460f0 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 7b 48 31 allocated. {H1
46100 37 30 33 33 7d 20 53 51 4c 69 74 65 20 77 69 6c 7033} SQLite wil
46110 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20 65 69 l.** never do ei
46120 74 68 65 72 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a ther. {END}.**.*
46130 2a 20 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e * If the argumen
46140 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 t to sqlite3_mut
46150 65 78 5f 65 6e 74 65 72 28 29 2c 20 73 71 6c 69 ex_enter(), sqli
46160 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2c te3_mutex_try(),
46170 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d or.** sqlite3_m
46180 75 74 65 78 5f 6c 65 61 76 65 28 29 20 69 73 20 utex_leave() is
46190 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 a NULL pointer,
461a0 74 68 65 6e 20 61 6c 6c 20 74 68 72 65 65 20 72 then all three r
461b0 6f 75 74 69 6e 65 73 0a 2a 2a 20 62 65 68 61 76 outines.** behav
461c0 65 20 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a e as no-ops..**.
461d0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
461e0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 lite3_mutex_held
461f0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
46200 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 _mutex_notheld()
46210 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 ]..*/.sqlite3_mu
46220 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74 tex *sqlite3_mut
46230 65 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 ex_alloc(int);.v
46240 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 oid sqlite3_mute
46250 78 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 6d x_free(sqlite3_m
46260 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c utex*);.void sql
46270 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 ite3_mutex_enter
46280 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 (sqlite3_mutex*)
46290 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 ;.int sqlite3_mu
462a0 74 65 78 5f 74 72 79 28 73 71 6c 69 74 65 33 5f tex_try(sqlite3_
462b0 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 mutex*);.void sq
462c0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 lite3_mutex_leav
462d0 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a e(sqlite3_mutex*
462e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
462f0 45 46 3a 20 4d 75 74 65 78 20 4d 65 74 68 6f 64 EF: Mutex Method
46300 73 20 4f 62 6a 65 63 74 20 7b 48 31 37 31 32 30 s Object {H17120
46310 7d 20 3c 53 32 30 31 33 30 3e 0a 2a 2a 20 45 58 } <S20130>.** EX
46320 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a PERIMENTAL.**.**
46330 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 An instance of
46340 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 64 this structure d
46350 65 66 69 6e 65 73 20 74 68 65 20 6c 6f 77 2d 6c efines the low-l
46360 65 76 65 6c 20 72 6f 75 74 69 6e 65 73 0a 2a 2a evel routines.**
46370 20 75 73 65 64 20 74 6f 20 61 6c 6c 6f 63 61 74 used to allocat
46380 65 20 61 6e 64 20 75 73 65 20 6d 75 74 65 78 65 e and use mutexe
46390 73 2e 0a 2a 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79 s..**.** Usually
463a0 2c 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 , the default mu
463b0 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 tex implementati
463c0 6f 6e 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 ons provided by
463d0 53 51 4c 69 74 65 20 61 72 65 0a 2a 2a 20 73 75 SQLite are.** su
463e0 66 66 69 63 69 65 6e 74 2c 20 68 6f 77 65 76 65 fficient, howeve
463f0 72 20 74 68 65 20 75 73 65 72 20 68 61 73 20 74 r the user has t
46400 68 65 20 6f 70 74 69 6f 6e 20 6f 66 20 73 75 62 he option of sub
46410 73 74 69 74 75 74 69 6e 67 20 61 20 63 75 73 74 stituting a cust
46420 6f 6d 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 om.** implementa
46430 74 69 6f 6e 20 66 6f 72 20 73 70 65 63 69 61 6c tion for special
46440 69 7a 65 64 20 64 65 70 6c 6f 79 6d 65 6e 74 73 ized deployments
46450 20 6f 72 20 73 79 73 74 65 6d 73 20 66 6f 72 20 or systems for
46460 77 68 69 63 68 20 53 51 4c 69 74 65 0a 2a 2a 20 which SQLite.**
46470 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 does not provide
46480 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c a suitable impl
46490 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 49 6e 20 74 ementation. In t
464a0 68 69 73 20 63 61 73 65 2c 20 74 68 65 20 75 73 his case, the us
464b0 65 72 0a 2a 2a 20 63 72 65 61 74 65 73 20 61 6e er.** creates an
464c0 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 20 69 d populates an i
464d0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
464e0 73 74 72 75 63 74 75 72 65 20 74 6f 20 70 61 73 structure to pas
464f0 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f s.** to sqlite3_
46500 63 6f 6e 66 69 67 28 29 20 61 6c 6f 6e 67 20 77 config() along w
46510 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ith the [SQLITE_
46520 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 CONFIG_MUTEX] op
46530 74 69 6f 6e 2e 0a 2a 2a 20 41 64 64 69 74 69 6f tion..** Additio
46540 6e 61 6c 6c 79 2c 20 61 6e 20 69 6e 73 74 61 6e nally, an instan
46550 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 ce of this struc
46560 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 ture can be used
46570 20 61 73 20 61 6e 0a 2a 2a 20 6f 75 74 70 75 74 as an.** output
46580 20 76 61 72 69 61 62 6c 65 20 77 68 65 6e 20 71 variable when q
46590 75 65 72 79 69 6e 67 20 74 68 65 20 73 79 73 74 uerying the syst
465a0 65 6d 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 em for the curre
465b0 6e 74 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c nt mutex.** impl
465c0 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 75 73 69 6e ementation, usin
465d0 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f g the [SQLITE_CO
465e0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 20 6f NFIG_GETMUTEX] o
465f0 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ption..**.** The
46600 20 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68 xMutexInit meth
46610 6f 64 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 od defined by th
46620 69 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20 is structure is
46630 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 invoked as.** pa
46640 72 74 20 6f 66 20 73 79 73 74 65 6d 20 69 6e 69 rt of system ini
46650 74 69 61 6c 69 7a 61 74 69 6f 6e 20 62 79 20 74 tialization by t
46660 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 he sqlite3_initi
46670 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e alize() function
46680 2e 0a 2a 2a 20 7b 48 31 37 30 30 31 7d 20 54 68 ..** {H17001} Th
46690 65 20 78 4d 75 74 65 78 49 6e 69 74 20 72 6f 75 e xMutexInit rou
466a0 74 69 6e 65 20 73 68 61 6c 6c 20 62 65 20 63 61 tine shall be ca
466b0 6c 6c 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f lled by SQLite o
466c0 6e 63 65 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 nce for each.**
466d0 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 effective call t
466e0 6f 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 o [sqlite3_initi
466f0 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 alize()]..**.**
46700 54 68 65 20 78 4d 75 74 65 78 45 6e 64 20 6d 65 The xMutexEnd me
46710 74 68 6f 64 20 64 65 66 69 6e 65 64 20 62 79 20 thod defined by
46720 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 69 this structure i
46730 73 20 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 s invoked as.**
46740 70 61 72 74 20 6f 66 20 73 79 73 74 65 6d 20 73 part of system s
46750 68 75 74 64 6f 77 6e 20 62 79 20 74 68 65 20 73 hutdown by the s
46760 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
46770 29 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 0a ) function. The.
46780 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
46790 6e 20 6f 66 20 74 68 69 73 20 6d 65 74 68 6f 64 n of this method
467a0 20 69 73 20 65 78 70 65 63 74 65 64 20 74 6f 20 is expected to
467b0 72 65 6c 65 61 73 65 20 61 6c 6c 20 6f 75 74 73 release all outs
467c0 74 61 6e 64 69 6e 67 0a 2a 2a 20 72 65 73 6f 75 tanding.** resou
467d0 72 63 65 73 20 6f 62 74 61 69 6e 65 64 20 62 79 rces obtained by
467e0 20 74 68 65 20 6d 75 74 65 78 20 6d 65 74 68 6f the mutex metho
467f0 64 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ds implementatio
46800 6e 2c 20 65 73 70 65 63 69 61 6c 6c 79 0a 2a 2a n, especially.**
46810 20 74 68 6f 73 65 20 6f 62 74 61 69 6e 65 64 20 those obtained
46820 62 79 20 74 68 65 20 78 4d 75 74 65 78 49 6e 69 by the xMutexIni
46830 74 20 6d 65 74 68 6f 64 2e 20 7b 48 31 37 30 30 t method. {H1700
46840 33 7d 20 54 68 65 20 78 4d 75 74 65 78 45 6e 64 3} The xMutexEnd
46850 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 ().** interface
46860 73 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 shall be invoked
46870 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 63 once for each c
46880 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
46890 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a shutdown()]..**.
468a0 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 ** The remaining
468b0 20 73 65 76 65 6e 20 6d 65 74 68 6f 64 73 20 64 seven methods d
468c0 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 efined by this s
468d0 74 72 75 63 74 75 72 65 20 28 78 4d 75 74 65 78 tructure (xMutex
468e0 41 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d 75 74 65 78 Alloc,.** xMutex
468f0 46 72 65 65 2c 20 78 4d 75 74 65 78 45 6e 74 65 Free, xMutexEnte
46900 72 2c 20 78 4d 75 74 65 78 54 72 79 2c 20 78 4d r, xMutexTry, xM
46910 75 74 65 78 4c 65 61 76 65 2c 20 78 4d 75 74 65 utexLeave, xMute
46920 78 48 65 6c 64 20 61 6e 64 0a 2a 2a 20 78 4d 75 xHeld and.** xMu
46930 74 65 78 4e 6f 74 68 65 6c 64 29 20 69 6d 70 6c texNotheld) impl
46940 65 6d 65 6e 74 20 74 68 65 20 66 6f 6c 6c 6f 77 ement the follow
46950 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20 28 ing interfaces (
46960 72 65 73 70 65 63 74 69 76 65 6c 79 29 3a 0a 2a respectively):.*
46970 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c *.** <ul>.** <
46980 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 li> [sqlite3_mu
46990 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 3c 2f 6c tex_alloc()] </l
469a0 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 i>.** <li> [s
469b0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 qlite3_mutex_fre
469c0 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 e()] </li>.**
469d0 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d <li> [sqlite3_m
469e0 75 74 65 78 5f 65 6e 74 65 72 28 29 5d 20 3c 2f utex_enter()] </
469f0 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b li>.** <li> [
46a00 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 sqlite3_mutex_tr
46a10 79 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 y()] </li>.**
46a20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d <li> [sqlite3_m
46a30 75 74 65 78 5f 6c 65 61 76 65 28 29 5d 20 3c 2f utex_leave()] </
46a40 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b li>.** <li> [
46a50 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 sqlite3_mutex_he
46a60 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 ld()] </li>.**
46a70 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f <li> [sqlite3_
46a80 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d mutex_notheld()]
46a90 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a </li>.** </ul>.
46aa0 2a 2a 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 64 **.** The only d
46ab0 69 66 66 65 72 65 6e 63 65 20 69 73 20 74 68 61 ifference is tha
46ac0 74 20 74 68 65 20 70 75 62 6c 69 63 20 73 71 6c t the public sql
46ad0 69 74 65 33 5f 58 58 58 20 66 75 6e 63 74 69 6f ite3_XXX functio
46ae0 6e 73 20 65 6e 75 6d 65 72 61 74 65 64 0a 2a 2a ns enumerated.**
46af0 20 61 62 6f 76 65 20 73 69 6c 65 6e 74 6c 79 20 above silently
46b00 69 67 6e 6f 72 65 20 61 6e 79 20 69 6e 76 6f 63 ignore any invoc
46b10 61 74 69 6f 6e 73 20 74 68 61 74 20 70 61 73 73 ations that pass
46b20 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
46b30 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 instead.** of a
46b40 76 61 6c 69 64 20 6d 75 74 65 78 20 68 61 6e 64 valid mutex hand
46b50 6c 65 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e le. The implemen
46b60 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 6d tations of the m
46b70 65 74 68 6f 64 73 20 64 65 66 69 6e 65 64 0a 2a ethods defined.*
46b80 2a 20 62 79 20 74 68 69 73 20 73 74 72 75 63 74 * by this struct
46b90 75 72 65 20 61 72 65 20 6e 6f 74 20 72 65 71 75 ure are not requ
46ba0 69 72 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 74 ired to handle t
46bb0 68 69 73 20 63 61 73 65 2c 20 74 68 65 20 72 65 his case, the re
46bc0 73 75 6c 74 73 0a 2a 2a 20 6f 66 20 70 61 73 73 sults.** of pass
46bd0 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 ing a NULL point
46be0 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 er instead of a
46bf0 76 61 6c 69 64 20 6d 75 74 65 78 20 68 61 6e 64 valid mutex hand
46c00 6c 65 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 le are undefined
46c10 0a 2a 2a 20 28 69 2e 65 2e 20 69 74 20 69 73 20 .** (i.e. it is
46c20 61 63 63 65 70 74 61 62 6c 65 20 74 6f 20 70 72 acceptable to pr
46c30 6f 76 69 64 65 20 61 6e 20 69 6d 70 6c 65 6d 65 ovide an impleme
46c40 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 73 65 67 ntation that seg
46c50 66 61 75 6c 74 73 20 69 66 0a 2a 2a 20 69 74 20 faults if.** it
46c60 69 73 20 70 61 73 73 65 64 20 61 20 4e 55 4c 4c is passed a NULL
46c70 20 70 6f 69 6e 74 65 72 29 2e 0a 2a 2f 0a 74 79 pointer)..*/.ty
46c80 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
46c90 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
46ca0 64 73 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ds sqlite3_mutex
46cb0 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 _methods;.struct
46cc0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d sqlite3_mutex_m
46cd0 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 28 ethods {. int (
46ce0 2a 78 4d 75 74 65 78 49 6e 69 74 29 28 76 6f 69 *xMutexInit)(voi
46cf0 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 d);. int (*xMut
46d00 65 78 45 6e 64 29 28 76 6f 69 64 29 3b 0a 20 20 exEnd)(void);.
46d10 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 28 sqlite3_mutex *(
46d20 2a 78 4d 75 74 65 78 41 6c 6c 6f 63 29 28 69 6e *xMutexAlloc)(in
46d30 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 t);. void (*xMu
46d40 74 65 78 46 72 65 65 29 28 73 71 6c 69 74 65 33 texFree)(sqlite3
46d50 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 _mutex *);. voi
46d60 64 20 28 2a 78 4d 75 74 65 78 45 6e 74 65 72 29 d (*xMutexEnter)
46d70 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a (sqlite3_mutex *
46d80 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 );. int (*xMute
46d90 78 54 72 79 29 28 73 71 6c 69 74 65 33 5f 6d 75 xTry)(sqlite3_mu
46da0 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 tex *);. void (
46db0 2a 78 4d 75 74 65 78 4c 65 61 76 65 29 28 73 71 *xMutexLeave)(sq
46dc0 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a lite3_mutex *);.
46dd0 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 48 65 int (*xMutexHe
46de0 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 ld)(sqlite3_mute
46df0 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d x *);. int (*xM
46e00 75 74 65 78 4e 6f 74 68 65 6c 64 29 28 73 71 6c utexNotheld)(sql
46e10 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d ite3_mutex *);.}
46e20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
46e30 46 3a 20 4d 75 74 65 78 20 56 65 72 69 66 69 63 F: Mutex Verific
46e40 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b ation Routines {
46e50 48 31 37 30 38 30 7d 20 3c 53 32 30 31 33 30 3e H17080} <S20130>
46e60 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 <S30800>.**.**
46e70 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 The sqlite3_mute
46e80 78 5f 68 65 6c 64 28 29 20 61 6e 64 20 73 71 6c x_held() and sql
46e90 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 ite3_mutex_nothe
46ea0 6c 64 28 29 20 72 6f 75 74 69 6e 65 73 0a 2a 2a ld() routines.**
46eb0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f are intended fo
46ec0 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 73 73 r use inside ass
46ed0 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 ert() statements
46ee0 2e 20 7b 48 31 37 30 38 31 7d 20 54 68 65 20 53 . {H17081} The S
46ef0 51 4c 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 QLite core.** ne
46f00 76 65 72 20 75 73 65 73 20 74 68 65 73 65 20 72 ver uses these r
46f10 6f 75 74 69 6e 65 73 20 65 78 63 65 70 74 20 69 outines except i
46f20 6e 73 69 64 65 20 61 6e 20 61 73 73 65 72 74 28 nside an assert(
46f30 29 20 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f ) and applicatio
46f40 6e 73 0a 2a 2a 20 61 72 65 20 61 64 76 69 73 65 ns.** are advise
46f50 64 20 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 d to follow the
46f60 6c 65 61 64 20 6f 66 20 74 68 65 20 63 6f 72 65 lead of the core
46f70 2e 20 20 7b 48 31 37 30 38 32 7d 20 54 68 65 20 . {H17082} The
46f80 63 6f 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f core only.** pro
46f90 76 69 64 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61 vides implementa
46fa0 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 73 65 20 tions for these
46fb0 72 6f 75 74 69 6e 65 73 20 77 68 65 6e 20 69 74 routines when it
46fc0 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 is compiled.**
46fd0 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f with the SQLITE_
46fe0 44 45 42 55 47 20 66 6c 61 67 2e 20 20 7b 41 31 DEBUG flag. {A1
46ff0 37 30 38 37 7d 20 45 78 74 65 72 6e 61 6c 20 6d 7087} External m
47000 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 utex implementat
47010 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 6f 6e 6c 79 ions.** are only
47020 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 72 6f required to pro
47030 76 69 64 65 20 74 68 65 73 65 20 72 6f 75 74 69 vide these routi
47040 6e 65 73 20 69 66 20 53 51 4c 49 54 45 5f 44 45 nes if SQLITE_DE
47050 42 55 47 20 69 73 0a 2a 2a 20 64 65 66 69 6e 65 BUG is.** define
47060 64 20 61 6e 64 20 69 66 20 4e 44 45 42 55 47 20 d and if NDEBUG
47070 69 73 20 6e 6f 74 20 64 65 66 69 6e 65 64 2e 0a is not defined..
47080 2a 2a 0a 2a 2a 20 7b 48 31 37 30 38 33 7d 20 54 **.** {H17083} T
47090 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 73 68 hese routines sh
470a0 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 72 75 65 ould return true
470b0 20 69 66 20 74 68 65 20 6d 75 74 65 78 20 69 6e if the mutex in
470c0 20 74 68 65 69 72 20 61 72 67 75 6d 65 6e 74 0a their argument.
470d0 2a 2a 20 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f ** is held or no
470e0 74 20 68 65 6c 64 2c 20 72 65 73 70 65 63 74 69 t held, respecti
470f0 76 65 6c 79 2c 20 62 79 20 74 68 65 20 63 61 6c vely, by the cal
47100 6c 69 6e 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a ling thread..**.
47110 2a 2a 20 7b 58 31 37 30 38 34 7d 20 54 68 65 20 ** {X17084} The
47120 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 implementation i
47130 73 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74 s not required t
47140 6f 20 70 72 6f 76 69 64 65 64 20 76 65 72 73 69 o provided versi
47150 6f 6e 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 ons of these.**
47160 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 61 63 routines that ac
47170 74 75 61 6c 6c 79 20 77 6f 72 6b 2e 20 49 66 20 tually work. If
47180 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 the implementati
47190 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 on does not prov
471a0 69 64 65 20 77 6f 72 6b 69 6e 67 0a 2a 2a 20 76 ide working.** v
471b0 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 ersions of these
471c0 20 72 6f 75 74 69 6e 65 73 2c 20 69 74 20 73 68 routines, it sh
471d0 6f 75 6c 64 20 61 74 20 6c 65 61 73 74 20 70 72 ould at least pr
471e0 6f 76 69 64 65 20 73 74 75 62 73 20 74 68 61 74 ovide stubs that
471f0 20 61 6c 77 61 79 73 0a 2a 2a 20 72 65 74 75 72 always.** retur
47200 6e 20 74 72 75 65 20 73 6f 20 74 68 61 74 20 6f n true so that o
47210 6e 65 20 64 6f 65 73 20 6e 6f 74 20 67 65 74 20 ne does not get
47220 73 70 75 72 69 6f 75 73 20 61 73 73 65 72 74 69 spurious asserti
47230 6f 6e 20 66 61 69 6c 75 72 65 73 2e 0a 2a 2a 0a on failures..**.
47240 2a 2a 20 7b 48 31 37 30 38 35 7d 20 49 66 20 74 ** {H17085} If t
47250 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 he argument to s
47260 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c qlite3_mutex_hel
47270 64 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f d() is a NULL po
47280 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 inter then.** th
47290 65 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 e routine should
472a0 20 72 65 74 75 72 6e 20 31 2e 20 20 7b 45 4e 44 return 1. {END
472b0 7d 20 54 68 69 73 20 73 65 65 6d 73 20 63 6f 75 } This seems cou
472c0 6e 74 65 72 2d 69 6e 74 75 69 74 69 76 65 20 73 nter-intuitive s
472d0 69 6e 63 65 0a 2a 2a 20 63 6c 65 61 72 6c 79 20 ince.** clearly
472e0 74 68 65 20 6d 75 74 65 78 20 63 61 6e 6e 6f 74 the mutex cannot
472f0 20 62 65 20 68 65 6c 64 20 69 66 20 69 74 20 64 be held if it d
47300 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 2e 20 20 oes not exist.
47310 42 75 74 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 But the.** the r
47320 65 61 73 6f 6e 20 74 68 65 20 6d 75 74 65 78 20 eason the mutex
47330 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20 69 does not exist i
47340 73 20 62 65 63 61 75 73 65 20 74 68 65 20 62 75 s because the bu
47350 69 6c 64 20 69 73 20 6e 6f 74 0a 2a 2a 20 75 73 ild is not.** us
47360 69 6e 67 20 6d 75 74 65 78 65 73 2e 20 20 41 6e ing mutexes. An
47370 64 20 77 65 20 64 6f 20 6e 6f 74 20 77 61 6e 74 d we do not want
47380 20 74 68 65 20 61 73 73 65 72 74 28 29 20 63 6f the assert() co
47390 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 ntaining the.**
473a0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
473b0 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 74 6f 20 mutex_held() to
473c0 66 61 69 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a fail, so a non-z
473d0 65 72 6f 20 72 65 74 75 72 6e 20 69 73 0a 2a 2a ero return is.**
473e0 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 the appropriate
473f0 20 74 68 69 6e 67 20 74 6f 20 64 6f 2e 20 20 7b thing to do. {
47400 48 31 37 30 38 36 7d 20 54 68 65 20 73 71 6c 69 H17086} The sqli
47410 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c te3_mutex_nothel
47420 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 d().** interface
47430 20 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74 should also ret
47440 75 72 6e 20 31 20 77 68 65 6e 20 67 69 76 65 6e urn 1 when given
47450 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
47460 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
47470 6d 75 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 74 mutex_held(sqlit
47480 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 e3_mutex*);.int
47490 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f sqlite3_mutex_no
474a0 74 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 theld(sqlite3_mu
474b0 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 tex*);../*.** CA
474c0 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 54 79 PI3REF: Mutex Ty
474d0 70 65 73 20 7b 48 31 37 30 30 31 7d 20 3c 48 31 pes {H17001} <H1
474e0 37 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7000>.**.** The
474f0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 [sqlite3_mutex_a
47500 6c 6c 6f 63 28 29 5d 20 69 6e 74 65 72 66 61 63 lloc()] interfac
47510 65 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 e takes a single
47520 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 69 argument.** whi
47530 63 68 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 ch is one of the
47540 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 se integer const
47550 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ants..**.** The
47560 73 65 74 20 6f 66 20 73 74 61 74 69 63 20 6d 75 set of static mu
47570 74 65 78 65 73 20 6d 61 79 20 63 68 61 6e 67 65 texes may change
47580 20 66 72 6f 6d 20 6f 6e 65 20 53 51 4c 69 74 65 from one SQLite
47590 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 0a release to the.
475a0 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 ** next. Applic
475b0 61 74 69 6f 6e 73 20 74 68 61 74 20 6f 76 65 72 ations that over
475c0 72 69 64 65 20 74 68 65 20 62 75 69 6c 74 2d 69 ride the built-i
475d0 6e 20 6d 75 74 65 78 20 6c 6f 67 69 63 20 6d 75 n mutex logic mu
475e0 73 74 20 62 65 0a 2a 2a 20 70 72 65 70 61 72 65 st be.** prepare
475f0 64 20 74 6f 20 61 63 63 6f 6d 6d 6f 64 61 74 65 d to accommodate
47600 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 74 additional stat
47610 69 63 20 6d 75 74 65 78 65 73 2e 0a 2a 2f 0a 23 ic mutexes..*/.#
47620 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 define SQLITE_MU
47630 54 45 58 5f 46 41 53 54 20 20 20 20 20 20 20 20 TEX_FAST
47640 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 0.#define S
47650 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 QLITE_MUTEX_RECU
47660 52 53 49 56 45 20 20 20 20 20 20 20 20 31 0a 23 RSIVE 1.#
47670 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 define SQLITE_MU
47680 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 TEX_STATIC_MASTE
47690 52 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 R 2.#define S
476a0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 QLITE_MUTEX_STAT
476b0 49 43 5f 4d 45 4d 20 20 20 20 20 20 20 33 20 20 IC_MEM 3
476c0 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f /* sqlite3_mallo
476d0 63 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 c() */.#define S
476e0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 QLITE_MUTEX_STAT
476f0 49 43 5f 4d 45 4d 32 20 20 20 20 20 20 34 20 20 IC_MEM2 4
47700 2f 2a 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 /* sqlite3_relea
47710 73 65 5f 6d 65 6d 6f 72 79 28 29 20 2a 2f 0a 23 se_memory() */.#
47720 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 define SQLITE_MU
47730 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 20 TEX_STATIC_PRNG
47740 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 5 /* sqlit
47750 65 33 5f 72 61 6e 64 6f 6d 28 29 20 2a 2f 0a 23 e3_random() */.#
47760 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 define SQLITE_MU
47770 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 20 20 TEX_STATIC_LRU
47780 20 20 20 20 20 36 20 20 2f 2a 20 6c 72 75 20 70 6 /* lru p
47790 61 67 65 20 6c 69 73 74 20 2a 2f 0a 23 64 65 66 age list */.#def
477a0 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 ine SQLITE_MUTEX
477b0 5f 53 54 41 54 49 43 5f 4c 52 55 32 20 20 20 20 _STATIC_LRU2
477c0 20 20 37 20 20 2f 2a 20 6c 72 75 20 70 61 67 65 7 /* lru page
477d0 20 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 list */../*.**
477e0 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 CAPI3REF: Retrie
477f0 76 65 20 74 68 65 20 6d 75 74 65 78 20 66 6f 72 ve the mutex for
47800 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a database conn
47810 65 63 74 69 6f 6e 20 7b 48 31 37 30 30 32 7d 20 ection {H17002}
47820 3c 48 31 37 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 <H17000>.**.** T
47830 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 his interface re
47840 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
47850 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 the [sqlite3_mut
47860 65 78 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 ex] object that
47870 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 65 73 20 61 .** serializes a
47880 63 63 65 73 73 20 74 6f 20 74 68 65 20 5b 64 61 ccess to the [da
47890 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
478a0 6e 5d 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 n] given in the
478b0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 65 6e argument.** when
478c0 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 the [threading
478d0 6d 6f 64 65 5d 20 69 73 20 53 65 72 69 61 6c 69 mode] is Seriali
478e0 7a 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b zed..** If the [
478f0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
47900 69 73 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 is Single-thread
47910 20 6f 72 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 or Multi-thread
47920 20 74 68 65 6e 20 74 68 69 73 0a 2a 2a 20 72 6f then this.** ro
47930 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 utine returns a
47940 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f NULL pointer..*/
47950 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a .sqlite3_mutex *
47960 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 sqlite3_db_mutex
47970 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
47980 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 77 ** CAPI3REF: Low
47990 2d 4c 65 76 65 6c 20 43 6f 6e 74 72 6f 6c 20 4f -Level Control O
479a0 66 20 44 61 74 61 62 61 73 65 20 46 69 6c 65 73 f Database Files
479b0 20 7b 48 31 31 33 30 30 7d 20 3c 53 33 30 38 30 {H11300} <S3080
479c0 30 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 31 0>.**.** {H11301
479d0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 } The [sqlite3_f
479e0 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 ile_control()] i
479f0 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 nterface makes a
47a00 20 64 69 72 65 63 74 20 63 61 6c 6c 20 74 6f 20 direct call to
47a10 74 68 65 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 the.** xFileCont
47a20 72 6f 6c 20 6d 65 74 68 6f 64 20 66 6f 72 20 74 rol method for t
47a30 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d he [sqlite3_io_m
47a40 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 ethods] object a
47a50 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 ssociated.** wit
47a60 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 h a particular d
47a70 61 74 61 62 61 73 65 20 69 64 65 6e 74 69 66 69 atabase identifi
47a80 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 ed by the second
47a90 20 61 72 67 75 6d 65 6e 74 2e 20 7b 48 31 31 33 argument. {H113
47aa0 30 32 7d 20 54 68 65 0a 2a 2a 20 6e 61 6d 65 20 02} The.** name
47ab0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 of the database
47ac0 69 73 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 is the name assi
47ad0 67 6e 65 64 20 74 6f 20 74 68 65 20 64 61 74 61 gned to the data
47ae0 62 61 73 65 20 62 79 20 74 68 65 0a 2a 2a 20 3c base by the.** <
47af0 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f 61 74 74 a href="lang_att
47b00 61 63 68 2e 68 74 6d 6c 22 3e 41 54 54 41 43 48 ach.html">ATTACH
47b10 3c 2f 61 3e 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 </a> SQL command
47b20 20 74 68 61 74 20 6f 70 65 6e 65 64 20 74 68 65 that opened the
47b30 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 7b 48 .** database. {H
47b40 31 31 33 30 33 7d 20 54 6f 20 63 6f 6e 74 72 6f 11303} To contro
47b50 6c 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 l the main datab
47b60 61 73 65 20 66 69 6c 65 2c 20 75 73 65 20 74 68 ase file, use th
47b70 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 0a 2a 2a e name "main".**
47b80 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 or a NULL point
47b90 65 72 2e 20 7b 48 31 31 33 30 34 7d 20 54 68 65 er. {H11304} The
47ba0 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 third and fourt
47bb0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 h parameters to
47bc0 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 this routine.**
47bd0 61 72 65 20 70 61 73 73 65 64 20 64 69 72 65 63 are passed direc
47be0 74 6c 79 20 74 68 72 6f 75 67 68 20 74 6f 20 74 tly through to t
47bf0 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 he second and th
47c00 69 72 64 20 70 61 72 61 6d 65 74 65 72 73 20 6f ird parameters o
47c10 66 0a 2a 2a 20 74 68 65 20 78 46 69 6c 65 43 6f f.** the xFileCo
47c20 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 20 7b ntrol method. {
47c30 48 31 31 33 30 35 7d 20 54 68 65 20 72 65 74 75 H11305} The retu
47c40 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 rn value of the
47c50 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 0a 2a 2a 20 xFileControl.**
47c60 6d 65 74 68 6f 64 20 62 65 63 6f 6d 65 73 20 74 method becomes t
47c70 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
47c80 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e of this routine.
47c90 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 36 7d 20 .**.** {H11306}
47ca0 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 If the second pa
47cb0 72 61 6d 65 74 65 72 20 28 7a 44 62 4e 61 6d 65 rameter (zDbName
47cc0 29 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 ) does not match
47cd0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 6e 79 the name of any
47ce0 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62 61 73 .** open databas
47cf0 65 20 66 69 6c 65 2c 20 74 68 65 6e 20 53 51 4c e file, then SQL
47d00 49 54 45 5f 45 52 52 4f 52 20 69 73 20 72 65 74 ITE_ERROR is ret
47d10 75 72 6e 65 64 2e 20 7b 48 31 31 33 30 37 7d 20 urned. {H11307}
47d20 54 68 69 73 20 65 72 72 6f 72 0a 2a 2a 20 63 6f This error.** co
47d30 64 65 20 69 73 20 6e 6f 74 20 72 65 6d 65 6d 62 de is not rememb
47d40 65 72 65 64 20 61 6e 64 20 77 69 6c 6c 20 6e 6f ered and will no
47d50 74 20 62 65 20 72 65 63 61 6c 6c 65 64 20 62 79 t be recalled by
47d60 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 [sqlite3_errcod
47d70 65 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 e()].** or [sqli
47d80 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 20 7b te3_errmsg()]. {
47d90 41 31 31 33 30 38 7d 20 54 68 65 20 75 6e 64 65 A11308} The unde
47da0 72 6c 79 69 6e 67 20 78 46 69 6c 65 43 6f 6e 74 rlying xFileCont
47db0 72 6f 6c 20 6d 65 74 68 6f 64 20 6d 69 67 68 74 rol method might
47dc0 0a 2a 2a 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 .** also return
47dd0 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 7b SQLITE_ERROR. {
47de0 41 31 31 33 30 39 7d 20 54 68 65 72 65 20 69 73 A11309} There is
47df0 20 6e 6f 20 77 61 79 20 74 6f 20 64 69 73 74 69 no way to disti
47e00 6e 67 75 69 73 68 20 62 65 74 77 65 65 6e 0a 2a nguish between.*
47e10 2a 20 61 6e 20 69 6e 63 6f 72 72 65 63 74 20 7a * an incorrect z
47e20 44 62 4e 61 6d 65 20 61 6e 64 20 61 6e 20 53 51 DbName and an SQ
47e30 4c 49 54 45 5f 45 52 52 4f 52 20 72 65 74 75 72 LITE_ERROR retur
47e40 6e 20 66 72 6f 6d 20 74 68 65 20 75 6e 64 65 72 n from the under
47e50 6c 79 69 6e 67 0a 2a 2a 20 78 46 69 6c 65 43 6f lying.** xFileCo
47e60 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 7b 45 ntrol method. {E
47e70 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c ND}.**.** See al
47e80 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 so: [SQLITE_FCNT
47e90 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 0a 2a 2f 0a L_LOCKSTATE].*/.
47ea0 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 int sqlite3_file
47eb0 5f 63 6f 6e 74 72 6f 6c 28 73 71 6c 69 74 65 33 _control(sqlite3
47ec0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
47ed0 44 62 4e 61 6d 65 2c 20 69 6e 74 20 6f 70 2c 20 DbName, int op,
47ee0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 void*);../*.** C
47ef0 41 50 49 33 52 45 46 3a 20 54 65 73 74 69 6e 67 API3REF: Testing
47f00 20 49 6e 74 65 72 66 61 63 65 20 7b 48 31 31 34 Interface {H114
47f10 30 30 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 00} <S30800>.**.
47f20 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 74 ** The sqlite3_t
47f30 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 20 69 6e est_control() in
47f40 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 terface is used
47f50 74 6f 20 72 65 61 64 20 6f 75 74 20 69 6e 74 65 to read out inte
47f60 72 6e 61 6c 0a 2a 2a 20 73 74 61 74 65 20 6f 66 rnal.** state of
47f70 20 53 51 4c 69 74 65 20 61 6e 64 20 74 6f 20 69 SQLite and to i
47f80 6e 6a 65 63 74 20 66 61 75 6c 74 73 20 69 6e 74 nject faults int
47f90 6f 20 53 51 4c 69 74 65 20 66 6f 72 20 74 65 73 o SQLite for tes
47fa0 74 69 6e 67 0a 2a 2a 20 70 75 72 70 6f 73 65 73 ting.** purposes
47fb0 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 . The first par
47fc0 61 6d 65 74 65 72 20 69 73 20 61 6e 20 6f 70 65 ameter is an ope
47fd0 72 61 74 69 6f 6e 20 63 6f 64 65 20 74 68 61 74 ration code that
47fe0 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 74 determines.** t
47ff0 68 65 20 6e 75 6d 62 65 72 2c 20 6d 65 61 6e 69 he number, meani
48000 6e 67 2c 20 61 6e 64 20 6f 70 65 72 61 74 69 6f ng, and operatio
48010 6e 20 6f 66 20 61 6c 6c 20 73 75 62 73 65 71 75 n of all subsequ
48020 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 2e 0a ent parameters..
48030 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 **.** This inter
48040 66 61 63 65 20 69 73 20 6e 6f 74 20 66 6f 72 20 face is not for
48050 75 73 65 20 62 79 20 61 70 70 6c 69 63 61 74 69 use by applicati
48060 6f 6e 73 2e 20 20 49 74 20 65 78 69 73 74 73 20 ons. It exists
48070 73 6f 6c 65 6c 79 0a 2a 2a 20 66 6f 72 20 76 65 solely.** for ve
48080 72 69 66 79 69 6e 67 20 74 68 65 20 63 6f 72 72 rifying the corr
48090 65 63 74 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 ect operation of
480a0 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 the SQLite libr
480b0 61 72 79 2e 20 20 44 65 70 65 6e 64 69 6e 67 0a ary. Depending.
480c0 2a 2a 20 6f 6e 20 68 6f 77 20 74 68 65 20 53 51 ** on how the SQ
480d0 4c 69 74 65 20 6c 69 62 72 61 72 79 20 69 73 20 Lite library is
480e0 63 6f 6d 70 69 6c 65 64 2c 20 74 68 69 73 20 69 compiled, this i
480f0 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 6e nterface might n
48100 6f 74 20 65 78 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 ot exist..**.**
48110 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 The details of t
48120 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 he operation cod
48130 65 73 2c 20 74 68 65 69 72 20 6d 65 61 6e 69 6e es, their meanin
48140 67 73 2c 20 74 68 65 20 70 61 72 61 6d 65 74 65 gs, the paramete
48150 72 73 0a 2a 2a 20 74 68 65 79 20 74 61 6b 65 2c rs.** they take,
48160 20 61 6e 64 20 77 68 61 74 20 74 68 65 79 20 64 and what they d
48170 6f 20 61 72 65 20 61 6c 6c 20 73 75 62 6a 65 63 o are all subjec
48180 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 t to change with
48190 6f 75 74 20 6e 6f 74 69 63 65 2e 0a 2a 2a 20 55 out notice..** U
481a0 6e 6c 69 6b 65 20 6d 6f 73 74 20 6f 66 20 74 68 nlike most of th
481b0 65 20 53 51 4c 69 74 65 20 41 50 49 2c 20 74 68 e SQLite API, th
481c0 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e is function is n
481d0 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f ot guaranteed to
481e0 0a 2a 2a 20 6f 70 65 72 61 74 65 20 63 6f 6e 73 .** operate cons
481f0 69 73 74 65 6e 74 6c 79 20 66 72 6f 6d 20 6f 6e istently from on
48200 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 e release to the
48210 20 6e 65 78 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 next..*/.int sq
48220 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 lite3_test_contr
48230 6f 6c 28 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b ol(int op, ...);
48240 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
48250 3a 20 54 65 73 74 69 6e 67 20 49 6e 74 65 72 66 : Testing Interf
48260 61 63 65 20 4f 70 65 72 61 74 69 6f 6e 20 43 6f ace Operation Co
48270 64 65 73 20 7b 48 31 31 34 31 30 7d 20 3c 48 31 des {H11410} <H1
48280 31 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 1400>.**.** Thes
48290 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 e constants are
482a0 74 68 65 20 76 61 6c 69 64 20 6f 70 65 72 61 74 the valid operat
482b0 69 6f 6e 20 63 6f 64 65 20 70 61 72 61 6d 65 74 ion code paramet
482c0 65 72 73 20 75 73 65 64 0a 2a 2a 20 61 73 20 74 ers used.** as t
482d0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
482e0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 65 t to [sqlite3_te
482f0 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d 2e 0a 2a st_control()]..*
48300 2a 0a 2a 2a 20 54 68 65 73 65 20 70 61 72 61 6d *.** These param
48310 65 74 65 72 73 20 61 6e 64 20 74 68 65 69 72 20 eters and their
48320 6d 65 61 6e 69 6e 67 73 20 61 72 65 20 73 75 62 meanings are sub
48330 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 0a 2a ject to change.*
48340 2a 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 * without notice
48350 2e 20 20 54 68 65 73 65 20 76 61 6c 75 65 73 20 . These values
48360 61 72 65 20 66 6f 72 20 74 65 73 74 69 6e 67 20 are for testing
48370 70 75 72 70 6f 73 65 73 20 6f 6e 6c 79 2e 0a 2a purposes only..*
48380 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 * Applications s
48390 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 61 6e hould not use an
483a0 79 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d y of these param
483b0 65 74 65 72 73 20 6f 72 20 74 68 65 0a 2a 2a 20 eters or the.**
483c0 5b 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f [sqlite3_test_co
483d0 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 ntrol()] interfa
483e0 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ce..*/.#define S
483f0 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 QLITE_TESTCTRL_P
48400 52 4e 47 5f 53 41 56 45 20 20 20 20 20 20 20 20 RNG_SAVE
48410 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 5.#defin
48420 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 e SQLITE_TESTCTR
48430 4c 5f 50 52 4e 47 5f 52 45 53 54 4f 52 45 20 20 L_PRNG_RESTORE
48440 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 6.#de
48450 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 fine SQLITE_TEST
48460 43 54 52 4c 5f 50 52 4e 47 5f 52 45 53 45 54 20 CTRL_PRNG_RESET
48470 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 7.
48480 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
48490 45 53 54 43 54 52 4c 5f 42 49 54 56 45 43 5f 54 ESTCTRL_BITVEC_T
484a0 45 53 54 20 20 20 20 20 20 20 20 20 20 20 20 20 EST
484b0 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 8.#define SQLIT
484c0 45 5f 54 45 53 54 43 54 52 4c 5f 46 41 55 4c 54 E_TESTCTRL_FAULT
484d0 5f 49 4e 53 54 41 4c 4c 20 20 20 20 20 20 20 20 _INSTALL
484e0 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 9.#define SQ
484f0 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 42 45 LITE_TESTCTRL_BE
48500 4e 49 47 4e 5f 4d 41 4c 4c 4f 43 5f 48 4f 4f 4b NIGN_MALLOC_HOOK
48510 53 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 S 10../*.**
48520 43 41 50 49 33 52 45 46 3a 20 53 51 4c 69 74 65 CAPI3REF: SQLite
48530 20 52 75 6e 74 69 6d 65 20 53 74 61 74 75 73 20 Runtime Status
48540 7b 48 31 37 32 30 30 7d 20 3c 53 36 30 32 30 30 {H17200} <S60200
48550 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 >.** EXPERIMENTA
48560 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 L.**.** This int
48570 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 erface is used t
48580 6f 20 72 65 74 72 69 65 76 65 20 72 75 6e 74 69 o retrieve runti
48590 6d 65 20 73 74 61 74 75 73 20 69 6e 66 6f 72 6d me status inform
485a0 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 74 ation.** about t
485b0 68 65 20 70 72 65 66 6f 72 6d 61 6e 63 65 20 6f he preformance o
485c0 66 20 53 51 4c 69 74 65 2c 20 61 6e 64 20 6f 70 f SQLite, and op
485d0 74 69 6f 6e 61 6c 6c 79 20 74 6f 20 72 65 73 65 tionally to rese
485e0 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 68 69 67 t various.** hig
485f0 68 77 61 74 65 72 20 6d 61 72 6b 73 2e 20 20 54 hwater marks. T
48600 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
48610 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 t is an integer
48620 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 code for.** the
48630 73 70 65 63 69 66 69 63 20 70 61 72 61 6d 65 74 specific paramet
48640 65 72 20 74 6f 20 6d 65 61 73 75 72 65 2e 20 20 er to measure.
48650 52 65 63 6f 67 6e 69 7a 65 64 20 69 6e 74 65 67 Recognized integ
48660 65 72 20 63 6f 64 65 73 0a 2a 2a 20 61 72 65 20 er codes.** are
48670 6f 66 20 74 68 65 20 66 6f 72 6d 20 5b 53 51 4c of the form [SQL
48680 49 54 45 5f 53 54 41 54 55 53 5f 4d 45 4d 4f 52 ITE_STATUS_MEMOR
48690 59 5f 55 53 45 44 20 7c 20 53 51 4c 49 54 45 5f Y_USED | SQLITE_
486a0 53 54 41 54 55 53 5f 2e 2e 2e 5d 2e 0a 2a 2a 20 STATUS_...]..**
486b0 54 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 The current valu
486c0 65 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 e of the paramet
486d0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 er is returned i
486e0 6e 74 6f 20 2a 70 43 75 72 72 65 6e 74 2e 0a 2a nto *pCurrent..*
486f0 2a 20 54 68 65 20 68 69 67 68 65 73 74 20 72 65 * The highest re
48700 63 6f 72 64 65 64 20 76 61 6c 75 65 20 69 73 20 corded value is
48710 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 48 69 returned in *pHi
48720 67 68 77 61 74 65 72 2e 20 20 49 66 20 74 68 65 ghwater. If the
48730 0a 2a 2a 20 72 65 73 65 74 46 6c 61 67 20 69 73 .** resetFlag is
48740 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 true, then the
48750 68 69 67 68 65 73 74 20 72 65 63 6f 72 64 20 76 highest record v
48760 61 6c 75 65 20 69 73 20 72 65 73 65 74 20 61 66 alue is reset af
48770 74 65 72 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 ter.** *pHighwat
48780 65 72 20 69 73 20 77 72 69 74 74 65 6e 2e 20 53 er is written. S
48790 6f 6d 65 20 70 61 72 61 6d 65 74 65 72 73 20 64 ome parameters d
487a0 6f 20 6e 6f 74 20 72 65 63 6f 72 64 20 74 68 65 o not record the
487b0 20 68 69 67 68 65 73 74 0a 2a 2a 20 76 61 6c 75 highest.** valu
487c0 65 2e 20 20 46 6f 72 20 74 68 6f 73 65 20 70 61 e. For those pa
487d0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6e 6f 74 68 rameters.** noth
487e0 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 20 69 ing is written i
487f0 6e 74 6f 20 2a 70 48 69 67 68 77 61 74 65 72 20 nto *pHighwater
48800 61 6e 64 20 74 68 65 20 72 65 73 65 74 46 6c 61 and the resetFla
48810 67 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a g is ignored..**
48820 20 4f 74 68 65 72 20 70 61 72 61 6d 65 74 65 72 Other parameter
48830 73 20 72 65 63 6f 72 64 20 6f 6e 6c 79 20 74 68 s record only th
48840 65 20 68 69 67 68 77 61 74 65 72 20 6d 61 72 6b e highwater mark
48850 20 61 6e 64 20 6e 6f 74 20 74 68 65 20 63 75 72 and not the cur
48860 72 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 2e 20 20 rent.** value.
48870 46 6f 72 20 74 68 65 73 65 20 6c 61 74 74 65 72 For these latter
48880 20 70 61 72 61 6d 65 74 65 72 73 20 6e 6f 74 68 parameters noth
48890 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 20 69 ing is written i
488a0 6e 74 6f 20 2a 70 43 75 72 72 65 6e 74 2e 0a 2a nto *pCurrent..*
488b0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
488c0 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 e returns SQLITE
488d0 5f 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73 20 61 _OK on success a
488e0 6e 64 20 61 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a nd a non-zero.**
488f0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e [error code] on
48900 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 failure..**.**
48910 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 This routine is
48920 74 68 72 65 61 64 73 61 66 65 20 62 75 74 20 69 threadsafe but i
48930 73 20 6e 6f 74 20 61 74 6f 6d 69 63 2e 20 20 54 s not atomic. T
48940 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 0a his routine can.
48950 2a 2a 20 63 61 6c 6c 65 64 20 77 68 69 6c 65 20 ** called while
48960 6f 74 68 65 72 20 74 68 72 65 61 64 73 20 61 72 other threads ar
48970 65 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 73 61 e running the sa
48980 6d 65 20 6f 72 20 64 69 66 66 65 72 65 6e 74 20 me or different
48990 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 66 SQLite.** interf
489a0 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 20 74 aces. However t
489b0 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e he values return
489c0 65 64 20 69 6e 20 2a 70 43 75 72 72 65 6e 74 20 ed in *pCurrent
489d0 61 6e 64 0a 2a 2a 20 2a 70 48 69 67 68 77 61 74 and.** *pHighwat
489e0 65 72 20 72 65 66 6c 65 63 74 20 74 68 65 20 73 er reflect the s
489f0 74 61 74 75 73 20 6f 66 20 53 51 4c 69 74 65 20 tatus of SQLite
48a00 61 74 20 64 69 66 66 65 72 65 6e 74 20 70 6f 69 at different poi
48a10 6e 74 73 20 69 6e 20 74 69 6d 65 0a 2a 2a 20 61 nts in time.** a
48a20 6e 64 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c nd it is possibl
48a30 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 e that another t
48a40 68 72 65 61 64 20 6d 69 67 68 74 20 63 68 61 6e hread might chan
48a50 67 65 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 ge the parameter
48a60 0a 2a 2a 20 69 6e 20 62 65 74 77 65 65 6e 20 74 .** in between t
48a70 68 65 20 74 69 6d 65 73 20 77 68 65 6e 20 2a 70 he times when *p
48a80 43 75 72 72 65 6e 74 20 61 6e 64 20 2a 70 48 69 Current and *pHi
48a90 67 68 77 61 74 65 72 20 61 72 65 20 77 72 69 74 ghwater are writ
48aa0 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ten..**.** See a
48ab0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 62 lso: [sqlite3_db
48ac0 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2f 0a 53 51 _status()].*/.SQ
48ad0 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 LITE_EXPERIMENTA
48ae0 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 L int sqlite3_st
48af0 61 74 75 73 28 69 6e 74 20 6f 70 2c 20 69 6e 74 atus(int op, int
48b00 20 2a 70 43 75 72 72 65 6e 74 2c 20 69 6e 74 20 *pCurrent, int
48b10 2a 70 48 69 67 68 77 61 74 65 72 2c 20 69 6e 74 *pHighwater, int
48b20 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 0a 2f resetFlag);.../
48b30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
48b40 74 61 74 75 73 20 50 61 72 61 6d 65 74 65 72 73 tatus Parameters
48b50 20 7b 48 31 37 32 35 30 7d 20 3c 48 31 37 32 30 {H17250} <H1720
48b60 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 0>.** EXPERIMENT
48b70 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 AL.**.** These i
48b80 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 nteger constants
48b90 20 64 65 73 69 67 6e 61 74 65 20 76 61 72 69 6f designate vario
48ba0 75 73 20 72 75 6e 2d 74 69 6d 65 20 73 74 61 74 us run-time stat
48bb0 75 73 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a us parameters.**
48bc0 20 74 68 61 74 20 63 61 6e 20 62 65 20 72 65 74 that can be ret
48bd0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 urned by [sqlite
48be0 33 5f 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2a 0a 3_status()]..**.
48bf0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 ** <dl>.** <dt>S
48c00 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 45 4d QLITE_STATUS_MEM
48c10 4f 52 59 5f 55 53 45 44 3c 2f 64 74 3e 0a 2a 2a ORY_USED</dt>.**
48c20 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 <dd>This parame
48c30 74 65 72 20 69 73 20 74 68 65 20 63 75 72 72 65 ter is the curre
48c40 6e 74 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d nt amount of mem
48c50 6f 72 79 20 63 68 65 63 6b 65 64 20 6f 75 74 0a ory checked out.
48c60 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ** using [sqlite
48c70 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 65 69 74 3_malloc()], eit
48c80 68 65 72 20 64 69 72 65 63 74 6c 79 20 6f 72 20 her directly or
48c90 69 6e 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 indirectly. The
48ca0 0a 2a 2a 20 66 69 67 75 72 65 20 69 6e 63 6c 75 .** figure inclu
48cb0 64 65 73 20 63 61 6c 6c 73 20 6d 61 64 65 20 74 des calls made t
48cc0 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f o [sqlite3_mallo
48cd0 63 28 29 5d 20 62 79 20 74 68 65 20 61 70 70 6c c()] by the appl
48ce0 69 63 61 74 69 6f 6e 0a 2a 2a 20 61 6e 64 20 69 ication.** and i
48cf0 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 75 nternal memory u
48d00 73 61 67 65 20 62 79 20 74 68 65 20 53 51 4c 69 sage by the SQLi
48d10 74 65 20 6c 69 62 72 61 72 79 2e 20 20 53 63 72 te library. Scr
48d20 61 74 63 68 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 atch memory.** c
48d30 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 5b 53 51 ontrolled by [SQ
48d40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 LITE_CONFIG_SCRA
48d50 54 43 48 5d 20 61 6e 64 20 61 75 78 69 6c 69 61 TCH] and auxilia
48d60 72 79 20 70 61 67 65 2d 63 61 63 68 65 0a 2a 2a ry page-cache.**
48d70 20 6d 65 6d 6f 72 79 20 63 6f 6e 74 72 6f 6c 6c memory controll
48d80 65 64 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f ed by [SQLITE_CO
48d90 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 20 NFIG_PAGECACHE]
48da0 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 is not included
48db0 69 6e 0a 2a 2a 20 74 68 69 73 20 70 61 72 61 6d in.** this param
48dc0 65 74 65 72 2e 20 20 54 68 65 20 61 6d 6f 75 6e eter. The amoun
48dd0 74 20 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 t returned is th
48de0 65 20 73 75 6d 20 6f 66 20 74 68 65 20 61 6c 6c e sum of the all
48df0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 73 69 7a 65 73 ocation.** sizes
48e00 20 61 73 20 72 65 70 6f 72 74 65 64 20 62 79 20 as reported by
48e10 74 68 65 20 78 53 69 7a 65 20 6d 65 74 68 6f 64 the xSize method
48e20 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d in [sqlite3_mem
48e30 5f 6d 65 74 68 6f 64 73 5d 2e 3c 2f 64 64 3e 0a _methods].</dd>.
48e40 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
48e50 5f 53 54 41 54 55 53 5f 4d 41 4c 4c 4f 43 5f 53 _STATUS_MALLOC_S
48e60 49 5a 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e IZE</dt>.** <dd>
48e70 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 72 This parameter r
48e80 65 63 6f 72 64 73 20 74 68 65 20 6c 61 72 67 65 ecords the large
48e90 73 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 st memory alloca
48ea0 74 69 6f 6e 20 72 65 71 75 65 73 74 0a 2a 2a 20 tion request.**
48eb0 68 61 6e 64 65 64 20 74 6f 20 5b 73 71 6c 69 74 handed to [sqlit
48ec0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 e3_malloc()] or
48ed0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
48ee0 28 29 5d 20 28 6f 72 20 74 68 65 69 72 0a 2a 2a ()] (or their.**
48ef0 20 69 6e 74 65 72 6e 61 6c 20 65 71 75 69 76 61 internal equiva
48f00 6c 65 6e 74 73 29 2e 20 20 4f 6e 6c 79 20 74 68 lents). Only th
48f10 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
48f20 20 69 6e 20 74 68 65 0a 2a 2a 20 2a 70 48 69 67 in the.** *pHig
48f30 68 77 61 74 65 72 20 70 61 72 61 6d 65 74 65 72 hwater parameter
48f40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 to [sqlite3_sta
48f50 74 75 73 28 29 5d 20 69 73 20 6f 66 20 69 6e 74 tus()] is of int
48f60 65 72 65 73 74 2e 20 20 0a 2a 2a 20 54 68 65 20 erest. .** The
48f70 76 61 6c 75 65 20 77 72 69 74 74 65 6e 20 69 6e value written in
48f80 74 6f 20 74 68 65 20 2a 70 43 75 72 72 65 6e 74 to the *pCurrent
48f90 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 6e parameter is un
48fa0 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a defined.</dd>.**
48fb0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 .** <dt>SQLITE_S
48fc0 54 41 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f TATUS_PAGECACHE_
48fd0 55 53 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 USED</dt>.** <dd
48fe0 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 >This parameter
48ff0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
49000 65 72 20 6f 66 20 70 61 67 65 73 20 75 73 65 64 er of pages used
49010 20 6f 75 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b out of the.** [
49020 70 61 67 65 63 61 63 68 65 20 6d 65 6d 6f 72 79 pagecache memory
49030 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 74 68 61 74 allocator] that
49040 20 77 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 was configured
49050 75 73 69 6e 67 20 0a 2a 2a 20 5b 53 51 4c 49 54 using .** [SQLIT
49060 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
49070 48 45 5d 2e 20 20 54 68 65 0a 2a 2a 20 76 61 6c HE]. The.** val
49080 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 69 ue returned is i
49090 6e 20 70 61 67 65 73 2c 20 6e 6f 74 20 69 6e 20 n pages, not in
490a0 62 79 74 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a bytes.</dd>.**.*
490b0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 54 41 * <dt>SQLITE_STA
490c0 54 55 53 5f 50 41 47 45 43 41 43 48 45 5f 4f 56 TUS_PAGECACHE_OV
490d0 45 52 46 4c 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c ERFLOW</dt>.** <
490e0 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 dd>This paramete
490f0 72 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 r returns the nu
49100 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 mber of bytes of
49110 20 70 61 67 65 20 63 61 63 68 65 0a 2a 2a 20 61 page cache.** a
49120 6c 6c 6f 63 61 74 69 6f 6e 20 77 68 69 63 68 20 llocation which
49130 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 73 74 61 could not be sta
49140 74 69 73 66 69 65 64 20 62 79 20 74 68 65 20 5b tisfied by the [
49150 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 SQLITE_CONFIG_PA
49160 47 45 43 41 43 48 45 5d 0a 2a 2a 20 62 75 66 66 GECACHE].** buff
49170 65 72 20 61 6e 64 20 77 68 65 72 65 20 66 6f 72 er and where for
49180 63 65 64 20 74 6f 20 6f 76 65 72 66 6c 6f 77 20 ced to overflow
49190 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c to [sqlite3_mall
491a0 6f 63 28 29 5d 2e 20 20 54 68 65 0a 2a 2a 20 72 oc()]. The.** r
491b0 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 6e eturned value in
491c0 63 6c 75 64 65 73 20 61 6c 6c 6f 63 61 74 69 6f cludes allocatio
491d0 6e 73 20 74 68 61 74 20 6f 76 65 72 66 6c 6f 77 ns that overflow
491e0 65 64 20 62 65 63 61 75 73 65 20 74 68 65 79 0a ed because they.
491f0 2a 2a 20 77 68 65 72 65 20 74 6f 6f 20 6c 61 72 ** where too lar
49200 67 65 20 28 74 68 65 79 20 77 65 72 65 20 6c 61 ge (they were la
49210 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 22 73 rger than the "s
49220 7a 22 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a z" parameter to.
49230 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ** [SQLITE_CONFI
49240 47 5f 50 41 47 45 43 41 43 48 45 5d 29 20 61 6e G_PAGECACHE]) an
49250 64 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 74 68 d allocations th
49260 61 74 20 6f 76 65 72 66 6c 6f 77 65 64 20 62 65 at overflowed be
49270 63 61 75 73 65 0a 2a 2a 20 6e 6f 20 73 70 61 63 cause.** no spac
49280 65 20 77 61 73 20 6c 65 66 74 20 69 6e 20 74 68 e was left in th
49290 65 20 70 61 67 65 20 63 61 63 68 65 2e 3c 2f 64 e page cache.</d
492a0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
492b0 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 43 ITE_STATUS_PAGEC
492c0 41 43 48 45 5f 53 49 5a 45 3c 2f 64 74 3e 0a 2a ACHE_SIZE</dt>.*
492d0 2a 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d * <dd>This param
492e0 65 74 65 72 20 72 65 63 6f 72 64 73 20 74 68 65 eter records the
492f0 20 6c 61 72 67 65 73 74 20 6d 65 6d 6f 72 79 20 largest memory
49300 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 allocation reque
49310 73 74 0a 2a 2a 20 68 61 6e 64 65 64 20 74 6f 20 st.** handed to
49320 5b 70 61 67 65 63 61 63 68 65 20 6d 65 6d 6f 72 [pagecache memor
49330 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e 20 20 4f y allocator]. O
49340 6e 6c 79 20 74 68 65 20 76 61 6c 75 65 20 72 65 nly the value re
49350 74 75 72 6e 65 64 20 69 6e 20 74 68 65 0a 2a 2a turned in the.**
49360 20 2a 70 48 69 67 68 77 61 74 65 72 20 70 61 72 *pHighwater par
49370 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 ameter to [sqlit
49380 65 33 5f 73 74 61 74 75 73 28 29 5d 20 69 73 20 e3_status()] is
49390 6f 66 20 69 6e 74 65 72 65 73 74 2e 20 20 0a 2a of interest. .*
493a0 2a 20 54 68 65 20 76 61 6c 75 65 20 77 72 69 74 * The value writ
493b0 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 2a 70 43 ten into the *pC
493c0 75 72 72 65 6e 74 20 70 61 72 61 6d 65 74 65 72 urrent parameter
493d0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f is undefined.</
493e0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
493f0 4c 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 LITE_STATUS_SCRA
49400 54 43 48 5f 55 53 45 44 3c 2f 64 74 3e 0a 2a 2a TCH_USED</dt>.**
49410 20 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 <dd>This parame
49420 74 65 72 20 72 65 74 75 72 6e 73 20 74 68 65 20 ter returns the
49430 6e 75 6d 62 65 72 20 6f 66 20 61 6c 6c 6f 63 61 number of alloca
49440 74 69 6f 6e 73 20 75 73 65 64 20 6f 75 74 20 6f tions used out o
49450 66 20 74 68 65 0a 2a 2a 20 5b 73 63 72 61 74 63 f the.** [scratc
49460 68 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 h memory allocat
49470 6f 72 5d 20 63 6f 6e 66 69 67 75 72 65 64 20 75 or] configured u
49480 73 69 6e 67 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f sing.** [SQLITE_
49490 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 2e CONFIG_SCRATCH].
494a0 20 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 The value retu
494b0 72 6e 65 64 20 69 73 20 69 6e 20 61 6c 6c 6f 63 rned is in alloc
494c0 61 74 69 6f 6e 73 2c 20 6e 6f 74 0a 2a 2a 20 69 ations, not.** i
494d0 6e 20 62 79 74 65 73 2e 20 20 53 69 6e 63 65 20 n bytes. Since
494e0 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 20 a single thread
494f0 6d 61 79 20 6f 6e 6c 79 20 68 61 76 65 20 6f 6e may only have on
49500 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 e scratch alloca
49510 74 69 6f 6e 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 tion.** outstand
49520 69 6e 67 20 61 74 20 74 69 6d 65 2c 20 74 68 69 ing at time, thi
49530 73 20 70 61 72 61 6d 65 74 65 72 20 61 6c 73 6f s parameter also
49540 20 72 65 70 6f 72 74 73 20 74 68 65 20 6e 75 6d reports the num
49550 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 0a 2a ber of threads.*
49560 2a 20 75 73 69 6e 67 20 73 63 72 61 74 63 68 20 * using scratch
49570 6d 65 6d 6f 72 79 20 61 74 20 74 68 65 20 73 61 memory at the sa
49580 6d 65 20 74 69 6d 65 2e 3c 2f 64 64 3e 0a 2a 2a me time.</dd>.**
49590 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 53 .** <dt>SQLITE_S
495a0 54 41 54 55 53 5f 53 43 52 41 54 43 48 5f 4f 56 TATUS_SCRATCH_OV
495b0 45 52 46 4c 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c ERFLOW</dt>.** <
495c0 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 dd>This paramete
495d0 72 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 r returns the nu
495e0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 mber of bytes of
495f0 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 0a scratch memory.
49600 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 77 68 ** allocation wh
49610 69 63 68 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 ich could not be
49620 20 73 74 61 74 69 73 66 69 65 64 20 62 79 20 74 statisfied by t
49630 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 he [SQLITE_CONFI
49640 47 5f 53 43 52 41 54 43 48 5d 0a 2a 2a 20 62 75 G_SCRATCH].** bu
49650 66 66 65 72 20 61 6e 64 20 77 68 65 72 65 20 66 ffer and where f
49660 6f 72 63 65 64 20 74 6f 20 6f 76 65 72 66 6c 6f orced to overflo
49670 77 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 w to [sqlite3_ma
49680 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 76 61 lloc()]. The va
49690 6c 75 65 73 0a 2a 2a 20 72 65 74 75 72 6e 65 64 lues.** returned
496a0 20 69 6e 63 6c 75 64 65 20 6f 76 65 72 66 6c 6f include overflo
496b0 77 73 20 62 65 63 61 75 73 65 20 74 68 65 20 72 ws because the r
496c0 65 71 75 65 73 74 65 64 20 61 6c 6c 6f 63 61 74 equested allocat
496d0 69 6f 6e 20 77 61 73 20 74 6f 6f 0a 2a 2a 20 6c ion was too.** l
496e0 61 72 67 65 72 20 28 74 68 61 74 20 69 73 2c 20 arger (that is,
496f0 62 65 63 61 75 73 65 20 74 68 65 20 72 65 71 75 because the requ
49700 65 73 74 65 64 20 61 6c 6c 6f 63 61 74 69 6f 6e ested allocation
49710 20 77 61 73 20 6c 61 72 67 65 72 20 74 68 61 6e was larger than
49720 20 74 68 65 0a 2a 2a 20 22 73 7a 22 20 70 61 72 the.** "sz" par
49730 61 6d 65 74 65 72 20 74 6f 20 5b 53 51 4c 49 54 ameter to [SQLIT
49740 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 E_CONFIG_SCRATCH
49750 5d 29 20 61 6e 64 20 62 65 63 61 75 73 65 20 6e ]) and because n
49760 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 o scratch buffer
49770 0a 2a 2a 20 73 6c 6f 74 73 20 77 65 72 65 20 61 .** slots were a
49780 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 3c 2f 64 vailable..** </d
49790 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
497a0 49 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54 ITE_STATUS_SCRAT
497b0 43 48 5f 53 49 5a 45 3c 2f 64 74 3e 0a 2a 2a 20 CH_SIZE</dt>.**
497c0 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 <dd>This paramet
497d0 65 72 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c er records the l
497e0 61 72 67 65 73 74 20 6d 65 6d 6f 72 79 20 61 6c argest memory al
497f0 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 location request
49800 0a 2a 2a 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 .** handed to [s
49810 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 6c cratch memory al
49820 6c 6f 63 61 74 6f 72 5d 2e 20 20 4f 6e 6c 79 20 locator]. Only
49830 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
49840 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 2a 70 48 ed in the.** *pH
49850 69 67 68 77 61 74 65 72 20 70 61 72 61 6d 65 74 ighwater paramet
49860 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 er to [sqlite3_s
49870 74 61 74 75 73 28 29 5d 20 69 73 20 6f 66 20 69 tatus()] is of i
49880 6e 74 65 72 65 73 74 2e 20 20 0a 2a 2a 20 54 68 nterest. .** Th
49890 65 20 76 61 6c 75 65 20 77 72 69 74 74 65 6e 20 e value written
498a0 69 6e 74 6f 20 74 68 65 20 2a 70 43 75 72 72 65 into the *pCurre
498b0 6e 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nt parameter is
498c0 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a undefined.</dd>.
498d0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
498e0 5f 53 54 41 54 55 53 5f 50 41 52 53 45 52 5f 53 _STATUS_PARSER_S
498f0 54 41 43 4b 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 TACK</dt>.** <dd
49900 3e 54 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 >This parameter
49910 72 65 63 6f 72 64 73 20 74 68 65 20 64 65 65 70 records the deep
49920 65 73 74 20 70 61 72 73 65 72 20 73 74 61 63 6b est parser stack
49930 2e 20 20 49 74 20 69 73 20 6f 6e 6c 79 0a 2a 2a . It is only.**
49940 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 53 meaningful if S
49950 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
49960 64 20 77 69 74 68 20 5b 59 59 54 52 41 43 4b 4d d with [YYTRACKM
49970 41 58 53 54 41 43 4b 44 45 50 54 48 5d 2e 3c 2f AXSTACKDEPTH].</
49980 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a dd>.** </dl>.**.
49990 2a 2a 20 4e 65 77 20 73 74 61 74 75 73 20 70 61 ** New status pa
499a0 72 61 6d 65 74 65 72 73 20 6d 61 79 20 62 65 20 rameters may be
499b0 61 64 64 65 64 20 66 72 6f 6d 20 74 69 6d 65 20 added from time
499c0 74 6f 20 74 69 6d 65 2e 0a 2a 2f 0a 23 64 65 66 to time..*/.#def
499d0 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 ine SQLITE_STATU
499e0 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 20 20 20 S_MEMORY_USED
499f0 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 0.#define
49a00 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 SQLITE_STATUS_P
49a10 41 47 45 43 41 43 48 45 5f 55 53 45 44 20 20 20 AGECACHE_USED
49a20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 1.#define SQ
49a30 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 45 LITE_STATUS_PAGE
49a40 43 41 43 48 45 5f 4f 56 45 52 46 4c 4f 57 20 20 CACHE_OVERFLOW
49a50 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
49a60 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54 43 48 E_STATUS_SCRATCH
49a70 5f 55 53 45 44 20 20 20 20 20 20 20 20 20 33 0a _USED 3.
49a80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
49a90 54 41 54 55 53 5f 53 43 52 41 54 43 48 5f 4f 56 TATUS_SCRATCH_OV
49aa0 45 52 46 4c 4f 57 20 20 20 20 20 34 0a 23 64 65 ERFLOW 4.#de
49ab0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 fine SQLITE_STAT
49ac0 55 53 5f 4d 41 4c 4c 4f 43 5f 53 49 5a 45 20 20 US_MALLOC_SIZE
49ad0 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 5.#defin
49ae0 65 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f e SQLITE_STATUS_
49af0 50 41 52 53 45 52 5f 53 54 41 43 4b 20 20 20 20 PARSER_STACK
49b00 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 6.#define S
49b10 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 50 41 47 QLITE_STATUS_PAG
49b20 45 43 41 43 48 45 5f 53 49 5a 45 20 20 20 20 20 ECACHE_SIZE
49b30 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 7.#define SQLI
49b40 54 45 5f 53 54 41 54 55 53 5f 53 43 52 41 54 43 TE_STATUS_SCRATC
49b50 48 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 38 H_SIZE 8
49b60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
49b70 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 : Database Conne
49b80 63 74 69 6f 6e 20 53 74 61 74 75 73 20 7b 48 31 ction Status {H1
49b90 37 35 30 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 7500} <S60200>.*
49ba0 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a * EXPERIMENTAL.*
49bb0 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 *.** This interf
49bc0 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 ace is used to r
49bd0 65 74 72 69 65 76 65 20 72 75 6e 74 69 6d 65 20 etrieve runtime
49be0 73 74 61 74 75 73 20 69 6e 66 6f 72 6d 61 74 69 status informati
49bf0 6f 6e 20 0a 2a 2a 20 61 62 6f 75 74 20 61 20 73 on .** about a s
49c00 69 6e 67 6c 65 20 5b 64 61 74 61 62 61 73 65 20 ingle [database
49c10 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 connection]. Th
49c20 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
49c30 20 69 73 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 is the.** datab
49c40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f ase connection o
49c50 62 6a 65 63 74 20 74 6f 20 62 65 20 69 6e 74 65 bject to be inte
49c60 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 73 rrogated. The s
49c70 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 0a 2a econd argument.*
49c80 2a 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 * is the paramet
49c90 65 72 20 74 6f 20 69 6e 74 65 72 72 6f 67 61 74 er to interrogat
49ca0 65 2e 20 20 43 75 72 72 65 6e 74 6c 79 2c 20 74 e. Currently, t
49cb0 68 65 20 6f 6e 6c 79 20 61 6c 6c 6f 77 65 64 20 he only allowed
49cc0 76 61 6c 75 65 0a 2a 2a 20 66 6f 72 20 74 68 65 value.** for the
49cd0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
49ce0 72 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 42 53 r is [SQLITE_DBS
49cf0 54 41 54 55 53 5f 4c 4f 4f 4b 41 53 49 44 45 5f TATUS_LOOKASIDE_
49d00 55 53 45 44 5d 2e 0a 2a 2a 20 41 64 64 69 74 69 USED]..** Additi
49d10 6f 6e 61 6c 20 6f 70 74 69 6f 6e 73 20 77 69 6c onal options wil
49d20 6c 20 6c 69 6b 65 6c 79 20 61 70 70 65 61 72 20 l likely appear
49d30 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
49d40 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a es of SQLite..**
49d50 0a 2a 2a 20 54 68 65 20 63 75 72 72 65 6e 74 20 .** The current
49d60 76 61 6c 75 65 20 6f 66 20 74 68 65 20 72 65 71 value of the req
49d70 75 65 73 74 65 64 20 70 61 72 61 6d 65 74 65 72 uested parameter
49d80 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f is written into
49d90 20 2a 70 43 75 72 0a 2a 2a 20 61 6e 64 20 74 68 *pCur.** and th
49da0 65 20 68 69 67 68 65 73 74 20 69 6e 73 74 61 6e e highest instan
49db0 74 61 6e 65 6f 75 73 20 76 61 6c 75 65 20 69 73 taneous value is
49dc0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 written into *p
49dd0 48 69 77 74 72 2e 20 20 49 66 0a 2a 2a 20 74 68 Hiwtr. If.** th
49de0 65 20 72 65 73 65 74 46 6c 67 20 69 73 20 74 72 e resetFlg is tr
49df0 75 65 2c 20 74 68 65 6e 20 74 68 65 20 68 69 67 ue, then the hig
49e00 68 65 73 74 20 69 6e 73 74 61 6e 74 61 6e 65 6f hest instantaneo
49e10 75 73 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 72 us value is.** r
49e20 65 73 65 74 20 62 61 63 6b 20 64 6f 77 6e 20 74 eset back down t
49e30 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 o the current va
49e40 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 lue..**.** See a
49e50 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 73 74 lso: [sqlite3_st
49e60 61 74 75 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c atus()] and [sql
49e70 69 74 65 33 5f 73 74 6d 74 5f 73 74 61 74 75 73 ite3_stmt_status
49e80 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 ()]..*/.SQLITE_E
49e90 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 XPERIMENTAL int
49ea0 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 sqlite3_db_statu
49eb0 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 s(sqlite3*, int
49ec0 6f 70 2c 20 69 6e 74 20 2a 70 43 75 72 2c 20 69 op, int *pCur, i
49ed0 6e 74 20 2a 70 48 69 77 74 72 2c 20 69 6e 74 20 nt *pHiwtr, int
49ee0 72 65 73 65 74 46 6c 67 29 3b 0a 0a 2f 2a 0a 2a resetFlg);../*.*
49ef0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 74 * CAPI3REF: Stat
49f00 75 73 20 50 61 72 61 6d 65 74 65 72 73 20 66 6f us Parameters fo
49f10 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 r database conne
49f20 63 74 69 6f 6e 73 20 7b 48 31 37 35 32 30 7d 20 ctions {H17520}
49f30 3c 48 31 37 35 30 30 3e 0a 2a 2a 20 45 58 50 45 <H17500>.** EXPE
49f40 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 53 RIMENTAL.**.** S
49f50 74 61 74 75 73 20 76 65 72 62 73 20 66 6f 72 20 tatus verbs for
49f60 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 [sqlite3_db_stat
49f70 75 73 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c us()]..**.** <dl
49f80 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f >.** <dt>SQLITE_
49f90 44 42 53 54 41 54 55 53 5f 4c 4f 4f 4b 41 53 49 DBSTATUS_LOOKASI
49fa0 44 45 5f 55 53 45 44 3c 2f 64 74 3e 0a 2a 2a 20 DE_USED</dt>.**
49fb0 3c 64 64 3e 54 68 69 73 20 70 61 72 61 6d 65 74 <dd>This paramet
49fc0 65 72 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e er returns the n
49fd0 75 6d 62 65 72 20 6f 66 20 6c 6f 6f 6b 61 73 69 umber of lookasi
49fe0 64 65 20 6d 65 6d 6f 72 79 20 73 6c 6f 74 73 20 de memory slots
49ff0 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 63 68 65 currently.** che
4a000 63 6b 65 64 20 6f 75 74 2e 3c 2f 64 64 3e 0a 2a cked out.</dd>.*
4a010 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 * </dl>.*/.#defi
4a020 6e 65 20 53 51 4c 49 54 45 5f 44 42 53 54 41 54 ne SQLITE_DBSTAT
4a030 55 53 5f 4c 4f 4f 4b 41 53 49 44 45 5f 55 53 45 US_LOOKASIDE_USE
4a040 44 20 20 20 20 20 30 0a 0a 0a 2f 2a 0a 2a 2a 20 D 0.../*.**
4a050 43 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 CAPI3REF: Prepar
4a060 65 64 20 53 74 61 74 65 6d 65 6e 74 20 53 74 61 ed Statement Sta
4a070 74 75 73 20 7b 48 31 37 35 35 30 7d 20 3c 53 36 tus {H17550} <S6
4a080 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 0200>.** EXPERIM
4a090 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 61 63 68 ENTAL.**.** Each
4a0a0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
4a0b0 65 6e 74 20 6d 61 69 6e 74 61 69 6e 73 20 76 61 ent maintains va
4a0c0 72 69 6f 75 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 rious.** [SQLITE
4a0d0 5f 53 54 4d 54 53 54 41 54 55 53 5f 53 4f 52 54 _STMTSTATUS_SORT
4a0e0 20 7c 20 63 6f 75 6e 74 65 72 73 5d 20 74 68 61 | counters] tha
4a0f0 74 20 6d 65 61 73 75 72 65 20 74 68 65 20 6e 75 t measure the nu
4a100 6d 62 65 72 0a 2a 2a 20 6f 66 20 74 69 6d 65 73 mber.** of times
4a110 20 69 74 20 68 61 73 20 70 65 72 66 6f 72 6d 65 it has performe
4a120 64 20 73 70 65 63 69 66 69 63 20 6f 70 65 72 61 d specific opera
4a130 74 69 6f 6e 73 2e 20 20 54 68 65 73 65 20 63 6f tions. These co
4a140 75 6e 74 65 72 73 20 63 61 6e 0a 2a 2a 20 62 65 unters can.** be
4a150 20 75 73 65 64 20 74 6f 20 6d 6f 6e 69 74 6f 72 used to monitor
4a160 20 74 68 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 the performance
4a170 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73 characteristics
4a180 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 64 of the prepared
4a190 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 .** statements.
4a1a0 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 For example, if
4a1b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 the number of t
4a1c0 61 62 6c 65 20 73 74 65 70 73 20 67 72 65 61 74 able steps great
4a1d0 6c 79 20 65 78 63 65 65 64 73 0a 2a 2a 20 74 68 ly exceeds.** th
4a1e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 61 62 6c e number of tabl
4a1f0 65 20 73 65 61 72 63 68 65 73 20 6f 72 20 72 65 e searches or re
4a200 73 75 6c 74 20 72 6f 77 73 2c 20 74 68 61 74 20 sult rows, that
4a210 77 6f 75 6c 64 20 74 65 6e 64 20 74 6f 20 69 6e would tend to in
4a220 64 69 63 61 74 65 0a 2a 2a 20 74 68 61 74 20 74 dicate.** that t
4a230 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 he prepared stat
4a240 65 6d 65 6e 74 20 69 73 20 75 73 69 6e 67 20 61 ement is using a
4a250 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e full table scan
4a260 20 72 61 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 rather than.**
4a270 61 6e 20 69 6e 64 65 78 2e 20 20 0a 2a 2a 0a 2a an index. .**.*
4a280 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 * This interface
4a290 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 74 72 is used to retr
4a2a0 69 65 76 65 20 61 6e 64 20 72 65 73 65 74 20 63 ieve and reset c
4a2b0 6f 75 6e 74 65 72 20 76 61 6c 75 65 73 20 66 72 ounter values fr
4a2c0 6f 6d 0a 2a 2a 20 61 20 5b 70 72 65 70 61 72 65 om.** a [prepare
4a2d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 54 d statement]. T
4a2e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
4a2f0 74 20 69 73 20 74 68 65 20 70 72 65 70 61 72 65 t is the prepare
4a300 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f d statement.** o
4a310 62 6a 65 63 74 20 74 6f 20 62 65 20 69 6e 74 65 bject to be inte
4a320 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 73 rrogated. The s
4a330 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 0a 2a econd argument.*
4a340 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 * is an integer
4a350 63 6f 64 65 20 66 6f 72 20 61 20 73 70 65 63 69 code for a speci
4a360 66 69 63 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 fic [SQLITE_STMT
4a370 53 54 41 54 55 53 5f 53 4f 52 54 20 7c 20 63 6f STATUS_SORT | co
4a380 75 6e 74 65 72 5d 0a 2a 2a 20 74 6f 20 62 65 20 unter].** to be
4a390 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 0a 2a interrogated. .*
4a3a0 2a 20 54 68 65 20 63 75 72 72 65 6e 74 20 76 61 * The current va
4a3b0 6c 75 65 20 6f 66 20 74 68 65 20 72 65 71 75 65 lue of the reque
4a3c0 73 74 65 64 20 63 6f 75 6e 74 65 72 20 69 73 20 sted counter is
4a3d0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 returned..** If
4a3e0 74 68 65 20 72 65 73 65 74 46 6c 67 20 69 73 20 the resetFlg is
4a3f0 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63 true, then the c
4a400 6f 75 6e 74 65 72 20 69 73 20 72 65 73 65 74 20 ounter is reset
4a410 74 6f 20 7a 65 72 6f 20 61 66 74 65 72 20 74 68 to zero after th
4a420 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 is.** interface
4a430 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a call returns..**
4a440 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
4a450 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d qlite3_status()]
4a460 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 64 62 and [sqlite3_db
4a470 5f 73 74 61 74 75 73 28 29 5d 2e 0a 2a 2f 0a 53 _status()]..*/.S
4a480 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 QLITE_EXPERIMENT
4a490 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 AL int sqlite3_s
4a4a0 74 6d 74 5f 73 74 61 74 75 73 28 73 71 6c 69 74 tmt_status(sqlit
4a4b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 6f 70 e3_stmt*, int op
4a4c0 2c 69 6e 74 20 72 65 73 65 74 46 6c 67 29 3b 0a ,int resetFlg);.
4a4d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
4a4e0 20 53 74 61 74 75 73 20 50 61 72 61 6d 65 74 65 Status Paramete
4a4f0 72 73 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 rs for prepared
4a500 73 74 61 74 65 6d 65 6e 74 73 20 7b 48 31 37 35 statements {H175
4a510 37 30 7d 20 3c 48 31 37 35 35 30 3e 0a 2a 2a 20 70} <H17550>.**
4a520 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a EXPERIMENTAL.**.
4a530 2a 2a 20 54 68 65 73 65 20 70 72 65 70 72 6f 63 ** These preproc
4a540 65 73 73 6f 72 20 6d 61 63 72 6f 73 20 64 65 66 essor macros def
4a550 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 ine integer code
4a560 73 20 74 68 61 74 20 6e 61 6d 65 20 63 6f 75 6e s that name coun
4a570 74 65 72 0a 2a 2a 20 76 61 6c 75 65 73 20 61 73 ter.** values as
4a580 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 sociated with th
4a590 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f e [sqlite3_stmt_
4a5a0 73 74 61 74 75 73 28 29 5d 20 69 6e 74 65 72 66 status()] interf
4a5b0 61 63 65 2e 0a 2a 2a 20 54 68 65 20 6d 65 61 6e ace..** The mean
4a5c0 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 ings of the vari
4a5d0 6f 75 73 20 63 6f 75 6e 74 65 72 73 20 61 72 65 ous counters are
4a5e0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
4a5f0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 ** <dl>.** <dt>S
4a600 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55 53 QLITE_STMTSTATUS
4a610 5f 46 55 4c 4c 53 43 41 4e 5f 53 54 45 50 3c 2f _FULLSCAN_STEP</
4a620 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 dt>.** <dd>This
4a630 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 is the number of
4a640 20 74 69 6d 65 73 20 74 68 61 74 20 53 51 4c 69 times that SQLi
4a650 74 65 20 68 61 73 20 73 74 65 70 70 65 64 20 66 te has stepped f
4a660 6f 72 77 61 72 64 20 69 6e 0a 2a 2a 20 61 20 74 orward in.** a t
4a670 61 62 6c 65 20 61 73 20 70 61 72 74 20 6f 66 20 able as part of
4a680 61 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 a full table sca
4a690 6e 2e 20 20 4c 61 72 67 65 20 6e 75 6d 62 65 72 n. Large number
4a6a0 73 20 66 6f 72 20 74 68 69 73 20 63 6f 75 6e 74 s for this count
4a6b0 65 72 0a 2a 2a 20 6d 61 79 20 69 6e 64 69 63 61 er.** may indica
4a6c0 74 65 20 6f 70 70 6f 72 74 75 6e 69 74 69 65 73 te opportunities
4a6d0 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 for performance
4a6e0 20 69 6d 70 72 6f 76 65 6d 65 6e 74 20 74 68 72 improvement thr
4a6f0 6f 75 67 68 20 0a 2a 2a 20 63 61 72 65 66 75 6c ough .** careful
4a700 20 75 73 65 20 6f 66 20 69 6e 64 69 63 65 73 2e use of indices.
4a710 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
4a720 53 51 4c 49 54 45 5f 53 54 4d 54 53 54 41 54 55 SQLITE_STMTSTATU
4a730 53 5f 53 4f 52 54 3c 2f 64 74 3e 0a 2a 2a 20 3c S_SORT</dt>.** <
4a740 64 64 3e 54 68 69 73 20 69 73 20 74 68 65 20 6e dd>This is the n
4a750 75 6d 62 65 72 20 6f 66 20 73 6f 72 74 20 6f 70 umber of sort op
4a760 65 72 61 74 69 6f 6e 73 20 74 68 61 74 20 68 61 erations that ha
4a770 76 65 20 6f 63 63 75 72 72 65 64 2e 0a 2a 2a 20 ve occurred..**
4a780 41 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61 6c 75 65 A non-zero value
4a790 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 65 72 in this counter
4a7a0 20 6d 61 79 20 69 6e 64 69 63 61 74 65 20 61 6e may indicate an
4a7b0 20 6f 70 70 6f 72 74 75 6e 69 74 79 20 74 6f 0a opportunity to.
4a7c0 2a 2a 20 69 6d 70 72 6f 76 65 6d 65 6e 74 20 70 ** improvement p
4a7d0 65 72 66 6f 72 6d 61 6e 63 65 20 74 68 72 6f 75 erformance throu
4a7e0 67 68 20 63 61 72 65 66 75 6c 20 75 73 65 20 6f gh careful use o
4a7f0 66 20 69 6e 64 69 63 65 73 2e 3c 2f 64 64 3e 0a f indices.</dd>.
4a800 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 **.** </dl>.*/.#
4a810 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 define SQLITE_ST
4a820 4d 54 53 54 41 54 55 53 5f 46 55 4c 4c 53 43 41 MTSTATUS_FULLSCA
4a830 4e 5f 53 54 45 50 20 20 20 20 20 31 0a 23 64 65 N_STEP 1.#de
4a840 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 4d 54 fine SQLITE_STMT
4a850 53 54 41 54 55 53 5f 53 4f 52 54 20 20 20 20 20 STATUS_SORT
4a860 20 20 20 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2../*.*
4a870 2a 20 43 41 50 49 33 52 45 46 3a 20 43 75 73 74 * CAPI3REF: Cust
4a880 6f 6d 20 50 61 67 65 20 43 61 63 68 65 20 4f 62 om Page Cache Ob
4a890 6a 65 63 74 0a 2a 2a 20 45 58 50 45 52 49 4d 45 ject.** EXPERIME
4a8a0 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 NTAL.**.** The s
4a8b0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 20 74 79 qlite3_pcache ty
4a8c0 70 65 20 69 73 20 6f 70 61 71 75 65 2e 20 20 49 pe is opaque. I
4a8d0 74 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 t is implemented
4a8e0 20 62 79 0a 2a 2a 20 74 68 65 20 70 6c 75 67 67 by.** the plugg
4a8f0 61 62 6c 65 20 6d 6f 64 75 6c 65 2e 20 20 54 68 able module. Th
4a900 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 68 61 e SQLite core ha
4a910 73 20 6e 6f 20 6b 6e 6f 77 6c 65 64 67 65 20 6f s no knowledge o
4a920 66 0a 2a 2a 20 69 74 73 20 73 69 7a 65 20 6f 72 f.** its size or
4a930 20 69 6e 74 65 72 6e 61 6c 20 73 74 72 75 63 74 internal struct
4a940 75 72 65 20 61 6e 64 20 6e 65 76 65 72 20 64 65 ure and never de
4a950 61 6c 73 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 als with the.**
4a960 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 20 6f sqlite3_pcache o
4a970 62 6a 65 63 74 20 65 78 63 65 70 74 20 62 79 20 bject except by
4a980 68 6f 6c 64 69 6e 67 20 61 6e 64 20 70 61 73 73 holding and pass
4a990 69 6e 67 20 70 6f 69 6e 74 65 72 73 0a 2a 2a 20 ing pointers.**
4a9a0 74 6f 20 74 68 65 20 6f 62 6a 65 63 74 2e 0a 2a to the object..*
4a9b0 2a 0a 2a 2a 20 53 65 65 20 5b 73 71 6c 69 74 65 *.** See [sqlite
4a9c0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3_pcache_methods
4a9d0 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c ] for additional
4a9e0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f information..*/
4a9f0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
4aa00 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 20 73 sqlite3_pcache s
4aa10 71 6c 69 74 65 33 5f 70 63 61 63 68 65 3b 0a 0a qlite3_pcache;..
4aa20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
4aa30 41 70 70 6c 69 63 61 74 69 6f 6e 20 44 65 66 69 Application Defi
4aa40 6e 65 64 20 50 61 67 65 20 43 61 63 68 65 2e 0a ned Page Cache..
4aa50 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a ** EXPERIMENTAL.
4aa60 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 **.** The [sqlit
4aa70 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 e3_config]([SQLI
4aa80 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
4aa90 5d 2c 20 2e 2e 2e 29 20 69 6e 74 65 72 66 61 63 ], ...) interfac
4aaa0 65 20 63 61 6e 0a 2a 2a 20 72 65 67 69 73 74 65 e can.** registe
4aab0 72 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 r an alternative
4aac0 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c page cache impl
4aad0 65 6d 65 6e 74 61 74 69 6f 6e 20 62 79 20 70 61 ementation by pa
4aae0 73 73 69 6e 67 20 69 6e 20 61 6e 20 0a 2a 2a 20 ssing in an .**
4aaf0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
4ab00 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d sqlite3_pcache_m
4ab10 65 74 68 6f 64 73 20 73 74 72 75 63 74 75 72 65 ethods structure
4ab20 2e 20 54 68 65 20 6d 61 6a 6f 72 69 74 79 20 6f . The majority o
4ab30 66 20 74 68 65 20 0a 2a 2a 20 68 65 61 70 20 6d f the .** heap m
4ab40 65 6d 6f 72 79 20 75 73 65 64 20 62 79 20 73 71 emory used by sq
4ab50 6c 69 74 65 20 69 73 20 75 73 65 64 20 62 79 20 lite is used by
4ab60 74 68 65 20 70 61 67 65 20 63 61 63 68 65 20 74 the page cache t
4ab70 6f 20 63 61 63 68 65 20 64 61 74 61 20 72 65 61 o cache data rea
4ab80 64 20 0a 2a 2a 20 66 72 6f 6d 2c 20 6f 72 20 72 d .** from, or r
4ab90 65 61 64 79 20 74 6f 20 62 65 20 77 72 69 74 74 eady to be writt
4aba0 65 6e 20 74 6f 2c 20 74 68 65 20 64 61 74 61 62 en to, the datab
4abb0 61 73 65 20 66 69 6c 65 2e 20 42 79 20 69 6d 70 ase file. By imp
4abc0 6c 65 6d 65 6e 74 69 6e 67 20 61 20 0a 2a 2a 20 lementing a .**
4abd0 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 custom page cach
4abe0 65 20 75 73 69 6e 67 20 74 68 69 73 20 41 50 49 e using this API
4abf0 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e , an application
4ac00 20 63 61 6e 20 63 6f 6e 74 72 6f 6c 20 6d 6f 72 can control mor
4ac10 65 20 0a 2a 2a 20 70 72 65 63 69 73 65 6c 79 20 e .** precisely
4ac20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 the amount of me
4ac30 6d 6f 72 79 20 63 6f 6e 73 75 6d 65 64 20 62 79 mory consumed by
4ac40 20 73 71 6c 69 74 65 2c 20 74 68 65 20 77 61 79 sqlite, the way
4ac50 20 69 6e 20 77 68 69 63 68 20 0a 2a 2a 20 73 61 in which .** sa
4ac60 69 64 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c id memory is all
4ac70 6f 63 61 74 65 64 20 61 6e 64 20 72 65 6c 65 61 ocated and relea
4ac80 73 65 64 2c 20 61 6e 64 20 74 68 65 20 70 6f 6c sed, and the pol
4ac90 69 63 69 65 73 20 75 73 65 64 20 74 6f 20 0a 2a icies used to .*
4aca0 2a 20 64 65 74 65 72 6d 69 6e 65 20 65 78 61 63 * determine exac
4acb0 74 6c 79 20 77 68 69 63 68 20 70 61 72 74 73 20 tly which parts
4acc0 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69 of a database fi
4acd0 6c 65 20 61 72 65 20 63 61 63 68 65 64 20 61 6e le are cached an
4ace0 64 20 66 6f 72 20 0a 2a 2a 20 68 6f 77 20 6c 6f d for .** how lo
4acf0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f ng..**.** The co
4ad00 6e 74 65 6e 74 73 20 6f 66 20 74 68 65 20 73 74 ntents of the st
4ad10 72 75 63 74 75 72 65 20 61 72 65 20 63 6f 70 69 ructure are copi
4ad20 65 64 20 74 6f 20 61 6e 20 69 6e 74 65 72 6e 61 ed to an interna
4ad30 6c 20 62 75 66 66 65 72 20 62 79 20 73 71 6c 69 l buffer by sqli
4ad40 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 te.** within the
4ad50 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
4ad60 33 5f 63 6f 6e 66 69 67 5d 2e 0a 2a 2a 0a 2a 2a 3_config]..**.**
4ad70 20 54 68 65 20 78 49 6e 69 74 28 29 20 6d 65 74 The xInit() met
4ad80 68 6f 64 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e hod is called on
4ad90 63 65 20 66 6f 72 20 65 61 63 68 20 63 61 6c 6c ce for each call
4ada0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 to [sqlite3_ini
4adb0 74 69 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 28 75 tialize()].** (u
4adc0 73 75 61 6c 6c 79 20 6f 6e 6c 79 20 6f 6e 63 65 sually only once
4add0 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 during the life
4ade0 74 69 6d 65 20 6f 66 20 74 68 65 20 70 72 6f 63 time of the proc
4adf0 65 73 73 29 2e 20 49 74 20 69 73 20 70 61 73 73 ess). It is pass
4ae00 65 64 0a 2a 2a 20 61 20 63 6f 70 79 20 6f 66 20 ed.** a copy of
4ae10 74 68 65 20 73 71 6c 69 74 65 33 5f 70 63 61 63 the sqlite3_pcac
4ae20 68 65 5f 6d 65 74 68 6f 64 73 2e 70 41 72 67 20 he_methods.pArg
4ae30 76 61 6c 75 65 2e 20 49 74 20 63 61 6e 20 62 65 value. It can be
4ae40 20 75 73 65 64 20 74 6f 20 73 65 74 0a 2a 2a 20 used to set.**
4ae50 75 70 20 67 6c 6f 62 61 6c 20 73 74 72 75 63 74 up global struct
4ae60 75 72 65 73 20 61 6e 64 20 6d 75 74 65 78 65 73 ures and mutexes
4ae70 20 72 65 71 75 69 72 65 64 20 62 79 20 74 68 65 required by the
4ae80 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 custom page cac
4ae90 68 65 20 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 he .** implement
4aea0 61 74 69 6f 6e 2e 20 54 68 65 20 78 53 68 75 74 ation. The xShut
4aeb0 64 6f 77 6e 28 29 20 6d 65 74 68 6f 64 20 69 73 down() method is
4aec0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 called from wit
4aed0 68 69 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 hin .** [sqlite3
4aee0 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2c 20 69 66 _shutdown()], if
4aef0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
4af00 20 69 6e 76 6f 6b 65 73 20 74 68 69 73 20 41 50 invokes this AP
4af10 49 2e 20 49 74 20 63 61 6e 20 62 65 20 75 73 65 I. It can be use
4af20 64 0a 2a 2a 20 74 6f 20 63 6c 65 61 6e 20 75 70 d.** to clean up
4af30 20 61 6e 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 any outstanding
4af40 20 72 65 73 6f 75 72 63 65 73 20 62 65 66 6f 72 resources befor
4af50 65 20 70 72 6f 63 65 73 73 20 73 68 75 74 64 6f e process shutdo
4af60 77 6e 2c 20 69 66 20 72 65 71 75 69 72 65 64 2e wn, if required.
4af70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 43 72 65 61 .**.** The xCrea
4af80 74 65 28 29 20 6d 65 74 68 6f 64 20 69 73 20 75 te() method is u
4af90 73 65 64 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 sed to construct
4afa0 20 61 20 6e 65 77 20 63 61 63 68 65 20 69 6e 73 a new cache ins
4afb0 74 61 6e 63 65 2e 20 54 68 65 0a 2a 2a 20 66 69 tance. The.** fi
4afc0 72 73 74 20 70 61 72 61 6d 65 74 65 72 2c 20 73 rst parameter, s
4afd0 7a 50 61 67 65 2c 20 69 73 20 74 68 65 20 73 69 zPage, is the si
4afe0 7a 65 20 69 6e 20 62 79 74 65 73 20 6f 66 20 74 ze in bytes of t
4aff0 68 65 20 70 61 67 65 73 20 74 68 61 74 20 6d 75 he pages that mu
4b000 73 74 0a 2a 2a 20 62 65 20 61 6c 6c 6f 63 61 74 st.** be allocat
4b010 65 64 20 62 79 20 74 68 65 20 63 61 63 68 65 2e ed by the cache.
4b020 20 73 7a 50 61 67 65 20 77 69 6c 6c 20 6e 6f 74 szPage will not
4b030 20 62 65 20 61 20 70 6f 77 65 72 20 6f 66 20 74 be a power of t
4b040 77 6f 2e 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e wo. The.** secon
4b050 64 20 61 72 67 75 6d 65 6e 74 2c 20 62 50 75 72 d argument, bPur
4b060 67 65 61 62 6c 65 2c 20 69 73 20 74 72 75 65 20 geable, is true
4b070 69 66 20 74 68 65 20 63 61 63 68 65 20 62 65 69 if the cache bei
4b080 6e 67 20 63 72 65 61 74 65 64 20 77 69 6c 6c 0a ng created will.
4b090 2a 2a 20 62 65 20 75 73 65 64 20 74 6f 20 63 61 ** be used to ca
4b0a0 63 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 che database pag
4b0b0 65 73 20 72 65 61 64 20 66 72 6f 6d 20 61 20 66 es read from a f
4b0c0 69 6c 65 20 73 74 6f 72 65 64 20 6f 6e 20 64 69 ile stored on di
4b0d0 73 6b 2c 20 6f 72 0a 2a 2a 20 66 61 6c 73 65 20 sk, or.** false
4b0e0 69 66 20 69 74 20 69 73 20 75 73 65 64 20 66 6f if it is used fo
4b0f0 72 20 61 6e 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 r an in-memory d
4b100 61 74 61 62 61 73 65 2e 20 54 68 65 20 63 61 63 atabase. The cac
4b110 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
4b120 6e 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 68 61 n.** does not ha
4b130 76 65 20 74 6f 20 64 6f 20 61 6e 79 74 68 69 6e ve to do anythin
4b140 67 20 73 70 65 63 69 61 6c 20 62 61 73 65 64 20 g special based
4b150 6f 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 on the value of
4b160 62 50 75 72 67 65 61 62 6c 65 2c 0a 2a 2a 20 69 bPurgeable,.** i
4b170 74 20 69 73 20 70 75 72 65 6c 79 20 61 64 76 69 t is purely advi
4b180 73 6f 72 79 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 sory. .**.** The
4b190 20 78 43 61 63 68 65 73 69 7a 65 28 29 20 6d 65 xCachesize() me
4b1a0 74 68 6f 64 20 6d 61 79 20 62 65 20 63 61 6c 6c thod may be call
4b1b0 65 64 20 61 74 20 61 6e 79 20 74 69 6d 65 20 62 ed at any time b
4b1c0 79 20 53 51 4c 69 74 65 20 74 6f 20 73 65 74 20 y SQLite to set
4b1d0 74 68 65 0a 2a 2a 20 73 75 67 67 65 73 74 65 64 the.** suggested
4b1e0 20 6d 61 78 69 6d 75 6d 20 63 61 63 68 65 2d 73 maximum cache-s
4b1f0 69 7a 65 20 28 6e 75 6d 62 65 72 20 6f 66 20 70 ize (number of p
4b200 61 67 65 73 20 73 74 6f 72 65 64 20 62 79 29 20 ages stored by)
4b210 74 68 65 20 63 61 63 68 65 0a 2a 2a 20 69 6e 73 the cache.** ins
4b220 74 61 6e 63 65 20 70 61 73 73 65 64 20 61 73 20 tance passed as
4b230 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
4b240 6e 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 nt. This is the
4b250 76 61 6c 75 65 20 63 6f 6e 66 69 67 75 72 65 64 value configured
4b260 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 53 51 using.** the SQ
4b270 4c 69 74 65 20 22 5b 50 52 41 47 4d 41 20 63 61 Lite "[PRAGMA ca
4b280 63 68 65 5f 73 69 7a 65 5d 22 20 63 6f 6d 6d 61 che_size]" comma
4b290 6e 64 2e 20 41 73 20 77 69 74 68 20 74 68 65 20 nd. As with the
4b2a0 62 50 75 72 67 65 61 62 6c 65 20 70 61 72 61 6d bPurgeable param
4b2b0 65 74 65 72 2c 0a 2a 2a 20 74 68 65 20 69 6d 70 eter,.** the imp
4b2c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e lementation is n
4b2d0 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 64 ot required to d
4b2e0 6f 20 61 6e 79 74 68 69 6e 67 20 73 70 65 63 69 o anything speci
4b2f0 61 6c 20 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 al with this.**
4b300 76 61 6c 75 65 2c 20 69 74 20 69 73 20 61 64 76 value, it is adv
4b310 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a isory only..**.*
4b320 2a 20 54 68 65 20 78 50 61 67 65 63 6f 75 6e 74 * The xPagecount
4b330 28 29 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 () method should
4b340 20 72 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 return the numb
4b350 65 72 20 6f 66 20 70 61 67 65 73 20 63 75 72 72 er of pages curr
4b360 65 6e 74 6c 79 0a 2a 2a 20 73 74 6f 72 65 64 20 ently.** stored
4b370 69 6e 20 74 68 65 20 63 61 63 68 65 20 73 75 70 in the cache sup
4b380 70 6c 69 65 64 20 61 73 20 61 6e 20 61 72 67 75 plied as an argu
4b390 6d 65 6e 74 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 ment..** .** The
4b3a0 20 78 46 65 74 63 68 28 29 20 6d 65 74 68 6f 64 xFetch() method
4b3b0 20 69 73 20 75 73 65 64 20 74 6f 20 66 65 74 63 is used to fetc
4b3c0 68 20 61 20 70 61 67 65 20 61 6e 64 20 72 65 74 h a page and ret
4b3d0 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f urn a pointer to
4b3e0 20 69 74 2e 20 0a 2a 2a 20 41 20 27 70 61 67 65 it. .** A 'page
4b3f0 27 2c 20 69 6e 20 74 68 69 73 20 63 6f 6e 74 65 ', in this conte
4b400 78 74 2c 20 69 73 20 61 20 62 75 66 66 65 72 20 xt, is a buffer
4b410 6f 66 20 73 7a 50 61 67 65 20 62 79 74 65 73 20 of szPage bytes
4b420 61 6c 69 67 6e 65 64 20 61 74 20 61 6e 0a 2a 2a aligned at an.**
4b430 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 8-byte boundary
4b440 2e 20 54 68 65 20 70 61 67 65 20 74 6f 20 62 65 . The page to be
4b450 20 66 65 74 63 68 65 64 20 69 73 20 64 65 74 65 fetched is dete
4b460 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 6b 65 rmined by the ke
4b470 79 2e 20 54 68 65 0a 2a 2a 20 6d 69 6d 69 6d 75 y. The.** mimimu
4b480 6d 20 6b 65 79 20 76 61 6c 75 65 20 69 73 20 31 m key value is 1
4b490 2e 20 41 66 74 65 72 20 69 74 20 68 61 73 20 62 . After it has b
4b4a0 65 65 6e 20 72 65 74 72 69 65 76 65 64 20 75 73 een retrieved us
4b4b0 69 6e 67 20 78 46 65 74 63 68 2c 20 74 68 65 20 ing xFetch, the
4b4c0 70 61 67 65 20 0a 2a 2a 20 69 73 20 63 6f 6e 73 page .** is cons
4b4d0 69 64 65 72 65 64 20 74 6f 20 62 65 20 70 69 6e idered to be pin
4b4e0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ned..**.** If th
4b4f0 65 20 72 65 71 75 65 73 74 65 64 20 70 61 67 65 e requested page
4b500 20 69 73 20 61 6c 72 65 61 64 79 20 69 6e 20 74 is already in t
4b510 68 65 20 70 61 67 65 20 63 61 63 68 65 2c 20 74 he page cache, t
4b520 68 65 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f hen a pointer to
4b530 0a 2a 2a 20 74 68 65 20 63 61 63 68 65 64 20 62 .** the cached b
4b540 75 66 66 65 72 20 73 68 6f 75 6c 64 20 62 65 20 uffer should be
4b550 72 65 74 75 72 6e 65 64 20 77 69 74 68 20 69 74 returned with it
4b560 73 20 63 6f 6e 74 65 6e 74 73 20 69 6e 74 61 63 s contents intac
4b570 74 2e 20 49 66 20 74 68 65 0a 2a 2a 20 70 61 67 t. If the.** pag
4b580 65 20 69 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 e is not already
4b590 20 69 6e 20 74 68 65 20 63 61 63 68 65 2c 20 74 in the cache, t
4b5a0 68 65 6e 20 74 68 65 20 65 78 70 65 63 74 65 64 hen the expected
4b5b0 20 62 65 68 61 76 69 6f 75 72 20 6f 66 20 74 68 behaviour of th
4b5c0 65 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 64 65 e.** cache is de
4b5d0 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 termined by the
4b5e0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 63 72 65 value of the cre
4b5f0 61 74 65 46 6c 61 67 20 70 61 72 61 6d 65 74 65 ateFlag paramete
4b600 72 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 78 r passed.** to x
4b610 46 65 74 63 68 2c 20 61 63 63 6f 72 64 69 6e 67 Fetch, according
4b620 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e to the followin
4b630 67 20 74 61 62 6c 65 3a 0a 2a 2a 0a 2a 2a 20 3c g table:.**.** <
4b640 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 31 20 77 table border=1 w
4b650 69 64 74 68 3d 38 35 25 20 61 6c 69 67 6e 3d 63 idth=85% align=c
4b660 65 6e 74 65 72 3e 0a 2a 2a 20 20 20 3c 74 72 3e enter>.** <tr>
4b670 3c 74 68 3e 63 72 65 61 74 65 46 6c 61 67 3c 74 <th>createFlag<t
4b680 68 3e 45 78 70 65 63 74 65 64 20 42 65 68 61 76 h>Expected Behav
4b690 69 6f 75 72 0a 2a 2a 20 20 20 3c 74 72 3e 3c 74 iour.** <tr><t
4b6a0 64 3e 30 3c 74 64 3e 4e 55 4c 4c 20 73 68 6f 75 d>0<td>NULL shou
4b6b0 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 ld be returned.
4b6c0 4e 6f 20 6e 65 77 20 63 61 63 68 65 20 65 6e 74 No new cache ent
4b6d0 72 79 20 69 73 20 63 72 65 61 74 65 64 2e 0a 2a ry is created..*
4b6e0 2a 20 20 20 3c 74 72 3e 3c 74 64 3e 31 3c 74 64 * <tr><td>1<td
4b6f0 3e 49 66 20 63 72 65 61 74 65 46 6c 61 67 20 69 >If createFlag i
4b700 73 20 73 65 74 20 74 6f 20 31 2c 20 74 68 69 73 s set to 1, this
4b710 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 indicates that
4b720 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 .**
4b730 20 20 20 53 51 4c 69 74 65 20 69 73 20 68 6f 6c SQLite is hol
4b740 64 69 6e 67 20 70 69 6e 6e 65 64 20 70 61 67 65 ding pinned page
4b750 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 6e s that can be un
4b760 70 69 6e 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 pinned.**
4b770 20 20 20 20 20 20 20 20 20 62 79 20 77 72 69 74 by writ
4b780 69 6e 67 20 74 68 65 69 72 20 63 6f 6e 74 65 6e ing their conten
4b790 74 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 ts to the databa
4b7a0 73 65 20 66 69 6c 65 20 28 61 0a 2a 2a 20 20 20 se file (a.**
4b7b0 20 20 20 20 20 20 20 20 20 20 20 20 20 72 65 6c rel
4b7c0 61 74 69 76 65 6c 79 20 65 78 70 65 6e 73 69 76 atively expensiv
4b7d0 65 20 6f 70 65 72 61 74 69 6f 6e 29 2e 20 49 6e e operation). In
4b7e0 20 74 68 69 73 20 73 69 74 75 61 74 69 6f 6e 20 this situation
4b7f0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 the.**
4b800 20 20 20 20 20 20 63 61 63 68 65 20 69 6d 70 6c cache impl
4b810 65 6d 65 6e 74 61 74 69 6f 6e 20 68 61 73 20 74 ementation has t
4b820 77 6f 20 63 68 6f 69 63 65 73 3a 20 69 74 20 63 wo choices: it c
4b830 61 6e 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2c 0a an return NULL,.
4b840 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 **
4b850 20 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 in which case
4b860 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 74 74 65 SQLite will atte
4b870 6d 70 74 20 74 6f 20 75 6e 70 69 6e 20 6f 6e 65 mpt to unpin one
4b880 20 6f 72 20 6d 6f 72 65 20 0a 2a 2a 20 20 20 20 or more .**
4b890 20 20 20 20 20 20 20 20 20 20 20 20 70 61 67 65 page
4b8a0 73 20 62 65 66 6f 72 65 20 72 65 2d 72 65 71 75 s before re-requ
4b8b0 65 73 74 69 6e 67 20 74 68 65 20 73 61 6d 65 20 esting the same
4b8c0 70 61 67 65 2c 20 6f 72 20 69 74 20 63 61 6e 0a page, or it can.
4b8d0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 **
4b8e0 20 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 77 allocate a new
4b8f0 20 70 61 67 65 20 61 6e 64 20 72 65 74 75 72 6e page and return
4b900 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 a pointer to it
4b910 2e 20 49 66 20 61 20 6e 65 77 0a 2a 2a 20 20 20 . If a new.**
4b920 20 20 20 20 20 20 20 20 20 20 20 20 20 70 61 67 pag
4b930 65 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 2c 20 e is allocated,
4b940 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 then it must be
4b950 63 6f 6d 70 6c 65 74 65 6c 79 20 7a 65 72 6f 65 completely zeroe
4b960 64 20 62 65 66 6f 72 65 20 0a 2a 2a 20 20 20 20 d before .**
4b970 20 20 20 20 20 20 20 20 20 20 20 20 69 74 20 69 it i
4b980 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 20 s returned..**
4b990 20 3c 74 72 3e 3c 74 64 3e 32 3c 74 64 3e 49 66 <tr><td>2<td>If
4b9a0 20 63 72 65 61 74 65 46 6c 61 67 20 69 73 20 73 createFlag is s
4b9b0 65 74 20 74 6f 20 32 2c 20 74 68 65 6e 20 53 51 et to 2, then SQ
4b9c0 4c 69 74 65 20 69 73 20 6e 6f 74 20 68 6f 6c 64 Lite is not hold
4b9d0 69 6e 67 20 61 6e 79 0a 2a 2a 20 20 20 20 20 20 ing any.**
4b9e0 20 20 20 20 20 20 20 20 20 20 70 69 6e 6e 65 64 pinned
4b9f0 20 70 61 67 65 73 20 61 73 73 6f 63 69 61 74 65 pages associate
4ba00 64 20 77 69 74 68 20 74 68 65 20 73 70 65 63 69 d with the speci
4ba10 66 69 63 20 63 61 63 68 65 20 70 61 73 73 65 64 fic cache passed
4ba20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 .**
4ba30 20 20 20 61 73 20 74 68 65 20 66 69 72 73 74 20 as the first
4ba40 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 46 65 74 argument to xFet
4ba50 63 68 28 29 20 74 68 61 74 20 63 61 6e 20 62 65 ch() that can be
4ba60 20 75 6e 70 69 6e 6e 65 64 2e 20 54 68 65 0a 2a unpinned. The.*
4ba70 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 *
4ba80 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 cache implement
4ba90 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 61 74 74 ation should att
4baa0 65 6d 70 74 20 74 6f 20 61 6c 6c 6f 63 61 74 65 empt to allocate
4bab0 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 a new.**
4bac0 20 20 20 20 20 20 20 20 20 63 61 63 68 65 20 65 cache e
4bad0 6e 74 72 79 20 61 6e 64 20 72 65 74 75 72 6e 20 ntry and return
4bae0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e a pointer to it.
4baf0 20 41 67 61 69 6e 2c 20 74 68 65 20 6e 65 77 0a Again, the new.
4bb00 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 **
4bb10 20 20 70 61 67 65 20 73 68 6f 75 6c 64 20 62 65 page should be
4bb20 20 7a 65 72 6f 65 64 20 62 65 66 6f 72 65 20 69 zeroed before i
4bb30 74 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 49 t is returned. I
4bb40 66 20 74 68 65 20 78 46 65 74 63 68 28 29 0a 2a f the xFetch().*
4bb50 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 *
4bb60 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 method returns
4bb70 4e 55 4c 4c 20 77 68 65 6e 20 63 72 65 61 74 65 NULL when create
4bb80 46 6c 61 67 3d 3d 32 2c 20 53 51 4c 69 74 65 20 Flag==2, SQLite
4bb90 61 73 73 75 6d 65 73 20 74 68 61 74 0a 2a 2a 20 assumes that.**
4bba0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 61 a
4bbb0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
4bbc0 6f 6e 20 66 61 69 6c 65 64 20 61 6e 64 20 72 65 on failed and re
4bbd0 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4e 4f 4d turns SQLITE_NOM
4bbe0 45 4d 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 EM to the.**
4bbf0 20 20 20 20 20 20 20 20 20 20 20 20 75 73 65 72 user
4bc00 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a ..** </table>.**
4bc10 0a 2a 2a 20 78 55 6e 70 69 6e 28 29 20 69 73 20 .** xUnpin() is
4bc20 63 61 6c 6c 65 64 20 62 79 20 53 51 4c 69 74 65 called by SQLite
4bc30 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 with a pointer
4bc40 74 6f 20 61 20 63 75 72 72 65 6e 74 6c 79 20 70 to a currently p
4bc50 69 6e 6e 65 64 20 70 61 67 65 0a 2a 2a 20 61 73 inned page.** as
4bc60 20 69 74 73 20 73 65 63 6f 6e 64 20 61 72 67 75 its second argu
4bc70 6d 65 6e 74 2e 20 49 66 20 74 68 65 20 74 68 69 ment. If the thi
4bc80 72 64 20 70 61 72 61 6d 65 74 65 72 2c 20 64 69 rd parameter, di
4bc90 73 63 61 72 64 2c 20 69 73 20 6e 6f 6e 2d 7a 65 scard, is non-ze
4bca0 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 ro,.** then the
4bcb0 70 61 67 65 20 73 68 6f 75 6c 64 20 62 65 20 65 page should be e
4bcc0 76 69 63 74 65 64 20 66 72 6f 6d 20 74 68 65 20 victed from the
4bcd0 63 61 63 68 65 2e 20 49 6e 20 74 68 69 73 20 63 cache. In this c
4bce0 61 73 65 20 53 51 4c 69 74 65 20 0a 2a 2a 20 61 ase SQLite .** a
4bcf0 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 ssumes that the
4bd00 6e 65 78 74 20 74 69 6d 65 20 74 68 65 20 70 61 next time the pa
4bd10 67 65 20 69 73 20 72 65 74 72 69 65 76 65 64 20 ge is retrieved
4bd20 66 72 6f 6d 20 74 68 65 20 63 61 63 68 65 20 75 from the cache u
4bd30 73 69 6e 67 0a 2a 2a 20 74 68 65 20 78 46 65 74 sing.** the xFet
4bd40 63 68 28 29 20 6d 65 74 68 6f 64 2c 20 69 74 20 ch() method, it
4bd50 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e 20 will be zeroed.
4bd60 49 66 20 74 68 65 20 64 69 73 63 61 72 64 20 70 If the discard p
4bd70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 7a arameter is.** z
4bd80 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 70 61 ero, then the pa
4bd90 67 65 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 ge is considered
4bda0 20 74 6f 20 62 65 20 75 6e 70 69 6e 6e 65 64 2e to be unpinned.
4bdb0 20 54 68 65 20 63 61 63 68 65 20 69 6d 70 6c 65 The cache imple
4bdc0 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6d 61 79 mentation.** may
4bdd0 20 63 68 6f 6f 73 65 20 74 6f 20 72 65 63 6c 61 choose to recla
4bde0 69 6d 20 28 66 72 65 65 20 6f 72 20 72 65 63 79 im (free or recy
4bdf0 63 6c 65 29 20 75 6e 70 69 6e 6e 65 64 20 70 61 cle) unpinned pa
4be00 67 65 73 20 61 74 20 61 6e 79 20 74 69 6d 65 2e ges at any time.
4be10 0a 2a 2a 20 53 51 4c 69 74 65 20 61 73 73 75 6d .** SQLite assum
4be20 65 73 20 74 68 61 74 20 6e 65 78 74 20 74 69 6d es that next tim
4be30 65 20 74 68 65 20 70 61 67 65 20 69 73 20 72 65 e the page is re
4be40 74 72 69 65 76 65 64 20 66 72 6f 6d 20 74 68 65 trieved from the
4be50 20 63 61 63 68 65 0a 2a 2a 20 69 74 20 77 69 6c cache.** it wil
4be60 6c 20 65 69 74 68 65 72 20 62 65 20 7a 65 72 6f l either be zero
4be70 65 64 2c 20 6f 72 20 63 6f 6e 74 61 69 6e 20 74 ed, or contain t
4be80 68 65 20 73 61 6d 65 20 64 61 74 61 20 74 68 61 he same data tha
4be90 74 20 69 74 20 64 69 64 20 77 68 65 6e 20 69 74 t it did when it
4bea0 0a 2a 2a 20 77 61 73 20 75 6e 70 69 6e 6e 65 64 .** was unpinned
4beb0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68 ..**.** The cach
4bec0 65 20 69 73 20 6e 6f 74 20 72 65 71 75 69 72 65 e is not require
4bed0 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 61 6e 79 d to perform any
4bee0 20 72 65 66 65 72 65 6e 63 65 20 63 6f 75 6e 74 reference count
4bef0 69 6e 67 2e 20 41 20 73 69 6e 67 6c 65 20 0a 2a ing. A single .*
4bf00 2a 20 63 61 6c 6c 20 74 6f 20 78 55 6e 70 69 6e * call to xUnpin
4bf10 28 29 20 75 6e 70 69 6e 73 20 74 68 65 20 70 61 () unpins the pa
4bf20 67 65 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 ge regardless of
4bf30 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 the number of p
4bf40 72 69 6f 72 20 63 61 6c 6c 73 20 0a 2a 2a 20 74 rior calls .** t
4bf50 6f 20 78 46 65 74 63 68 28 29 2e 0a 2a 2a 0a 2a o xFetch()..**.*
4bf60 2a 20 54 68 65 20 78 52 65 6b 65 79 28 29 20 6d * The xRekey() m
4bf70 65 74 68 6f 64 20 69 73 20 75 73 65 64 20 74 6f ethod is used to
4bf80 20 63 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 change the key
4bf90 76 61 6c 75 65 20 61 73 73 6f 63 69 61 74 65 64 value associated
4bfa0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 70 61 67 with the.** pag
4bfb0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 e passed as the
4bfc0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
4bfd0 66 72 6f 6d 20 6f 6c 64 4b 65 79 20 74 6f 20 6e from oldKey to n
4bfe0 65 77 4b 65 79 2e 20 49 66 20 74 68 65 20 63 61 ewKey. If the ca
4bff0 63 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c che.** previousl
4c000 79 20 63 6f 6e 74 61 69 6e 73 20 61 6e 20 65 6e y contains an en
4c010 74 72 79 20 61 73 73 6f 63 69 61 74 65 64 20 77 try associated w
4c020 69 74 68 20 6e 65 77 4b 65 79 2c 20 69 74 20 73 ith newKey, it s
4c030 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 69 73 63 hould be.** disc
4c040 61 72 64 65 64 2e 20 41 6e 79 20 70 72 69 6f 72 arded. Any prior
4c050 20 63 61 63 68 65 20 65 6e 74 72 79 20 61 73 73 cache entry ass
4c060 6f 63 69 61 74 65 64 20 77 69 74 68 20 6e 65 77 ociated with new
4c070 4b 65 79 20 69 73 20 67 75 61 72 61 6e 74 65 65 Key is guarantee
4c080 64 20 6e 6f 74 0a 2a 2a 20 74 6f 20 62 65 20 70 d not.** to be p
4c090 69 6e 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 inned..**.** Whe
4c0a0 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 n SQLite calls t
4c0b0 68 65 20 78 54 72 75 6e 63 61 74 65 28 29 20 6d he xTruncate() m
4c0c0 65 74 68 6f 64 2c 20 74 68 65 20 63 61 63 68 65 ethod, the cache
4c0d0 20 6d 75 73 74 20 64 69 73 63 61 72 64 20 61 6c must discard al
4c0e0 6c 0a 2a 2a 20 65 78 69 73 74 69 6e 67 20 63 61 l.** existing ca
4c0f0 63 68 65 20 65 6e 74 72 69 65 73 20 77 69 74 68 che entries with
4c100 20 70 61 67 65 20 6e 75 6d 62 65 72 73 20 28 6b page numbers (k
4c110 65 79 73 29 20 67 72 65 61 74 65 72 20 74 68 61 eys) greater tha
4c120 6e 20 6f 72 20 65 71 75 61 6c 0a 2a 2a 20 74 6f n or equal.** to
4c130 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 the value of th
4c140 65 20 69 4c 69 6d 69 74 20 70 61 72 61 6d 65 74 e iLimit paramet
4c150 65 72 20 70 61 73 73 65 64 20 74 6f 20 78 54 72 er passed to xTr
4c160 75 6e 63 61 74 65 28 29 2e 20 49 66 20 61 6e 79 uncate(). If any
4c170 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 70 61 67 .** of these pag
4c180 65 73 20 61 72 65 20 70 69 6e 6e 65 64 2c 20 74 es are pinned, t
4c190 68 65 79 20 61 72 65 20 69 6d 70 6c 69 63 69 74 hey are implicit
4c1a0 6c 79 20 75 6e 70 69 6e 6e 65 64 2c 20 6d 65 61 ly unpinned, mea
4c1b0 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 74 68 65 ning that.** the
4c1c0 79 20 63 61 6e 20 62 65 20 73 61 66 65 6c 79 20 y can be safely
4c1d0 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 0a 2a 2a discarded..**.**
4c1e0 20 54 68 65 20 78 44 65 73 74 72 6f 79 28 29 20 The xDestroy()
4c1f0 6d 65 74 68 6f 64 20 69 73 20 75 73 65 64 20 74 method is used t
4c200 6f 20 64 65 6c 65 74 65 20 61 20 63 61 63 68 65 o delete a cache
4c210 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 78 43 allocated by xC
4c220 72 65 61 74 65 28 29 2e 0a 2a 2a 20 41 6c 6c 20 reate()..** All
4c230 72 65 73 6f 75 72 63 65 73 20 61 73 73 6f 63 69 resources associ
4c240 61 74 65 64 20 77 69 74 68 20 74 68 65 20 73 70 ated with the sp
4c250 65 63 69 66 69 65 64 20 63 61 63 68 65 20 73 68 ecified cache sh
4c260 6f 75 6c 64 20 62 65 20 66 72 65 65 64 2e 20 41 ould be freed. A
4c270 66 74 65 72 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 fter.** calling
4c280 74 68 65 20 78 44 65 73 74 72 6f 79 28 29 20 6d the xDestroy() m
4c290 65 74 68 6f 64 2c 20 53 51 4c 69 74 65 20 63 6f ethod, SQLite co
4c2a0 6e 73 69 64 65 72 73 20 74 68 65 20 5b 73 71 6c nsiders the [sql
4c2b0 69 74 65 33 5f 70 63 61 63 68 65 2a 5d 0a 2a 2a ite3_pcache*].**
4c2c0 20 68 61 6e 64 6c 65 20 69 6e 76 61 6c 69 64 2c handle invalid,
4c2d0 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 20 75 73 and will not us
4c2e0 65 20 69 74 20 77 69 74 68 20 61 6e 79 20 6f 74 e it with any ot
4c2f0 68 65 72 20 73 71 6c 69 74 65 33 5f 70 63 61 63 her sqlite3_pcac
4c300 68 65 5f 6d 65 74 68 6f 64 73 0a 2a 2a 20 66 75 he_methods.** fu
4c310 6e 63 74 69 6f 6e 73 2e 0a 2a 2f 0a 74 79 70 65 nctions..*/.type
4c320 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
4c330 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 e3_pcache_method
4c340 73 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 s sqlite3_pcache
4c350 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 _methods;.struct
4c360 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f sqlite3_pcache_
4c370 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 methods {. void
4c380 20 2a 70 41 72 67 3b 0a 20 20 69 6e 74 20 28 2a *pArg;. int (*
4c390 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 0a 20 xInit)(void*);.
4c3a0 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 void (*xShutdow
4c3b0 6e 29 28 76 6f 69 64 2a 29 3b 0a 20 20 73 71 6c n)(void*);. sql
4c3c0 69 74 65 33 5f 70 63 61 63 68 65 20 2a 28 2a 78 ite3_pcache *(*x
4c3d0 43 72 65 61 74 65 29 28 69 6e 74 20 73 7a 50 61 Create)(int szPa
4c3e0 67 65 2c 20 69 6e 74 20 62 50 75 72 67 65 61 62 ge, int bPurgeab
4c3f0 6c 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 43 le);. void (*xC
4c400 61 63 68 65 73 69 7a 65 29 28 73 71 6c 69 74 65 achesize)(sqlite
4c410 33 5f 70 63 61 63 68 65 2a 2c 20 69 6e 74 20 6e 3_pcache*, int n
4c420 43 61 63 68 65 73 69 7a 65 29 3b 0a 20 20 69 6e Cachesize);. in
4c430 74 20 28 2a 78 50 61 67 65 63 6f 75 6e 74 29 28 t (*xPagecount)(
4c440 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 2a 29 sqlite3_pcache*)
4c450 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 46 65 74 ;. void *(*xFet
4c460 63 68 29 28 73 71 6c 69 74 65 33 5f 70 63 61 63 ch)(sqlite3_pcac
4c470 68 65 2a 2c 20 75 6e 73 69 67 6e 65 64 20 6b 65 he*, unsigned ke
4c480 79 2c 20 69 6e 74 20 63 72 65 61 74 65 46 6c 61 y, int createFla
4c490 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 55 6e g);. void (*xUn
4c4a0 70 69 6e 29 28 73 71 6c 69 74 65 33 5f 70 63 61 pin)(sqlite3_pca
4c4b0 63 68 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 che*, void*, int
4c4c0 20 64 69 73 63 61 72 64 29 3b 0a 20 20 76 6f 69 discard);. voi
4c4d0 64 20 28 2a 78 52 65 6b 65 79 29 28 73 71 6c 69 d (*xRekey)(sqli
4c4e0 74 65 33 5f 70 63 61 63 68 65 2a 2c 20 76 6f 69 te3_pcache*, voi
4c4f0 64 2a 2c 20 75 6e 73 69 67 6e 65 64 20 6f 6c 64 d*, unsigned old
4c500 4b 65 79 2c 20 75 6e 73 69 67 6e 65 64 20 6e 65 Key, unsigned ne
4c510 77 4b 65 79 29 3b 0a 20 20 76 6f 69 64 20 28 2a wKey);. void (*
4c520 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 xTruncate)(sqlit
4c530 65 33 5f 70 63 61 63 68 65 2a 2c 20 75 6e 73 69 e3_pcache*, unsi
4c540 67 6e 65 64 20 69 4c 69 6d 69 74 29 3b 0a 20 20 gned iLimit);.
4c550 76 6f 69 64 20 28 2a 78 44 65 73 74 72 6f 79 29 void (*xDestroy)
4c560 28 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 2a (sqlite3_pcache*
4c570 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 55 6e 64 );.};../*.** Und
4c580 6f 20 74 68 65 20 68 61 63 6b 20 74 68 61 74 20 o the hack that
4c590 63 6f 6e 76 65 72 74 73 20 66 6c 6f 61 74 69 6e converts floatin
4c5a0 67 20 70 6f 69 6e 74 20 74 79 70 65 73 20 74 6f g point types to
4c5b0 20 69 6e 74 65 67 65 72 20 66 6f 72 0a 2a 2a 20 integer for.**
4c5c0 62 75 69 6c 64 73 20 6f 6e 20 70 72 6f 63 65 73 builds on proces
4c5d0 73 6f 72 73 20 77 69 74 68 6f 75 74 20 66 6c 6f sors without flo
4c5e0 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 ating point supp
4c5f0 6f 72 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 ort..*/.#ifdef S
4c600 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 QLITE_OMIT_FLOAT
4c610 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 75 6e 64 65 ING_POINT.# unde
4c620 66 20 64 6f 75 62 6c 65 0a 23 65 6e 64 69 66 0a f double.#endif.
4c630 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 .#ifdef __cplusp
4c640 6c 75 73 0a 7d 20 20 2f 2a 20 45 6e 64 20 6f 66 lus.} /* End of
4c650 20 74 68 65 20 27 65 78 74 65 72 6e 20 22 43 22 the 'extern "C"
4c660 27 20 62 6c 6f 63 6b 20 2a 2f 0a 23 65 6e 64 69 ' block */.#endi
4c670 66 0a 23 65 6e 64 69 66 0a f.#endif.