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 68 65 20 72 69 67 68 74 20 74 6f rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69 ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69 ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67 n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73 est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20 C-language API
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69 r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73 e. This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69 the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20 ve source.** on
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72 how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73 faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 ion number) and
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 to "sqlite3.h"
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 .*/.#ifndef SQLI
05e0: 54 45 33 5f 48 0a 23 64 65 66 69 6e 65 20 53 51 TE3_H.#define SQ
05f0: 4c 49 54 45 33 5f 48 0a 23 69 6e 63 6c 75 64 65 LITE3_H.#include
0600: 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20 <stdarg.h>
0610: 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68 /* Needed for th
0620: 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20 e definition of
0630: 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a va_list */../*.*
0640: 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63 * Make sure we c
0650: 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75 an call this stu
0660: 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a ff from C++..*/.
0670: 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c #ifdef __cpluspl
0680: 75 73 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a us.extern "C" {.
0690: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 50 #endif.../*.** P
06a0: 72 6f 76 69 64 65 20 74 68 65 20 61 62 69 6c 69 rovide the abili
06b0: 74 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 6c ty to override l
06c0: 69 6e 6b 61 67 65 20 66 65 61 74 75 72 65 73 20 inkage features
06d0: 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 of the interface
06e0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c ..*/.#ifndef SQL
06f0: 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 ITE_EXTERN.# def
0700: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52 ine SQLITE_EXTER
0710: 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a N extern.#endif.
0720: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 #ifndef SQLITE_A
0730: 50 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 PI.# define SQLI
0740: 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 23 69 TE_API.#endif.#i
0750: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 43 44 45 fndef SQLITE_CDE
0760: 43 4c 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 CL.# define SQLI
0770: 54 45 5f 43 44 45 43 4c 0a 23 65 6e 64 69 66 0a TE_CDECL.#endif.
0780: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 #ifndef SQLITE_A
0790: 50 49 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 PICALL.# define
07a0: 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 SQLITE_APICALL.#
07b0: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 endif.#ifndef SQ
07c0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 LITE_STDCALL.# d
07d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 efine SQLITE_STD
07e0: 43 41 4c 4c 20 53 51 4c 49 54 45 5f 41 50 49 43 CALL SQLITE_APIC
07f0: 41 4c 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 ALL.#endif.#ifnd
0800: 65 66 20 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41 ef SQLITE_CALLBA
0810: 43 4b 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 CK.# define SQLI
0820: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 65 6e 64 TE_CALLBACK.#end
0830: 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 if.#ifndef SQLIT
0840: 45 5f 53 59 53 41 50 49 0a 23 20 64 65 66 69 6e E_SYSAPI.# defin
0850: 65 20 53 51 4c 49 54 45 5f 53 59 53 41 50 49 0a e SQLITE_SYSAPI.
0860: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 #endif../*.** Th
0870: 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 ese no-op macros
0880: 20 61 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f are used in fro
0890: 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 nt of interfaces
08a0: 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a to mark those.*
08b0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 * interfaces as
08c0: 65 69 74 68 65 72 20 64 65 70 72 65 63 61 74 65 either deprecate
08d0: 64 20 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 d or experimenta
08e0: 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 l. New applicat
08f0: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e ions.** should n
0900: 6f 74 20 75 73 65 20 64 65 70 72 65 63 61 74 65 ot use deprecate
0910: 64 20 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 d interfaces - t
0920: 68 65 79 20 61 72 65 20 73 75 70 70 6f 72 74 65 hey are supporte
0930: 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a d for backwards.
0940: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ** compatibility
0950: 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 only. Applicat
0960: 69 6f 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75 ion writers shou
0970: 6c 64 20 62 65 20 61 77 61 72 65 20 74 68 61 74 ld be aware that
0980: 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c .** experimental
0990: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
09a0: 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 subject to chang
09b0: 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61 e in point relea
09c0: 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ses..**.** These
09d0: 20 6d 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20 macros used to
09e0: 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f resolve to vario
09f0: 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70 us kinds of comp
0a00: 69 6c 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a iler magic that.
0a10: 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74 ** would generat
0a20: 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67 e warning messag
0a30: 65 73 20 77 68 65 6e 20 74 68 65 79 20 77 65 72 es when they wer
0a40: 65 20 75 73 65 64 2e 20 20 42 75 74 20 74 68 61 e used. But tha
0a50: 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61 t.** compiler ma
0a60: 67 69 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e gic ended up gen
0a70: 65 72 61 74 69 6e 67 20 73 75 63 68 20 61 20 66 erating such a f
0a80: 6c 75 72 72 79 20 6f 66 20 62 75 67 20 72 65 70 lurry of bug rep
0a90: 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20 orts.** that we
0aa0: 68 61 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c have taken it al
0ab0: 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62 l out and gone b
0ac0: 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d ack to using sim
0ad0: 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 ple.** noop macr
0ae0: 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 os..*/.#define S
0af0: 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 QLITE_DEPRECATED
0b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
0b10: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a EXPERIMENTAL../*
0b20: 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65 .** Ensure these
0b30: 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f symbols were no
0b40: 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d t defined by som
0b50: 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 64 65 e previous heade
0b60: 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 r file..*/.#ifde
0b70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e f SQLITE_VERSION
0b80: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f .# undef SQLITE_
0b90: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 VERSION.#endif.#
0ba0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 ifdef SQLITE_VER
0bb0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e SION_NUMBER.# un
0bc0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 def SQLITE_VERSI
0bd0: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66 ON_NUMBER.#endif
0be0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
0bf0: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c : Compile-Time L
0c00: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e ibrary Version N
0c10: 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 umbers.**.** ^(T
0c20: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 he [SQLITE_VERSI
0c30: 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 ON] C preprocess
0c40: 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20 or macro in the
0c50: 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72 sqlite3.h header
0c60: 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f .** evaluates to
0c70: 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 a string litera
0c80: 6c 20 74 68 61 74 20 69 73 20 74 68 65 20 53 51 l that is the SQ
0c90: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20 Lite version in
0ca0: 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58 the.** format "X
0cb0: 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73 .Y.Z" where X is
0cc0: 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69 the major versi
0cd0: 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79 on number (alway
0ce0: 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 s 3 for.** SQLit
0cf0: 65 33 29 20 61 6e 64 20 59 20 69 73 20 74 68 65 e3) and Y is the
0d00: 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e minor version n
0d10: 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74 umber and Z is t
0d20: 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 he release numbe
0d30: 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 r.)^.** ^(The [S
0d40: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 QLITE_VERSION_NU
0d50: 4d 42 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65 MBER] C preproce
0d60: 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c ssor macro resol
0d70: 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 ves to an intege
0d80: 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61 r.** with the va
0d90: 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b lue (X*1000000 +
0da0: 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 Y*1000 + Z) whe
0db0: 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61 re X, Y, and Z a
0dc0: 72 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e re the same.** n
0dd0: 75 6d 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b umbers used in [
0de0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e SQLITE_VERSION].
0df0: 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 )^.** The SQLITE
0e00: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 _VERSION_NUMBER
0e10: 66 6f 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65 for any given re
0e20: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 lease of SQLite
0e30: 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 will also.** be
0e40: 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 larger than the
0e50: 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69 release from whi
0e60: 63 68 20 69 74 20 69 73 20 64 65 72 69 76 65 64 ch it is derived
0e70: 2e 20 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c . Either Y will
0e80: 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73 .** be held cons
0e90: 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20 tant and Z will
0ea0: 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f be incremented o
0eb0: 72 20 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65 r else Y will be
0ec0: 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 incremented.**
0ed0: 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65 and Z will be re
0ee0: 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a set to zero..**.
0ef0: 2a 2a 20 53 69 6e 63 65 20 5b 76 65 72 73 69 6f ** Since [versio
0f00: 6e 20 33 2e 36 2e 31 38 5d 20 28 5b 64 61 74 65 n 3.6.18] ([date
0f10: 6f 66 3a 33 2e 36 2e 31 38 5d 29 2c 20 0a 2a 2a of:3.6.18]), .**
0f20: 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 SQLite source c
0f30: 6f 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f ode has been sto
0f40: 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61 red in the.** <a
0f50: 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 href="http://ww
0f60: 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67 w.fossil-scm.org
0f70: 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67 /">Fossil config
0f80: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 uration manageme
0f90: 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e nt.** system</a>
0fa0: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 . ^The SQLITE_S
0fb0: 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 6f 20 65 OURCE_ID macro e
0fc0: 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61 valuates to.** a
0fd0: 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 64 string which id
0fe0: 65 6e 74 69 66 69 65 73 20 61 20 70 61 72 74 69 entifies a parti
0ff0: 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f cular check-in o
1000: 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68 f SQLite.** with
1010: 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61 in its configura
1020: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 tion management
1030: 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 53 51 system. ^The SQ
1040: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a LITE_SOURCE_ID.*
1050: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e * string contain
1060: 73 20 74 68 65 20 64 61 74 65 20 61 6e 64 20 74 s the date and t
1070: 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65 63 6b ime of the check
1080: 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20 61 6e -in (UTC) and an
1090: 20 53 48 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66 SHA1.** hash of
10a0: 20 74 68 65 20 65 6e 74 69 72 65 20 73 6f 75 72 the entire sour
10b0: 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 ce tree..**.** S
10c0: 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
10d0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c 3_libversion()],
10e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 .** [sqlite3_lib
10f0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 version_number()
1100: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72 ], [sqlite3_sour
1110: 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c ceid()],.** [sql
1120: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 ite_version()] a
1130: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 nd [sqlite_sourc
1140: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 e_id()]..*/.#def
1150: 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 ine SQLITE_VERSI
1160: 4f 4e 20 20 20 20 20 20 20 20 22 2d 2d 56 45 52 ON "--VER
1170: 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20 53 51 4c S--".#define SQL
1180: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 ITE_VERSION_NUMB
1190: 45 52 20 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d ER --VERSION-NUM
11a0: 42 45 52 2d 2d 0a 23 64 65 66 69 6e 65 20 53 51 BER--.#define SQ
11b0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 LITE_SOURCE_ID
11c0: 20 20 20 20 22 2d 2d 53 4f 55 52 43 45 2d 49 44 "--SOURCE-ID
11d0: 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 --"../*.** CAPI3
11e0: 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 REF: Run-Time Li
11f0: 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 brary Version Nu
1200: 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 mbers.** KEYWORD
1210: 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 S: sqlite3_versi
1220: 6f 6e 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 on sqlite3_sourc
1230: 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 eid.**.** These
1240: 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f 76 69 interfaces provi
1250: 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f de the same info
1260: 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b rmation as the [
1270: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c SQLITE_VERSION],
1280: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 .** [SQLITE_VERS
1290: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 ION_NUMBER], and
12a0: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f [SQLITE_SOURCE_
12b0: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 ID] C preprocess
12c0: 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74 or macros.** but
12d0: 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 20 are associated
12e0: 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 with the library
12f0: 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 instead of the
1300: 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28 header file. ^(
1310: 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 Cautious.** prog
1320: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e rammers might in
1330: 63 6c 75 64 65 20 61 73 73 65 72 74 28 29 20 73 clude assert() s
1340: 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 tatements in the
1350: 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 ir application t
1360: 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74 o.** verify that
1370: 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 values returned
1380: 20 62 79 20 74 68 65 73 65 20 69 6e 74 65 72 66 by these interf
1390: 61 63 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d aces match the m
13a0: 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20 acros in.** the
13b0: 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73 header, and thus
13c0: 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 ensure that the
13d0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a application is.
13e0: 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 ** compiled with
13f0: 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72 matching librar
1400: 79 20 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c y and header fil
1410: 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b es..**.** <block
1420: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 quote><pre>.** a
1430: 73 73 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c ssert( sqlite3_l
1440: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 ibversion_number
1450: 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49 ()==SQLITE_VERSI
1460: 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 ON_NUMBER );.**
1470: 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 assert( strcmp(s
1480: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 qlite3_sourceid(
1490: 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f ),SQLITE_SOURCE_
14a0: 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 ID)==0 );.** ass
14b0: 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 ert( strcmp(sqli
14c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 te3_libversion()
14d0: 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 ,SQLITE_VERSION)
14e0: 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e ==0 );.** </pre>
14f0: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a </blockquote>)^.
1500: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
1510: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 e3_version[] str
1520: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e ing constant con
1530: 74 61 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f tains the text o
1540: 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f f [SQLITE_VERSIO
1550: 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 N].** macro. ^T
1560: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 he sqlite3_libve
1570: 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e rsion() function
1580: 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
1590: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 er to the.** to
15a0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 the sqlite3_vers
15b0: 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e ion[] string con
15c0: 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 stant. The sqli
15d0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 te3_libversion()
15e0: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 .** function is
15f0: 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 provided for use
1600: 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 in DLLs since D
1610: 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 LL users usually
1620: 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 do not have.**
1630: 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74 6f direct access to
1640: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 string constant
1650: 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c s within the DLL
1660: 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 . ^The.** sqlit
1670: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 e3_libversion_nu
1680: 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 mber() function
1690: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 returns an integ
16a0: 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b er equal to.** [
16b0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e SQLITE_VERSION_N
16c0: 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71 UMBER]. ^The sq
16d0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 lite3_sourceid()
16e0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e function return
16f0: 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 s .** a pointer
1700: 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 to a string cons
1710: 74 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 tant whose value
1720: 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 is the same as
1730: 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the .** [SQLITE_
1740: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 SOURCE_ID] C pre
1750: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e processor macro.
1760: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
1770: 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e [sqlite_version
1780: 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f ()] and [sqlite_
1790: 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f source_id()]..*/
17a0: 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 .SQLITE_EXTERN c
17b0: 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74 65 onst char sqlite
17c0: 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 3_version[];.con
17d0: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
17e0: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 _libversion(void
17f0: 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 );.const char *s
1800: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 qlite3_sourceid(
1810: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 void);.int sqlit
1820: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 e3_libversion_nu
1830: 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a mber(void);../*.
1840: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e ** CAPI3REF: Run
1850: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 43 6f -Time Library Co
1860: 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f 6e mpilation Option
1870: 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a 2a s Diagnostics.**
1880: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1890: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 _compileoption_u
18a0: 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 sed() function r
18b0: 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20 0a 2a eturns 0 or 1 .*
18c0: 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77 68 65 * indicating whe
18d0: 74 68 65 72 20 74 68 65 20 73 70 65 63 69 66 69 ther the specifi
18e0: 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 64 65 ed option was de
18f0: 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f 6d fined at .** com
1900: 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68 65 pile time. ^The
1910: 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69 78 20 SQLITE_ prefix
1920: 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 66 may be omitted f
1930: 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74 69 rom the .** opti
1940: 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 20 74 on name passed t
1950: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c o sqlite3_compil
1960: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e 20 eoption_used().
1970: 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c .**.** ^The sql
1980: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 ite3_compileopti
1990: 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 69 6f on_get() functio
19a0: 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 74 69 n allows iterati
19b0: 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c ng.** over the l
19c0: 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74 ist of options t
19d0: 68 61 74 20 77 65 72 65 20 64 65 66 69 6e 65 64 hat were defined
19e0: 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 at compile time
19f0: 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67 by.** returning
1a00: 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c the N-th compil
1a10: 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74 e time option st
1a20: 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73 20 ring. ^If N is
1a30: 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a out of range,.**
1a40: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 sqlite3_compile
1a50: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 65 74 option_get() ret
1a60: 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e urns a NULL poin
1a70: 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 ter. ^The SQLIT
1a80: 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 69 73 E_ .** prefix is
1a90: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 61 6e omitted from an
1aa0: 79 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e y strings return
1ab0: 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 ed by .** sqlite
1ac0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 3_compileoption_
1ad0: 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 get()..**.** ^Su
1ae0: 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20 64 69 pport for the di
1af0: 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 69 6f agnostic functio
1b00: 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 ns sqlite3_compi
1b10: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a leoption_used().
1b20: 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 ** and sqlite3_c
1b30: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 ompileoption_get
1b40: 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 () may be omitte
1b50: 64 20 62 79 20 73 70 65 63 69 66 79 69 6e 67 20 d by specifying
1b60: 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the .** [SQLITE_
1b70: 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 OMIT_COMPILEOPTI
1b80: 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f 6e ON_DIAGS] option
1b90: 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 at compile time
1ba0: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
1bb0: 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 : SQL functions
1bc0: 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f [sqlite_compileo
1bd0: 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61 6e ption_used()] an
1be0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f 6d d.** [sqlite_com
1bf0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 pileoption_get()
1c00: 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70 69 ] and the [compi
1c10: 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d le_options pragm
1c20: 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 a]..*/.#ifndef S
1c30: 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 QLITE_OMIT_COMPI
1c40: 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a 69 LEOPTION_DIAGS.i
1c50: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 nt sqlite3_compi
1c60: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f leoption_used(co
1c70: 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 nst char *zOptNa
1c80: 6d 65 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 me);.const char
1c90: 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 *sqlite3_compile
1ca0: 6f 70 74 69 6f 6e 5f 67 65 74 28 69 6e 74 20 4e option_get(int N
1cb0: 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a );.#endif../*.**
1cc0: 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 CAPI3REF: Test
1cd0: 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c 69 To See If The Li
1ce0: 62 72 61 72 79 20 49 73 20 54 68 72 65 61 64 73 brary Is Threads
1cf0: 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 afe.**.** ^The s
1d00: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 qlite3_threadsaf
1d10: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 e() function ret
1d20: 75 72 6e 73 20 7a 65 72 6f 20 69 66 20 61 6e 64 urns zero if and
1d30: 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 4c 69 only if.** SQLi
1d40: 74 65 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 te was compiled
1d50: 77 69 74 68 20 6d 75 74 65 78 69 6e 67 20 63 6f with mutexing co
1d60: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74 de omitted due t
1d70: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 o the.** [SQLITE
1d80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d _THREADSAFE] com
1d90: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
1da0: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e being set to 0.
1db0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 .**.** SQLite ca
1dc0: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 n be compiled wi
1dd0: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 th or without mu
1de0: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 texes. When.**
1df0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 the [SQLITE_THRE
1e00: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f ADSAFE] C prepro
1e10: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 cessor macro is
1e20: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 1 or 2, mutexes.
1e30: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 ** are enabled a
1e40: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 nd SQLite is thr
1e50: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 eadsafe. When t
1e60: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 he.** [SQLITE_TH
1e70: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 READSAFE] macro
1e80: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 is 0, .** the mu
1e90: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 texes are omitte
1ea0: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 d. Without the
1eb0: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e mutexes, it is n
1ec0: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 ot safe.** to us
1ed0: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 e SQLite concurr
1ee0: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 ently from more
1ef0: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e than one thread.
1f00: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 .**.** Enabling
1f10: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61 mutexes incurs a
1f20: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 measurable perf
1f30: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e ormance penalty.
1f40: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20 .** So if speed
1f50: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 is of utmost imp
1f60: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 ortance, it make
1f70: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62 s sense to disab
1f80: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 le.** the mutexe
1f90: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69 s. But for maxi
1fa0: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65 mum safety, mute
1fb0: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e xes should be en
1fc0: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 abled..** ^The d
1fd0: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 efault behavior
1fe0: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 is for mutexes t
1ff0: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a o be enabled..**
2000: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 .** This interfa
2010: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 ce can be used b
2020: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e y an application
2030: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 to make sure th
2040: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f at the.** versio
2050: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 n of SQLite that
2060: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 it is linking a
2070: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 gainst was compi
2080: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 led with.** the
2090: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 desired setting
20a0: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 of the [SQLITE_T
20b0: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f HREADSAFE] macro
20c0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 ..**.** This int
20d0: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f erface only repo
20e0: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 rts on the compi
20f0: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 le-time mutex se
2100: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 tting.** of the
2110: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
2120: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 FE] flag. If SQ
2130: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
2140: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f with.** SQLITE_
2150: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20 THREADSAFE=1 or
2160: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 =2 then mutexes
2170: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 are enabled by d
2180: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 efault but.** ca
2190: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 n be fully or pa
21a0: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 rtially disabled
21b0: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f using a call to
21c0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
21d0: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 ()].** with the
21e0: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f verbs [SQLITE_CO
21f0: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 NFIG_SINGLETHREA
2200: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 D], [SQLITE_CONF
2210: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c IG_MULTITHREAD],
2220: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 .** or [SQLITE_C
2230: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 ONFIG_SERIALIZED
2240: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e ]. ^(The return
2250: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a value of the.**
2260: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 sqlite3_threads
2270: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73 afe() function s
2280: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f hows only the co
2290: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 mpile-time setti
22a0: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20 ng of.** thread
22b0: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20 safety, not any
22c0: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 run-time changes
22d0: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67 to that setting
22e0: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69 made by.** sqli
22f0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e te3_config(). In
2300: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 other words, th
2310: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 e return value f
2320: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65 rom sqlite3_thre
2330: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75 adsafe().** is u
2340: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c nchanged by call
2350: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e s to sqlite3_con
2360: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 fig().)^.**.** S
2370: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e ee the [threadin
2380: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 g mode] document
2390: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 ation for additi
23a0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
23b0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
23c0: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 _threadsafe(void
23d0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
23e0: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e EF: Database Con
23f0: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a nection Handle.*
2400: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 * KEYWORDS: {dat
2410: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2420: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e } {database conn
2430: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 ections}.**.** E
2440: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 ach open SQLite
2450: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 database is repr
2460: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 esented by a poi
2470: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 nter to an insta
2480: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 nce of.** the op
2490: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e aque structure n
24a0: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 amed "sqlite3".
24b0: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f It is useful to
24c0: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c think of an sql
24d0: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 ite3.** pointer
24e0: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 as an object. T
24f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e he [sqlite3_open
2500: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ()], [sqlite3_op
2510: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 en16()], and.**
2520: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
2530: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 ()] interfaces a
2540: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 re its construct
2550: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 ors, and [sqlite
2560: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 3_close()].** an
2570: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 d [sqlite3_close
2580: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64 _v2()] are its d
2590: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65 estructors. The
25a0: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 re are many othe
25b0: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 r.** interfaces
25c0: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c (such as.** [sql
25d0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
25e0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 )], [sqlite3_cre
25f0: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c ate_function()],
2600: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
2610: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d _busy_timeout()]
2620: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 to name but thr
2630: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 ee) that are met
2640: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 hods on an.** sq
2650: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f lite3 object..*/
2660: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
2670: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b sqlite3 sqlite3;
2680: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2690: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72 : 64-Bit Integer
26a0: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 Types.** KEYWOR
26b0: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 DS: sqlite_int64
26c0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a sqlite_uint64.*
26d0: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 *.** Because the
26e0: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 re is no cross-p
26f0: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 latform way to s
2700: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e pecify 64-bit in
2710: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 teger types.** S
2720: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 QLite includes t
2730: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 ypedefs for 64-b
2740: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e it signed and un
2750: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e signed integers.
2760: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
2770: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c e3_int64 and sql
2780: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 ite3_uint64 are
2790: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79 the preferred ty
27a0: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a pe definitions..
27b0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e ** The sqlite_in
27c0: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 t64 and sqlite_u
27d0: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20 int64 types are
27e0: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 supported for ba
27f0: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 ckwards.** compa
2800: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a tibility only..*
2810: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
2820: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 3_int64 and sqli
2830: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63 te_int64 types c
2840: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 an store integer
2850: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 values.** betwe
2860: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35 en -922337203685
2870: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32 4775808 and +922
2880: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37 3372036854775807
2890: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 inclusive. ^Th
28a0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e e.** sqlite3_uin
28b0: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 t64 and sqlite_u
28c0: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 int64 types can
28d0: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 store integer va
28e0: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e lues .** between
28f0: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34 0 and +18446744
2900: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63 073709551615 inc
2910: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 lusive..*/.#ifde
2920: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 f SQLITE_INT64_T
2930: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 YPE. typedef SQ
2940: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 LITE_INT64_TYPE
2950: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 23 20 sqlite_int64;.#
2960: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 55 49 4e ifdef SQLITE_UIN
2970: 54 36 34 5f 54 59 50 45 0a 20 20 20 20 74 79 70 T64_TYPE. typ
2980: 65 64 65 66 20 53 51 4c 49 54 45 5f 55 49 4e 54 edef SQLITE_UINT
2990: 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 64_TYPE sqlite_u
29a0: 69 6e 74 36 34 3b 0a 23 20 65 6c 73 65 20 20 0a int64;.# else .
29b0: 20 20 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 typedef unsi
29c0: 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 gned SQLITE_INT6
29d0: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 4_TYPE sqlite_ui
29e0: 6e 74 36 34 3b 0a 23 20 65 6e 64 69 66 0a 23 65 nt64;.# endif.#e
29f0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 lif defined(_MSC
2a00: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 _VER) || defined
2a10: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 (__BORLANDC__).
2a20: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 typedef __int64
2a30: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 sqlite_int64;.
2a40: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 typedef unsigne
2a50: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 d __int64 sqlite
2a60: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 _uint64;.#else.
2a70: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f typedef long lo
2a80: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e ng int sqlite_in
2a90: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 t64;. typedef u
2aa0: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e nsigned long lon
2ab0: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e g int sqlite_uin
2ac0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 t64;.#endif.type
2ad0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 def sqlite_int64
2ae0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a sqlite3_int64;.
2af0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 typedef sqlite_u
2b00: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 int64 sqlite3_ui
2b10: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 nt64;../*.** If
2b20: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 compiling for a
2b30: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c processor that l
2b40: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f acks floating po
2b50: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 int support,.**
2b60: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 substitute integ
2b70: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d er for floating-
2b80: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 point..*/.#ifdef
2b90: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f SQLITE_OMIT_FLO
2ba0: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 ATING_POINT.# de
2bb0: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 fine double sqli
2bc0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 te3_int64.#endif
2bd0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2be0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 : Closing A Data
2bf0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a base Connection.
2c00: 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73 ** DESTRUCTOR: s
2c10: 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 qlite3.**.** ^Th
2c20: 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 e sqlite3_close(
2c30: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c ) and sqlite3_cl
2c40: 6f 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 ose_v2() routine
2c50: 73 20 61 72 65 20 64 65 73 74 72 75 63 74 6f 72 s are destructor
2c60: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 s.** for the [sq
2c70: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a lite3] object..*
2c80: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 * ^Calls to sqli
2c90: 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 te3_close() and
2ca0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 sqlite3_close_v2
2cb0: 28 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 () return [SQLIT
2cc0: 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20 E_OK] if.** the
2cd0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 [sqlite3] object
2ce0: 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79 is successfully
2cf0: 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61 destroyed and a
2d00: 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a ll associated.**
2d10: 20 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64 resources are d
2d20: 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a eallocated..**.*
2d30: 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 * ^If the databa
2d40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
2d50: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
2d60: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 unfinalized pre
2d70: 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 pared.** stateme
2d80: 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65 nts or unfinishe
2d90: 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 d sqlite3_backup
2da0: 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71 objects then sq
2db0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a lite3_close().**
2dc0: 20 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 will leave the
2dd0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2de0: 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74 ion open and ret
2df0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 urn [SQLITE_BUSY
2e00: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 ]..** ^If sqlite
2e10: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 3_close_v2() is
2e20: 63 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69 called with unfi
2e30: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 nalized prepared
2e40: 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 statements.** a
2e50: 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 nd/or unfinished
2e60: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73 sqlite3_backups
2e70: 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 , then the datab
2e80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 ase connection b
2e90: 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 ecomes.** an unu
2ea0: 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77 sable "zombie" w
2eb0: 68 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61 hich will automa
2ec0: 74 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c tically be deall
2ed0: 6f 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a ocated when the.
2ee0: 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65 64 ** last prepared
2ef0: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69 statement is fi
2f00: 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c nalized or the l
2f10: 61 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b ast sqlite3_back
2f20: 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65 up is.** finishe
2f30: 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f d. The sqlite3_
2f40: 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72 close_v2() inter
2f50: 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64 face is intended
2f60: 20 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a for use with.**
2f70: 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20 host languages
2f80: 74 68 61 74 20 61 72 65 20 67 61 72 62 61 67 65 that are garbage
2f90: 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20 collected, and
2fa0: 77 68 65 72 65 20 74 68 65 20 6f 72 64 65 72 20 where the order
2fb0: 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74 in which.** dest
2fc0: 72 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c ructors are call
2fd0: 65 64 20 69 73 20 61 72 62 69 74 72 61 72 79 2e ed is arbitrary.
2fe0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 .**.** Applicati
2ff0: 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 ons should [sqli
3000: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 te3_finalize | f
3010: 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 inalize] all [pr
3020: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
3030: 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f s],.** [sqlite3_
3040: 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f blob_close | clo
3050: 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 se] all [BLOB ha
3060: 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 ndles], and .**
3070: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f [sqlite3_backup_
3080: 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d finish | finish]
3090: 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61 all [sqlite3_ba
30a0: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73 ckup] objects as
30b0: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 sociated.** with
30c0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f the [sqlite3] o
30d0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 bject prior to a
30e0: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f ttempting to clo
30f0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 se the object.
3100: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 ^If.** sqlite3_c
3110: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c lose_v2() is cal
3120: 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 led on a [databa
3130: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 se connection] t
3140: 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a hat still has.**
3150: 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 outstanding [pr
3160: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
3170: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 s], [BLOB handle
3180: 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 s], and/or.** [s
3190: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f qlite3_backup] o
31a0: 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72 bjects then it r
31b0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
31c0: 4b 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c K] and the deall
31d0: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 ocation.** of re
31e0: 73 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72 sources is defer
31f0: 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 red until all [p
3200: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
3210: 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c ts], [BLOB handl
3220: 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c es],.** and [sql
3230: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a ite3_backup] obj
3240: 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65 ects are also de
3250: 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e stroyed..**.** ^
3260: 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 If an [sqlite3]
3270: 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f object is destro
3280: 79 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e yed while a tran
3290: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c saction is open,
32a0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 .** the transact
32b0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 ion is automatic
32c0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b ally rolled back
32d0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 ..**.** The C pa
32e0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
32f0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e te3_close(C)] an
3300: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 d [sqlite3_close
3310: 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 _v2(C)].** must
3320: 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c be either a NULL
3330: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 .** pointer or a
3340: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 n [sqlite3] obje
3350: 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 ct pointer obtai
3360: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c ned.** from [sql
3370: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 ite3_open()], [s
3380: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
3390: 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 , or.** [sqlite3
33a0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 _open_v2()], and
33b0: 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 not previously
33c0: 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c closed..** ^Call
33d0: 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 ing sqlite3_clos
33e0: 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 e() or sqlite3_c
33f0: 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61 lose_v2() with a
3400: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a NULL pointer.**
3410: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68 argument is a h
3420: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a armless no-op..*
3430: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c /.int sqlite3_cl
3440: 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69 ose(sqlite3*);.i
3450: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 nt sqlite3_close
3460: 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a _v2(sqlite3*);..
3470: 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 /*.** The type f
3480: 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 or a callback fu
3490: 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 nction..** This
34a0: 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 is legacy and de
34b0: 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 precated. It is
34c0: 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 included for hi
34d0: 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 storical.** comp
34e0: 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 atibility and is
34f0: 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e not documented.
3500: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 .*/.typedef int
3510: 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 (*sqlite3_callba
3520: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 ck)(void*,int,ch
3530: 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a ar**, char**);..
3540: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
3550: 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 One-Step Query E
3560: 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 xecution Interfa
3570: 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 ce.** METHOD: sq
3580: 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 lite3.**.** The
3590: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
35a0: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f nterface is a co
35b0: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65 nvenience wrappe
35c0: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c r around.** [sql
35d0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
35e0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 )], [sqlite3_ste
35f0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 p()], and [sqlit
3600: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a e3_finalize()],.
3610: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 ** that allows a
3620: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f n application to
3630: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 run multiple st
3640: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a atements of SQL.
3650: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e ** without havin
3660: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f g to use a lot o
3670: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a f C code. .**.**
3680: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 ^The sqlite3_ex
3690: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 ec() interface r
36a0: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 uns zero or more
36b0: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a UTF-8 encoded,.
36c0: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 ** semicolon-sep
36d0: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d arate SQL statem
36e0: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f ents passed into
36f0: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e its 2nd argumen
3700: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e t,.** in the con
3710: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74 text of the [dat
3720: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
3730: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69 ] passed in as i
3740: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 ts 1st.** argume
3750: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c nt. ^If the cal
3760: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f lback function o
3770: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 f the 3rd argume
3780: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 nt to.** sqlite3
3790: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e _exec() is not N
37a0: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20 ULL, then it is
37b0: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 invoked for each
37c0: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 result row.** c
37d0: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 oming out of the
37e0: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73 evaluated SQL s
37f0: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 tatements. ^The
3800: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 4th argument to
3810: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 .** sqlite3_exec
3820: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 () is relayed th
3830: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 rough to the 1st
3840: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 argument of eac
3850: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e h.** callback in
3860: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 vocation. ^If t
3870: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e he callback poin
3880: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 ter to sqlite3_e
3890: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c xec().** is NULL
38a0: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 , then no callba
38b0: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b ck is ever invok
38c0: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f ed and result ro
38d0: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 ws are.** ignore
38e0: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 d..**.** ^If an
38f0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 error occurs whi
3900: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 le evaluating th
3910: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 e SQL statements
3920: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 passed into.**
3930: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 sqlite3_exec(),
3940: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f then execution o
3950: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 f the current st
3960: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e atement stops an
3970: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 d.** subsequent
3980: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 statements are s
3990: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 kipped. ^If the
39a0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 5th parameter t
39b0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 o sqlite3_exec()
39c0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 .** is not NULL
39d0: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d then any error m
39e0: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 essage is writte
39f0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 n into memory ob
3a00: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b tained.** from [
3a10: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
3a20: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 ] and passed bac
3a30: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 k through the 5t
3a40: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 h parameter..**
3a50: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 To avoid memory
3a60: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 leaks, the appli
3a70: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e cation should in
3a80: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 voke [sqlite3_fr
3a90: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f ee()].** on erro
3aa0: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 r message string
3ab0: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 s returned throu
3ac0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d gh the 5th param
3ad0: 65 74 65 72 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 eter of.** sqlit
3ae0: 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20 e3_exec() after
3af0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 the error messag
3b00: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c e string is no l
3b10: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a onger needed..**
3b20: 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 ^If the 5th par
3b30: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
3b40: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 3_exec() is not
3b50: 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f NULL and no erro
3b60: 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 rs.** occur, the
3b70: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 n sqlite3_exec()
3b80: 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65 sets the pointe
3b90: 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72 r in its 5th par
3ba0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c ameter to.** NUL
3bb0: 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 L before returni
3bc0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e ng..**.** ^If an
3bd0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
3be0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
3bf0: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 non-zero, the s
3c00: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a qlite3_exec().**
3c10: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
3c20: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 SQLITE_ABORT wi
3c30: 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 thout invoking t
3c40: 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 he callback agai
3c50: 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 n and.** without
3c60: 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 running any sub
3c70: 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 sequent SQL stat
3c80: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ements..**.** ^T
3c90: 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 he 2nd argument
3ca0: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 to the sqlite3_e
3cb0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 xec() callback f
3cc0: 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a unction is the.*
3cd0: 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 * number of colu
3ce0: 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c mns in the resul
3cf0: 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67 t. ^The 3rd arg
3d00: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c ument to the sql
3d10: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 ite3_exec().** c
3d20: 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 allback is an ar
3d30: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 ray of pointers
3d40: 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69 to strings obtai
3d50: 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a ned as if from.*
3d60: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
3d70: 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 n_text()], one f
3d80: 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 or each column.
3d90: 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 ^If an element
3da0: 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 of a.** result r
3db0: 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 ow is NULL then
3dc0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
3dd0: 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 g string pointer
3de0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 for the.** sqli
3df0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 te3_exec() callb
3e00: 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f ack is a NULL po
3e10: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68 inter. ^The 4th
3e20: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
3e30: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 .** sqlite3_exec
3e40: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 () callback is a
3e50: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 n array of point
3e60: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77 ers to strings w
3e70: 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 here each.** ent
3e80: 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68 ry represents th
3e90: 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 e name of corres
3ea0: 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63 ponding result c
3eb0: 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 olumn as obtaine
3ec0: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 d.** from [sqlit
3ed0: 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 e3_column_name()
3ee0: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 ]..**.** ^If the
3ef0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 2nd parameter t
3f00: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 o sqlite3_exec()
3f10: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
3f20: 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a er, a pointer.**
3f30: 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 to an empty str
3f40: 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 ing, or a pointe
3f50: 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 r that contains
3f60: 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 only whitespace
3f70: 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 and/or .** SQL c
3f80: 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f omments, then no
3f90: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
3fa0: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e are evaluated an
3fb0: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a d the database.*
3fc0: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 * is not changed
3fd0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 ..**.** Restrict
3fe0: 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ions:.**.** <ul>
3ff0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 .** <li> The app
4000: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 65 6e lication must en
4010: 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73 sure that the 1s
4020: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 t parameter to s
4030: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a qlite3_exec().**
4040: 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64 is a valid
4050: 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 and open [datab
4060: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e ase connection].
4070: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 .** <li> The app
4080: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f lication must no
4090: 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61 74 t close the [dat
40a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
40b0: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a ] specified by.*
40c0: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70 * the 1st p
40d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
40e0: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 te3_exec() while
40f0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
4100: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c is running..** <
4110: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 li> The applicat
4120: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 ion must not mod
4130: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 ify the SQL stat
4140: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 ement text passe
4150: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 d into.** t
4160: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
4170: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 of sqlite3_exec
4180: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 () while sqlite3
4190: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 _exec() is runni
41a0: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a ng..** </ul>.*/.
41b0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 int sqlite3_exec
41c0: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 (. sqlite3*,
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
41f0: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 * An open databa
4200: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 se */. const ch
4210: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 ar *sql,
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4230: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 /* SQL to be
4240: 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 evaluated */. i
4250: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 nt (*callback)(v
4260: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c oid*,int,char**,
4270: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c char**), /* Cal
4280: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a lback function *
4290: 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 /. void *,
42a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
42b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
42c0: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 * 1st argument t
42d0: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 o callback */.
42e0: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 char **errmsg
42f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4300: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 /* Er
4310: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 ror msg written
4320: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a here */.);../*.*
4330: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 * CAPI3REF: Resu
4340: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 lt Codes.** KEYW
4350: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f ORDS: {result co
4360: 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a de definitions}.
4370: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 **.** Many SQLit
4380: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 e functions retu
4390: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65 rn an integer re
43a0: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 sult code from t
43b0: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 he set shown.**
43c0: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f here in order to
43d0: 20 69 6e 64 69 63 61 74 65 20 73 75 63 63 65 73 indicate succes
43e0: 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a s or failure..**
43f0: 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f .** New error co
4400: 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 des may be added
4410: 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 in future versi
4420: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a ons of SQLite..*
4430: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
4440: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
4450: 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 code definitions
4460: 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ].*/.#define SQL
4470: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 ITE_OK
4480: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 0 /* Successf
4490: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 ul result */./*
44a0: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 beginning-of-err
44b0: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 or-codes */.#def
44c0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 ine SQLITE_ERROR
44d0: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 1 /* S
44e0: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 QL error or miss
44f0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a ing database */.
4500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
4510: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 NTERNAL 2
4520: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 /* Internal logi
4530: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 c error in SQLit
4540: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
4550: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20 ITE_PERM
4560: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70 3 /* Access p
4570: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 ermission denied
4580: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4590: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20 TE_ABORT
45a0: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 4 /* Callback
45b0: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 routine requeste
45c0: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 d an abort */.#d
45d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 efine SQLITE_BUS
45e0: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a Y 5 /*
45f0: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69 The database fi
4600: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a le is locked */.
4610: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
4620: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20 OCKED 6
4630: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68 /* A table in th
4640: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f e database is lo
4650: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 cked */.#define
4660: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 SQLITE_NOMEM
4670: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 7 /* A mal
4680: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a loc() failed */.
4690: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
46a0: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 EADONLY 8
46b0: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72 /* Attempt to wr
46c0: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 ite a readonly d
46d0: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 atabase */.#defi
46e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 ne SQLITE_INTERR
46f0: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 UPT 9 /* Op
4700: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 eration terminat
4710: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e ed by sqlite3_in
4720: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 terrupt()*/.#def
4730: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
4740: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53 10 /* S
4750: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b ome kind of disk
4760: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 I/O error occur
4770: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 red */.#define S
4780: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20 QLITE_CORRUPT
4790: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61 11 /* The da
47a0: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67 tabase disk imag
47b0: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a e is malformed *
47c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
47d0: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20 _NOTFOUND 12
47e0: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 /* Unknown opc
47f0: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 ode in sqlite3_f
4800: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f ile_control() */
4810: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4820: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 FULL 13
4830: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 /* Insertion fa
4840: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74 iled because dat
4850: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f abase is full */
4860: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4870: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 CANTOPEN 14
4880: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 /* Unable to op
4890: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
48a0: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 file */.#define
48b0: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 SQLITE_PROTOCOL
48c0: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62 15 /* Datab
48d0: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f ase lock protoco
48e0: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 l error */.#defi
48f0: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 ne SQLITE_EMPTY
4900: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 16 /* Da
4910: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 tabase is empty
4920: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4930: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 E_SCHEMA 17
4940: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 /* The databa
4950: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 se schema change
4960: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
4970: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 ITE_TOOBIG
4980: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 18 /* String o
4990: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 r BLOB exceeds s
49a0: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 ize limit */.#de
49b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
49c0: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 TRAINT 19 /*
49d0: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e Abort due to con
49e0: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f straint violatio
49f0: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c n */.#define SQL
4a00: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 ITE_MISMATCH
4a10: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 20 /* Data typ
4a20: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 e mismatch */.#d
4a30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 efine SQLITE_MIS
4a40: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a USE 21 /*
4a50: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e Library used in
4a60: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 correctly */.#de
4a70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 fine SQLITE_NOLF
4a80: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 S 22 /*
4a90: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 Uses OS features
4aa0: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f not supported o
4ab0: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e n host */.#defin
4ac0: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 e SQLITE_AUTH
4ad0: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 23 /* Aut
4ae0: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 horization denie
4af0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
4b00: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 ITE_FORMAT
4b10: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 24 /* Auxiliar
4b20: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 y database forma
4b30: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 t error */.#defi
4b40: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 ne SQLITE_RANGE
4b50: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 25 /* 2n
4b60: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 d parameter to s
4b70: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 qlite3_bind out
4b80: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 of range */.#def
4b90: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 ine SQLITE_NOTAD
4ba0: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 B 26 /* F
4bb0: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 ile opened that
4bc0: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 is not a databas
4bd0: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e e file */.#defin
4be0: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 e SQLITE_NOTICE
4bf0: 20 20 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 27 /* Not
4c00: 69 66 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 ifications from
4c10: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f sqlite3_log() */
4c20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4c30: 57 41 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20 WARNING 28
4c40: 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f /* Warnings fro
4c50: 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 m sqlite3_log()
4c60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4c70: 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 E_ROW 10
4c80: 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 0 /* sqlite3_st
4c90: 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 ep() has another
4ca0: 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 row ready */.#d
4cb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e efine SQLITE_DON
4cc0: 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a E 101 /*
4cd0: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
4ce0: 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 has finished exe
4cf0: 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 cuting */./* end
4d00: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 -of-error-codes
4d10: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
4d20: 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 EF: Extended Res
4d30: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 ult Codes.** KEY
4d40: 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 WORDS: {extended
4d50: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 result code def
4d60: 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 initions}.**.**
4d70: 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 In its default c
4d80: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 onfiguration, SQ
4d90: 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 Lite API routine
4da0: 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 s return one of
4db0: 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 30 integer.** [r
4dc0: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 esult codes]. H
4dd0: 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e owever, experien
4de0: 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 ce has shown tha
4df0: 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 t many of.** the
4e00: 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 se result codes
4e10: 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 are too coarse-g
4e20: 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f rained. They do
4e30: 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a not provide as.
4e40: 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 ** much informat
4e50: 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 ion about proble
4e60: 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 ms as programmer
4e70: 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 s might like. I
4e80: 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a n an effort to.*
4e90: 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 * address this,
4ea0: 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f newer versions o
4eb0: 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f f SQLite (versio
4ec0: 6e 20 33 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a n 3.3.8 [dateof:
4ed0: 33 2e 33 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 3.3.8].** and la
4ee0: 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 ter) include.**
4ef0: 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 support for addi
4f00: 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f tional result co
4f10: 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 des that provide
4f20: 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 more detailed i
4f30: 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 nformation.** ab
4f40: 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 73 out errors. Thes
4f50: 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 e [extended resu
4f60: 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20 65 6e lt codes] are en
4f70: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 abled or disable
4f80: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 d.** on a per da
4f90: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
4fa0: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 n basis using th
4fb0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 e.** [sqlite3_ex
4fc0: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f tended_result_co
4fd0: 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c des()] API. Or,
4fe0: 20 74 68 65 20 65 78 74 65 6e 64 65 64 20 63 6f the extended co
4ff0: 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f de for.** the mo
5000: 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f 72 20 st recent error
5010: 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 can be obtained
5020: 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 using.** [sqlite
5030: 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 3_extended_errco
5040: 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e de()]..*/.#defin
5050: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 e SQLITE_IOERR_R
5060: 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 EAD
5070: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
5080: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (1<<8)).#define
5090: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 SQLITE_IOERR_SH
50a0: 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 ORT_READ
50b0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
50c0: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (2<<8)).#define
50d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 SQLITE_IOERR_WRI
50e0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28 TE (
50f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
5100: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 3<<8)).#define S
5110: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e QLITE_IOERR_FSYN
5120: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 C (S
5130: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 QLITE_IOERR | (4
5140: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5150: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 LITE_IOERR_DIR_F
5160: 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 SYNC (SQ
5170: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c LITE_IOERR | (5<
5180: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5190: 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 ITE_IOERR_TRUNCA
51a0: 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51 4c TE (SQL
51b0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c ITE_IOERR | (6<<
51c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
51d0: 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 TE_IOERR_FSTAT
51e0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
51f0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 TE_IOERR | (7<<8
5200: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5210: 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 E_IOERR_UNLOCK
5220: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
5230: 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 E_IOERR | (8<<8)
5240: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5250: 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 _IOERR_RDLOCK
5260: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5270: 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 _IOERR | (9<<8))
5280: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5290: 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 IOERR_DELETE
52a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
52b0: 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 IOERR | (10<<8))
52c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
52d0: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 IOERR_BLOCKED
52e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
52f0: 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 IOERR | (11<<8))
5300: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5310: 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 IOERR_NOMEM
5320: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5330: 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 IOERR | (12<<8))
5340: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5350: 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 IOERR_ACCESS
5360: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5370: 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 IOERR | (13<<8))
5380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5390: 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 IOERR_CHECKRESER
53a0: 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f VEDLOCK (SQLITE_
53b0: 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 IOERR | (14<<8))
53c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
53d0: 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 IOERR_LOCK
53e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
53f0: 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 IOERR | (15<<8))
5400: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5410: 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 IOERR_CLOSE
5420: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5430: 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 IOERR | (16<<8))
5440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5450: 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 IOERR_DIR_CLOSE
5460: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5470: 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 IOERR | (17<<8))
5480: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5490: 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 IOERR_SHMOPEN
54a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
54b0: 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 IOERR | (18<<8))
54c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
54d0: 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 IOERR_SHMSIZE
54e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
54f0: 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 IOERR | (19<<8))
5500: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5510: 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 IOERR_SHMLOCK
5520: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5530: 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 IOERR | (20<<8))
5540: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5550: 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 IOERR_SHMMAP
5560: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5570: 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 IOERR | (21<<8))
5580: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5590: 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20 IOERR_SEEK
55a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
55b0: 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 IOERR | (22<<8))
55c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
55d0: 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 IOERR_DELETE_NOE
55e0: 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f NT (SQLITE_
55f0: 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 IOERR | (23<<8))
5600: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5610: 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20 20 20 IOERR_MMAP
5620: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5630: 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38 29 29 IOERR | (24<<8))
5640: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5650: 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50 41 54 IOERR_GETTEMPPAT
5660: 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f H (SQLITE_
5670: 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38 29 29 IOERR | (25<<8))
5680: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5690: 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48 20 20 IOERR_CONVPATH
56a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
56b0: 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38 29 29 IOERR | (26<<8))
56c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
56d0: 49 4f 45 52 52 5f 56 4e 4f 44 45 20 20 20 20 20 IOERR_VNODE
56e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
56f0: 49 4f 45 52 52 20 7c 20 28 32 37 3c 3c 38 29 29 IOERR | (27<<8))
5700: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5710: 49 4f 45 52 52 5f 41 55 54 48 20 20 20 20 20 20 IOERR_AUTH
5720: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5730: 49 4f 45 52 52 20 7c 20 28 32 38 3c 3c 38 29 29 IOERR | (28<<8))
5740: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5750: 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 LOCKED_SHAREDCAC
5760: 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f HE (SQLITE_
5770: 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 LOCKED | (1<<8)
5780: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5790: 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20 _BUSY_RECOVERY
57a0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
57b0: 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 _BUSY | (1<<8
57c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
57d0: 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f 54 20 E_BUSY_SNAPSHOT
57e0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
57f0: 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32 3c 3c E_BUSY | (2<<
5800: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5810: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 TE_CANTOPEN_NOTE
5820: 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 4c 49 MPDIR (SQLI
5830: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 TE_CANTOPEN | (1
5840: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5850: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 LITE_CANTOPEN_IS
5860: 44 49 52 20 20 20 20 20 20 20 20 20 20 28 53 51 DIR (SQ
5870: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 LITE_CANTOPEN |
5880: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (2<<8)).#define
5890: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f SQLITE_CANTOPEN_
58a0: 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20 28 FULLPATH (
58b0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 SQLITE_CANTOPEN
58c0: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (3<<8)).#defin
58d0: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 e SQLITE_CANTOPE
58e0: 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 N_CONVPATH
58f0: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 (SQLITE_CANTOPE
5900: 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 N | (4<<8)).#def
5910: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 ine SQLITE_CORRU
5920: 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 PT_VTAB
5930: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 (SQLITE_CORRU
5940: 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 PT | (1<<8)).#de
5950: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 fine SQLITE_READ
5960: 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20 ONLY_RECOVERY
5970: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 (SQLITE_READ
5980: 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 ONLY | (1<<8)).#
5990: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 define SQLITE_RE
59a0: 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 ADONLY_CANTLOCK
59b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 (SQLITE_RE
59c0: 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 ADONLY | (2<<8))
59d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
59e0: 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 READONLY_ROLLBAC
59f0: 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f K (SQLITE_
5a00: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 READONLY | (3<<8
5a10: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5a20: 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 E_READONLY_DBMOV
5a30: 45 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 ED (SQLIT
5a40: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c E_READONLY | (4<
5a50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5a60: 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 ITE_ABORT_ROLLBA
5a70: 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 4c CK (SQL
5a80: 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c ITE_ABORT | (2<<
5a90: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5aa0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 TE_CONSTRAINT_CH
5ab0: 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49 ECK (SQLI
5ac0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 TE_CONSTRAINT |
5ad0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (1<<8)).#define
5ae0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5af0: 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 T_COMMITHOOK (
5b00: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5b10: 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 T | (2<<8)).#def
5b20: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 ine SQLITE_CONST
5b30: 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 RAINT_FOREIGNKEY
5b40: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 (SQLITE_CONST
5b50: 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a RAINT | (3<<8)).
5b60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
5b70: 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 ONSTRAINT_FUNCTI
5b80: 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 ON (SQLITE_C
5b90: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c ONSTRAINT | (4<<
5ba0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5bb0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f TE_CONSTRAINT_NO
5bc0: 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 TNULL (SQLI
5bd0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 TE_CONSTRAINT |
5be0: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (5<<8)).#define
5bf0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5c00: 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28 T_PRIMARYKEY (
5c10: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5c20: 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 T | (6<<8)).#def
5c30: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 ine SQLITE_CONST
5c40: 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20 20 RAINT_TRIGGER
5c50: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 (SQLITE_CONST
5c60: 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a RAINT | (7<<8)).
5c70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
5c80: 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 ONSTRAINT_UNIQUE
5c90: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 (SQLITE_C
5ca0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c ONSTRAINT | (8<<
5cb0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5cc0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 TE_CONSTRAINT_VT
5cd0: 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 AB (SQLI
5ce0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 TE_CONSTRAINT |
5cf0: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (9<<8)).#define
5d00: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5d10: 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20 28 T_ROWID (
5d20: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5d30: 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 T |(10<<8)).#def
5d40: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 ine SQLITE_NOTIC
5d50: 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 E_RECOVER_WAL
5d60: 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 (SQLITE_NOTIC
5d70: 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 E | (1<<8)).#def
5d80: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 ine SQLITE_NOTIC
5d90: 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 E_RECOVER_ROLLBA
5da0: 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 CK (SQLITE_NOTIC
5db0: 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 E | (2<<8)).#def
5dc0: 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 ine SQLITE_WARNI
5dd0: 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20 NG_AUTOINDEX
5de0: 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 (SQLITE_WARNI
5df0: 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 NG | (1<<8)).#de
5e00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 fine SQLITE_AUTH
5e10: 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20 20 _USER
5e20: 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54 48 (SQLITE_AUTH
5e30: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 | (1<<8)).#defi
5e40: 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 ne SQLITE_OK_LOA
5e50: 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 20 20 D_PERMANENTLY
5e60: 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 28 (SQLITE_OK | (
5e70: 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 1<<8))../*.** CA
5e80: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f PI3REF: Flags Fo
5e90: 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 r File Open Oper
5ea0: 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 ations.**.** The
5eb0: 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 se bit values ar
5ec0: 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 e intended for u
5ed0: 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 se in the.** 3rd
5ee0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
5ef0: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f e [sqlite3_open_
5f00: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 v2()] interface
5f10: 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 and.** in the 4t
5f20: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
5f30: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e he [sqlite3_vfs.
5f40: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a xOpen] method..*
5f50: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
5f60: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 _OPEN_READONLY
5f70: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 0x0000000
5f80: 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 1 /* Ok for sql
5f90: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a ite3_open_v2() *
5fa0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
5fb0: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 _OPEN_READWRITE
5fc0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 0x0000000
5fd0: 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 2 /* Ok for sql
5fe0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a ite3_open_v2() *
5ff0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6000: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 _OPEN_CREATE
6010: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 0x0000000
6020: 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 4 /* Ok for sql
6030: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a ite3_open_v2() *
6040: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6050: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c _OPEN_DELETEONCL
6060: 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 OSE 0x0000000
6070: 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 8 /* VFS only *
6080: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6090: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 _OPEN_EXCLUSIVE
60a0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 0x0000001
60b0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 0 /* VFS only *
60c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
60d0: 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 _OPEN_AUTOPROXY
60e0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 0x0000002
60f0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 0 /* VFS only *
6100: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6110: 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 _OPEN_URI
6120: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 0x0000004
6130: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 0 /* Ok for sql
6140: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a ite3_open_v2() *
6150: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6160: 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 _OPEN_MEMORY
6170: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 0x0000008
6180: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 0 /* Ok for sql
6190: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a ite3_open_v2() *
61a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
61b0: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 _OPEN_MAIN_DB
61c0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 0x0000010
61d0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 0 /* VFS only *
61e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
61f0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 _OPEN_TEMP_DB
6200: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 0x0000020
6210: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 0 /* VFS only *
6220: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6230: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f _OPEN_TRANSIENT_
6240: 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 DB 0x0000040
6250: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 0 /* VFS only *
6260: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6270: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e _OPEN_MAIN_JOURN
6280: 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 AL 0x0000080
6290: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 0 /* VFS only *
62a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
62b0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e _OPEN_TEMP_JOURN
62c0: 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 AL 0x0000100
62d0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 0 /* VFS only *
62e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
62f0: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c _OPEN_SUBJOURNAL
6300: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 0x0000200
6310: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 0 /* VFS only *
6320: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6330: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 _OPEN_MASTER_JOU
6340: 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 RNAL 0x0000400
6350: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 0 /* VFS only *
6360: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6370: 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 _OPEN_NOMUTEX
6380: 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 0x0000800
6390: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 0 /* Ok for sql
63a0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a ite3_open_v2() *
63b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
63c0: 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 _OPEN_FULLMUTEX
63d0: 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 0x0001000
63e0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 0 /* Ok for sql
63f0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a ite3_open_v2() *
6400: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6410: 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 _OPEN_SHAREDCACH
6420: 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 E 0x0002000
6430: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 0 /* Ok for sql
6440: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a ite3_open_v2() *
6450: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6460: 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 _OPEN_PRIVATECAC
6470: 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 HE 0x0004000
6480: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 0 /* Ok for sql
6490: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a ite3_open_v2() *
64a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
64b0: 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 _OPEN_WAL
64c0: 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 0x0008000
64d0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 0 /* VFS only *
64e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
64f0: 5f 4f 50 45 4e 5f 46 49 4c 45 50 52 4f 54 45 43 _OPEN_FILEPROTEC
6500: 54 49 4f 4e 5f 4d 41 53 4b 20 20 20 20 20 20 20 TION_MASK
6510: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6520: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 37 30 0x0070
6530: 30 30 30 30 0a 0a 2f 2a 20 52 65 73 65 72 76 65 0000../* Reserve
6540: 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 d:
6550: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46 0x00F
6560: 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 00000 */../*.**
6570: 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 CAPI3REF: Device
6580: 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 Characteristics
6590: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 .**.** The xDevi
65a0: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 ceCharacteristic
65b0: 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 s method of the
65c0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
65d0: 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 ods].** object r
65e0: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 eturns an intege
65f0: 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 r which is a vec
6600: 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 tor of these.**
6610: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 bit values expre
6620: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 ssing I/O charac
6630: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 teristics of the
6640: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a mass storage.**
6650: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c device that hol
6660: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 ds the file that
6670: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f the [sqlite3_io
6680: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 _methods].** ref
6690: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 ers to..**.** Th
66a0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
66b0: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d TOMIC property m
66c0: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 eans that all wr
66d0: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 ites of.** any s
66e0: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 ize are atomic.
66f0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
6700: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 P_ATOMICnnn valu
6710: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 es.** mean that
6720: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 writes of blocks
6730: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 that are nnn by
6740: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a tes in size and.
6750: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 ** are aligned t
6760: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 o an address whi
6770: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ch is an integer
6780: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 multiple of.**
6790: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 nnn are atomic.
67a0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
67b0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 P_SAFE_APPEND va
67c0: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 lue means.** tha
67d0: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 t when data is a
67e0: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c ppended to a fil
67f0: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 e, the data is a
6800: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 ppended.** first
6810: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f then the size o
6820: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 f the file is ex
6830: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 tended, never th
6840: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 e other.** way a
6850: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 round. The SQLI
6860: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 TE_IOCAP_SEQUENT
6870: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 IAL property mea
6880: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 ns that.** infor
6890: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 mation is writte
68a0: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 n to disk in the
68b0: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 same order as c
68c0: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 alls.** to xWrit
68d0: 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 e(). The SQLITE
68e0: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 _IOCAP_POWERSAFE
68f0: 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 _OVERWRITE prope
6900: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a rty means that.*
6910: 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 * after reboot f
6920: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 ollowing a crash
6930: 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 or power loss,
6940: 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 the only bytes i
6950: 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 n a.** file that
6960: 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 were written at
6970: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
6980: 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 level might hav
6990: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 e changed.** and
69a0: 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 that adjacent b
69b0: 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 ytes, even bytes
69c0: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 within the same
69d0: 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 sector are.** g
69e0: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 uaranteed to be
69f0: 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 unchanged. The
6a00: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 SQLITE_IOCAP_UND
6a10: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 ELETABLE_WHEN_OP
6a20: 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 EN.** flag indic
6a30: 61 74 65 73 20 74 68 61 74 20 61 20 66 69 6c 65 ates that a file
6a40: 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 cannot be delet
6a50: 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 ed when open. T
6a60: 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 he.** SQLITE_IOC
6a70: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 AP_IMMUTABLE fla
6a80: 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 g indicates that
6a90: 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a the file is on.
6aa0: 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 ** read-only med
6ab0: 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 ia and cannot be
6ac0: 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 changed even by
6ad0: 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a processes with.
6ae0: 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 ** elevated priv
6af0: 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 ileges..*/.#defi
6b00: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
6b10: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 ATOMIC
6b20: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 0x0000000
6b30: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
6b40: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 _IOCAP_ATOMIC512
6b50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 0x
6b60: 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 00000002.#define
6b70: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
6b80: 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20 OMIC1K
6b90: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 0x00000004.
6ba0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
6bb0: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 OCAP_ATOMIC2K
6bc0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
6bd0: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 000008.#define S
6be0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
6bf0: 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 IC4K
6c00: 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 0x00000010.#d
6c10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
6c20: 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 AP_ATOMIC8K
6c30: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
6c40: 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0020.#define SQL
6c50: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
6c60: 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 16K
6c70: 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 0x00000040.#def
6c80: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
6c90: 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 _ATOMIC32K
6ca0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
6cb0: 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 80.#define SQLIT
6cc0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 E_IOCAP_ATOMIC64
6cd0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 K 0
6ce0: 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e x00000100.#defin
6cf0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 e SQLITE_IOCAP_S
6d00: 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20 AFE_APPEND
6d10: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0x00000200
6d20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6d30: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c IOCAP_SEQUENTIAL
6d40: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
6d50: 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 0000400.#define
6d60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 SQLITE_IOCAP_UND
6d70: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 ELETABLE_WHEN_OP
6d80: 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 EN 0x00000800.#
6d90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
6da0: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 CAP_POWERSAFE_OV
6db0: 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30 ERWRITE 0x000
6dc0: 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 01000.#define SQ
6dd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 LITE_IOCAP_IMMUT
6de0: 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 ABLE
6df0: 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0x00002000../*
6e00: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 .** CAPI3REF: Fi
6e10: 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c le Locking Level
6e20: 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 s.**.** SQLite u
6e30: 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 ses one of these
6e40: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 integer values
6e50: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a as the second.**
6e60: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c argument to cal
6e70: 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 ls it makes to t
6e80: 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 he xLock() and x
6e90: 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 Unlock() methods
6ea0: 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 .** of an [sqlit
6eb0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f e3_io_methods] o
6ec0: 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e bject..*/.#defin
6ed0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f e SQLITE_LOCK_NO
6ee0: 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 NE 0.#d
6ef0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 efine SQLITE_LOC
6f00: 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20 K_SHARED
6f10: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
6f20: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 _LOCK_RESERVED
6f30: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 2.#define SQ
6f40: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e LITE_LOCK_PENDIN
6f50: 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e G 3.#defin
6f60: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 e SQLITE_LOCK_EX
6f70: 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f CLUSIVE 4../
6f80: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
6f90: 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 ynchronization T
6fa0: 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 ype Flags.**.**
6fb0: 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f When SQLite invo
6fc0: 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 kes the xSync()
6fd0: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 method of an.**
6fe0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
6ff0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 ods] object it u
7000: 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f ses a combinatio
7010: 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e n of.** these in
7020: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 teger values as
7030: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d the second argum
7040: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 ent..**.** When
7050: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f the SQLITE_SYNC_
7060: 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 DATAONLY flag is
7070: 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 used, it means
7080: 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 that the.** sync
7090: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 operation only
70a0: 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 needs to flush d
70b0: 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 ata to mass stor
70c0: 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 age. Inode.** i
70d0: 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 nformation need
70e0: 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 not be flushed.
70f0: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 If the lower fou
7100: 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c r bits of the fl
7110: 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 ag.** equal SQLI
7120: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 TE_SYNC_NORMAL,
7130: 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 that means to us
7140: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 e normal fsync()
7150: 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 semantics..** I
7160: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 f the lower four
7170: 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 bits equal SQLI
7180: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 TE_SYNC_FULL, th
7190: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 at means.** to u
71a0: 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c se Mac OS X styl
71b0: 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 e fullsync inste
71c0: 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a ad of fsync()..*
71d0: 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 *.** Do not conf
71e0: 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 use the SQLITE_S
71f0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 YNC_NORMAL and S
7200: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 QLITE_SYNC_FULL
7210: 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 flags.** with th
7220: 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 e [PRAGMA synchr
7230: 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e onous]=NORMAL an
7240: 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 d [PRAGMA synchr
7250: 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 onous]=FULL.** s
7260: 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 ettings. The [s
7270: 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d ynchronous pragm
7280: 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 a] determines wh
7290: 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a en calls to the.
72a0: 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 ** xSync VFS met
72b0: 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 hod occur and ap
72c0: 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 plies uniformly
72d0: 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 across all platf
72e0: 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c orms..** The SQL
72f0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 ITE_SYNC_NORMAL
7300: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f and SQLITE_SYNC_
7310: 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 FULL flags deter
7320: 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 mine how.** ener
7330: 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 getic or rigorou
7340: 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 s or forceful th
7350: 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e e sync operation
7360: 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c s are and.** onl
7370: 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 y make a differe
7380: 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 nce on Mac OSX f
7390: 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 or the default S
73a0: 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 QLite code..** (
73b0: 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 Third-party VFS
73c0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
73d0: 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 might also make
73e0: 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a the distinction.
73f0: 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 ** between SQLIT
7400: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e E_SYNC_NORMAL an
7410: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 d SQLITE_SYNC_FU
7420: 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 LL, but among th
7430: 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 e.** operating s
7440: 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 ystems natively
7450: 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c supported by SQL
7460: 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 ite, only Mac OS
7470: 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 X.** cares about
7480: 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e the difference.
7490: 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ).*/.#define SQL
74a0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 ITE_SYNC_NORMAL
74b0: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 0x00002.#
74c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 define SQLITE_SY
74d0: 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 NC_FULL
74e0: 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 0x00003.#define
74f0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 SQLITE_SYNC_DAT
7500: 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 AONLY 0x000
7510: 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 10../*.** CAPI3R
7520: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 EF: OS Interface
7530: 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c Open File Handl
7540: 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 e.**.** An [sqli
7550: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 te3_file] object
7560: 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f represents an o
7570: 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 pen file in the
7580: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 .** [sqlite3_vfs
7590: 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 | OS interface
75a0: 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 layer]. Individ
75b0: 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 ual OS interface
75c0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
75d0: 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 ons will.** want
75e0: 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 to subclass thi
75f0: 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 s object by appe
7600: 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c nding additional
7610: 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 fields.** for t
7620: 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 heir own use. T
7630: 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 he pMethods entr
7640: 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 y is a pointer t
7650: 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 o an.** [sqlite3
7660: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a _io_methods] obj
7670: 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 ect that defines
7680: 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 methods for per
7690: 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f forming.** I/O o
76a0: 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 perations on the
76b0: 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 open file..*/.t
76c0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
76d0: 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 lite3_file sqlit
76e0: 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 e3_file;.struct
76f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 sqlite3_file {.
7700: 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 const struct sq
7710: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
7720: 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 *pMethods; /*
7730: 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f Methods for an o
7740: 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a pen file */.};..
7750: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
7760: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c OS Interface Fil
7770: 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 e Virtual Method
7780: 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 s Object.**.** E
7790: 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 very file opened
77a0: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 by the [sqlite3
77b0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 _vfs.xOpen] meth
77c0: 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a od populates an.
77d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 ** [sqlite3_file
77e0: 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f ] object (or, mo
77f0: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 re commonly, a s
7800: 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a ubclass of the.*
7810: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d * [sqlite3_file]
7820: 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 object) with a
7830: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
7840: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f stance of this o
7850: 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f bject..** This o
7860: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 bject defines th
7870: 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 e methods used t
7880: 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 o perform variou
7890: 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 s operations.**
78a0: 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e against the open
78b0: 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 file represente
78c0: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 d by the [sqlite
78d0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 3_file] object..
78e0: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 **.** If the [sq
78f0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d lite3_vfs.xOpen]
7900: 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 method sets the
7910: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d sqlite3_file.pM
7920: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a ethods element .
7930: 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c ** to a non-NULL
7940: 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 pointer, then t
7950: 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 he sqlite3_io_me
7960: 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 thods.xClose met
7970: 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e hod.** may be in
7980: 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 voked even if th
7990: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 e [sqlite3_vfs.x
79a0: 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 Open] reported t
79b0: 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 hat it failed.
79c0: 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 The.** only way
79d0: 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c to prevent a cal
79e0: 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c l to xClose foll
79f0: 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b owing a failed [
7a00: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 sqlite3_vfs.xOpe
7a10: 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 n].** is for the
7a20: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f [sqlite3_vfs.xO
7a30: 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 pen] to set the
7a40: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 sqlite3_file.pMe
7a50: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a thods element.**
7a60: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 to NULL..**.**
7a70: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 The flags argume
7a80: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 nt to xSync may
7a90: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 be one of [SQLIT
7aa0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f E_SYNC_NORMAL] o
7ab0: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e r.** [SQLITE_SYN
7ac0: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 C_FULL]. The fi
7ad0: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 rst choice is th
7ae0: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 e normal fsync()
7af0: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 ..** The second
7b00: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 choice is a Mac
7b10: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 OS X style fulls
7b20: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 ync. The [SQLIT
7b30: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d E_SYNC_DATAONLY]
7b40: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 .** flag may be
7b50: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 ORed in to indic
7b60: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 ate that only th
7b70: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 e data of the fi
7b80: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 le.** and not it
7b90: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f s inode needs to
7ba0: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a be synced..**.*
7bb0: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 * The integer va
7bc0: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 lues to xLock()
7bd0: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 and xUnlock() ar
7be0: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e e one of.** <ul>
7bf0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
7c00: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 _LOCK_NONE],.**
7c10: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 <li> [SQLITE_LOC
7c20: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c K_SHARED],.** <l
7c30: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f i> [SQLITE_LOCK_
7c40: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c RESERVED],.** <l
7c50: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f i> [SQLITE_LOCK_
7c60: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 PENDING], or.**
7c70: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 <li> [SQLITE_LOC
7c80: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a K_EXCLUSIVE]..**
7c90: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 </ul>.** xLock(
7ca0: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 ) increases the
7cb0: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 lock. xUnlock()
7cc0: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f decreases the lo
7cd0: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 ck..** The xChec
7ce0: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 kReservedLock()
7cf0: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 method checks wh
7d00: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 ether any databa
7d10: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a se connection,.*
7d20: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 * either in this
7d30: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 process or in s
7d40: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 ome other proces
7d50: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 s, is holding a
7d60: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e RESERVED,.** PEN
7d70: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 DING, or EXCLUSI
7d80: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 VE lock on the f
7d90: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 ile. It returns
7da0: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 true.** if such
7db0: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 a lock exists a
7dc0: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 nd false otherwi
7dd0: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 se..**.** The xF
7de0: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 ileControl() met
7df0: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 hod is a generic
7e00: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 interface that
7e10: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a allows custom.**
7e20: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 VFS implementat
7e30: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 ions to directly
7e40: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e control an open
7e50: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a file using the.
7e60: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 ** [sqlite3_file
7e70: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 _control()] inte
7e80: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f rface. The seco
7e90: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 nd "op" argument
7ea0: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 is an.** intege
7eb0: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 r opcode. The t
7ec0: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 hird argument is
7ed0: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 a generic point
7ee0: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a er intended to.*
7ef0: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 * point to a str
7f00: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 ucture that may
7f10: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 contain argument
7f20: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 s or space in wh
7f30: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 ich to.** write
7f40: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 return values.
7f50: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 Potential uses f
7f60: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 or xFileControl(
7f70: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 ) might be.** fu
7f80: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c nctions to enabl
7f90: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 e blocking locks
7fa0: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 with timeouts,
7fb0: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a to change the.**
7fc0: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 locking strateg
7fd0: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 y (for example t
7fe0: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c o use dot-file l
7ff0: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 ocks), to inquir
8000: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 e.** about the s
8010: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c tatus of a lock,
8020: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 or to break sta
8030: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 le locks. The S
8040: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 QLite.** core re
8050: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 serves all opcod
8060: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 es less than 100
8070: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 for its own use
8080: 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e ..** A [file con
8090: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c trol opcodes | l
80a0: 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 ist of opcodes]
80b0: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 less than 100 is
80c0: 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 available..** A
80d0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 pplications that
80e0: 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d define a custom
80f0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 xFileControl me
8100: 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 thod should use
8110: 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 opcodes.** great
8120: 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 er than 100 to a
8130: 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 void conflicts.
8140: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 VFS implementat
8150: 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 ions should.** r
8160: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f eturn [SQLITE_NO
8170: 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 TFOUND] for file
8180: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 control opcodes
8190: 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f that they do no
81a0: 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a t.** recognize..
81b0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f **.** The xSecto
81c0: 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 rSize() method r
81d0: 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f eturns the secto
81e0: 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a r size of the.**
81f0: 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 device that und
8200: 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e erlies the file.
8210: 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a The sector siz
8220: 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 e is the.** mini
8230: 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 mum write that c
8240: 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 an be performed
8250: 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 without disturbi
8260: 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 ng.** other byte
8270: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 s in the file.
8280: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 The xDeviceChara
8290: 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 cteristics().**
82a0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 method returns a
82b0: 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 bit vector desc
82c0: 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 ribing behaviors
82d0: 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 of the.** under
82e0: 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a lying device:.**
82f0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
8300: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
8310: 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b TOMIC].** <li> [
8320: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
8330: 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 MIC512].** <li>
8340: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
8350: 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 OMIC1K].** <li>
8360: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
8370: 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 OMIC2K].** <li>
8380: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
8390: 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 OMIC4K].** <li>
83a0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
83b0: 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 OMIC8K].** <li>
83c0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
83d0: 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e OMIC16K].** <li>
83e0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
83f0: 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 TOMIC32K].** <li
8400: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
8410: 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c ATOMIC64K].** <l
8420: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
8430: 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a _SAFE_APPEND].**
8440: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
8450: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a CAP_SEQUENTIAL].
8460: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
8470: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c IOCAP_UNDELETABL
8480: 45 5f 57 48 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 E_WHEN_OPEN].**
8490: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
84a0: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 AP_POWERSAFE_OVE
84b0: 52 57 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 RWRITE].** <li>
84c0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d [SQLITE_IOCAP_IM
84d0: 4d 55 54 41 42 4c 45 5d 0a 2a 2a 20 3c 2f 75 6c MUTABLE].** </ul
84e0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 >.**.** The SQLI
84f0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 TE_IOCAP_ATOMIC
8500: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 property means t
8510: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f hat all writes o
8520: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 f.** any size ar
8530: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 e atomic. The S
8540: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
8550: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 ICnnn values.**
8560: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 mean that writes
8570: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 of blocks that
8580: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e are nnn bytes in
8590: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 size and.** are
85a0: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 aligned to an a
85b0: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 ddress which is
85c0: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 an integer multi
85d0: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 ple of.** nnn ar
85e0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 e atomic. The S
85f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 QLITE_IOCAP_SAFE
8600: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 _APPEND value me
8610: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e ans.** that when
8620: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 data is appende
8630: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 d to a file, the
8640: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 data is appende
8650: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 d.** first then
8660: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
8670: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 file is extended
8680: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 , never the othe
8690: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e r.** way around.
86a0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 The SQLITE_IOC
86b0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 AP_SEQUENTIAL pr
86c0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 operty means tha
86d0: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e t.** information
86e0: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 is written to d
86f0: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 isk in the same
8700: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a order as calls.*
8710: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a * to xWrite()..*
8720: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 *.** If xRead()
8730: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 returns SQLITE_I
8740: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 OERR_SHORT_READ
8750: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c it must also fil
8760: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 l.** in the unre
8770: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 ad portions of t
8780: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a he buffer with z
8790: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 eros. A VFS tha
87a0: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 t.** fails to ze
87b0: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 ro-fill short re
87c0: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 ads might seem t
87d0: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 o work. However
87e0: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 ,.** failure to
87f0: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 zero-fill short
8800: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 reads will event
8810: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a ually lead to.**
8820: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 database corrup
8830: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 tion..*/.typedef
8840: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
8850: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 io_methods sqlit
8860: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 e3_io_methods;.s
8870: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f truct sqlite3_io
8880: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 _methods {. int
8890: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 iVersion;. int
88a0: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 (*xClose)(sqlit
88b0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 e3_file*);. int
88c0: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 (*xRead)(sqlite
88d0: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 3_file*, void*,
88e0: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 int iAmt, sqlite
88f0: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 3_int64 iOfst);.
8900: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 int (*xWrite)(
8910: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 sqlite3_file*, c
8920: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 onst void*, int
8930: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e iAmt, sqlite3_in
8940: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e t64 iOfst);. in
8950: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 t (*xTruncate)(s
8960: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 qlite3_file*, sq
8970: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 lite3_int64 size
8980: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 );. int (*xSync
8990: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
89a0: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 int flags);. i
89b0: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 nt (*xFileSize)(
89c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 sqlite3_file*, s
89d0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 qlite3_int64 *pS
89e0: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c ize);. int (*xL
89f0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ock)(sqlite3_fil
8a00: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 e*, int);. int
8a10: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 (*xUnlock)(sqlit
8a20: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a e3_file*, int);.
8a30: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 int (*xCheckRe
8a40: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 servedLock)(sqli
8a50: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a te3_file*, int *
8a60: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 pResOut);. int
8a70: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 (*xFileControl)(
8a80: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
8a90: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 nt op, void *pAr
8aa0: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 g);. int (*xSec
8ab0: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 torSize)(sqlite3
8ac0: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 _file*);. int (
8ad0: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 *xDeviceCharacte
8ae0: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 ristics)(sqlite3
8af0: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 _file*);. /* Me
8b00: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 thods above are
8b10: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f valid for versio
8b20: 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 n 1 */. int (*x
8b30: 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f ShmMap)(sqlite3_
8b40: 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 file*, int iPg,
8b50: 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 int pgsz, int, v
8b60: 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b oid volatile**);
8b70: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 . int (*xShmLoc
8b80: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a k)(sqlite3_file*
8b90: 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e , int offset, in
8ba0: 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b t n, int flags);
8bb0: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 . void (*xShmBa
8bc0: 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 rrier)(sqlite3_f
8bd0: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 ile*);. int (*x
8be0: 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 ShmUnmap)(sqlite
8bf0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 3_file*, int del
8c00: 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d eteFlag);. /* M
8c10: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 ethods above are
8c20: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 valid for versi
8c30: 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a on 2 */. int (*
8c40: 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f xFetch)(sqlite3_
8c50: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 file*, sqlite3_i
8c60: 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 nt64 iOfst, int
8c70: 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 iAmt, void **pp)
8c80: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 ;. int (*xUnfet
8c90: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ch)(sqlite3_file
8ca0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
8cb0: 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 iOfst, void *p)
8cc0: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 ;. /* Methods a
8cd0: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 bove are valid f
8ce0: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a or version 3 */.
8cf0: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 /* Additional
8d00: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 methods may be a
8d10: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 dded in future r
8d20: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f eleases */.};../
8d30: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
8d40: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e tandard File Con
8d50: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 trol Opcodes.**
8d60: 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 KEYWORDS: {file
8d70: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d control opcodes}
8d80: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f {file control o
8d90: 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 pcode}.**.** The
8da0: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 se integer const
8db0: 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 ants are opcodes
8dc0: 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f for the xFileCo
8dd0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 ntrol method.**
8de0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
8df0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 io_methods] obje
8e00: 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b ct and for the [
8e10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e sqlite3_file_con
8e20: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 trol()].** inter
8e30: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e face..**.** <ul>
8e40: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
8e50: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 _FCNTL_LOCKSTATE
8e60: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 ]].** The [SQLIT
8e70: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 E_FCNTL_LOCKSTAT
8e80: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 E] opcode is use
8e90: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e d for debugging.
8ea0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 This.** opcode
8eb0: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c causes the xFil
8ec0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 eControl method
8ed0: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 to write the cur
8ee0: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a rent state of.**
8ef0: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f the lock (one o
8f00: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e f [SQLITE_LOCK_N
8f10: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f ONE], [SQLITE_LO
8f20: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b CK_SHARED],.** [
8f30: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 SQLITE_LOCK_RESE
8f40: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c RVED], [SQLITE_L
8f50: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 OCK_PENDING], or
8f60: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 [SQLITE_LOCK_EX
8f70: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 CLUSIVE]).** int
8f80: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 o an integer tha
8f90: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d t the pArg argum
8fa0: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 ent points to. T
8fb0: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a his capability.*
8fc0: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 * is used during
8fd0: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20 testing and is
8fe0: 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77 only available w
8ff0: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54 hen the SQLITE_T
9000: 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 EST.** compile-t
9010: 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 ime option is us
9020: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b ed..**.** <li>[[
9030: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a SQLITE_FCNTL_SIZ
9040: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 E_HINT]].** The
9050: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 [SQLITE_FCNTL_SI
9060: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 ZE_HINT] opcode
9070: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 is used by SQLit
9080: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 e to give the VF
9090: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e S.** layer a hin
90a0: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 t of how large t
90b0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
90c0: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 will grow to be
90d0: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 during the.** c
90e0: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 urrent transacti
90f0: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 on. This hint i
9100: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 s not guaranteed
9110: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 to be accurate
9120: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 but it.** is oft
9130: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 en close. The u
9140: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 nderlying VFS mi
9150: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 ght choose to pr
9160: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 eallocate databa
9170: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 se.** file space
9180: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 based on this h
9190: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 int in order to
91a0: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 help writes to t
91b0: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 he database.** f
91c0: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a ile run faster..
91d0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
91e0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 TE_FCNTL_CHUNK_S
91f0: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 IZE]].** The [SQ
9200: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b LITE_FCNTL_CHUNK
9210: 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 _SIZE] opcode is
9220: 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 used to request
9230: 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a that the VFS.**
9240: 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 extends and tru
9250: 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62 ncates the datab
9260: 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e ase file in chun
9270: 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 ks of a size spe
9280: 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 cified.** by the
9290: 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 user. The fourt
92a0: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 h argument to [s
92b0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
92c0: 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a rol()] should .*
92d0: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e * point to an in
92e0: 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 teger (type int)
92f0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 containing the
9300: 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 new chunk-size t
9310: 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 o use.** for the
9320: 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 nominated datab
9330: 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 ase. Allocating
9340: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 database file sp
9350: 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 ace in large.**
9360: 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 chunks (say 1MB
9370: 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 at a time), may
9380: 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 reduce file-syst
9390: 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e em fragmentation
93a0: 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 and.** improve
93b0: 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 performance on s
93c0: 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a ome systems..**.
93d0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
93e0: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 FCNTL_FILE_POINT
93f0: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c ER]].** The [SQL
9400: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 ITE_FCNTL_FILE_P
9410: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 OINTER] opcode i
9420: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e s used to obtain
9430: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f a pointer.** to
9440: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 the [sqlite3_fi
9450: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 le] object assoc
9460: 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72 iated with a par
9470: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 ticular database
9480: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 .** connection.
9490: 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 See also [SQLIT
94a0: 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f E_FCNTL_JOURNAL_
94b0: 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 POINTER]..**.**
94c0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
94d0: 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 TL_JOURNAL_POINT
94e0: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c ER]].** The [SQL
94f0: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 ITE_FCNTL_JOURNA
9500: 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 L_POINTER] opcod
9510: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 e is used to obt
9520: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a ain a pointer.**
9530: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
9540: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 _file] object as
9550: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 sociated with th
9560: 65 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28 e journal file (
9570: 65 69 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72 either.** the [r
9580: 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d ollback journal]
9590: 20 6f 72 20 74 68 65 20 5b 77 72 69 74 65 2d 61 or the [write-a
95a0: 68 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61 head log]) for a
95b0: 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 particular data
95c0: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 base.** connecti
95d0: 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 on. See also [S
95e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 QLITE_FCNTL_FILE
95f0: 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a _POINTER]..**.**
9600: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
9610: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 NTL_SYNC_OMITTED
9620: 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 ]].** No longer
9630: 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c in use..**.** <l
9640: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
9650: 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b _SYNC]].** The [
9660: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e SQLITE_FCNTL_SYN
9670: 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e C] opcode is gen
9680: 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c erated internall
9690: 79 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a y by SQLite and.
96a0: 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 ** sent to the V
96b0: 46 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 FS immediately b
96c0: 65 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20 efore the xSync
96d0: 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 method is invoke
96e0: 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 d on a.** databa
96f0: 73 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 se file descript
9700: 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78 or. Or, if the x
9710: 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e Sync method is n
9720: 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 ot invoked .** b
9730: 65 63 61 75 73 65 20 74 68 65 20 75 73 65 72 20 ecause the user
9740: 68 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53 has configured S
9750: 51 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b QLite with .** [
9760: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f PRAGMA synchrono
9770: 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 us | PRAGMA sync
9780: 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 hronous=OFF] it
9790: 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c is invoked in pl
97a0: 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 ace .** of the x
97b0: 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 Sync method. In
97c0: 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65 20 most cases, the
97d0: 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 pointer argument
97e0: 20 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 passed with.**
97f0: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f this file-contro
9800: 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 l is NULL. Howev
9810: 65 72 2c 20 69 66 20 74 68 65 20 64 61 74 61 62 er, if the datab
9820: 61 73 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e ase file is bein
9830: 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 g synced.** as p
9840: 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 art of a multi-d
9850: 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 atabase commit,
9860: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 the argument poi
9870: 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 nts to a nul-ter
9880: 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e minated.** strin
9890: 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 g containing the
98a0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 transactions ma
98b0: 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c ster-journal fil
98c0: 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68 e name. VFSes th
98d0: 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 at .** do not ne
98e0: 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73 ed this signal s
98f0: 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 hould silently i
9900: 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 gnore this opcod
9910: 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 e. Applications
9920: 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 .** should not c
9930: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c all [sqlite3_fil
9940: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 e_control()] wit
9950: 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 h this opcode as
9960: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a doing so may .*
9970: 2a 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 * disrupt the op
9980: 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 eration of the s
9990: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 pecialized VFSes
99a0: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 that do require
99b0: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 it. .**.** <li
99c0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
99d0: 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d COMMIT_PHASETWO]
99e0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
99f0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 _FCNTL_COMMIT_PH
9a00: 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 ASETWO] opcode i
9a10: 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 s generated inte
9a20: 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 rnally by SQLite
9a30: 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 .** and sent to
9a40: 74 68 65 20 56 46 53 20 61 66 74 65 72 20 61 20 the VFS after a
9a50: 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 transaction has
9a60: 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 been committed i
9a70: 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 mmediately.** bu
9a80: 74 20 62 65 66 6f 72 65 20 74 68 65 20 64 61 74 t before the dat
9a90: 61 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 abase is unlocke
9aa0: 64 2e 20 56 46 53 65 73 20 74 68 61 74 20 64 6f d. VFSes that do
9ab0: 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 not need this s
9ac0: 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 ignal.** should
9ad0: 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 silently ignore
9ae0: 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 this opcode. App
9af0: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 lications should
9b00: 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 not call.** [sq
9b10: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 lite3_file_contr
9b20: 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 ol()] with this
9b30: 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 opcode as doing
9b40: 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 so may disrupt t
9b50: 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e he .** operation
9b60: 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 of the speciali
9b70: 7a 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 zed VFSes that d
9b80: 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a o require it. .
9b90: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
9ba0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 TE_FCNTL_WIN32_A
9bb0: 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 V_RETRY]].** ^Th
9bc0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
9bd0: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 WIN32_AV_RETRY]
9be0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 opcode is used t
9bf0: 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f o configure auto
9c00: 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 matic.** retry c
9c10: 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 ounts and interv
9c20: 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 als for certain
9c30: 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 disk I/O operati
9c40: 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 ons for the.** w
9c50: 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 indows [VFS] in
9c60: 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 order to provide
9c70: 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 robustness in t
9c80: 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a he presence of.*
9c90: 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f * anti-virus pro
9ca0: 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 grams. By defau
9cb0: 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 lt, the windows
9cc0: 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 VFS will retry f
9cd0: 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c ile read,.** fil
9ce0: 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c e write, and fil
9cf0: 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 e delete operati
9d00: 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d ons up to 10 tim
9d10: 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 es, with a delay
9d20: 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 .** of 25 millis
9d30: 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 econds before th
9d40: 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e e first retry an
9d50: 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 d with the delay
9d60: 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 increasing.** b
9d70: 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 y an additional
9d80: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 25 milliseconds
9d90: 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71 with each subseq
9da0: 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 uent retry. Thi
9db0: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f s.** opcode allo
9dc0: 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c ws these two val
9dd0: 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20 ues (10 retries
9de0: 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f and 25 milliseco
9df0: 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a nds of delay).**
9e00: 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e to be adjusted.
9e10: 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 The values are
9e20: 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c changed for all
9e30: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
9e40: 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 tions.** within
9e50: 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 the same process
9e60: 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 . The argument
9e70: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
9e80: 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a an array of two.
9e90: 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 ** integers wher
9ea0: 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 e the first inte
9eb0: 67 65 72 20 69 20 74 68 65 20 6e 65 77 20 72 65 ger i the new re
9ec0: 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 try count and th
9ed0: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 e second.** inte
9ee0: 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 ger is the delay
9ef0: 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 . If either int
9f00: 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 eger is negative
9f10: 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 , then the setti
9f20: 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 ng.** is not cha
9f30: 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 nged but instead
9f40: 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 the prior value
9f50: 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 of that setting
9f60: 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 is written.** i
9f70: 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e nto the array en
9f80: 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 try, allowing th
9f90: 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 e current retry
9fa0: 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a settings to be.*
9fb0: 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 * interrogated.
9fc0: 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 The zDbName par
9fd0: 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 ameter is ignore
9fe0: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 d..**.** <li>[[S
9ff0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 QLITE_FCNTL_PERS
a000: 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 IST_WAL]].** ^Th
a010: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
a020: 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 PERSIST_WAL] opc
a030: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 ode is used to s
a040: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a et or query the.
a050: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 ** persistent [W
a060: 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 AL | Write Ahead
a070: 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 Log] setting.
a080: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 By default, the
a090: 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 auxiliary.** wri
a0a0: 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 te ahead log and
a0b0: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 shared memory f
a0c0: 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 iles used for tr
a0d0: 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f ansaction contro
a0e0: 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 l.** are automat
a0f0: 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 ically deleted w
a100: 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 hen the latest c
a110: 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 onnection to the
a120: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f database.** clo
a130: 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 ses. Setting pe
a140: 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 rsistent WAL mod
a150: 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 e causes those f
a160: 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 iles to persist
a170: 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 after.** close.
a180: 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 Persisting the
a190: 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 files is useful
a1a0: 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 when other proce
a1b0: 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 sses that do not
a1c0: 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 .** have write p
a1d0: 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 ermission on the
a1e0: 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 directory conta
a1f0: 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 ining the databa
a200: 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 se file want.**
a210: 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61 to read the data
a220: 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 base file, as th
a230: 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 e WAL and shared
a240: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 memory files mu
a250: 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f st exist.** in o
a260: 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 rder for the dat
a270: 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 abase to be read
a280: 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 able. The fourt
a290: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a h parameter to.*
a2a0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f * [sqlite3_file_
a2b0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 control()] for t
a2c0: 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c his opcode shoul
a2d0: 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 d be a pointer t
a2e0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a o an integer..**
a2f0: 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 That integer is
a300: 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 0 to disable pe
a310: 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 rsistent WAL mod
a320: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 e or 1 to enable
a330: 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 persistent.** W
a340: 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 AL mode. If the
a350: 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 integer is -1,
a360: 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 then it is overw
a370: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 ritten with the
a380: 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 current.** WAL p
a390: 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 ersistence setti
a3a0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b ng..**.** <li>[[
a3b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 SQLITE_FCNTL_POW
a3c0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 ERSAFE_OVERWRITE
a3d0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 ]].** ^The [SQLI
a3e0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 TE_FCNTL_POWERSA
a3f0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 FE_OVERWRITE] op
a400: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 code is used to
a410: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 set or query the
a420: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 .** persistent "
a430: 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 powersafe-overwr
a440: 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 ite" or "PSOW" s
a450: 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f etting. The PSO
a460: 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 W setting.** det
a470: 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c ermines the [SQL
a480: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 ITE_IOCAP_POWERS
a490: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 AFE_OVERWRITE] b
a4a0: 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 it of the.** xDe
a4b0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 viceCharacterist
a4c0: 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 ics methods. The
a4d0: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
a4e0: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 r to.** [sqlite3
a4f0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d _file_control()]
a500: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 for this opcode
a510: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 should be a poi
a520: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 nter to an integ
a530: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 er..** That inte
a540: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 ger is 0 to disa
a550: 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 ble zero-damage
a560: 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 mode or 1 to ena
a570: 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a ble zero-damage.
a580: 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 ** mode. If the
a590: 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 integer is -1,
a5a0: 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 then it is overw
a5b0: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 ritten with the
a5c0: 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d current.** zero-
a5d0: 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 damage mode sett
a5e0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b ing..**.** <li>[
a5f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 [SQLITE_FCNTL_OV
a600: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 ERWRITE]].** ^Th
a610: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
a620: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 OVERWRITE] opcod
a630: 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 e is invoked by
a640: 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 SQLite after ope
a650: 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 ning.** a write
a660: 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 transaction to i
a670: 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e ndicate that, un
a680: 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 less it is rolle
a690: 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a d back for some.
a6a0: 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 ** reason, the e
a6b0: 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66 ntire database f
a6c0: 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 ile will be over
a6d0: 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 written by the c
a6e0: 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 urrent .** trans
a6f0: 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 action. This is
a700: 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f used by VACUUM o
a710: 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a perations..**.**
a720: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
a730: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a NTL_VFSNAME]].**
a740: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 ^The [SQLITE_FC
a750: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 NTL_VFSNAME] opc
a760: 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ode can be used
a770: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 to obtain the na
a780: 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 mes of.** all [V
a790: 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 FSes] in the VFS
a7a0: 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d stack. The nam
a7b0: 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 es are of all VF
a7c0: 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a S shims and the.
a7d0: 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d ** final bottom-
a7e0: 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 level VFS are wr
a7f0: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 itten into memor
a800: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
a810: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c .** [sqlite3_mal
a820: 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 loc()] and the r
a830: 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 esult is stored
a840: 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 in the char* var
a850: 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 iable.** that th
a860: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
a870: 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 er of [sqlite3_f
a880: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 ile_control()] p
a890: 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 oints to..** The
a8a0: 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f caller is respo
a8b0: 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 nsible for freei
a8c0: 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 ng the memory wh
a8d0: 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 en done. As wit
a8e0: 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f h.** all file-co
a8f0: 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 ntrol actions, t
a900: 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 here is no guara
a910: 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77 ntee that this w
a920: 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 ill actually.**
a930: 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 do anything. Ca
a940: 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 llers should ini
a950: 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 tialize the char
a960: 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 * variable to a
a970: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 NULL.** pointer
a980: 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c in case this fil
a990: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 e-control is not
a9a0: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 implemented. T
a9b0: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c his file-control
a9c0: 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 .** is intended
a9d0: 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 for diagnostic u
a9e0: 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c se only..**.** <
a9f0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
aa00: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a L_VFS_POINTER]].
aa10: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f ** ^The [SQLITE_
aa20: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 FCNTL_VFS_POINTE
aa30: 52 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 R] opcode finds
aa40: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
aa50: 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 top-level.** [V
aa60: 46 53 65 73 5d 20 63 75 72 72 65 6e 74 6c 79 20 FSes] currently
aa70: 69 6e 20 75 73 65 2e 20 20 5e 28 54 68 65 20 61 in use. ^(The a
aa80: 72 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 rgument X in.**
aa90: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e sqlite3_file_con
aaa0: 74 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46 trol(db,SQLITE_F
aab0: 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 CNTL_VFS_POINTER
aac0: 2c 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f ,X) must be.** o
aad0: 66 20 74 79 70 65 20 22 5b 73 71 6c 69 74 65 33 f type "[sqlite3
aae0: 5f 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73 _vfs] **". This
aaf0: 20 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20 73 65 opcodes will se
ab00: 74 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 t *X.** to a poi
ab10: 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d nter to the top-
ab20: 6c 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 level VFS.)^.**
ab30: 5e 57 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 ^When there are
ab40: 6d 75 6c 74 69 70 6c 65 20 56 46 53 20 73 68 69 multiple VFS shi
ab50: 6d 73 20 69 6e 20 74 68 65 20 73 74 61 63 6b 2c ms in the stack,
ab60: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 66 69 6e this opcode fin
ab70: 64 73 20 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d ds the.** upper-
ab80: 6d 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a most shim only..
ab90: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
aba0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d TE_FCNTL_PRAGMA]
abb0: 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 ].** ^Whenever a
abc0: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d [PRAGMA] statem
abd0: 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 ent is parsed, a
abe0: 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f n [SQLITE_FCNTL_
abf0: 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 PRAGMA] .** file
ac00: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 control is sent
ac10: 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 to the open [sq
ac20: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 lite3_file] obje
ac30: 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 ct corresponding
ac40: 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 .** to the datab
ac50: 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 ase file to whic
ac60: 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 h the pragma sta
ac70: 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e tement refers. ^
ac80: 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 The argument.**
ac90: 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 to the [SQLITE_F
aca0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c CNTL_PRAGMA] fil
acb0: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 e control is an
acc0: 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e array of.** poin
acd0: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 ters to strings
ace0: 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 (char**) in whic
acf0: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 h the second ele
ad00: 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 ment of the arra
ad10: 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 y.** is the name
ad20: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 of the pragma a
ad30: 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 nd the third ele
ad40: 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 ment is the argu
ad50: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 ment to the.** p
ad60: 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 ragma or NULL if
ad70: 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 the pragma has
ad80: 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 no argument. ^T
ad90: 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 he handler for a
ada0: 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e n.** [SQLITE_FCN
adb0: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 TL_PRAGMA] file
adc0: 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 control can opti
add0: 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 onally make the
ade0: 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a first element.**
adf0: 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 of the char** a
ae00: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f rgument point to
ae10: 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e a string obtain
ae20: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
ae30: 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f _mprintf()].** o
ae40: 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 r the equivalent
ae50: 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 and that string
ae60: 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 will become the
ae70: 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 result of the p
ae80: 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 ragma or.** the
ae90: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 error message if
aea0: 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c the pragma fail
aeb0: 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 s. ^If the.** [S
aec0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 QLITE_FCNTL_PRAG
aed0: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c MA] file control
aee0: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
aef0: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e _NOTFOUND], then
af00: 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 normal .** [PRA
af10: 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 GMA] processing
af20: 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 continues. ^If
af30: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 the [SQLITE_FCNT
af40: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c L_PRAGMA].** fil
af50: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e e control return
af60: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 s [SQLITE_OK], t
af70: 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 hen the parser a
af80: 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a ssumes that the.
af90: 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c ** VFS has handl
afa0: 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 ed the PRAGMA it
afb0: 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 self and the par
afc0: 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 ser generates a
afd0: 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 no-op.** prepare
afe0: 64 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20 72 d statement if r
aff0: 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 73 20 esult string is
b000: 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 NULL, or that re
b010: 74 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 turns a copy.**
b020: 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 74 of the result st
b030: 72 69 6e 67 20 69 66 20 74 68 65 20 73 74 72 69 ring if the stri
b040: 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a ng is non-NULL..
b050: 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 ** ^If the [SQLI
b060: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d TE_FCNTL_PRAGMA]
b070: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 file control re
b080: 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 turns.** any res
b090: 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 ult code other t
b0a0: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 han [SQLITE_OK]
b0b0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f or [SQLITE_NOTFO
b0c0: 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 UND], that means
b0d0: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 .** that the VFS
b0e0: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 encountered an
b0f0: 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 error while hand
b100: 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 ling the [PRAGMA
b110: 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d ] and the.** com
b120: 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 pilation of the
b130: 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 PRAGMA fails wit
b140: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 h an error. ^Th
b150: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
b160: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 PRAGMA].** file
b170: 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 control occurs a
b180: 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 t the beginning
b190: 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d of pragma statem
b1a0: 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 ent analysis and
b1b0: 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c so.** it is abl
b1c0: 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 e to override bu
b1d0: 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 ilt-in [PRAGMA]
b1e0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a statements..**.*
b1f0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
b200: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 CNTL_BUSYHANDLER
b210: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 ]].** ^The [SQLI
b220: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e TE_FCNTL_BUSYHAN
b230: 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f DLER].** file-co
b240: 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 ntrol may be inv
b250: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f oked by SQLite o
b260: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 n the database f
b270: 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 ile handle.** sh
b280: 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 ortly after it i
b290: 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 s opened in orde
b2a0: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 r to provide a c
b2b0: 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 ustom VFS with a
b2c0: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 ccess.** to the
b2d0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 connections busy
b2e0: 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 -handler callbac
b2f0: 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 k. The argument
b300: 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 is of type (void
b310: 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 **).** - an arr
b320: 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 ay of two (void
b330: 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 *) values. The f
b340: 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 irst (void *) ac
b350: 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a tually points.**
b360: 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f to a function o
b370: 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 f type (int (*)(
b380: 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 void *)). In ord
b390: 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 er to invoke the
b3a0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 connections.**
b3b0: 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 busy-handler, th
b3c0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 is function shou
b3d0: 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 ld be invoked wi
b3e0: 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 th the second (v
b3f0: 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 oid *) in.** the
b400: 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e array as the on
b410: 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 ly argument. If
b420: 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a it returns non-z
b430: 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 ero, then the op
b440: 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c eration.** shoul
b450: 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 d be retried. If
b460: 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f it returns zero
b470: 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 , the custom VFS
b480: 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 should abandon
b490: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f the.** current o
b4a0: 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 peration..**.**
b4b0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
b4c0: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d TL_TEMPFILENAME]
b4d0: 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f ].** ^Applicatio
b4e0: 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 n can invoke the
b4f0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 [SQLITE_FCNTL_T
b500: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c EMPFILENAME] fil
b510: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 e-control.** to
b520: 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 have SQLite gene
b530: 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 rate a.** tempor
b540: 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 ary filename usi
b550: 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f ng the same algo
b560: 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f rithm that is fo
b570: 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 llowed to genera
b580: 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 te.** temporary
b590: 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 filenames for TE
b5a0: 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 MP tables and ot
b5b0: 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 her internal use
b5c0: 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d s. The.** argum
b5d0: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 ent should be a
b5e0: 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c char** which wil
b5f0: 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 l be filled with
b600: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a the filename.**
b610: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 written into me
b620: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 mory obtained fr
b630: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
b640: 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c oc()]. The call
b650: 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 er should.** inv
b660: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 oke [sqlite3_fre
b670: 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 e()] on the resu
b680: 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 lt to avoid a me
b690: 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a mory leak..**.**
b6a0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
b6b0: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a NTL_MMAP_SIZE]].
b6c0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
b6d0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 CNTL_MMAP_SIZE]
b6e0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 file control is
b6f0: 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72 used to query or
b700: 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 set the.** maxi
b710: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 mum number of by
b720: 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 tes that will be
b730: 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 used for memory
b740: 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 -mapped I/O..**
b750: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 The argument is
b760: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 a pointer to a v
b770: 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c alue of type sql
b780: 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a ite3_int64 that.
b790: 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72 ** is an advisor
b7a0: 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 y maximum number
b7b0: 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 of bytes in the
b7c0: 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 file to memory
b7d0: 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 map. The.** poi
b7e0: 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74 nter is overwrit
b7f0: 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64 ten with the old
b800: 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d value. The lim
b810: 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 it is not change
b820: 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 d if.** the valu
b830: 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 e originally poi
b840: 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74 nted to is negat
b850: 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 ive, and so the
b860: 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a current limit .*
b870: 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64 * can be queried
b880: 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 by passing in a
b890: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 pointer to a ne
b8a0: 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 gative number.
b8b0: 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e This.** file-con
b8c0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74 trol is used int
b8d0: 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 ernally to imple
b8e0: 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 ment [PRAGMA mma
b8f0: 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c p_size]..**.** <
b900: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
b910: 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 L_TRACE]].** The
b920: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 [SQLITE_FCNTL_T
b930: 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 RACE] file contr
b940: 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69 ol provides advi
b950: 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e sory information
b960: 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61 .** to the VFS a
b970: 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69 bout what the hi
b980: 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74 gher layers of t
b990: 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 he SQLite stack
b9a0: 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 are doing..** Th
b9b0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 is file control
b9c0: 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20 is used by some
b9d0: 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61 VFS activity tra
b9e0: 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a cing [shims]..**
b9f0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 The argument is
ba00: 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
ba10: 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68 ed string. High
ba20: 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65 er layers in the
ba30: 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b .** SQLite stack
ba40: 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e may generate in
ba50: 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20 stances of this
ba60: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a file control if.
ba70: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 ** the [SQLITE_U
ba80: 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 SE_FCNTL_TRACE]
ba90: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
baa0: 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a ion is enabled..
bab0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
bac0: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 TE_FCNTL_HAS_MOV
bad0: 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c ED]].** The [SQL
bae0: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f ITE_FCNTL_HAS_MO
baf0: 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f VED] file contro
bb00: 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 l interprets its
bb10: 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a argument as a.*
bb20: 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 * pointer to an
bb30: 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20 77 integer and it w
bb40: 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 rites a boolean
bb50: 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 into that intege
bb60: 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f r depending.** o
bb70: 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 n whether or not
bb80: 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62 65 the file has be
bb90: 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 en renamed, move
bba0: 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69 d, or deleted si
bbb0: 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 nce it.** was fi
bbc0: 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a rst opened..**.*
bbd0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
bbe0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 CNTL_WIN32_GET_H
bbf0: 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b ANDLE]].** The [
bc00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e SQLITE_FCNTL_WIN
bc10: 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 32_GET_HANDLE] o
bc20: 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 pcode can be use
bc30: 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 0a d to obtain the.
bc40: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6e 61 ** underlying na
bc50: 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 tive file handle
bc60: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
bc70: 20 61 20 66 69 6c 65 20 68 61 6e 64 6c 65 2e 20 a file handle.
bc80: 20 54 68 69 73 20 66 69 6c 65 0a 2a 2a 20 63 6f This file.** co
bc90: 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 ntrol interprets
bca0: 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 its argument as
bcb0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
bcc0: 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64 native file hand
bcd0: 6c 65 20 61 6e 64 0a 2a 2a 20 77 72 69 74 65 73 le and.** writes
bce0: 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 76 the resulting v
bcf0: 61 6c 75 65 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a alue there..**.*
bd00: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
bd10: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 CNTL_WIN32_SET_H
bd20: 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b ANDLE]].** The [
bd30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e SQLITE_FCNTL_WIN
bd40: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 32_SET_HANDLE] o
bd50: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f pcode is used fo
bd60: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 r debugging. Th
bd70: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 is.** opcode cau
bd80: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e ses the xFileCon
bd90: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 trol method to s
bda0: 77 61 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e wap the file han
bdb0: 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65 dle with the one
bdc0: 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 .** pointed to b
bdd0: 79 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d y the pArg argum
bde0: 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61 62 ent. This capab
bdf0: 69 6c 69 74 79 20 69 73 20 75 73 65 64 20 64 75 ility is used du
be00: 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 ring testing.**
be10: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 and only needs t
be20: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 o be supported w
be30: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20 hen SQLITE_TEST
be40: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a is defined..**.*
be50: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
be60: 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d CNTL_WAL_BLOCK]]
be70: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
be80: 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d FCNTL_WAL_BLOCK]
be90: 20 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 is a signal to
bea0: 74 68 65 20 56 46 53 20 6c 61 79 65 72 20 74 68 the VFS layer th
beb0: 61 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 at it might.** b
bec0: 65 20 61 64 76 61 6e 74 61 67 65 6f 75 73 20 74 e advantageous t
bed0: 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e o block on the n
bee0: 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 ext WAL lock if
bef0: 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 the lock is not
bf00: 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 immediately.** a
bf10: 76 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 vailable. The W
bf20: 41 4c 20 73 75 62 73 79 73 74 65 6d 20 69 73 73 AL subsystem iss
bf30: 75 65 73 20 74 68 69 73 20 73 69 67 6e 61 6c 20 ues this signal
bf40: 64 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 during rare.** c
bf50: 69 72 63 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 ircumstances in
bf60: 6f 72 64 65 72 20 74 6f 20 66 69 78 20 61 20 70 order to fix a p
bf70: 72 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 69 6f roblem with prio
bf80: 72 69 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a rity inversion..
bf90: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 ** Applications
bfa0: 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f should <em>not</
bfb0: 65 6d 3e 20 75 73 65 20 74 68 69 73 20 66 69 6c em> use this fil
bfc0: 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a e-control..**.**
bfd0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
bfe0: 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 NTL_ZIPVFS]].**
bff0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
c000: 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 L_ZIPVFS] opcode
c010: 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 is implemented
c020: 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 by zipvfs only.
c030: 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 All other.** VFS
c040: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 should return S
c050: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 QLITE_NOTFOUND f
c060: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a or this opcode..
c070: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
c080: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a TE_FCNTL_RBU]].*
c090: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 * The [SQLITE_FC
c0a0: 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 NTL_RBU] opcode
c0b0: 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 is implemented b
c0c0: 79 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 y the special VF
c0d0: 53 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 S used by.** the
c0e0: 20 52 42 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f RBU extension o
c0f0: 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 nly. All other
c100: 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 VFS should retur
c110: 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e n SQLITE_NOTFOUN
c120: 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 D for.** this op
c130: 63 6f 64 65 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e code. .** </ul>
c140: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
c150: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 TE_FCNTL_LOCKSTA
c160: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TE
c170: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 1.#define SQLIT
c180: 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b E_FCNTL_GET_LOCK
c190: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 PROXYFILE
c1a0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
c1b0: 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 _FCNTL_SET_LOCKP
c1c0: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 33 ROXYFILE 3
c1d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
c1e0: 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f FCNTL_LAST_ERRNO
c1f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 4.
c200: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
c210: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 CNTL_SIZE_HINT
c220: 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 5.#
c230: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
c240: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 NTL_CHUNK_SIZE
c250: 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 6.#d
c260: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
c270: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 TL_FILE_POINTER
c280: 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 7.#de
c290: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
c2a0: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 L_SYNC_OMITTED
c2b0: 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 8.#def
c2c0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
c2d0: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 _WIN32_AV_RETRY
c2e0: 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 9.#defi
c2f0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
c300: 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 PERSIST_WAL
c310: 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 10.#defin
c320: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f e SQLITE_FCNTL_O
c330: 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20 VERWRITE
c340: 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 11.#define
c350: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 SQLITE_FCNTL_VF
c360: 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 SNAME
c370: 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 12.#define
c380: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 SQLITE_FCNTL_POW
c390: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 ERSAFE_OVERWRITE
c3a0: 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 13.#define S
c3b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 QLITE_FCNTL_PRAG
c3c0: 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 MA
c3d0: 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 14.#define SQ
c3e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 LITE_FCNTL_BUSYH
c3f0: 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 ANDLER
c400: 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 15.#define SQL
c410: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 ITE_FCNTL_TEMPFI
c420: 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 LENAME
c430: 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 16.#define SQLI
c440: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 TE_FCNTL_MMAP_SI
c450: 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ZE
c460: 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 18.#define SQLIT
c470: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 E_FCNTL_TRACE
c480: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 1
c490: 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 9.#define SQLITE
c4a0: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 _FCNTL_HAS_MOVED
c4b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20
c4c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
c4d0: 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 FCNTL_SYNC
c4e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 0a 21.
c4f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
c500: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 CNTL_COMMIT_PHAS
c510: 45 54 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23 ETWO 22.#
c520: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
c530: 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 NTL_WIN32_SET_HA
c540: 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a 23 64 NDLE 23.#d
c550: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
c560: 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 TL_WAL_BLOCK
c570: 20 20 20 20 20 20 20 20 20 20 32 34 0a 23 64 65 24.#de
c580: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
c590: 4c 5f 5a 49 50 56 46 53 20 20 20 20 20 20 20 20 L_ZIPVFS
c5a0: 20 20 20 20 20 20 20 20 20 32 35 0a 23 64 65 66 25.#def
c5b0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
c5c0: 5f 52 42 55 20 20 20 20 20 20 20 20 20 20 20 20 _RBU
c5d0: 20 20 20 20 20 20 20 20 32 36 0a 23 64 65 66 69 26.#defi
c5e0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
c5f0: 56 46 53 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 VFS_POINTER
c600: 20 20 20 20 20 20 20 32 37 0a 23 64 65 66 69 6e 27.#defin
c610: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a e SQLITE_FCNTL_J
c620: 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 20 20 OURNAL_POINTER
c630: 20 20 20 20 20 20 32 38 0a 23 64 65 66 69 6e 65 28.#define
c640: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 SQLITE_FCNTL_WI
c650: 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 20 20 N32_GET_HANDLE
c660: 20 20 20 20 20 32 39 0a 23 64 65 66 69 6e 65 20 29.#define
c670: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 44 42 SQLITE_FCNTL_PDB
c680: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
c690: 20 20 20 20 33 30 0a 0a 2f 2a 20 64 65 70 72 65 30../* depre
c6a0: 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 cated names */.#
c6b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 define SQLITE_GE
c6c0: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 T_LOCKPROXYFILE
c6d0: 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 SQLITE_FCNT
c6e0: 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 L_GET_LOCKPROXYF
c6f0: 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 ILE.#define SQLI
c700: 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 TE_SET_LOCKPROXY
c710: 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 FILE SQLITE
c720: 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 _FCNTL_SET_LOCKP
c730: 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 ROXYFILE.#define
c740: 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 SQLITE_LAST_ERR
c750: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 53 NO S
c760: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 QLITE_FCNTL_LAST
c770: 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 _ERRNO.../*.** C
c780: 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 API3REF: Mutex H
c790: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 andle.**.** The
c7a0: 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 mutex module wit
c7b0: 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e hin SQLite defin
c7c0: 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 es [sqlite3_mute
c7d0: 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 x] to be an.** a
c7e0: 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 bstract type for
c7f0: 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e a mutex object.
c800: 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 The SQLite cor
c810: 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a e never looks.**
c820: 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c at the internal
c830: 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 representation
c840: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d of an [sqlite3_m
c850: 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a utex]. It only.
c860: 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f ** deals with po
c870: 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 inters to the [s
c880: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 qlite3_mutex] ob
c890: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 ject..**.** Mute
c8a0: 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 xes are created
c8b0: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d using [sqlite3_m
c8c0: 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a utex_alloc()]..*
c8d0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
c8e0: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 sqlite3_mutex s
c8f0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f qlite3_mutex;../
c900: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c *.** CAPI3REF: L
c910: 6f 61 64 61 62 6c 65 20 45 78 74 65 6e 73 69 6f oadable Extensio
c920: 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41 20 n Thunk.**.** A
c930: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6f pointer to the o
c940: 70 61 71 75 65 20 73 71 6c 69 74 65 33 5f 61 70 paque sqlite3_ap
c950: 69 5f 72 6f 75 74 69 6e 65 73 20 73 74 72 75 63 i_routines struc
c960: 74 75 72 65 20 69 73 20 70 61 73 73 65 64 20 61 ture is passed a
c970: 73 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20 70 s.** the third p
c980: 61 72 61 6d 65 74 65 72 20 74 6f 20 65 6e 74 72 arameter to entr
c990: 79 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f 61 y points of [loa
c9a0: 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73 dable extensions
c9b0: 5d 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74 72 75 ]. This.** stru
c9c0: 63 74 75 72 65 20 6d 75 73 74 20 62 65 20 74 79 cture must be ty
c9d0: 70 65 64 65 66 65 64 20 69 6e 20 6f 72 64 65 72 pedefed in order
c9e0: 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 to work around
c9f0: 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e 67 compiler warning
ca00: 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c 61 s.** on some pla
ca10: 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65 64 tforms..*/.typed
ca20: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
ca30: 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 3_api_routines s
ca40: 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 qlite3_api_routi
ca50: 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 nes;../*.** CAPI
ca60: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 3REF: OS Interfa
ca70: 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 ce Object.**.**
ca80: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 An instance of t
ca90: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f he sqlite3_vfs o
caa0: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 bject defines th
cab0: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 e interface betw
cac0: 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 een.** the SQLit
cad0: 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 e core and the u
cae0: 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 nderlying operat
caf0: 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 ing system. The
cb00: 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 "vfs".** in the
cb10: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a name of the obj
cb20: 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 ect stands for "
cb30: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 virtual file sys
cb40: 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 tem". See.** th
cb50: 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 e [VFS | VFS doc
cb60: 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 umentation] for
cb70: 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 further informat
cb80: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 ion..**.** The v
cb90: 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 alue of the iVer
cba0: 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e sion field is in
cbb0: 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 itially 1 but ma
cbc0: 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a y be larger in.*
cbd0: 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e * future version
cbe0: 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 s of SQLite. Ad
cbf0: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 ditional fields
cc00: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 may be appended
cc10: 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 to this.** objec
cc20: 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 t when the iVers
cc30: 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 ion value is inc
cc40: 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 reased. Note th
cc50: 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 at the structure
cc60: 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 .** of the sqlit
cc70: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 e3_vfs object ch
cc80: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 anges in the tra
cc90: 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e nsaction between
cca0: 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 .** SQLite versi
ccb0: 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 on 3.5.9 and 3.6
ccc0: 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 .0 and yet the i
ccd0: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 Version field wa
cce0: 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 s not.** modifie
ccf0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f d..**.** The szO
cd00: 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 sFile field is t
cd10: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 he size of the s
cd20: 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 ubclassed [sqlit
cd30: 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 e3_file].** stru
cd40: 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 cture used by th
cd50: 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e is VFS. mxPathn
cd60: 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d ame is the maxim
cd70: 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 um length of.**
cd80: 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 a pathname in th
cd90: 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 is VFS..**.** Re
cda0: 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 gistered sqlite3
cdb0: 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 _vfs objects are
cdc0: 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 kept on a linke
cdd0: 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 d list formed by
cde0: 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f .** the pNext po
cdf0: 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c inter. The [sql
ce00: 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 ite3_vfs_registe
ce10: 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c r()].** and [sql
ce20: 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 ite3_vfs_unregis
ce30: 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ter()] interface
ce40: 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 s manage this li
ce50: 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 st.** in a threa
ce60: 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 d-safe way. The
ce70: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 [sqlite3_vfs_fi
ce80: 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a nd()] interface.
ce90: 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 ** searches the
cea0: 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 list. Neither t
ceb0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 he application c
cec0: 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a ode nor the VFS.
ced0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
cee0: 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 n should use the
cef0: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a pNext pointer..
cf00: 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 **.** The pNext
cf10: 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c field is the onl
cf20: 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 y field in the s
cf30: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 qlite3_vfs.** st
cf40: 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c ructure that SQL
cf50: 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f ite will ever mo
cf60: 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 dify. SQLite wi
cf70: 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a ll only access.*
cf80: 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 * or modify this
cf90: 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c field while hol
cfa0: 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 ding a particula
cfb0: 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a r static mutex..
cfc0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
cfd0: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 on should never
cfe0: 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 modify anything
cff0: 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 within the sqlit
d000: 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 e3_vfs.** object
d010: 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 once the object
d020: 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 has been regist
d030: 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ered..**.** The
d040: 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 zName field hold
d050: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
d060: 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 e VFS module. T
d070: 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 he name must.**
d080: 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 be unique across
d090: 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 all VFS modules
d0a0: 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 ..**.** [[sqlite
d0b0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 3_vfs.xOpen]].**
d0c0: 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 ^SQLite guarant
d0d0: 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 ees that the zFi
d0e0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 lename parameter
d0f0: 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 to xOpen.** is
d100: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f either a NULL po
d110: 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 inter or string
d120: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d obtained.** from
d130: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 xFullPathname()
d140: 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 with an optiona
d150: 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a l suffix added..
d160: 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 ** ^If a suffix
d170: 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 is added to the
d180: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 zFilename parame
d190: 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 ter, it will.**
d1a0: 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e consist of a sin
d1b0: 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 gle "-" characte
d1c0: 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f r followed by no
d1d0: 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 more than.** 11
d1e0: 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e alphanumeric an
d1f0: 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 d/or "-" charact
d200: 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ers..** ^SQLite
d210: 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 further guarante
d220: 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 es that.** the s
d230: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 tring will be va
d240: 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 lid and unchange
d250: 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 d until xClose()
d260: 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 is.** called. B
d270: 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 ecause of the pr
d280: 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c evious sentence,
d290: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 .** the [sqlite3
d2a0: 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c _file] can safel
d2b0: 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 y store a pointe
d2c0: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 r to the.** file
d2d0: 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 name if it needs
d2e0: 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 to remember the
d2f0: 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f filename for so
d300: 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 me reason..** If
d310: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 the zFilename p
d320: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 arameter to xOpe
d330: 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e n is a NULL poin
d340: 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a ter then xOpen.*
d350: 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 * must invent it
d360: 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 s own temporary
d370: 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c name for the fil
d380: 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 e. ^Whenever th
d390: 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 e .** xFilename
d3a0: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c parameter is NUL
d3b0: 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 L it will also b
d3c0: 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 e the case that
d3d0: 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 the.** flags par
d3e0: 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c ameter will incl
d3f0: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e ude [SQLITE_OPEN
d400: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e _DELETEONCLOSE].
d410: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 .**.** The flags
d420: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 argument to xOp
d430: 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c en() includes al
d440: 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a l bits set in.**
d450: 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d the flags argum
d460: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ent to [sqlite3_
d470: 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 open_v2()]. Or
d480: 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e if [sqlite3_open
d490: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 ()].** or [sqlit
d4a0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 e3_open16()] is
d4b0: 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 used, then flags
d4c0: 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 includes at lea
d4d0: 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 st.** [SQLITE_OP
d4e0: 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 EN_READWRITE] |
d4f0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 [SQLITE_OPEN_CRE
d500: 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 ATE]. .** If xOp
d510: 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c en() opens a fil
d520: 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e e read-only then
d530: 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c it sets *pOutFl
d540: 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 ags to.** includ
d550: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 e [SQLITE_OPEN_R
d560: 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 EADONLY]. Other
d570: 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c bits in *pOutFl
d580: 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a ags may be set..
d590: 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 **.** ^(SQLite w
d5a0: 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 ill also add one
d5b0: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e of the followin
d5c0: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 g flags to the x
d5d0: 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 Open().** call,
d5e0: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 depending on the
d5f0: 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 object being op
d600: 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ened:.**.** <ul>
d610: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
d620: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a E_OPEN_MAIN_DB].
d630: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
d640: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e _OPEN_MAIN_JOURN
d650: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 AL].** <li> [SQ
d660: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 LITE_OPEN_TEMP_D
d670: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c B].** <li> [SQL
d680: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f ITE_OPEN_TEMP_JO
d690: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 URNAL].** <li>
d6a0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 [SQLITE_OPEN_TRA
d6b0: 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c NSIENT_DB].** <l
d6c0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
d6d0: 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 _SUBJOURNAL].**
d6e0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
d6f0: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 EN_MASTER_JOURNA
d700: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c L].** <li> [SQL
d710: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a ITE_OPEN_WAL].**
d720: 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 </ul>)^.**.** T
d730: 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c he file I/O impl
d740: 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 ementation can u
d750: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 se the object ty
d760: 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 pe flags to.** c
d770: 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 hange the way it
d780: 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 deals with file
d790: 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c s. For example,
d7a0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a an application.
d7b0: 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 ** that does not
d7c0: 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 care about cras
d7d0: 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f h recovery or ro
d7e0: 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b llback might mak
d7f0: 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 e.** the open of
d800: 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 a journal file
d810: 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 a no-op. Writes
d820: 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c to this journal
d830: 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 would.** also b
d840: 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e e no-ops, and an
d850: 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 y attempt to rea
d860: 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f d the journal wo
d870: 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 uld return.** SQ
d880: 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 LITE_IOERR. Or
d890: 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 the implementati
d8a0: 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 on might recogni
d8b0: 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 ze that a databa
d8c0: 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 se.** file will
d8d0: 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c be doing page-al
d8e0: 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 igned sector rea
d8f0: 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e ds and writes in
d900: 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 a random.** ord
d910: 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 er and set up it
d920: 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 s I/O subsystem
d930: 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a accordingly..**.
d940: 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 ** SQLite might
d950: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 also add one of
d960: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c the following fl
d970: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e ags to the xOpen
d980: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c method:.**.** <
d990: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c ul>.** <li> [SQL
d9a0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f ITE_OPEN_DELETEO
d9b0: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 NCLOSE].** <li>
d9c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 [SQLITE_OPEN_EXC
d9d0: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e LUSIVE].** </ul>
d9e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 .**.** The [SQLI
d9f0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e TE_OPEN_DELETEON
da00: 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e CLOSE] flag mean
da10: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c s the file shoul
da20: 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 d be.** deleted
da30: 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 when it is close
da40: 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 d. ^The [SQLITE
da50: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c _OPEN_DELETEONCL
da60: 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 OSE].** will be
da70: 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 set for TEMP dat
da80: 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 abases and their
da90: 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 journals, trans
daa0: 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 ient.** database
dab0: 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 s, and subjourna
dac0: 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b ls..**.** ^The [
dad0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c SQLITE_OPEN_EXCL
dae0: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 USIVE] flag is a
daf0: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f lways used in co
db00: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 njunction.** wit
db10: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 h the [SQLITE_OP
db20: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c EN_CREATE] flag,
db30: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 which are both
db40: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c directly.** anal
db50: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 ogous to the O_E
db60: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 XCL and O_CREAT
db70: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 flags of the POS
db80: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 IX open().** API
db90: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 . The SQLITE_OP
dba0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 EN_EXCLUSIVE fla
dbb0: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 g, when paired w
dbc0: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 ith the .** SQLI
dbd0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 TE_OPEN_CREATE,
dbe0: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 is used to indic
dbf0: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 ate that file sh
dc00: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 ould always.** b
dc10: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 e created, and t
dc20: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 hat it is an err
dc30: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 or if it already
dc40: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 exists..** It i
dc50: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 s <i>not</i> use
dc60: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 d to indicate th
dc70: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 e file should be
dc80: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 opened .** for
dc90: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 exclusive access
dca0: 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 ..**.** ^At leas
dcb0: 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 t szOsFile bytes
dcc0: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 of memory are a
dcd0: 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 llocated by SQLi
dce0: 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 te.** to hold th
dcf0: 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 e [sqlite3_file
dd00: 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 ] structure pass
dd10: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a ed as the third.
dd20: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 ** argument to x
dd30: 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e Open. The xOpen
dd40: 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 method does not
dd50: 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f have to.** allo
dd60: 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 cate the structu
dd70: 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 re; it should ju
dd80: 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 st fill it in.
dd90: 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 Note that.** the
dda0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 xOpen method mu
ddb0: 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 st set the sqlit
ddc0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 e3_file.pMethods
ddd0: 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 to either.** a
dde0: 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 valid [sqlite3_i
ddf0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 o_methods] objec
de00: 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 t or to NULL. x
de10: 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 Open must do.**
de20: 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 this even if the
de30: 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 open fails. SQ
de40: 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 Lite expects tha
de50: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 t the sqlite3_fi
de60: 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 le.pMethods.** e
de70: 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 lement will be v
de80: 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e alid after xOpen
de90: 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c returns regardl
dea0: 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 ess of the succe
deb0: 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 ss.** or failure
dec0: 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 of the xOpen ca
ded0: 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 ll..**.** [[sqli
dee0: 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d te3_vfs.xAccess]
def0: 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 ].** ^The flags
df00: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 argument to xAcc
df10: 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 ess() may be [SQ
df20: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 LITE_ACCESS_EXIS
df30: 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 TS].** to test f
df40: 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 or the existence
df50: 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b of a file, or [
df60: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 SQLITE_ACCESS_RE
df70: 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 ADWRITE] to.** t
df80: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 est whether a fi
df90: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 le is readable a
dfa0: 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 nd writable, or
dfb0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 [SQLITE_ACCESS_R
dfc0: 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 EAD].** to test
dfd0: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 whether a file i
dfe0: 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 s at least reada
dff0: 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 ble. The file
e000: 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 can be a.** dire
e010: 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 ctory..**.** ^SQ
e020: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 Lite will always
e030: 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 allocate at lea
e040: 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 st mxPathname+1
e050: 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a bytes for the.**
e060: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78 output buffer x
e070: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 FullPathname. T
e080: 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 he exact size of
e090: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 the output buff
e0a0: 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 er.** is also pa
e0b0: 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 ssed as a parame
e0c0: 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 ter to both met
e0d0: 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 hods. If the out
e0e0: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 put buffer.** is
e0f0: 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 not large enoug
e100: 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f h, [SQLITE_CANTO
e110: 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 PEN] should be r
e120: 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 eturned. Since t
e130: 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 his is.** handle
e140: 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 d as a fatal err
e150: 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 or by SQLite, vf
e160: 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e s implementation
e170: 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f s should endeavo
e180: 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 r.** to prevent
e190: 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 this by setting
e1a0: 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 mxPathname to a
e1b0: 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 sufficiently lar
e1c0: 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 ge value..**.**
e1d0: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 The xRandomness(
e1e0: 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 ), xSleep(), xCu
e1f0: 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 rrentTime(), and
e200: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 xCurrentTimeInt
e210: 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 64().** interfac
e220: 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 es are not stric
e230: 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 tly a part of th
e240: 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 e filesystem, bu
e250: 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e t they are.** in
e260: 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 cluded in the VF
e270: 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 S structure for
e280: 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a completeness..**
e290: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 The xRandomness
e2a0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 () function atte
e2b0: 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e mpts to return n
e2c0: 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f Bytes bytes.** o
e2d0: 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 f good-quality r
e2e0: 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a andomness into z
e2f0: 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e Out. The return
e300: 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 value is.** the
e310: 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f actual number o
e320: 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f f bytes of rando
e330: 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a mness obtained..
e340: 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 ** The xSleep()
e350: 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 method causes th
e360: 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 e calling thread
e370: 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 to sleep for at
e380: 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 .** least the nu
e390: 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 mber of microsec
e3a0: 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 onds given. ^Th
e3b0: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 e xCurrentTime()
e3c0: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 .** method retur
e3d0: 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 ns a Julian Day
e3e0: 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 Number for the c
e3f0: 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 urrent date and
e400: 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f time as.** a flo
e410: 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 ating point valu
e420: 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 e..** ^The xCurr
e430: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d entTimeInt64() m
e440: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 ethod returns, a
e450: 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 s an integer, th
e460: 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 e Julian.** Day
e470: 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 Number multiplie
e480: 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74 d by 86400000 (t
e490: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c he number of mil
e4a0: 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a liseconds in .**
e4b0: 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e a 24-hour day).
e4c0: 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 .** ^SQLite wi
e4d0: 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72 ll use the xCurr
e4e0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d entTimeInt64() m
e4f0: 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 ethod to get the
e500: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 current.** date
e510: 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 and time if tha
e520: 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 t method is avai
e530: 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 lable (if iVersi
e540: 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 on is 2 or .** g
e550: 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 reater and the f
e560: 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 unction pointer
e570: 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 is not NULL) and
e580: 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a will fall back.
e590: 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 ** to xCurrentTi
e5a0: 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 me() if xCurrent
e5b0: 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 TimeInt64() is u
e5c0: 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a navailable..**.*
e5d0: 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 * ^The xSetSyste
e5e0: 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 mCall(), xGetSys
e5f0: 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 temCall(), and x
e600: 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 NestSystemCall()
e610: 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 interfaces.** a
e620: 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 re not used by t
e630: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 he SQLite core.
e640: 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 These optional
e650: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 interfaces are p
e660: 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f rovided.** by so
e670: 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 me VFSes to faci
e680: 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f litate testing o
e690: 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 f the VFS code.
e6a0: 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a By overriding .*
e6b0: 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 * system calls w
e6c0: 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e ith functions un
e6d0: 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c der its control,
e6e0: 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 a test program
e6f0: 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 can.** simulate
e700: 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 faults and error
e710: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 conditions that
e720: 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 would otherwise
e730: 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a be difficult.**
e740: 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 or impossible t
e750: 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 o induce. The s
e760: 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c et of system cal
e770: 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f ls that can be o
e780: 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 verridden.** var
e790: 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 ies from one VFS
e7a0: 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 to another, and
e7b0: 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f from one versio
e7c0: 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 n of the same VF
e7d0: 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 S to the.** next
e7e0: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 . Applications
e7f0: 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69 that use these i
e800: 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 nterfaces must b
e810: 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 e prepared for a
e820: 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 ny.** or all of
e830: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 these interfaces
e840: 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 to be NULL or f
e850: 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f or their behavio
e860: 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 r to change.** f
e870: 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 rom one release
e880: 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 to the next. Ap
e890: 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 plications must
e8a0: 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 not attempt to a
e8b0: 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 ccess.** any of
e8c0: 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 these methods if
e8d0: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 the iVersion of
e8e0: 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 the VFS is less
e8f0: 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 than 3..*/.type
e900: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
e910: 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 e3_vfs sqlite3_v
e920: 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 fs;.typedef void
e930: 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 (*sqlite3_sysca
e940: 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 ll_ptr)(void);.s
e950: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 truct sqlite3_vf
e960: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 s {. int iVersi
e970: 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f on; /
e980: 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 * Structure vers
e990: 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 ion number (curr
e9a0: 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e ently 3) */. in
e9b0: 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 t szOsFile;
e9c0: 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f /* Size o
e9d0: 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c f subclassed sql
e9e0: 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 ite3_file */. i
e9f0: 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 nt mxPathname;
ea00: 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d /* Maxim
ea10: 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 um file pathname
ea20: 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c length */. sql
ea30: 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b ite3_vfs *pNext;
ea40: 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 /* Next re
ea50: 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a gistered VFS */.
ea60: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e const char *zN
ea70: 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 ame; /* Na
ea80: 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 me of this virtu
ea90: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a al file system *
eaa0: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 /. void *pAppDa
eab0: 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 ta; /*
eac0: 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 Pointer to appli
ead0: 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 cation-specific
eae0: 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a data */. int (*
eaf0: 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 xOpen)(sqlite3_v
eb00: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
eb10: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f *zName, sqlite3_
eb20: 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 file*,.
eb30: 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c int flags,
eb40: 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 int *pOutFlags)
eb50: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 ;. int (*xDelet
eb60: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c e)(sqlite3_vfs*,
eb70: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
eb80: 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 me, int syncDir)
eb90: 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 ;. int (*xAcces
eba0: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c s)(sqlite3_vfs*,
ebb0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
ebc0: 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 me, int flags, i
ebd0: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 nt *pResOut);.
ebe0: 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e int (*xFullPathn
ebf0: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ame)(sqlite3_vfs
ec00: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
ec10: 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 Name, int nOut,
ec20: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 char *zOut);. v
ec30: 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 oid *(*xDlOpen)(
ec40: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
ec50: 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e nst char *zFilen
ec60: 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 ame);. void (*x
ec70: 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 DlError)(sqlite3
ec80: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 _vfs*, int nByte
ec90: 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 , char *zErrMsg)
eca0: 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c ;. void (*(*xDl
ecb0: 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 Sym)(sqlite3_vfs
ecc0: 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 *,void*, const c
ecd0: 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 har *zSymbol))(v
ece0: 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 oid);. void (*x
ecf0: 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 DlClose)(sqlite3
ed00: 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 _vfs*, void*);.
ed10: 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 int (*xRandomne
ed20: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ss)(sqlite3_vfs*
ed30: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 , int nByte, cha
ed40: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 r *zOut);. int
ed50: 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 (*xSleep)(sqlite
ed60: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 3_vfs*, int micr
ed70: 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 oseconds);. int
ed80: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 (*xCurrentTime)
ed90: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 (sqlite3_vfs*, d
eda0: 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 ouble*);. int (
edb0: 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 *xGetLastError)(
edc0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e sqlite3_vfs*, in
edd0: 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a t, char *);. /*
ede0: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 . ** The method
edf0: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 s above are in v
ee00: 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 ersion 1 of the
ee10: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 sqlite_vfs objec
ee20: 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f t. ** definitio
ee30: 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 n. Those that f
ee40: 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 ollow are added
ee50: 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 in version 2 or
ee60: 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 later. */. int
ee70: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 (*xCurrentTimeI
ee80: 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 nt64)(sqlite3_vf
ee90: 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 s*, sqlite3_int6
eea0: 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 4*);. /*. ** T
eeb0: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 he methods above
eec0: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 are in versions
eed0: 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 1 and 2 of the
eee0: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 sqlite_vfs objec
eef0: 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 t.. ** Those be
ef00: 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 low are for vers
ef10: 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 ion 3 and greate
ef20: 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a r.. */. int (*
ef30: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 xSetSystemCall)(
ef40: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
ef50: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
ef60: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c sqlite3_syscall
ef70: 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 _ptr);. sqlite3
ef80: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 _syscall_ptr (*x
ef90: 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 GetSystemCall)(s
efa0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
efb0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b st char *zName);
efc0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 . const char *(
efd0: 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c *xNextSystemCall
efe0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
eff0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
f000: 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 e);. /*. ** Th
f010: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 e methods above
f020: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 are in versions
f030: 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 1 through 3 of t
f040: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 he sqlite_vfs ob
f050: 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 ject.. ** New f
f060: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 ields may be app
f070: 65 6e 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 ended in future
f080: 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 versions. The i
f090: 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c Version. ** val
f0a0: 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e ue will incremen
f0b0: 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 t whenever this
f0c0: 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d happens. . */.}
f0d0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
f0e0: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 F: Flags for the
f0f0: 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 xAccess VFS met
f100: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 hod.**.** These
f110: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 integer constant
f120: 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 s can be used as
f130: 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d the third param
f140: 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 eter to.** the x
f150: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 Access method of
f160: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 an [sqlite3_vfs
f170: 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 ] object. They
f180: 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 determine.** wha
f190: 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 t kind of permis
f1a0: 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 sions the xAcces
f1b0: 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b s method is look
f1c0: 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 ing for..** With
f1d0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 SQLITE_ACCESS_E
f1e0: 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 XISTS, the xAcce
f1f0: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d ss method.** sim
f200: 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 ply checks wheth
f210: 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 er the file exis
f220: 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 ts..** With SQLI
f230: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 TE_ACCESS_READWR
f240: 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 ITE, the xAccess
f250: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b method.** check
f260: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 s whether the na
f270: 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 med directory is
f280: 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 both readable a
f290: 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 nd writable.** (
f2a0: 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 in other words,
f2b0: 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 if files can be
f2c0: 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 added, removed,
f2d0: 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 and renamed with
f2e0: 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 in.** the direct
f2f0: 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c ory)..** The SQL
f300: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 ITE_ACCESS_READW
f310: 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 RITE constant is
f320: 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 currently used
f330: 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b only by the.** [
f340: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 temp_store_direc
f350: 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 tory pragma], th
f360: 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 ough this could
f370: 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 change in a futu
f380: 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 re.** release of
f390: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 SQLite..** With
f3a0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 SQLITE_ACCESS_R
f3b0: 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 EAD, the xAccess
f3c0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b method.** check
f3d0: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 s whether the fi
f3e0: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 le is readable.
f3f0: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 The SQLITE_ACCE
f400: 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 SS_READ constant
f410: 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 is.** currently
f420: 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 unused, though
f430: 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 it might be used
f440: 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c in a future rel
f450: 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 ease of.** SQLit
f460: 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 e..*/.#define SQ
f470: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 LITE_ACCESS_EXIS
f480: 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 TS 0.#define
f490: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 SQLITE_ACCESS_RE
f4a0: 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 ADWRITE 1 /* U
f4b0: 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 sed by PRAGMA te
f4c0: 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f mp_store_directo
f4d0: 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ry */.#define SQ
f4e0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
f4f0: 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 2 /* Unu
f500: 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 sed */../*.** CA
f510: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f PI3REF: Flags fo
f520: 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 r the xShmLock V
f530: 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 FS method.**.**
f540: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f These integer co
f550: 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 nstants define t
f560: 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 he various locki
f570: 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a ng operations.**
f580: 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 allowed by the
f590: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 xShmLock method
f5a0: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d of [sqlite3_io_m
f5b0: 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a ethods]. The.**
f5c0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 following are t
f5d0: 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f he only legal co
f5e0: 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c mbinations of fl
f5f0: 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 ags to the.** xS
f600: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a hmLock method:.*
f610: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
f620: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f > SQLITE_SHM_LO
f630: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f CK | SQLITE_SHM_
f640: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 SHARED.** <li>
f650: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 SQLITE_SHM_LOCK
f660: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 | SQLITE_SHM_EXC
f670: 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 LUSIVE.** <li>
f680: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 SQLITE_SHM_UNLOC
f690: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 K | SQLITE_SHM_S
f6a0: 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 HARED.** <li> S
f6b0: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b QLITE_SHM_UNLOCK
f6c0: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 | SQLITE_SHM_EX
f6d0: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e CLUSIVE.** </ul>
f6e0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f .**.** When unlo
f6f0: 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 cking, the same
f700: 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 SHARED or EXCLUS
f710: 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 IVE flag must be
f720: 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 supplied as.**
f730: 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68 65 was given on the
f740: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c corresponding l
f750: 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 ock. .**.** The
f760: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 xShmLock method
f770: 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 can transition
f780: 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 between unlocked
f790: 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a and SHARED or.*
f7a0: 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b * between unlock
f7b0: 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 ed and EXCLUSIVE
f7c0: 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 . It cannot tra
f7d0: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 nsition between
f7e0: 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 SHARED.** and EX
f7f0: 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 CLUSIVE..*/.#def
f800: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 ine SQLITE_SHM_U
f810: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 NLOCK 1.#d
f820: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d efine SQLITE_SHM
f830: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a _LOCK 2.
f840: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
f850: 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 HM_SHARED
f860: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
f870: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 _SHM_EXCLUSIVE
f880: 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 8../*.** CAPI3
f890: 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 REF: Maximum xSh
f8a0: 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a mLock index.**.*
f8b0: 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d * The xShmLock m
f8c0: 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 ethod on [sqlite
f8d0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 3_io_methods] ma
f8e0: 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 y use values.**
f8f0: 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 between 0 and th
f900: 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 is upper bound a
f910: 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 s its "offset" a
f920: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 rgument..** The
f930: 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c SQLite core will
f940: 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 never attempt t
f950: 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c o acquire or rel
f960: 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f ease a.** lock o
f970: 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 utside of this r
f980: 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ange.*/.#define
f990: 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b SQLITE_SHM_NLOCK
f9a0: 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 8.../*.*
f9b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 * CAPI3REF: Init
f9c0: 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 ialize The SQLit
f9d0: 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 e Library.**.**
f9e0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 ^The sqlite3_ini
f9f0: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e tialize() routin
fa00: 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 e initializes th
fa10: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 e.** SQLite libr
fa20: 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 ary. ^The sqlit
fa30: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f e3_shutdown() ro
fa40: 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 utine.** dealloc
fa50: 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 ates any resourc
fa60: 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c es that were all
fa70: 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 ocated by sqlite
fa80: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 3_initialize()..
fa90: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
faa0: 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 s are designed t
fab0: 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 o aid in process
fac0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
fad0: 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 and.** shutdown
fae0: 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 on embedded syst
faf0: 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f ems. Workstatio
fb00: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 n applications u
fb10: 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e sing.** SQLite n
fb20: 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e ormally do not n
fb30: 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 eed to invoke ei
fb40: 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f ther of these ro
fb50: 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 utines..**.** A
fb60: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
fb70: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 initialize() is
fb80: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 an "effective" c
fb90: 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 all if it is.**
fba0: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 the first time s
fbb0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
fbc0: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 e() is invoked d
fbd0: 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 uring the lifeti
fbe0: 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f me of.** the pro
fbf0: 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 cess, or if it i
fc00: 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 s the first time
fc10: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
fc20: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 ize() is invoked
fc30: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 .** following a
fc40: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
fc50: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f shutdown(). ^(O
fc60: 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 nly an effective
fc70: 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 call.** of sqli
fc80: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
fc90: 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 does any initia
fca0: 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f lization. All o
fcb0: 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 ther calls.** ar
fcc0: 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 e harmless no-op
fcd0: 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c s.)^.**.** A cal
fce0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 l to sqlite3_shu
fcf0: 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 tdown() is an "e
fd00: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 ffective" call i
fd10: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 f it is the firs
fd20: 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c t.** call to sql
fd30: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 ite3_shutdown()
fd40: 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 since the last s
fd50: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
fd60: 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 e(). ^(Only.**
fd70: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c an effective cal
fd80: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 l to sqlite3_shu
fd90: 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 tdown() does any
fda0: 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f deinitializatio
fdb0: 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 n..** All other
fdc0: 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 valid calls to s
fdd0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
fde0: 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e ) are harmless n
fdf0: 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 o-ops.)^.**.** T
fe00: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 he sqlite3_initi
fe10: 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 alize() interfac
fe20: 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c e is threadsafe,
fe30: 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 but sqlite3_shu
fe40: 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f tdown().** is no
fe50: 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f t. The sqlite3_
fe60: 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 shutdown() inter
fe70: 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 face must only b
fe80: 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a e called from a.
fe90: 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 ** single thread
fea0: 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 . All open [dat
feb0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
fec0: 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 s] must be close
fed0: 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 d and all.** oth
fee0: 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 er SQLite resour
fef0: 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c ces must be deal
ff00: 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f located prior to
ff10: 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c invoking.** sql
ff20: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e ite3_shutdown().
ff30: 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 .**.** Among oth
ff40: 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 er things, ^sqli
ff50: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
ff60: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 will invoke.**
ff70: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
ff80: 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e ). Similarly, ^
ff90: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
ffa0: 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b ().** will invok
ffb0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 e sqlite3_os_end
ffc0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ()..**.** ^The s
ffd0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
ffe0: 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 e() routine retu
fff0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 rns [SQLITE_OK]
10000 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e on success..** ^
10010 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 If for some reas
10020 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 on, sqlite3_init
10030 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 ialize() is unab
10040 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 le to initialize
10050 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 .** the library
10060 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 (perhaps it is u
10070 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 nable to allocat
10080 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 e a needed resou
10090 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 rce such.** as a
100a0 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 mutex) it retur
100b0 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 ns an [error cod
100c0 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 e] other than [S
100d0 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a QLITE_OK]..**.**
100e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e ^The sqlite3_in
100f0 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 itialize() routi
10100 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 ne is called int
10110 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 ernally by many
10120 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 other.** SQLite
10130 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 interfaces so th
10140 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f at an applicatio
10150 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e n usually does n
10160 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e ot need to.** in
10170 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 voke sqlite3_ini
10180 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 tialize() direct
10190 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 ly. For example
101a0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 , [sqlite3_open(
101b0 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 )].** calls sqli
101c0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
101d0 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c so the SQLite l
101e0 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 ibrary will be a
101f0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 utomatically.**
10200 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e initialized when
10210 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
10220 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 ] is called if i
10230 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 t has not be ini
10240 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 tialized.** alre
10250 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 ady. ^However,
10260 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d if SQLite is com
10270 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b piled with the [
10280 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f SQLITE_OMIT_AUTO
10290 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 INIT].** compile
102a0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 -time option, th
102b0 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 en the automatic
102c0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 calls to sqlite
102d0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 3_initialize().*
102e0 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e * are omitted an
102f0 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f d the applicatio
10300 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 n must call sqli
10310 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
10320 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 directly.** pri
10330 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 or to using any
10340 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 other SQLite int
10350 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 erface. For max
10360 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 imum portability
10370 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d ,.** it is recom
10380 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c mended that appl
10390 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 ications always
103a0 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 invoke sqlite3_i
103b0 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 nitialize().** d
103c0 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f irectly prior to
103d0 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 using any other
103e0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
103f0 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 e. Future relea
10400 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 ses.** of SQLite
10410 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69 may require thi
10420 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 s. In other wor
10430 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 ds, the behavior
10440 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 exhibited.** wh
10450 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d en SQLite is com
10460 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 piled with [SQLI
10470 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 TE_OMIT_AUTOINIT
10480 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 ] might become t
10490 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 he.** default be
104a0 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 havior in some f
104b0 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 uture release of
104c0 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 SQLite..**.** T
104d0 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e he sqlite3_os_in
104e0 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 it() routine doe
104f0 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 s operating-syst
10500 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 em specific.** i
10510 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 nitialization of
10520 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 the SQLite libr
10530 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 ary. The sqlite
10540 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 3_os_end().** ro
10550 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 utine undoes the
10560 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 effect of sqlit
10570 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 e3_os_init(). T
10580 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 ypical tasks.**
10590 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 performed by the
105a0 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c se routines incl
105b0 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f ude allocation o
105c0 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a r deallocation.*
105d0 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f * of static reso
105e0 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a urces, initializ
105f0 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 ation of global
10600 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 variables,.** se
10610 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 tting up a defau
10620 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d lt [sqlite3_vfs]
10630 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 module, or sett
10640 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 ing up.** a defa
10650 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ult configuratio
10660 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 n using [sqlite3
10670 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a _config()]..**.*
10680 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f * The applicatio
10690 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 n should never i
106a0 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c nvoke either sql
106b0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a ite3_os_init().*
106c0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f * or sqlite3_os_
106d0 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 end() directly.
106e0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
106f0 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 should only inv
10700 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 oke.** sqlite3_i
10710 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 nitialize() and
10720 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
10730 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 (). The sqlite3
10740 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e _os_init().** in
10750 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 terface is calle
10760 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 d automatically
10770 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 by sqlite3_initi
10780 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 alize() and.** s
10790 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 qlite3_os_end()
107a0 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c is called by sql
107b0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e ite3_shutdown().
107c0 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a Appropriate.**
107d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
107e0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f for sqlite3_os_
107f0 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 init() and sqlit
10800 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 e3_os_end().** a
10810 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 re built into SQ
10820 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 Lite when it is
10830 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 compiled for Uni
10840 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f x, Windows, or O
10850 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 S/2..** When [cu
10860 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 stom builds | bu
10870 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c ilt for other pl
10880 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 atforms].** (usi
10890 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f ng the [SQLITE_O
108a0 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 S_OTHER=1] compi
108b0 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f le-time.** optio
108c0 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 n) the applicati
108d0 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 on must supply a
108e0 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d suitable implem
108f0 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 entation for.**
10900 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
10910 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 ) and sqlite3_os
10920 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c _end(). An appl
10930 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 ication-supplied
10940 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
10950 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 on of sqlite3_os
10960 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 _init() or sqlit
10970 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d e3_os_end().** m
10980 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 ust return [SQLI
10990 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 TE_OK] on succes
109a0 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 s and some other
109b0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 [error code] up
109c0 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a on.** failure..*
109d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e /.int sqlite3_in
109e0 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a itialize(void);.
109f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 int sqlite3_shut
10a00 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 down(void);.int
10a10 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
10a20 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 void);.int sqlit
10a30 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b e3_os_end(void);
10a40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
10a50 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 : Configuring Th
10a60 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 e SQLite Library
10a70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
10a80 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 e3_config() inte
10a90 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f rface is used to
10aa0 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e make global con
10ab0 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 figuration.** ch
10ac0 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 anges to SQLite
10ad0 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 in order to tune
10ae0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 SQLite to the s
10af0 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 pecific needs of
10b00 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 .** the applicat
10b10 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c ion. The defaul
10b20 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 t configuration
10b30 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 is recommended f
10b40 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 or most.** appli
10b50 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 cations and so t
10b60 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 his routine is u
10b70 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 sually not neces
10b80 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 sary. It is.**
10b90 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 provided to supp
10ba0 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 ort rare applica
10bb0 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 tions with unusu
10bc0 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 al needs..**.**
10bd0 3c 62 3e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 <b>The sqlite3_c
10be0 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 onfig() interfac
10bf0 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 e is not threads
10c00 61 66 65 2e 20 54 68 65 20 61 70 70 6c 69 63 61 afe. The applica
10c10 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 tion.** must ens
10c20 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 ure that no othe
10c30 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 r SQLite interfa
10c40 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 ces are invoked
10c50 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 by other.** thre
10c60 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 ads while sqlite
10c70 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 3_config() is ru
10c80 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a nning.</b>.**.**
10c90 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e The sqlite3_con
10ca0 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 0a fig() interface.
10cb0 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 ** may only be i
10cc0 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 nvoked prior to
10cd0 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 library initiali
10ce0 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 zation using.**
10cf0 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c [sqlite3_initial
10d00 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 ize()] or after
10d10 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c shutdown by [sql
10d20 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d ite3_shutdown()]
10d30 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 ..** ^If sqlite3
10d40 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c _config() is cal
10d50 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 led after [sqlit
10d60 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d e3_initialize()]
10d70 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b and before.** [
10d80 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
10d90 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c ()] then it will
10da0 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d return SQLITE_M
10db0 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 ISUSE..** Note,
10dc0 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 however, that ^s
10dd0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
10de0 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 can be called as
10df0 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 part of the.**
10e00 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
10e10 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e f an application
10e20 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 -defined [sqlite
10e30 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 3_os_init()]..**
10e40 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 .** The first ar
10e50 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
10e60 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 3_config() is an
10e70 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e integer.** [con
10e80 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
10e90 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e n] that determin
10ea0 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 es.** what prope
10eb0 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 rty of SQLite is
10ec0 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 to be configure
10ed0 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 d. Subsequent a
10ee0 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 rguments.** vary
10ef0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 depending on th
10f00 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e e [configuration
10f10 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 option].** in t
10f20 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
10f30 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 t..**.** ^When a
10f40 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
10f50 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 ption is set, sq
10f60 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 lite3_config() r
10f70 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
10f80 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f K]..** ^If the o
10f90 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e ption is unknown
10fa0 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e or SQLite is un
10fb0 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 able to set the
10fc0 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 option.** then t
10fd0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 his routine retu
10fe0 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b rns a non-zero [
10ff0 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a error code]..*/.
11000 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 int sqlite3_conf
11010 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f ig(int, ...);../
11020 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
11030 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 onfigure databas
11040 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a e connections.**
11050 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
11060 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
11070 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 e3_db_config() i
11080 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 nterface is used
11090 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 to make configu
110a0 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 ration.** change
110b0 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 s to a [database
110c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 connection]. T
110d0 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 he interface is
110e0 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 similar to.** [s
110f0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
11100 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 except that the
11110 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 changes apply t
11120 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 o a single.** [d
11130 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
11140 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 on] (specified i
11150 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 n the first argu
11160 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ment)..**.** The
11170 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
11180 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 to sqlite3_db_c
11190 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 onfig(D,V,...)
111a0 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 is the.** [SQLIT
111b0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 E_DBCONFIG_LOOKA
111c0 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 SIDE | configura
111d0 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 tion verb] - an
111e0 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a integer code .**
111f0 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 that indicates
11200 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 what aspect of t
11210 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
11220 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e nection] is bein
11230 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a g configured..**
11240 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 Subsequent argu
11250 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e ments vary depen
11260 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 ding on the conf
11270 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a iguration verb..
11280 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 **.** ^Calls to
11290 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
112a0 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 g() return SQLIT
112b0 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 E_OK if and only
112c0 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 if.** the call
112d0 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 is considered su
112e0 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 ccessful..*/.int
112f0 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 sqlite3_db_conf
11300 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 ig(sqlite3*, int
11310 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a op, ...);../*.*
11320 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f * CAPI3REF: Memo
11330 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f ry Allocation Ro
11340 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 utines.**.** An
11350 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
11360 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 object defines
11370 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 the interface be
11380 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 tween SQLite.**
11390 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 and low-level me
113a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
113b0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 routines..**.**
113c0 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 This object is u
113d0 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 sed in only one
113e0 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c place in the SQL
113f0 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a ite interface..*
11400 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 * A pointer to a
11410 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
11420 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 is object is the
11430 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 argument to.**
11440 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
11450 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 )] when the conf
11460 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
11470 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 is.** [SQLITE_C
11480 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 ONFIG_MALLOC] or
11490 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
114a0 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a GETMALLOC]. .**
114b0 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 By creating an
114c0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
114d0 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 object.** and p
114e0 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 assing it to [sq
114f0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 lite3_config]([S
11500 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
11510 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 LOC]).** during
11520 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 configuration, a
11530 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 n application ca
11540 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 n specify an alt
11550 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f ernative.** memo
11560 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 ry allocation su
11570 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 bsystem for SQLi
11580 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c te to use for al
11590 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 l of its.** dyna
115a0 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 mic memory needs
115b0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ..**.** Note tha
115c0 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 t SQLite comes w
115d0 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 ith several [bui
115e0 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c lt-in memory all
115f0 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 ocators].** that
11600 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 are perfectly a
11610 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 dequate for the
11620 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a overwhelming maj
11630 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 ority of applica
11640 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 tions.** and tha
11650 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 t this object is
11660 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 only useful to
11670 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 a tiny minority
11680 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a of applications.
11690 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 ** with speciali
116a0 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 zed memory alloc
116b0 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e ation requiremen
116c0 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 ts. This object
116d0 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 is.** also used
116e0 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 during testing
116f0 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 of SQLite in ord
11700 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e er to specify an
11710 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 alternative.**
11720 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
11730 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 that simulates
11740 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 memory out-of-me
11750 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 mory conditions
11760 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 in.** order to v
11770 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 erify that SQLit
11780 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 e recovers grace
11790 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a fully from such.
117a0 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a ** conditions..*
117b0 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 *.** The xMalloc
117c0 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 , xRealloc, and
117d0 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 xFree methods mu
117e0 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 st work like the
117f0 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 .** malloc(), re
11800 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 alloc() and free
11810 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f () functions fro
11820 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 m the standard C
11830 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 library..** ^SQ
11840 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 Lite guarantees
11850 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 that the second
11860 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 argument to.** x
11870 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 Realloc is alway
11880 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e s a value return
11890 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 ed by a prior ca
118a0 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a ll to xRoundup..
118b0 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 **.** xSize shou
118c0 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c ld return the al
118d0 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 located size of
118e0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 a memory allocat
118f0 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c ion.** previousl
11900 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
11910 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c xMalloc or xReal
11920 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 loc. The alloca
11930 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 ted size.** is a
11940 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 lways at least a
11950 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 s big as the req
11960 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 uested size but
11970 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a may be larger..*
11980 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 *.** The xRoundu
11990 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 p method returns
119a0 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 what would be t
119b0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a he allocated siz
119c0 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 e of.** a memory
119d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 allocation give
119e0 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 n a particular r
119f0 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 equested size.
11a00 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 Most memory.** a
11a10 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 llocators round
11a20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 up memory alloca
11a30 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 tions at least t
11a40 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 o the next multi
11a50 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f ple.** of 8. So
11a60 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f me allocators ro
11a70 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 und up to a larg
11a80 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 er multiple or t
11a90 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a o a power of 2..
11aa0 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 ** Every memory
11ab0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 allocation reque
11ac0 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 st coming in thr
11ad0 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 ough [sqlite3_ma
11ae0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 lloc()].** or [s
11af0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
11b00 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 ] first calls xR
11b10 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 oundup. If xRou
11b20 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 ndup returns 0,
11b30 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 .** that causes
11b40 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
11b50 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 g memory allocat
11b60 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a ion to fail..**.
11b70 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 ** The xInit met
11b80 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 hod initializes
11b90 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 the memory alloc
11ba0 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d 70 ator. For examp
11bb0 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 le,.** it might
11bc0 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 allocate any req
11bd0 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 uire mutexes or
11be0 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 initialize inter
11bf0 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 nal data.** stru
11c00 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 ctures. The xSh
11c10 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 utdown method is
11c20 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 invoked (indire
11c30 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c ctly) by.** [sql
11c40 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d ite3_shutdown()]
11c50 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c and should deal
11c60 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 locate any resou
11c70 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a rces acquired.**
11c80 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 by xInit. The
11c90 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 pAppData pointer
11ca0 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 is used as the
11cb0 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 only parameter t
11cc0 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 o.** xInit and x
11cd0 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 Shutdown..**.**
11ce0 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 SQLite holds the
11cf0 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 [SQLITE_MUTEX_S
11d00 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 TATIC_MASTER] mu
11d10 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f tex when it invo
11d20 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 kes.** the xInit
11d30 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 method, so the
11d40 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 xInit method nee
11d50 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 d not be threads
11d60 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 afe. The.** xSh
11d70 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 utdown method is
11d80 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f only called fro
11d90 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 m [sqlite3_shutd
11da0 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 own()] so it doe
11db0 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f s.** not need to
11dc0 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65 be threadsafe e
11dd0 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 ither. For all
11de0 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 other methods, S
11df0 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 QLite.** holds t
11e00 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 he [SQLITE_MUTEX
11e10 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 _STATIC_MEM] mut
11e20 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 ex as long as th
11e30 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e e.** [SQLITE_CON
11e40 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 FIG_MEMSTATUS] c
11e50 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
11e60 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e ion is turned on
11e70 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 (which.** it is
11e80 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 by default) and
11e90 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 so the methods
11ea0 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c are automaticall
11eb0 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a y serialized..**
11ec0 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 However, if [SQ
11ed0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 LITE_CONFIG_MEMS
11ee0 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c TATUS] is disabl
11ef0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 ed, then the oth
11f00 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 er.** methods mu
11f10 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 st be threadsafe
11f20 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 or else make th
11f30 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d eir own arrangem
11f40 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 ents for.** seri
11f50 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a alization..**.**
11f60 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 SQLite will nev
11f70 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 er invoke xInit(
11f80 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 ) more than once
11f90 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 without an inte
11fa0 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 rvening.** call
11fb0 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a to xShutdown()..
11fc0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
11fd0 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 t sqlite3_mem_me
11fe0 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 thods sqlite3_me
11ff0 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 m_methods;.struc
12000 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 t sqlite3_mem_me
12010 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a thods {. void *
12020 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b (*xMalloc)(int);
12030 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f /* Memo
12040 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 ry allocation fu
12050 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 nction */. void
12060 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 (*xFree)(void*)
12070 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 ; /* Fr
12080 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 ee a prior alloc
12090 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 ation */. void
120a0 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 *(*xRealloc)(voi
120b0 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 d*,int); /* Res
120c0 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f ize an allocatio
120d0 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 n */. int (*xSi
120e0 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 ze)(void*);
120f0 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 /* Return
12100 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 the size of an a
12110 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 llocation */. i
12120 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 nt (*xRoundup)(i
12130 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a nt); /*
12140 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 Round up reques
12150 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 t size to alloca
12160 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 tion size */. i
12170 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 nt (*xInit)(void
12180 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a *); /*
12190 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 Initialize the
121a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
121b0 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 */. void (*xSh
121c0 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 utdown)(void*);
121d0 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 /* Deinitia
121e0 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 lize the memory
121f0 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 allocator */. v
12200 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 oid *pAppData;
12210 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
12220 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e Argument to xIn
12230 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f it() and xShutdo
12240 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a wn() */.};../*.*
12250 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 * CAPI3REF: Conf
12260 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e iguration Option
12270 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b s.** KEYWORDS: {
12280 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
12290 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 tion}.**.** Thes
122a0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 e constants are
122b0 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e the available in
122c0 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 teger configurat
122d0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 ion options that
122e0 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 .** can be passe
122f0 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 d as the first a
12300 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b rgument to the [
12310 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
12320 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a ] interface..**.
12330 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 ** New configura
12340 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 tion options may
12350 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 be added in fut
12360 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 ure releases of
12370 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 SQLite..** Exist
12380 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ing configuratio
12390 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 n options might
123a0 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e be discontinued.
123b0 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a Applications.*
123c0 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 * should check t
123d0 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 he return code f
123e0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e rom [sqlite3_con
123f0 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 fig()] to make s
12400 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 ure that.** the
12410 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 call worked. Th
12420 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 e [sqlite3_confi
12430 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 g()] interface w
12440 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 ill return a.**
12450 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 non-zero [error
12460 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f code] if a disco
12470 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 ntinued or unsup
12480 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 ported configura
12490 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 tion option.** i
124a0 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a s invoked..**.**
124b0 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 <dl>.** [[SQLIT
124c0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
124d0 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 HREAD]] <dt>SQLI
124e0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 TE_CONFIG_SINGLE
124f0 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c THREAD</dt>.** <
12500 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 dd>There are no
12510 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 arguments to thi
12520 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 s option. ^This
12530 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 option sets the
12540 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d .** [threading m
12550 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 ode] to Single-t
12560 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 hread. In other
12570 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 words, it disab
12580 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 les.** all mutex
12590 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c ing and puts SQL
125a0 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 ite into a mode
125b0 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c where it can onl
125c0 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 y be used.** by
125d0 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e a single thread.
125e0 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 ^If SQLite is
125f0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a compiled with.*
12600 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 * the [SQLITE_TH
12610 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 READSAFE | SQLIT
12620 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 E_THREADSAFE=0]
12630 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
12640 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 ion then.** it i
12650 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 s not possible t
12660 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 o change the [th
12670 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 reading mode] fr
12680 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a om its default.*
12690 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c * value of Singl
126a0 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 e-thread and so
126b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
126c0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a )] will return .
126d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ** [SQLITE_ERROR
126e0 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 ] if called with
126f0 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 the SQLITE_CONF
12700 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a IG_SINGLETHREAD.
12710 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ** configuration
12720 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a option.</dd>.**
12730 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
12740 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d FIG_MULTITHREAD]
12750 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
12760 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c FIG_MULTITHREAD<
12770 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 /dt>.** <dd>Ther
12780 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e e are no argumen
12790 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f ts to this optio
127a0 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e n. ^This option
127b0 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 sets the.** [th
127c0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f reading mode] to
127d0 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 Multi-thread.
127e0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 In other words,
127f0 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d it disables.** m
12800 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 utexing on [data
12810 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
12820 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 and [prepared s
12830 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 tatement] object
12840 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 s..** The applic
12850 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 ation is respons
12860 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 ible for seriali
12870 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a zing access to.*
12880 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
12890 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 ections] and [pr
128a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
128b0 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d s]. But other m
128c0 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e utexes.** are en
128d0 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 abled so that SQ
128e0 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 Lite will be saf
128f0 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 e to use in a mu
12900 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 lti-threaded.**
12910 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c environment as l
12920 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 ong as no two th
12930 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f reads attempt to
12940 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a use the same.**
12950 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
12960 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 ction] at the sa
12970 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 me time. ^If SQ
12980 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
12990 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 with.** the [SQ
129a0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 LITE_THREADSAFE
129b0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 | SQLITE_THREADS
129c0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 AFE=0] compile-t
129d0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a ime option then.
129e0 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 ** it is not pos
129f0 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 sible to set the
12a00 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 Multi-thread [t
12a10 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 hreading mode] a
12a20 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 nd.** [sqlite3_c
12a30 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 onfig()] will re
12a40 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 turn [SQLITE_ERR
12a50 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 OR] if called wi
12a60 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 th the.** SQLITE
12a70 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 _CONFIG_MULTITHR
12a80 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f EAD configuratio
12a90 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a n option.</dd>.*
12aa0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
12ab0 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d NFIG_SERIALIZED]
12ac0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
12ad0 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f FIG_SERIALIZED</
12ae0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 dt>.** <dd>There
12af0 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 are no argument
12b00 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e s to this option
12b10 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 . ^This option
12b20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 sets the.** [thr
12b30 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 eading mode] to
12b40 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f Serialized. In o
12b50 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 ther words, this
12b60 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a option enables.
12b70 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 ** all mutexes i
12b80 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 ncluding the rec
12b90 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 ursive.** mutexe
12ba0 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 s on [database c
12bb0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b onnection] and [
12bc0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
12bd0 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 nt] objects..**
12be0 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 In this mode (wh
12bf0 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 ich is the defau
12c00 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 lt when SQLite i
12c10 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a s compiled with.
12c20 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 ** [SQLITE_THREA
12c30 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 DSAFE=1]) the SQ
12c40 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c Lite library wil
12c50 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 l itself seriali
12c60 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 ze access.** to
12c70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
12c80 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 tions] and [prep
12c90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d ared statements]
12ca0 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 so that the.**
12cb0 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 application is f
12cc0 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 ree to use the s
12cd0 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f ame [database co
12ce0 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 nnection] or the
12cf0 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 .** same [prepar
12d00 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e ed statement] in
12d10 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 different threa
12d20 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 ds at the same t
12d30 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 ime..** ^If SQLi
12d40 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
12d50 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 ith.** the [SQLI
12d60 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 TE_THREADSAFE |
12d70 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
12d80 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d E=0] compile-tim
12d90 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a e option then.**
12da0 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 it is not possi
12db0 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 ble to set the S
12dc0 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 erialized [threa
12dd0 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a ding mode] and.*
12de0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
12df0 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e g()] will return
12e00 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
12e10 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 if called with t
12e20 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e he.** SQLITE_CON
12e30 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 FIG_SERIALIZED c
12e40 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
12e50 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ion.</dd>.**.**
12e60 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
12e70 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c MALLOC]] <dt>SQL
12e80 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f ITE_CONFIG_MALLO
12e90 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e C</dt>.** <dd> ^
12ea0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 (The SQLITE_CONF
12eb0 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e IG_MALLOC option
12ec0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
12ed0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 argument which i
12ee0 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 s .** a pointer
12ef0 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f to an instance o
12f00 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
12f10 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 em_methods] stru
12f20 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 cture..** The ar
12f30 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 gument specifies
12f40 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 .** alternative
12f50 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 low-level memory
12f60 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 allocation rout
12f70 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 ines to be used
12f80 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 in place of.** t
12f90 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
12fa0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 tion routines bu
12fb0 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e ilt into SQLite.
12fc0 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 )^ ^SQLite makes
12fd0 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 .** its own priv
12fe0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 ate copy of the
12ff0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b content of the [
13000 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
13010 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a ods] structure.*
13020 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 * before the [sq
13030 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
13040 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 call returns.</d
13050 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
13060 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c E_CONFIG_GETMALL
13070 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f OC]] <dt>SQLITE_
13080 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 CONFIG_GETMALLOC
13090 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 </dt>.** <dd> ^(
130a0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
130b0 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 G_GETMALLOC opti
130c0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
130d0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
130e0 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 .** is a pointer
130f0 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 to an instance
13100 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
13110 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 mem_methods] str
13120 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b ucture..** The [
13130 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
13140 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 ods].** structur
13150 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 e is filled with
13160 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 the currently d
13170 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c efined memory al
13180 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 location routine
13190 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 s.)^.** This opt
131a0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 ion can be used
131b0 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 to overload the
131c0 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 default memory a
131d0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 llocation.** rou
131e0 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 tines with a wra
131f0 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 pper that simula
13200 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c tions memory all
13210 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 ocation failure
13220 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d or.** tracks mem
13230 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 ory usage, for e
13240 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a xample. </dd>.**
13250 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
13260 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 FIG_MEMSTATUS]]
13270 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
13280 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e G_MEMSTATUS</dt>
13290 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 .** <dd> ^The SQ
132a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 LITE_CONFIG_MEMS
132b0 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b TATUS option tak
132c0 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 es single argume
132d0 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a nt of type int,.
132e0 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 ** interpreted a
132f0 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 s a boolean, whi
13300 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 ch enables or di
13310 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 sables the colle
13320 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f ction of.** memo
13330 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 ry allocation st
13340 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e atistics. ^(When
13350 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
13360 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 on statistics ar
13370 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c 20 74 e.** disabled, t
13380 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c he following SQL
13390 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 ite interfaces b
133a0 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 ecome non-operat
133b0 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e ional:.** <ul>
133c0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 .** <li> [sqli
133d0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 te3_memory_used(
133e0 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 )].** <li> [sq
133f0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
13400 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c hwater()].** <
13410 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 li> [sqlite3_sof
13420 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 t_heap_limit64()
13430 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c ].** <li> [sql
13440 69 74 65 33 5f 73 74 61 74 75 73 36 34 28 29 5d ite3_status64()]
13450 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a .** </ul>)^.**
13460 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 ^Memory allocat
13470 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 ion statistics a
13480 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 re enabled by de
13490 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c fault unless SQL
134a0 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c ite is.** compil
134b0 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f ed with [SQLITE_
134c0 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 DEFAULT_MEMSTATU
134d0 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 S]=0 in which ca
134e0 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c se memory.** all
134f0 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 ocation statisti
13500 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 cs are disabled
13510 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c by default..** <
13520 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
13530 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 ITE_CONFIG_SCRAT
13540 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f CH]] <dt>SQLITE_
13550 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f CONFIG_SCRATCH</
13560 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 dt>.** <dd> ^The
13570 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 SQLITE_CONFIG_S
13580 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 73 70 CRATCH option sp
13590 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 ecifies a static
135a0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a memory buffer.*
135b0 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 * that SQLite ca
135c0 6e 20 75 73 65 20 66 6f 72 20 73 63 72 61 74 63 n use for scratc
135d0 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54 68 65 h memory. ^(The
135e0 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 re are three arg
135f0 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53 51 4c uments.** to SQL
13600 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 ITE_CONFIG_SCRAT
13610 43 48 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61 CH: A pointer a
13620 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 n 8-byte.** alig
13630 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 ned memory buffe
13640 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 r from which the
13650 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 scratch allocat
13660 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 ions will be.**
13670 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 drawn, the size
13680 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20 of each scratch
13690 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c allocation (sz),
136a0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 .** and the maxi
136b0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 mum number of sc
136c0 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e ratch allocation
136d0 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65 20 s (N).)^.** The
136e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d first argument m
136f0 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 ust be a pointer
13700 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c to an 8-byte al
13710 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 igned buffer.**
13720 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e of at least sz*N
13730 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 bytes of memory
13740 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c ..** ^SQLite wil
13750 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65 20 74 l not use more t
13760 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20 han one scratch
13770 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65 buffers per thre
13780 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 ad..** ^SQLite w
13790 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 65 73 ill never reques
137a0 74 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66 t a scratch buff
137b0 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 er that is more
137c0 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 than 6.** times
137d0 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 the database pag
137e0 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53 e size..** ^If S
137f0 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 QLite needs need
13800 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 s additional.**
13810 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 scratch memory b
13820 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 eyond what is pr
13830 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63 ovided by this c
13840 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
13850 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 ion, then .** [s
13860 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
13870 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f will be used to
13880 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f obtain the memo
13890 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a ry needed.<p>.**
138a0 20 5e 57 68 65 6e 20 74 68 65 20 61 70 70 6c 69 ^When the appli
138b0 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65 73 20 cation provides
138c0 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20 73 63 any amount of sc
138d0 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 75 73 69 ratch memory usi
138e0 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e ng.** SQLITE_CON
138f0 46 49 47 5f 53 43 52 41 54 43 48 2c 20 53 51 4c FIG_SCRATCH, SQL
13900 69 74 65 20 61 76 6f 69 64 73 20 75 6e 6e 65 63 ite avoids unnec
13910 65 73 73 61 72 79 20 6c 61 72 67 65 0a 2a 2a 20 essary large.**
13920 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c [sqlite3_malloc|
13930 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 heap allocations
13940 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e 20 68 ]..** This can h
13950 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f elp [Robson proo
13960 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f 72 79 f|prevent memory
13970 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c allocation fail
13980 75 72 65 73 5d 20 64 75 65 20 74 6f 20 68 65 61 ures] due to hea
13990 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61 74 69 p.** fragmentati
139a0 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79 on in low-memory
139b0 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d embedded system
139c0 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a s..** </dd>.**.*
139d0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
139e0 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 G_PAGECACHE]] <d
139f0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
13a00 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a PAGECACHE</dt>.*
13a10 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 * <dd> ^The SQLI
13a20 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
13a30 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 CHE option speci
13a40 66 69 65 73 20 61 20 6d 65 6d 6f 72 79 20 70 6f fies a memory po
13a50 6f 6c 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 ol.** that SQLit
13a60 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68 e can use for th
13a70 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 e database page
13a80 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 cache with the d
13a90 65 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 efault page.** c
13aa0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ache implementat
13ab0 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 ion. .** This c
13ac0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
13ad0 69 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f 70 20 69 ion is a no-op i
13ae0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e f an application
13af0 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 -define page.**
13b00 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 cache implementa
13b10 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 tion is loaded u
13b20 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 sing the [SQLITE
13b30 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d _CONFIG_PCACHE2]
13b40 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 ..** ^There are
13b50 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 three arguments
13b60 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 to SQLITE_CONFIG
13b70 5f 50 41 47 45 43 41 43 48 45 3a 20 41 20 70 6f _PAGECACHE: A po
13b80 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 inter to.** 8-by
13b90 74 65 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 te aligned memor
13ba0 79 20 28 70 4d 65 6d 29 2c 20 74 68 65 20 73 69 y (pMem), the si
13bb0 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 ze of each page
13bc0 63 61 63 68 65 20 6c 69 6e 65 20 28 73 7a 29 2c cache line (sz),
13bd0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 .** and the numb
13be0 65 72 20 6f 66 20 63 61 63 68 65 20 6c 69 6e 65 er of cache line
13bf0 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a s (N)..** The sz
13c00 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 argument should
13c10 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 be the size of
13c20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 the largest data
13c30 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 base page.** (a
13c40 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 power of two bet
13c50 77 65 65 6e 20 35 31 32 20 61 6e 64 20 36 35 35 ween 512 and 655
13c60 33 36 29 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 36) plus some ex
13c70 74 72 61 20 62 79 74 65 73 20 66 6f 72 20 65 61 tra bytes for ea
13c80 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 ch.** page heade
13c90 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 r. ^The number
13ca0 6f 66 20 65 78 74 72 61 20 62 79 74 65 73 20 6e of extra bytes n
13cb0 65 65 64 65 64 20 62 79 20 74 68 65 20 70 61 67 eeded by the pag
13cc0 65 20 68 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 e header.** can
13cd0 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 be determined us
13ce0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ing [SQLITE_CONF
13cf0 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d IG_PCACHE_HDRSZ]
13d00 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61 72 6d ..** ^It is harm
13d10 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d less, apart from
13d20 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f the wasted memo
13d30 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 ry,.** for the s
13d40 7a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 z parameter to b
13d50 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 6e 65 e larger than ne
13d60 63 65 73 73 61 72 79 2e 20 20 54 68 65 20 70 4d cessary. The pM
13d70 65 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d em.** argument m
13d80 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 ust be either a
13d90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 NULL pointer or
13da0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
13db0 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 8-byte.** aligne
13dc0 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 d block of memor
13dd0 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a y of at least sz
13de0 2a 4e 20 62 79 74 65 73 2c 20 6f 74 68 65 72 77 *N bytes, otherw
13df0 69 73 65 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e ise.** subsequen
13e00 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e t behavior is un
13e10 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 57 68 65 defined..** ^Whe
13e20 6e 20 70 4d 65 6d 20 69 73 20 6e 6f 74 20 4e 55 n pMem is not NU
13e30 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 LL, SQLite will
13e40 73 74 72 69 76 65 20 74 6f 20 75 73 65 20 74 68 strive to use th
13e50 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 e memory provide
13e60 64 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66 79 20 d.** to satisfy
13e70 70 61 67 65 20 63 61 63 68 65 20 6e 65 65 64 73 page cache needs
13e80 2c 20 66 61 6c 6c 69 6e 67 20 62 61 63 6b 20 74 , falling back t
13e90 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f o [sqlite3_mallo
13ea0 63 28 29 5d 20 69 66 0a 2a 2a 20 61 20 70 61 67 c()] if.** a pag
13eb0 65 20 63 61 63 68 65 20 6c 69 6e 65 20 69 73 20 e cache line is
13ec0 6c 61 72 67 65 72 20 74 68 61 6e 20 73 7a 20 62 larger than sz b
13ed0 79 74 65 73 20 6f 72 20 69 66 20 61 6c 6c 20 6f ytes or if all o
13ee0 66 20 74 68 65 20 70 4d 65 6d 20 62 75 66 66 65 f the pMem buffe
13ef0 72 0a 2a 2a 20 69 73 20 65 78 68 61 75 73 74 65 r.** is exhauste
13f00 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65 6d 20 69 d..** ^If pMem i
13f10 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 s NULL and N is
13f20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 65 non-zero, then e
13f30 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e ach database con
13f40 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 nection.** does
13f50 61 6e 20 69 6e 69 74 69 61 6c 20 62 75 6c 6b 20 an initial bulk
13f60 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 70 allocation for p
13f70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 age cache memory
13f80 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 .** from [sqlite
13f90 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 75 66 66 3_malloc()] suff
13fa0 69 63 69 65 6e 74 20 66 6f 72 20 4e 20 63 61 63 icient for N cac
13fb0 68 65 20 6c 69 6e 65 73 20 69 66 20 4e 20 69 73 he lines if N is
13fc0 20 70 6f 73 69 74 69 76 65 20 6f 72 0a 2a 2a 20 positive or.**
13fd0 6f 66 20 2d 31 30 32 34 2a 4e 20 62 79 74 65 73 of -1024*N bytes
13fe0 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 if N is negativ
13ff0 65 2c 20 2e 20 5e 49 66 20 61 64 64 69 74 69 6f e, . ^If additio
14000 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 nal.** page cach
14010 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 e memory is need
14020 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 ed beyond what i
14030 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 s provided by th
14040 65 20 69 6e 69 74 69 61 6c 0a 2a 2a 20 61 6c 6c e initial.** all
14050 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 53 51 ocation, then SQ
14060 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 Lite goes to [sq
14070 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
14080 73 65 70 61 72 61 74 65 6c 79 20 66 6f 72 20 65 separately for e
14090 61 63 68 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 ach.** additiona
140a0 6c 20 63 61 63 68 65 20 6c 69 6e 65 2e 20 3c 2f l cache line. </
140b0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
140c0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d TE_CONFIG_HEAP]]
140d0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
140e0 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 IG_HEAP</dt>.**
140f0 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 <dd> ^The SQLITE
14100 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 _CONFIG_HEAP opt
14110 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 ion specifies a
14120 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 static memory bu
14130 66 66 65 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 ffer .** that SQ
14140 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 66 6f Lite will use fo
14150 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e r all of its dyn
14160 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f amic memory allo
14170 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 cation needs.**
14180 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f beyond those pro
14190 76 69 64 65 64 20 66 6f 72 20 62 79 20 5b 53 51 vided for by [SQ
141a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 LITE_CONFIG_SCRA
141b0 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c TCH] and.** [SQL
141c0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 ITE_CONFIG_PAGEC
141d0 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 ACHE]..** ^The S
141e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 QLITE_CONFIG_HEA
141f0 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 P option is only
14200 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 available if SQ
14210 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
14220 0a 2a 2a 20 77 69 74 68 20 65 69 74 68 65 72 20 .** with either
14230 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d [SQLITE_ENABLE_M
14240 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49 EMSYS3] or [SQLI
14250 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 TE_ENABLE_MEMSYS
14260 35 5d 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 5] and returns.*
14270 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d * [SQLITE_ERROR]
14280 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65 if invoked othe
14290 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 rwise..** ^There
142a0 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d are three argum
142b0 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 ents to SQLITE_C
142c0 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 ONFIG_HEAP:.** A
142d0 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 n 8-byte aligned
142e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
142f0 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e memory,.** the n
14300 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 umber of bytes i
14310 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 n the memory buf
14320 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e fer, and the min
14330 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 imum allocation
14340 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 size..** ^If the
14350 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 first pointer (
14360 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 the memory point
14370 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 er) is NULL, the
14380 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 n SQLite reverts
14390 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 .** to using its
143a0 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 default memory
143b0 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 allocator (the s
143c0 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 ystem malloc() i
143d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a mplementation),.
143e0 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 ** undoing any p
143f0 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 rior invocation
14400 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 of [SQLITE_CONFI
14410 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 G_MALLOC]. ^If
14420 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f the.** memory po
14430 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c inter is not NUL
14440 4c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 L then the alter
14450 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a native memory.**
14460 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e allocator is en
14470 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 gaged to handle
14480 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d all of SQLites m
14490 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
144a0 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 needs..** The f
144b0 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 irst pointer (th
144c0 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 e memory pointer
144d0 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 ) must be aligne
144e0 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a d to an 8-byte.*
144f0 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 * boundary or su
14500 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f bsequent behavio
14510 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c r of SQLite will
14520 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a be undefined..*
14530 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c * The minimum al
14540 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 location size is
14550 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 capped at 2**12
14560 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c . Reasonable val
14570 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d ues.** for the m
14580 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f inimum allocatio
14590 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 n size are 2**5
145a0 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 through 2**8.</d
145b0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
145c0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d E_CONFIG_MUTEX]]
145d0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
145e0 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a IG_MUTEX</dt>.**
145f0 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 <dd> ^(The SQLI
14600 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 TE_CONFIG_MUTEX
14610 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
14620 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 ingle argument w
14630 68 69 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69 hich is a.** poi
14640 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 nter to an insta
14650 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 nce of the [sqli
14660 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 te3_mutex_method
14670 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a s] structure..**
14680 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 The argument sp
14690 65 63 69 66 69 65 73 20 61 6c 74 65 72 6e 61 74 ecifies alternat
146a0 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 ive low-level mu
146b0 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 tex routines to
146c0 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c be used.** in pl
146d0 61 63 65 20 74 68 65 20 6d 75 74 65 78 20 72 6f ace the mutex ro
146e0 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 utines built int
146f0 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 o SQLite.)^ ^SQ
14700 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 Lite makes a cop
14710 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 y of.** the cont
14720 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 ent of the [sqli
14730 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 te3_mutex_method
14740 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66 s] structure bef
14750 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a ore the call to.
14760 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ** [sqlite3_conf
14770 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e ig()] returns. ^
14780 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
14790 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 piled with.** th
147a0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
147b0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 SAFE | SQLITE_TH
147c0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 READSAFE=0] comp
147d0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
147e0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 then.** the enti
147f0 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 re mutexing subs
14800 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 ystem is omitted
14810 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 from the build
14820 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 and hence calls
14830 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 to.** [sqlite3_c
14840 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 onfig()] with th
14850 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
14860 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 MUTEX configurat
14870 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a ion option will.
14880 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ** return [SQLIT
14890 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a E_ERROR].</dd>.*
148a0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
148b0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 NFIG_GETMUTEX]]
148c0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
148d0 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a G_GETMUTEX</dt>.
148e0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 ** <dd> ^(The SQ
148f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
14900 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 UTEX option take
14910 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
14920 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 ent which.** is
14930 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
14940 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
14950 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d [sqlite3_mutex_m
14960 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 ethods] structur
14970 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 e. The.** [sqli
14980 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 te3_mutex_method
14990 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 s].** structure
149a0 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 is filled with t
149b0 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 he currently def
149c0 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 ined mutex routi
149d0 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f nes.)^.** This o
149e0 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 ption can be use
149f0 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 d to overload th
14a00 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 e default mutex
14a10 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f allocation.** ro
14a20 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 utines with a wr
14a30 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 apper used to tr
14a40 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 ack mutex usage
14a50 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a for performance.
14a60 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 ** profiling or
14a70 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 testing, for exa
14a80 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 mple. ^If SQLi
14a90 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
14aa0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 ith.** the [SQLI
14ab0 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 TE_THREADSAFE |
14ac0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
14ad0 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d E=0] compile-tim
14ae0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a e option then.**
14af0 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 the entire mute
14b00 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 xing subsystem i
14b10 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 s omitted from t
14b20 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e he build and hen
14b30 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b ce calls to.** [
14b40 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
14b50 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 ] with the SQLIT
14b60 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 E_CONFIG_GETMUTE
14b70 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 X configuration
14b80 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 option will.** r
14b90 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 eturn [SQLITE_ER
14ba0 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ROR].</dd>.**.**
14bb0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
14bc0 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 _LOOKASIDE]] <dt
14bd0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c >SQLITE_CONFIG_L
14be0 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a OOKASIDE</dt>.**
14bf0 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 <dd> ^(The SQLI
14c00 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 TE_CONFIG_LOOKAS
14c10 49 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 IDE option takes
14c20 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 two arguments t
14c30 68 61 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a hat determine.**
14c40 20 74 68 65 20 64 65 66 61 75 6c 74 20 73 69 7a the default siz
14c50 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d e of lookaside m
14c60 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b 64 emory on each [d
14c70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
14c80 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 on]..** The firs
14c90 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 t argument is th
14ca0 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 e.** size of eac
14cb0 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 h lookaside buff
14cc0 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 er slot and the
14cd0 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 second is the nu
14ce0 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 mber of.** slots
14cf0 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 allocated to ea
14d00 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ch database conn
14d10 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c ection.)^ ^(SQL
14d20 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 ITE_CONFIG_LOOKA
14d30 53 49 44 45 0a 2a 2a 20 73 65 74 73 20 74 68 65 SIDE.** sets the
14d40 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 <i>default</i>
14d50 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 lookaside size.
14d60 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f The [SQLITE_DBCO
14d70 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a NFIG_LOOKASIDE].
14d80 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71 ** option to [sq
14d90 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
14da0 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 )] can be used t
14db0 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f o change the loo
14dc0 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 kaside.** config
14dd0 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 uration on indiv
14de0 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e idual connection
14df0 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a s.)^ </dd>.**.**
14e00 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
14e10 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 _PCACHE2]] <dt>S
14e20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
14e30 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 CHE2</dt>.** <dd
14e40 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 > ^(The SQLITE_C
14e50 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 ONFIG_PCACHE2 op
14e60 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e tion takes a sin
14e70 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 gle argument whi
14e80 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e ch is .** a poin
14e90 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 ter to an [sqlit
14ea0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 e3_pcache_method
14eb0 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 s2] object. Thi
14ec0 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 s object specifi
14ed0 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72 66 es.** the interf
14ee0 61 63 65 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 ace to a custom
14ef0 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 page cache imple
14f00 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 mentation.)^.**
14f10 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 ^SQLite makes a
14f20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c copy of the [sql
14f30 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 ite3_pcache_meth
14f40 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 ods2] object.</d
14f50 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
14f60 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 E_CONFIG_GETPCAC
14f70 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 HE2]] <dt>SQLITE
14f80 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 _CONFIG_GETPCACH
14f90 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 E2</dt>.** <dd>
14fa0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e ^(The SQLITE_CON
14fb0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 6f FIG_GETPCACHE2 o
14fc0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
14fd0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 ngle argument wh
14fe0 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e ich.** is a poin
14ff0 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 ter to an [sqlit
15000 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 e3_pcache_method
15010 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c s2] object. SQL
15020 69 74 65 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a ite copies of.**
15030 20 74 68 65 20 63 75 72 72 65 6e 74 20 70 61 67 the current pag
15040 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e e cache implemen
15050 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 tation into that
15060 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e object.)^ </dd>
15070 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
15080 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 CONFIG_LOG]] <dt
15090 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c >SQLITE_CONFIG_L
150a0 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 OG</dt>.** <dd>
150b0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
150c0 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 G_LOG option is
150d0 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 used to configur
150e0 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 e the SQLite.**
150f0 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f global [error lo
15100 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c g]..** (^The SQL
15110 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f ITE_CONFIG_LOG o
15120 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 ption takes two
15130 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 arguments: a poi
15140 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e nter to a.** fun
15150 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c ction with a cal
15160 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76 l signature of v
15170 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 oid(*)(void*,int
15180 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a ,const char*), .
15190 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 ** and a pointer
151a0 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 to void. ^If th
151b0 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 e function point
151c0 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 er is not NULL,
151d0 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 it is.** invoked
151e0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 by [sqlite3_log
151f0 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65 ()] to process e
15200 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e ach logging even
15210 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 t. ^If the.** f
15220 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 unction pointer
15230 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 is NULL, the [sq
15240 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 lite3_log()] int
15250 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61 erface becomes a
15260 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 no-op..** ^The
15270 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61 void pointer tha
15280 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 t is the second
15290 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 argument to SQLI
152a0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 TE_CONFIG_LOG is
152b0 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 .** passed throu
152c0 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 gh as the first
152d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
152e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
152f0 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 ined logger.** f
15300 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 unction whenever
15310 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 that function i
15320 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 s invoked. ^The
15330 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
15340 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 r to.** the logg
15350 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 er function is a
15360 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72 copy of the fir
15370 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
15380 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
15390 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f g.** [sqlite3_lo
153a0 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 g()] call and is
153b0 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 intended to be
153c0 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 a [result code]
153d0 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 or an.** [extend
153e0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e ed result code].
153f0 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 ^The third par
15400 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f ameter passed to
15410 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a the logger is.*
15420 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66 * log message af
15430 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 ter formatting v
15440 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 ia [sqlite3_snpr
15450 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 intf()]..** The
15460 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 SQLite logging i
15470 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 nterface is not
15480 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c reentrant; the l
15490 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a ogger function.*
154a0 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 * supplied by th
154b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 e application mu
154c0 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e st not invoke an
154d0 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 y SQLite interfa
154e0 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 ce..** In a mult
154f0 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 i-threaded appli
15500 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c cation, the appl
15510 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
15520 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 logger.** functi
15530 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 on must be threa
15540 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a dsafe. </dd>.**.
15550 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
15560 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c IG_URI]] <dt>SQL
15570 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a ITE_CONFIG_URI.*
15580 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 * <dd>^(The SQLI
15590 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70 TE_CONFIG_URI op
155a0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e tion takes a sin
155b0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 gle argument of
155c0 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 type int..** If
155d0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55 non-zero, then U
155e0 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 RI handling is g
155f0 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e lobally enabled.
15600 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 If the paramete
15610 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 r is zero,.** th
15620 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 en URI handling
15630 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 is globally disa
15640 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 bled.)^ ^If URI
15650 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 handling is glob
15660 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c ally.** enabled,
15670 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70 all filenames p
15680 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 assed to [sqlite
15690 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 3_open()], [sqli
156a0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a te3_open_v2()],.
156b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ** [sqlite3_open
156c0 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 16()] or.** spec
156d0 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 ified as part of
156e0 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e [ATTACH] comman
156f0 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 ds are interpret
15700 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 ed as URIs, rega
15710 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 rdless.** of whe
15720 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 ther or not the
15730 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 [SQLITE_OPEN_URI
15740 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 ] flag is set wh
15750 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a en the database.
15760 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 ** connection is
15770 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 opened. ^If it
15780 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 is globally disa
15790 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 bled, filenames
157a0 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 are.** only inte
157b0 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20 rpreted as URIs
157c0 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 if the SQLITE_OP
157d0 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 EN_URI flag is s
157e0 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 et when the.** d
157f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
15800 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 on is opened. ^(
15810 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 By default, URI
15820 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 handling is glob
15830 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 ally.** disabled
15840 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 . The default va
15850 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 lue may be chang
15860 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 ed by compiling
15870 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c with the.** [SQL
15880 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d ITE_USE_URI] sym
15890 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a bol defined.)^.*
158a0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
158b0 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e NFIG_COVERING_IN
158c0 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 DEX_SCAN]] <dt>S
158d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 QLITE_CONFIG_COV
158e0 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e ERING_INDEX_SCAN
158f0 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c .** <dd>^The SQL
15900 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 ITE_CONFIG_COVER
15910 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f ING_INDEX_SCAN o
15920 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
15930 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 ngle integer.**
15940 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 argument which i
15950 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 s interpreted as
15960 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 a boolean in or
15970 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 der to enable or
15980 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 disable.** the
15990 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 use of covering
159a0 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c indices for full
159b0 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 table scans in
159c0 74 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 the query optimi
159d0 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 zer..** ^The def
159e0 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20 ault setting is
159f0 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 determined.** by
15a00 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c the [SQLITE_ALL
15a10 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 OW_COVERING_INDE
15a20 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d X_SCAN] compile-
15a30 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 time option, or
15a40 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 is "on".** if th
15a50 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 at compile-time
15a60 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 option is omitte
15a70 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 d..** The abilit
15a80 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 y to disable the
15a90 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 use of covering
15aa0 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c indices for ful
15ab0 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a l table scans.**
15ac0 20 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65 is because some
15ad0 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 incorrectly cod
15ae0 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63 ed legacy applic
15af0 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c ations might mal
15b00 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e function.** when
15b10 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f the optimizatio
15b20 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 n is enabled. P
15b30 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 69 roviding the abi
15b40 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 lity to.** disab
15b50 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 le the optimizat
15b60 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f ion allows the o
15b70 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c lder, buggy appl
15b80 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 ication code to
15b90 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 work.** without
15ba0 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68 change even with
15bb0 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 newer versions
15bc0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a of SQLite..**.**
15bd0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
15be0 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 _PCACHE]] [[SQLI
15bf0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 TE_CONFIG_GETPCA
15c00 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c CHE]].** <dt>SQL
15c10 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 ITE_CONFIG_PCACH
15c20 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e E and SQLITE_CON
15c30 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a FIG_GETPCACHE.**
15c40 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 <dd> These opti
15c50 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 ons are obsolete
15c60 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 and should not
15c70 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 be used by new c
15c80 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 ode..** They are
15c90 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 retained for ba
15ca0 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 ckwards compatib
15cb0 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f ility but are no
15cc0 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 w no-ops..** </d
15cd0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
15ce0 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d E_CONFIG_SQLLOG]
15cf0 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f ].** <dt>SQLITE_
15d00 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a CONFIG_SQLLOG.**
15d10 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e <dd>This option
15d20 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 is only availab
15d30 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69 73 20 le if sqlite is
15d40 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 compiled with th
15d50 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 e.** [SQLITE_ENA
15d60 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d BLE_SQLLOG] pre-
15d70 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 processor macro
15d80 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72 defined. The fir
15d90 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 st argument shou
15da0 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 ld.** be a point
15db0 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e er to a function
15dc0 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29 of type void(*)
15dd0 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c (void*,sqlite3*,
15de0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 const char*, int
15df0 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 )..** The second
15e00 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 should be of ty
15e10 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 pe (void*). The
15e20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
15e30 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 61 ked by the libra
15e40 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 ry.** in three s
15e50 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 74 eparate circumst
15e60 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65 ances, identifie
15e70 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 70 d by the value p
15e80 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 assed as the.**
15e90 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
15ea0 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 . If the fourth
15eb0 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20 parameter is 0,
15ec0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 then the databas
15ed0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
15ee0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 passed as the se
15ef0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61 cond argument ha
15f00 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e s just been open
15f10 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 72 ed. The third ar
15f20 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 gument.** points
15f30 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e to a buffer con
15f40 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 taining the name
15f50 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74 of the main dat
15f60 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74 abase file. If t
15f70 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 he.** fourth par
15f80 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 65 ameter is 1, the
15f90 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d n the SQL statem
15fa0 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 69 ent that the thi
15fb0 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 rd parameter.**
15fc0 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 points to has ju
15fd0 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 64 st been executed
15fe0 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75 . Or, if the fou
15ff0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 rth parameter is
16000 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 2, then.** the
16010 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 connection being
16020 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 passed as the s
16030 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
16040 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e is being closed.
16050 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 The.** third pa
16060 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 65 rameter is passe
16070 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 d NULL In this c
16080 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 ase. An example
16090 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a 2a of using this.*
160a0 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 * configuration
160b0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 option can be se
160c0 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74 5f en in the "test_
160d0 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 sqllog.c" source
160e0 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 file in.** the
160f0 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 canonical SQLite
16100 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 source tree.</d
16110 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
16120 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 E_CONFIG_MMAP_SI
16130 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 ZE]].** <dt>SQLI
16140 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 TE_CONFIG_MMAP_S
16150 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 IZE.** <dd>^SQLI
16160 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 TE_CONFIG_MMAP_S
16170 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34 IZE takes two 64
16180 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28 73 71 -bit integer (sq
16190 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c lite3_int64) val
161a0 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 ues.** that are
161b0 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 the default mmap
161c0 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 size limit (the
161d0 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 default setting
161e0 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 for.** [PRAGMA
161f0 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 mmap_size]) and
16200 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f the maximum allo
16210 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 wed mmap size li
16220 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 mit..** ^The def
16230 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e ault setting can
16240 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 be overridden b
16250 79 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 y each database
16260 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 connection using
16270 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b .** either the [
16280 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 PRAGMA mmap_size
16290 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 ] command, or by
162a0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 using the.** [S
162b0 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 QLITE_FCNTL_MMAP
162c0 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 _SIZE] file cont
162d0 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 rol. ^(The maxi
162e0 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 mum allowed mmap
162f0 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 size.** will be
16300 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 silently trunca
16310 74 65 64 20 69 66 20 6e 65 63 65 73 73 61 72 79 ted if necessary
16320 20 73 6f 20 74 68 61 74 20 69 74 20 64 6f 65 73 so that it does
16330 20 6e 6f 74 20 65 78 63 65 65 64 20 74 68 65 0a not exceed the.
16340 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 ** compile-time
16350 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a maximum mmap siz
16360 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 e set by the.**
16370 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 [SQLITE_MAX_MMAP
16380 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 _SIZE] compile-t
16390 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a ime option.)^.**
163a0 20 5e 49 66 20 65 69 74 68 65 72 20 61 72 67 75 ^If either argu
163b0 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74 ment to this opt
163c0 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c ion is negative,
163d0 20 74 68 65 6e 20 74 68 61 74 20 61 72 67 75 6d then that argum
163e0 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 ent is.** change
163f0 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 d to its compile
16400 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a -time default..*
16410 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
16420 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 NFIG_WIN32_HEAPS
16430 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c IZE]].** <dt>SQL
16440 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 ITE_CONFIG_WIN32
16450 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 _HEAPSIZE.** <dd
16460 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e >^The SQLITE_CON
16470 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 FIG_WIN32_HEAPSI
16480 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c ZE option is onl
16490 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 y available if S
164a0 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 QLite is.** comp
164b0 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 iled for Windows
164c0 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 with the [SQLIT
164d0 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 E_WIN32_MALLOC]
164e0 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 pre-processor ma
164f0 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20 cro.** defined.
16500 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 ^SQLITE_CONFIG_W
16510 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74 61 IN32_HEAPSIZE ta
16520 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e 73 kes a 32-bit uns
16530 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76 61 igned integer va
16540 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 lue.** that spec
16550 69 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d 75 ifies the maximu
16560 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63 72 m size of the cr
16570 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a eated heap..**.*
16580 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
16590 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d G_PCACHE_HDRSZ]]
165a0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
165b0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 ONFIG_PCACHE_HDR
165c0 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 SZ.** <dd>^The S
165d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
165e0 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e CHE_HDRSZ option
165f0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
16600 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a parameter which.
16610 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 ** is a pointer
16620 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e to an integer an
16630 64 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74 68 d writes into th
16640 61 74 20 69 6e 74 65 67 65 72 20 74 68 65 20 6e at integer the n
16650 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a 2a umber of extra.*
16660 2a 20 62 79 74 65 73 20 70 65 72 20 70 61 67 65 * bytes per page
16670 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 61 required for ea
16680 63 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c 49 ch page in [SQLI
16690 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
166a0 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f CHE]..** The amo
166b0 75 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70 61 unt of extra spa
166c0 63 65 20 72 65 71 75 69 72 65 64 20 63 61 6e 20 ce required can
166d0 63 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e 67 change depending
166e0 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 on the compiler
166f0 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61 74 ,.** target plat
16700 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65 form, and SQLite
16710 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 version..**.**
16720 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
16730 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 PMASZ]].** <dt>S
16740 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 QLITE_CONFIG_PMA
16750 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 SZ.** <dd>^The S
16760 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 QLITE_CONFIG_PMA
16770 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 SZ option takes
16780 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 a single paramet
16790 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 er which.** is a
167a0 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 n unsigned integ
167b0 65 72 20 61 6e 64 20 73 65 74 73 20 74 68 65 20 er and sets the
167c0 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a "Minimum PMA Siz
167d0 65 22 20 66 6f 72 20 74 68 65 20 6d 75 6c 74 69 e" for the multi
167e0 74 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74 threaded.** sort
167f0 65 72 20 74 6f 20 74 68 61 74 20 69 6e 74 65 67 er to that integ
16800 65 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 er. The default
16810 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a minimum PMA Siz
16820 65 20 69 73 20 73 65 74 20 62 79 20 74 68 65 0a e is set by the.
16830 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45 ** [SQLITE_SORTE
16840 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 R_PMASZ] compile
16850 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e -time option. N
16860 65 77 20 74 68 72 65 61 64 73 20 61 72 65 20 6c ew threads are l
16870 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65 aunched.** to he
16880 6c 70 20 77 69 74 68 20 73 6f 72 74 20 6f 70 65 lp with sort ope
16890 72 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c rations when mul
168a0 74 69 74 68 72 65 61 64 65 64 20 73 6f 72 74 69 tithreaded sorti
168b0 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64 ng.** is enabled
168c0 20 28 75 73 69 6e 67 20 74 68 65 20 5b 50 52 41 (using the [PRA
168d0 47 4d 41 20 74 68 72 65 61 64 73 5d 20 63 6f 6d GMA threads] com
168e0 6d 61 6e 64 29 20 61 6e 64 20 74 68 65 20 61 6d mand) and the am
168f0 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a ount of content.
16900 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 64 20 ** to be sorted
16910 65 78 63 65 65 64 73 20 74 68 65 20 70 61 67 65 exceeds the page
16920 20 73 69 7a 65 20 74 69 6d 65 73 20 74 68 65 20 size times the
16930 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a minimum of the.*
16940 2a 20 5b 50 52 41 47 4d 41 20 63 61 63 68 65 5f * [PRAGMA cache_
16950 73 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 61 6e size] setting an
16960 64 20 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a d this value..**
16970 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
16980 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 FIG_STMTJRNL_SPI
16990 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 LL]].** <dt>SQLI
169a0 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 TE_CONFIG_STMTJR
169b0 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c 64 64 3e NL_SPILL.** <dd>
169c0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 ^The SQLITE_CONF
169d0 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c IG_STMTJRNL_SPIL
169e0 4c 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 L option takes a
169f0 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 single paramete
16a00 72 20 77 68 69 63 68 0a 2a 2a 20 62 65 63 6f 6d r which.** becom
16a10 65 73 20 74 68 65 20 5b 73 74 61 74 65 6d 65 6e es the [statemen
16a20 74 20 6a 6f 75 72 6e 61 6c 5d 20 73 70 69 6c 6c t journal] spill
16a30 2d 74 6f 2d 64 69 73 6b 20 74 68 72 65 73 68 6f -to-disk thresho
16a40 6c 64 2e 20 20 0a 2a 2a 20 5b 53 74 61 74 65 6d ld. .** [Statem
16a50 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d 20 61 72 ent journals] ar
16a60 65 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 e held in memory
16a70 20 75 6e 74 69 6c 20 74 68 65 69 72 20 73 69 7a until their siz
16a80 65 20 28 69 6e 20 62 79 74 65 73 29 0a 2a 2a 20 e (in bytes).**
16a90 65 78 63 65 65 64 73 20 74 68 69 73 20 74 68 72 exceeds this thr
16aa0 65 73 68 6f 6c 64 2c 20 61 74 20 77 68 69 63 68 eshold, at which
16ab0 20 70 6f 69 6e 74 20 74 68 65 79 20 61 72 65 20 point they are
16ac0 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 2e written to disk.
16ad0 0a 2a 2a 20 4f 72 20 69 66 20 74 68 65 20 74 68 .** Or if the th
16ae0 72 65 73 68 6f 6c 64 20 69 73 20 2d 31 2c 20 73 reshold is -1, s
16af0 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c tatement journal
16b00 73 20 61 72 65 20 61 6c 77 61 79 73 20 68 65 6c s are always hel
16b10 64 0a 2a 2a 20 65 78 63 6c 75 73 69 76 65 6c 79 d.** exclusively
16b20 20 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 in memory..** S
16b30 69 6e 63 65 20 6d 61 6e 79 20 73 74 61 74 65 6d ince many statem
16b40 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 6e 65 76 ent journals nev
16b50 65 72 20 62 65 63 6f 6d 65 20 6c 61 72 67 65 2c er become large,
16b60 20 73 65 74 74 69 6e 67 20 74 68 65 20 73 70 69 setting the spi
16b70 6c 6c 0a 2a 2a 20 74 68 72 65 73 68 6f 6c 64 20 ll.** threshold
16b80 74 6f 20 61 20 76 61 6c 75 65 20 73 75 63 68 20 to a value such
16b90 61 73 20 36 34 4b 69 42 20 63 61 6e 20 67 72 65 as 64KiB can gre
16ba0 61 74 6c 79 20 72 65 64 75 63 65 20 74 68 65 20 atly reduce the
16bb0 61 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20 49 2f 4f amount of.** I/O
16bc0 20 72 65 71 75 69 72 65 64 20 74 6f 20 73 75 70 required to sup
16bd0 70 6f 72 74 20 73 74 61 74 65 6d 65 6e 74 20 72 port statement r
16be0 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 ollback..** The
16bf0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f default value fo
16c00 72 20 74 68 69 73 20 73 65 74 74 69 6e 67 20 69 r this setting i
16c10 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 s controlled by
16c20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 the.** [SQLITE_S
16c30 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 20 63 TMTJRNL_SPILL] c
16c40 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
16c50 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a on..** </dl>.*/.
16c60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
16c70 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
16c80 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f AD 1 /* nil */
16c90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
16ca0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 CONFIG_MULTITHRE
16cb0 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a AD 2 /* nil *
16cc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
16cd0 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a _CONFIG_SERIALIZ
16ce0 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 ED 3 /* nil
16cf0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
16d00 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 E_CONFIG_MALLOC
16d10 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 4 /* sql
16d20 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
16d30 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
16d40 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 ITE_CONFIG_GETMA
16d50 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 LLOC 5 /* s
16d60 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
16d70 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ds* */.#define S
16d80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 QLITE_CONFIG_SCR
16d90 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a ATCH 6 /*
16da0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 void*, int sz,
16db0 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 int N */.#define
16dc0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
16dd0 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 AGECACHE 7
16de0 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a /* void*, int sz
16df0 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 , int N */.#defi
16e00 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
16e10 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 _HEAP 8
16e20 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 /* void*, int
16e30 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a nByte, int min *
16e40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
16e50 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 _CONFIG_MEMSTATU
16e60 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c S 9 /* bool
16e70 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ean */.#define S
16e80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 QLITE_CONFIG_MUT
16e90 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a EX 10 /*
16ea0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d sqlite3_mutex_m
16eb0 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 ethods* */.#defi
16ec0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
16ed0 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 _GETMUTEX 11
16ee0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 /* sqlite3_mut
16ef0 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f ex_methods* */./
16f00 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c * previously SQL
16f10 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b ITE_CONFIG_CHUNK
16f20 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 ALLOC 12 which i
16f30 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f s now unused. */
16f40 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .#define SQLITE
16f50 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 _CONFIG_LOOKASID
16f60 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 E 13 /* int
16f70 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 int */.#define S
16f80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
16f90 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a CHE 14 /*
16fa0 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e no-op */.#defin
16fb0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
16fc0 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 GETPCACHE 15
16fd0 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 /* no-op */.#de
16fe0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
16ff0 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 IG_LOG
17000 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 16 /* xFunc, vo
17010 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 id* */.#define S
17020 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 QLITE_CONFIG_URI
17030 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 17 /*
17040 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 int */.#define
17050 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
17060 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f ACHE2 18 /
17070 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 * sqlite3_pcache
17080 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 _methods2* */.#d
17090 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
170a0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 FIG_GETPCACHE2
170b0 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 19 /* sqlite3_
170c0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a pcache_methods2*
170d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
170e0 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 TE_CONFIG_COVERI
170f0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 NG_INDEX_SCAN 20
17100 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 /* int */.#def
17110 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
17120 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 G_SQLLOG 2
17130 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 1 /* xSqllog, v
17140 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 oid* */.#define
17150 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d SQLITE_CONFIG_MM
17160 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f AP_SIZE 22 /
17170 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c * sqlite3_int64,
17180 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a sqlite3_int64 *
17190 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
171a0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 _CONFIG_WIN32_HE
171b0 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20 APSIZE 23
171c0 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a /* int nByte */.
171d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
171e0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 ONFIG_PCACHE_HDR
171f0 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a SZ 24 /*
17200 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 int *psz */.#de
17210 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
17220 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20 IG_PMASZ
17230 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 25 /* un
17240 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 signed int szPma
17250 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
17260 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 TE_CONFIG_STMTJR
17270 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32 36 NL_SPILL 26
17280 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a /* int nByte *
17290 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
172a0 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e F: Database Conn
172b0 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 ection Configura
172c0 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a tion Options.**.
172d0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e ** These constan
172e0 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c ts are the avail
172f0 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e able integer con
17300 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
17310 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 ns that.** can b
17320 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 e passed as the
17330 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
17340 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
17350 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 db_config()] int
17360 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 erface..**.** Ne
17370 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 w configuration
17380 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 options may be a
17390 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 dded in future r
173a0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 eleases of SQLit
173b0 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 e..** Existing c
173c0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
173d0 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 ions might be di
173e0 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 scontinued. App
173f0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f lications.** sho
17400 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 uld check the re
17410 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b turn code from [
17420 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
17430 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 g()] to make sur
17440 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 e that.** the ca
17450 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 ll worked. ^The
17460 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e [sqlite3_db_con
17470 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 fig()] interface
17480 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a will return a.*
17490 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f * non-zero [erro
174a0 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 r code] if a dis
174b0 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 continued or uns
174c0 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 upported configu
174d0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a ration option.**
174e0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a is invoked..**.
174f0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 ** <dl>.** <dt>S
17500 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c QLITE_DBCONFIG_L
17510 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a OOKASIDE</dt>.**
17520 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 <dd> ^This opti
17530 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 on takes three a
17540 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 dditional argume
17550 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 nts that determi
17560 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b ne the .** [look
17570 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c aside memory all
17580 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 ocator] configur
17590 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 ation for the [d
175a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
175b0 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 on]..** ^The fir
175c0 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 st argument (the
175d0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
175e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f to [sqlite3_db_
175f0 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a config()] is a.*
17600 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d * pointer to a m
17610 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 emory buffer to
17620 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 use for lookasid
17630 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 e memory..** ^Th
17640 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
17650 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 after the SQLIT
17660 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 E_DBCONFIG_LOOKA
17670 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 SIDE verb.** may
17680 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 be NULL in whic
17690 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 h case SQLite wi
176a0 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a ll allocate the.
176b0 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 ** lookaside buf
176c0 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 fer itself using
176d0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
176e0 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 ()]. ^The second
176f0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
17700 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 .** size of each
17710 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 lookaside buffe
17720 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 r slot. ^The th
17730 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ird argument is
17740 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a the number of.**
17750 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a slots. The siz
17760 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 e of the buffer
17770 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 in the first arg
17780 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 ument must be gr
17790 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 eater than.** or
177a0 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 equal to the pr
177b0 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 oduct of the sec
177c0 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 ond and third ar
177d0 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 guments. The bu
177e0 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 ffer.** must be
177f0 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d aligned to an 8-
17800 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 byte boundary.
17810 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 ^If the second a
17820 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 rgument to.** SQ
17830 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f LITE_DBCONFIG_LO
17840 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 OKASIDE is not a
17850 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 multiple of 8,
17860 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 it is internally
17870 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e .** rounded down
17880 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 to the next sma
17890 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 ller multiple of
178a0 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 8. ^(The looka
178b0 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 side memory.** c
178c0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 onfiguration for
178d0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a database conn
178e0 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 ection can only
178f0 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 be changed when
17900 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 that.** connecti
17910 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e on is not curren
17920 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 tly using lookas
17930 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 ide memory, or i
17940 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a n other words.**
17950 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 when the "curre
17960 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e nt value" return
17970 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 ed by.** [sqlite
17980 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 3_db_status](D,[
17990 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f SQLITE_CONFIG_LO
179a0 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 OKASIDE],...) is
179b0 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 zero..** Any at
179c0 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 tempt to change
179d0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 the lookaside me
179e0 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 mory configurati
179f0 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 on when lookasid
17a00 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 e.** memory is i
17a10 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 n use leaves the
17a20 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 configuration u
17a30 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 nchanged and ret
17a40 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 urns .** [SQLITE
17a50 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a _BUSY].)^</dd>.*
17a60 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
17a70 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f DBCONFIG_ENABLE_
17a80 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 FKEY</dt>.** <dd
17a90 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 > ^This option i
17aa0 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 s used to enable
17ab0 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 or disable the
17ac0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a enforcement of.*
17ad0 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 * [foreign key c
17ae0 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 onstraints]. Th
17af0 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 ere should be tw
17b00 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 o additional arg
17b10 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 uments..** The f
17b20 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 irst argument is
17b30 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 an integer whic
17b40 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c h is 0 to disabl
17b50 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 e FK enforcement
17b60 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f ,.** positive to
17b70 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 enable FK enfor
17b80 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 cement or negati
17b90 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 ve to leave FK e
17ba0 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e nforcement.** un
17bb0 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 changed. The se
17bc0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 cond parameter i
17bd0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
17be0 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 n integer into w
17bf0 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 hich.** is writt
17c00 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 en 0 or 1 to ind
17c10 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b icate whether FK
17c20 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 enforcement is
17c30 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c off or on.** fol
17c40 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c lowing this call
17c50 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 . The second pa
17c60 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 rameter may be a
17c70 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 NULL pointer, i
17c80 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 n.** which case
17c90 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 the FK enforceme
17ca0 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f nt setting is no
17cb0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e t reported back.
17cc0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 </dd>.**.** <dt
17cd0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 >SQLITE_DBCONFIG
17ce0 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c _ENABLE_TRIGGER<
17cf0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 /dt>.** <dd> ^Th
17d00 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 is option is use
17d10 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 d to enable or d
17d20 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 isable [CREATE T
17d30 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 RIGGER | trigger
17d40 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f s]..** There sho
17d50 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 uld be two addit
17d60 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e ional arguments.
17d70 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 .** The first ar
17d80 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 gument is an int
17d90 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 eger which is 0
17da0 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 to disable trigg
17db0 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 ers,.** positive
17dc0 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 to enable trigg
17dd0 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 ers or negative
17de0 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 to leave the set
17df0 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a ting unchanged..
17e00 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 ** The second pa
17e10 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 rameter is a poi
17e20 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 nter to an integ
17e30 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a er into which.**
17e40 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 is written 0 or
17e50 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 1 to indicate w
17e60 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20 hether triggers
17e70 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 are disabled or
17e80 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f enabled.** follo
17e90 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 wing this call.
17ea0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 The second para
17eb0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e meter may be a N
17ec0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a ULL pointer, in.
17ed0 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 ** which case th
17ee0 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e e trigger settin
17ef0 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 g is not reporte
17f00 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a d back. </dd>.**
17f10 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 .** <dt>SQLITE_D
17f20 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 BCONFIG_ENABLE_F
17f30 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64 TS3_TOKENIZER</d
17f40 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 t>.** <dd> ^This
17f50 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 option is used
17f60 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 to enable or dis
17f70 61 62 6c 65 20 74 68 65 20 74 77 6f 2d 61 72 67 able the two-arg
17f80 75 6d 65 6e 74 0a 2a 2a 20 76 65 72 73 69 6f 6e ument.** version
17f90 20 6f 66 20 74 68 65 20 5b 66 74 73 33 5f 74 6f of the [fts3_to
17fa0 6b 65 6e 69 7a 65 72 28 29 5d 20 66 75 6e 63 74 kenizer()] funct
17fb0 69 6f 6e 20 77 68 69 63 68 20 69 73 20 70 61 72 ion which is par
17fc0 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 46 54 53 t of the.** [FTS
17fd0 33 5d 20 66 75 6c 6c 2d 74 65 78 74 20 73 65 61 3] full-text sea
17fe0 72 63 68 20 65 6e 67 69 6e 65 20 65 78 74 65 6e rch engine exten
17ff0 73 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 73 sion..** There s
18000 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 hould be two add
18010 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 itional argument
18020 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 s..** The first
18030 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 argument is an i
18040 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 nteger which is
18050 30 20 74 6f 20 64 69 73 61 62 6c 65 20 66 74 73 0 to disable fts
18060 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 3_tokenizer() or
18070 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 .** positive to
18080 65 6e 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 enable fts3_toke
18090 6e 69 7a 65 72 28 29 20 6f 72 20 6e 65 67 61 74 nizer() or negat
180a0 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 ive to leave the
180b0 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 setting.** unch
180c0 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 anged..** The se
180d0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 cond parameter i
180e0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
180f0 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 n integer into w
18100 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 hich.** is writt
18110 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 en 0 or 1 to ind
18120 69 63 61 74 65 20 77 68 65 74 68 65 72 20 66 74 icate whether ft
18130 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20 s3_tokenizer is
18140 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 disabled or enab
18150 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 led.** following
18160 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 this call. The
18170 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
18180 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 r may be a NULL
18190 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 pointer, in.** w
181a0 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 65 hich case the ne
181b0 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 w setting is not
181c0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 reported back.
181d0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
181e0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
181f0 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 ENABLE_LOAD_EXTE
18200 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 NSION</dt>.** <d
18210 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 d> ^This option
18220 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c is used to enabl
18230 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 e or disable the
18240 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 [sqlite3_load_e
18250 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 69 xtension()].** i
18260 6e 74 65 72 66 61 63 65 20 69 6e 64 65 70 65 6e nterface indepen
18270 64 65 6e 74 6c 79 20 6f 66 20 74 68 65 20 5b 6c dently of the [l
18280 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d oad_extension()]
18290 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a SQL function..*
182a0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 * The [sqlite3_e
182b0 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e nable_load_exten
182c0 73 69 6f 6e 28 29 5d 20 41 50 49 20 65 6e 61 62 sion()] API enab
182d0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 les or disables
182e0 62 6f 74 68 20 74 68 65 0a 2a 2a 20 43 2d 41 50 both the.** C-AP
182f0 49 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f I [sqlite3_load_
18300 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 61 6e 64 extension()] and
18310 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
18320 6e 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f n [load_extensio
18330 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 n()]..** There s
18340 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 hould be two add
18350 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 itional argument
18360 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 66 s..** When the f
18370 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
18380 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 this interface
18390 69 73 20 31 2c 20 74 68 65 6e 20 6f 6e 6c 79 20 is 1, then only
183a0 74 68 65 20 43 2d 41 50 49 20 69 73 0a 2a 2a 20 the C-API is.**
183b0 65 6e 61 62 6c 65 64 20 61 6e 64 20 74 68 65 20 enabled and the
183c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 6d SQL function rem
183d0 61 69 6e 73 20 64 69 73 61 62 6c 65 64 2e 20 20 ains disabled.
183e0 49 66 20 74 68 65 20 66 69 72 73 74 20 61 72 67 If the first arg
183f0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 69 73 ument to.** this
18400 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 30 2c interface is 0,
18410 20 74 68 65 6e 20 62 6f 74 68 20 74 68 65 20 43 then both the C
18420 2d 41 50 49 20 61 6e 64 20 74 68 65 20 53 51 4c -API and the SQL
18430 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 64 69 function are di
18440 73 61 62 6c 65 64 2e 0a 2a 2a 20 49 66 20 74 68 sabled..** If th
18450 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
18460 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 6e 6f 20 is -1, then no
18470 63 68 61 6e 67 65 73 20 61 72 65 20 6d 61 64 65 changes are made
18480 20 74 6f 20 73 74 61 74 65 20 6f 66 20 65 69 74 to state of eit
18490 68 65 72 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 her the.** C-API
184a0 20 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63 or the SQL func
184b0 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 73 65 63 tion..** The sec
184c0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ond parameter is
184d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
184e0 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 integer into wh
184f0 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 ich.** is writte
18500 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 n 0 or 1 to indi
18510 63 61 74 65 20 77 68 65 74 68 65 72 20 5b 73 71 cate whether [sq
18520 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e lite3_load_exten
18530 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 sion()] interfac
18540 65 0a 2a 2a 20 69 73 20 64 69 73 61 62 6c 65 64 e.** is disabled
18550 20 6f 72 20 65 6e 61 62 6c 65 64 20 66 6f 6c 6c or enabled foll
18560 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e owing this call.
18570 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 The second par
18580 61 6d 65 74 65 72 20 6d 61 79 0a 2a 2a 20 62 65 ameter may.** be
18590 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
185a0 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 in which case t
185b0 68 65 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69 he new setting i
185c0 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 s not reported b
185d0 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a ack..** </dd>.**
185e0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 .** <dt>SQLITE_D
185f0 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41 BCONFIG_MAINDBNA
18600 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 ME</dt>.** <dd>
18610 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 ^This option is
18620 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 used to change t
18630 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 22 he name of the "
18640 6d 61 69 6e 22 20 64 61 74 61 62 61 73 65 0a 2a main" database.*
18650 2a 20 73 63 68 65 6d 61 2e 20 20 5e 54 68 65 20 * schema. ^The
18660 73 6f 6c 65 20 61 72 67 75 6d 65 6e 74 20 69 73 sole argument is
18670 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
18680 63 6f 6e 73 74 61 6e 74 20 55 54 46 38 20 73 74 constant UTF8 st
18690 72 69 6e 67 0a 2a 2a 20 77 68 69 63 68 20 77 69 ring.** which wi
186a0 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 6e 65 ll become the ne
186b0 77 20 73 63 68 65 6d 61 20 6e 61 6d 65 20 69 6e w schema name in
186c0 20 70 6c 61 63 65 20 6f 66 20 22 6d 61 69 6e 22 place of "main"
186d0 2e 20 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 64 6f . ^SQLite.** do
186e0 65 73 20 6e 6f 74 20 6d 61 6b 65 20 61 20 63 6f es not make a co
186f0 70 79 20 6f 66 20 74 68 65 20 6e 65 77 20 6d 61 py of the new ma
18700 69 6e 20 73 63 68 65 6d 61 20 6e 61 6d 65 20 73 in schema name s
18710 74 72 69 6e 67 2c 20 73 6f 20 74 68 65 20 61 70 tring, so the ap
18720 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 plication.** mus
18730 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 t ensure that th
18740 65 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 e argument passe
18750 64 20 69 6e 74 6f 20 74 68 69 73 20 44 42 43 4f d into this DBCO
18760 4e 46 49 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 NFIG option is u
18770 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 75 6e 74 69 nchanged.** unti
18780 6c 20 61 66 74 65 72 20 74 68 65 20 64 61 74 61 l after the data
18790 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
187a0 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c 2f 64 64 3e closes..** </dd>
187b0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
187c0 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b E_DBCONFIG_NO_CK
187d0 50 54 5f 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e PT_ON_CLOSE</dt>
187e0 0a 2a 2a 20 3c 64 64 3e 20 55 73 75 61 6c 6c 79 .** <dd> Usually
187f0 2c 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 , when a databas
18800 65 20 69 6e 20 77 61 6c 20 6d 6f 64 65 20 69 73 e in wal mode is
18810 20 63 6c 6f 73 65 64 20 6f 72 20 64 65 74 61 63 closed or detac
18820 68 65 64 20 66 72 6f 6d 20 61 20 0a 2a 2a 20 64 hed from a .** d
18830 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 2c 20 atabase handle,
18840 53 51 4c 69 74 65 20 63 68 65 63 6b 73 20 69 66 SQLite checks if
18850 20 74 68 69 73 20 77 69 6c 6c 20 6d 65 61 6e 20 this will mean
18860 74 68 61 74 20 74 68 65 72 65 20 61 72 65 20 6e that there are n
18870 6f 77 20 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63 ow no .** connec
18880 74 69 6f 6e 73 20 61 74 20 61 6c 6c 20 74 6f 20 tions at all to
18890 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 49 66 the database. If
188a0 20 73 6f 2c 20 69 74 20 70 65 72 66 6f 72 6d 73 so, it performs
188b0 20 61 20 63 68 65 63 6b 70 6f 69 6e 74 20 0a 2a a checkpoint .*
188c0 2a 20 6f 70 65 72 61 74 69 6f 6e 20 62 65 66 6f * operation befo
188d0 72 65 20 63 6c 6f 73 69 6e 67 20 74 68 65 20 63 re closing the c
188e0 6f 6e 6e 65 63 74 69 6f 6e 2e 20 54 68 69 73 20 onnection. This
188f0 6f 70 74 69 6f 6e 20 6d 61 79 20 62 65 20 75 73 option may be us
18900 65 64 20 74 6f 0a 2a 2a 20 6f 76 65 72 72 69 64 ed to.** overrid
18910 65 20 74 68 69 73 20 62 65 68 61 76 69 6f 75 72 e this behaviour
18920 2e 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 . The first para
18930 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 meter passed to
18940 74 68 69 73 20 6f 70 65 72 61 74 69 6f 6e 0a 2a this operation.*
18950 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 * is an integer
18960 2d 20 6e 6f 6e 2d 7a 65 72 6f 20 74 6f 20 64 69 - non-zero to di
18970 73 61 62 6c 65 20 63 68 65 63 6b 70 6f 69 6e 74 sable checkpoint
18980 73 2d 6f 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a s-on-close, or z
18990 65 72 6f 20 28 74 68 65 0a 2a 2a 20 64 65 66 61 ero (the.** defa
189a0 75 6c 74 29 20 74 6f 20 65 6e 61 62 6c 65 20 74 ult) to enable t
189b0 68 65 6d 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 hem. The second
189c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 parameter is a p
189d0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 ointer to an int
189e0 65 67 65 72 0a 2a 2a 20 69 6e 74 6f 20 77 68 69 eger.** into whi
189f0 63 68 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 ch is written 0
18a00 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 or 1 to indicate
18a10 20 77 68 65 74 68 65 72 20 63 68 65 63 6b 70 6f whether checkpo
18a20 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a ints-on-close.**
18a30 20 68 61 76 65 20 62 65 65 6e 20 64 69 73 61 62 have been disab
18a40 6c 65 64 20 2d 20 30 20 69 66 20 74 68 65 79 20 led - 0 if they
18a50 61 72 65 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 are not disabled
18a60 2c 20 31 20 69 66 20 74 68 65 79 20 61 72 65 2e , 1 if they are.
18a70 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 .** </dd>.**.**
18a80 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 </dl>.*/.#define
18a90 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 SQLITE_DBCONFIG
18aa0 5f 4d 41 49 4e 44 42 4e 41 4d 45 20 20 20 20 20 _MAINDBNAME
18ab0 20 20 20 20 20 20 20 31 30 30 30 20 2f 2a 20 63 1000 /* c
18ac0 6f 6e 73 74 20 63 68 61 72 2a 20 2a 2f 0a 23 64 onst char* */.#d
18ad0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 efine SQLITE_DBC
18ae0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 ONFIG_LOOKASIDE
18af0 20 20 20 20 20 20 20 20 20 20 20 20 31 30 30 31 1001
18b00 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e /* void* int in
18b10 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
18b20 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 ITE_DBCONFIG_ENA
18b30 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 20 20 20 BLE_FKEY
18b40 20 20 20 31 30 30 32 20 2f 2a 20 69 6e 74 20 69 1002 /* int i
18b50 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nt* */.#define S
18b60 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 QLITE_DBCONFIG_E
18b70 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20 20 NABLE_TRIGGER
18b80 20 20 20 20 20 31 30 30 33 20 2f 2a 20 69 6e 74 1003 /* int
18b90 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 int* */.#define
18ba0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 SQLITE_DBCONFIG
18bb0 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b _ENABLE_FTS3_TOK
18bc0 45 4e 49 5a 45 52 20 31 30 30 34 20 2f 2a 20 69 ENIZER 1004 /* i
18bd0 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 nt int* */.#defi
18be0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 ne SQLITE_DBCONF
18bf0 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 IG_ENABLE_LOAD_E
18c00 58 54 45 4e 53 49 4f 4e 20 31 30 30 35 20 2f 2a XTENSION 1005 /*
18c10 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 int int* */.#de
18c20 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f fine SQLITE_DBCO
18c30 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f NFIG_NO_CKPT_ON_
18c40 43 4c 4f 53 45 20 20 20 20 20 20 31 30 30 36 20 CLOSE 1006
18c50 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a /* int int* */..
18c60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
18c70 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 Enable Or Disab
18c80 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 le Extended Resu
18c90 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 lt Codes.** METH
18ca0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a OD: sqlite3.**.*
18cb0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 * ^The sqlite3_e
18cc0 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 xtended_result_c
18cd0 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 odes() routine e
18ce0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c nables or disabl
18cf0 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e es the.** [exten
18d00 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
18d10 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c ] feature of SQL
18d20 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 ite. ^The extend
18d30 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 ed result.** cod
18d40 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 es are disabled
18d50 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 by default for h
18d60 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 istorical compat
18d70 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 ibility..*/.int
18d80 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
18d90 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 _result_codes(sq
18da0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 lite3*, int onof
18db0 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 f);../*.** CAPI3
18dc0 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 REF: Last Insert
18dd0 20 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 Rowid.** METHOD
18de0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
18df0 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d ^Each entry in m
18e00 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65 ost SQLite table
18e10 73 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57 s (except for [W
18e20 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 ITHOUT ROWID] ta
18e30 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 bles).** has a u
18e40 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 nique 64-bit sig
18e50 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b ned.** integer k
18e60 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 ey called the [R
18e70 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e OWID | "rowid"].
18e80 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 ^The rowid is a
18e90 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a lways available.
18ea0 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 ** as an undecla
18eb0 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 red column named
18ec0 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 ROWID, OID, or
18ed0 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 _ROWID_ as long
18ee0 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 as those.** name
18ef0 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 s are not also u
18f00 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c sed by explicitl
18f10 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d y declared colum
18f20 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 ns. ^If.** the t
18f30 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d able has a colum
18f40 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 n of type [INTEG
18f50 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 ER PRIMARY KEY]
18f60 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e then that column
18f70 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 .** is another a
18f80 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 lias for the row
18f90 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 id..**.** ^The s
18fa0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 qlite3_last_inse
18fb0 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65 rt_rowid(D) inte
18fc0 72 66 61 63 65 20 75 73 75 61 6c 6c 79 20 72 65 rface usually re
18fd0 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 turns the [rowid
18fe0 5d 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 ] of.** the most
18ff0 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 recent successf
19000 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f ul [INSERT] into
19010 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f a rowid table o
19020 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 r [virtual table
19030 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 ].** on database
19040 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 5e connection D. ^
19050 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 Inserts into [WI
19060 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 THOUT ROWID] tab
19070 6c 65 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 les are not.** r
19080 65 63 6f 72 64 65 64 2e 20 5e 49 66 20 6e 6f 20 ecorded. ^If no
19090 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 successful [INSE
190a0 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 RT]s into rowid
190b0 74 61 62 6c 65 73 20 68 61 76 65 20 65 76 65 72 tables have ever
190c0 20 6f 63 63 75 72 72 65 64 20 0a 2a 2a 20 6f 6e occurred .** on
190d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
190e0 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 74 68 65 6e nnection D, then
190f0 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e sqlite3_last_in
19100 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65 sert_rowid(D) re
19110 74 75 72 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e 0a turns .** zero..
19120 2a 2a 0a 2a 2a 20 41 73 20 77 65 6c 6c 20 61 73 **.** As well as
19130 20 62 65 69 6e 67 20 73 65 74 20 61 75 74 6f 6d being set autom
19140 61 74 69 63 61 6c 6c 79 20 61 73 20 72 6f 77 73 atically as rows
19150 20 61 72 65 20 69 6e 73 65 72 74 65 64 20 69 6e are inserted in
19160 74 6f 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 to database.** t
19170 61 62 6c 65 73 2c 20 74 68 65 20 76 61 6c 75 65 ables, the value
19180 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 returned by thi
19190 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 s function may b
191a0 65 20 73 65 74 20 65 78 70 6c 69 63 69 74 6c 79 e set explicitly
191b0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f by.** [sqlite3_
191c0 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f set_last_insert_
191d0 72 6f 77 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 rowid()].**.** S
191e0 6f 6d 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c ome virtual tabl
191f0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
19200 73 20 6d 61 79 20 49 4e 53 45 52 54 20 72 6f 77 s may INSERT row
19210 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 s into rowid tab
19220 6c 65 73 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f les as.** part o
19230 66 20 63 6f 6d 6d 69 74 74 69 6e 67 20 61 20 74 f committing a t
19240 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 2e 67 2e ransaction (e.g.
19250 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 61 to flush data a
19260 63 63 75 6d 75 6c 61 74 65 64 20 69 6e 20 6d 65 ccumulated in me
19270 6d 6f 72 79 0a 2a 2a 20 74 6f 20 64 69 73 6b 29 mory.** to disk)
19280 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 20 73 . In this case s
19290 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 ubsequent calls
192a0 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e to this function
192b0 20 72 65 74 75 72 6e 20 74 68 65 20 72 6f 77 69 return the rowi
192c0 64 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 d.** associated
192d0 77 69 74 68 20 74 68 65 73 65 20 69 6e 74 65 72 with these inter
192e0 6e 61 6c 20 49 4e 53 45 52 54 20 6f 70 65 72 61 nal INSERT opera
192f0 74 69 6f 6e 73 2c 20 77 68 69 63 68 20 6c 65 61 tions, which lea
19300 64 73 20 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74 75 ds to .** unintu
19310 69 74 69 76 65 20 72 65 73 75 6c 74 73 2e 20 56 itive results. V
19320 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 irtual table imp
19330 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 68 61 lementations tha
19340 74 20 64 6f 20 77 72 69 74 65 20 74 6f 20 72 6f t do write to ro
19350 77 69 64 0a 2a 2a 20 74 61 62 6c 65 73 20 69 6e wid.** tables in
19360 20 74 68 69 73 20 77 61 79 20 63 61 6e 20 61 76 this way can av
19370 6f 69 64 20 74 68 69 73 20 70 72 6f 62 6c 65 6d oid this problem
19380 20 62 79 20 72 65 73 74 6f 72 69 6e 67 20 74 68 by restoring th
19390 65 20 6f 72 69 67 69 6e 61 6c 20 0a 2a 2a 20 72 e original .** r
193a0 6f 77 69 64 20 76 61 6c 75 65 20 75 73 69 6e 67 owid value using
193b0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 [sqlite3_set_la
193c0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 st_insert_rowid(
193d0 29 5d 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e )] before return
193e0 69 6e 67 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 ing .** control
193f0 74 6f 20 74 68 65 20 75 73 65 72 2e 0a 2a 2a 0a to the user..**.
19400 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 ** ^(If an [INSE
19410 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 RT] occurs withi
19420 6e 20 61 20 74 72 69 67 67 65 72 20 74 68 65 6e n a trigger then
19430 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 this routine wi
19440 6c 6c 20 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 ll .** return th
19450 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 e [rowid] of the
19460 20 69 6e 73 65 72 74 65 64 20 72 6f 77 20 61 73 inserted row as
19470 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 long as the tri
19480 67 67 65 72 20 69 73 20 0a 2a 2a 20 72 75 6e 6e gger is .** runn
19490 69 6e 67 2e 20 4f 6e 63 65 20 74 68 65 20 74 72 ing. Once the tr
194a0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65 6e igger program en
194b0 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 ds, the value re
194c0 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 turned .** by th
194d0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 is routine rever
194e0 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 ts to what it wa
194f0 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 s before the tri
19500 67 67 65 72 20 77 61 73 20 66 69 72 65 64 2e 29 gger was fired.)
19510 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 ^.**.** ^An [INS
19520 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 ERT] that fails
19530 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 due to a constra
19540 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 int violation is
19550 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 not a.** succes
19560 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e sful [INSERT] an
19570 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 d does not chang
19580 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 e the value retu
19590 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 rned by this.**
195a0 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 routine. ^Thus
195b0 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 INSERT OR FAIL,
195c0 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 INSERT OR IGNORE
195d0 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c , INSERT OR ROLL
195e0 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 BACK,.** and INS
195f0 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b ERT OR ABORT mak
19600 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 e no changes to
19610 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
19620 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 of this.** rout
19630 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 ine when their i
19640 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 nsertion fails.
19650 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f ^(When INSERT O
19660 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 R REPLACE.** enc
19670 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 ounters a constr
19680 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 aint violation,
19690 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c it does not fail
196a0 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 . The.** INSERT
196b0 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f continues to co
196c0 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 mpletion after d
196d0 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 eleting rows tha
196e0 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 t caused.** the
196f0 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c constraint probl
19700 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 em so INSERT OR
19710 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 REPLACE will alw
19720 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 ays change.** th
19730 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f e return value o
19740 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 f this interface
19750 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 .)^.**.** ^For t
19760 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 he purposes of t
19770 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 his routine, an
19780 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 [INSERT] is cons
19790 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 idered to.** be
197a0 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 successful even
197b0 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 if it is subsequ
197c0 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 ently rolled bac
197d0 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 k..**.** This fu
197e0 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 nction is access
197f0 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 ible to SQL stat
19800 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a ements via the.*
19810 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 * [last_insert_r
19820 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 owid() SQL funct
19830 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 ion]..**.** If a
19840 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 separate thread
19850 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 performs a new
19860 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 [INSERT] on the
19870 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 same.** database
19880 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c connection whil
19890 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c e the [sqlite3_l
198a0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 ast_insert_rowid
198b0 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ()].** function
198c0 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 is running and t
198d0 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 hus changes the
198e0 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 last insert [row
198f0 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 id],.** then the
19900 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
19910 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 by [sqlite3_last
19920 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d _insert_rowid()]
19930 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 is.** unpredict
19940 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e able and might n
19950 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 ot equal either
19960 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e the old or the n
19970 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 ew.** last inser
19980 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 t [rowid]..*/.sq
19990 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 lite3_int64 sqli
199a0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f te3_last_insert_
199b0 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b rowid(sqlite3*);
199c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
199d0 3a 20 53 65 74 20 74 68 65 20 4c 61 73 74 20 49 : Set the Last I
199e0 6e 73 65 72 74 20 52 6f 77 69 64 20 76 61 6c 75 nsert Rowid valu
199f0 65 2e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 e..** METHOD: sq
19a00 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 lite3.**.** The
19a10 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 sqlite3_set_last
19a20 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 2c _insert_rowid(D,
19a30 20 52 29 20 6d 65 74 68 6f 64 20 61 6c 6c 6f 77 R) method allow
19a40 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f s the applicatio
19a50 6e 20 74 6f 0a 2a 2a 20 73 65 74 20 74 68 65 20 n to.** set the
19a60 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
19a70 79 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 y calling sqlite
19a80 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 3_last_insert_ro
19a90 77 69 64 28 44 29 20 74 6f 20 52 20 0a 2a 2a 20 wid(D) to R .**
19aa0 77 69 74 68 6f 75 74 20 69 6e 73 65 72 74 69 6e without insertin
19ab0 67 20 61 20 72 6f 77 20 69 6e 74 6f 20 74 68 65 g a row into the
19ac0 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 76 6f database..*/.vo
19ad0 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c id sqlite3_set_l
19ae0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 ast_insert_rowid
19af0 28 73 71 6c 69 74 65 33 2a 2c 73 71 6c 69 74 65 (sqlite3*,sqlite
19b00 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 3_int64);../*.**
19b10 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 CAPI3REF: Count
19b20 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 The Number Of R
19b30 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 ows Modified.**
19b40 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
19b50 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 **.** ^This func
19b60 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 tion returns the
19b70 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 number of rows
19b80 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74 modified, insert
19b90 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 ed or.** deleted
19ba0 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 by the most rec
19bb0 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 ently completed
19bc0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f INSERT, UPDATE o
19bd0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 r DELETE.** stat
19be0 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 ement on the dat
19bf0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
19c00 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 specified by th
19c10 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 e only parameter
19c20 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 ..** ^Executing
19c30 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f any other type o
19c40 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 f SQL statement
19c50 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 does not modify
19c60 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 the value.** ret
19c70 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 urned by this fu
19c80 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f nction..**.** ^O
19c90 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 nly changes made
19ca0 20 64 69 72 65 63 74 6c 79 20 62 79 20 74 68 65 directly by the
19cb0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 INSERT, UPDATE
19cc0 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d or DELETE statem
19cd0 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 ent are.** consi
19ce0 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61 72 dered - auxiliar
19cf0 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 y changes caused
19d00 20 62 79 20 5b 43 52 45 41 54 45 20 54 52 49 47 by [CREATE TRIG
19d10 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2c GER | triggers],
19d20 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 .** [foreign ke
19d30 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 y actions] or [R
19d40 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 EPLACE] constrai
19d50 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 nt resolution ar
19d60 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a e not counted..*
19d70 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f * .** Changes to
19d80 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65 a view that are
19d90 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 intercepted by
19da0 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 .** [INSTEAD OF
19db0 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45 41 trigger | INSTEA
19dc0 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20 61 D OF triggers] a
19dd0 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 re not counted.
19de0 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 ^The value .** r
19df0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
19e00 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d 6d e3_changes() imm
19e10 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 20 61 ediately after a
19e20 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 n INSERT, UPDATE
19e30 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 or .** DELETE s
19e40 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 tatement run on
19e50 61 20 76 69 65 77 20 69 73 20 61 6c 77 61 79 73 a view is always
19e60 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e zero. Only chan
19e70 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61 6c ges made to real
19e80 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65 20 .** tables are
19e90 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 counted..**.** T
19ea0 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20 63 hings are more c
19eb0 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74 68 omplicated if th
19ec0 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 e sqlite3_change
19ed0 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a s() function is.
19ee0 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68 69 6c ** executed whil
19ef0 65 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 e a trigger prog
19f00 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 ram is running.
19f10 54 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e 20 This may happen
19f20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 if the.** progra
19f30 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68 61 6e m uses the [chan
19f40 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 ges() SQL functi
19f50 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 on], or if some
19f60 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a other callback.*
19f70 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b * function invok
19f80 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 es sqlite3_chang
19f90 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20 45 es() directly. E
19fa0 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a ssentially:.** .
19fb0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 ** <ul>.** <li
19fc0 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65 72 > ^(Before enter
19fd0 69 6e 67 20 61 20 74 72 69 67 67 65 72 20 70 72 ing a trigger pr
19fe0 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65 20 ogram the value
19ff0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 returned by.**
1a000 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 68 sqlite3_ch
1a010 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e anges() function
1a020 20 69 73 20 73 61 76 65 64 2e 20 41 66 74 65 72 is saved. After
1a030 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72 6f the trigger pro
1a040 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 gram .**
1a050 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74 68 has finished, th
1a060 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 e original value
1a070 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a is restored.)^.
1a080 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 ** .** <li> ^(
1a090 57 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 Within a trigger
1a0a0 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49 4e program each IN
1a0b0 53 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64 SERT, UPDATE and
1a0c0 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 DELETE .**
1a0d0 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65 74 statement set
1a0e0 73 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 s the value retu
1a0f0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
1a100 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 changes() .**
1a110 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 upon comple
1a120 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 tion as normal.
1a130 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73 20 Of course, this
1a140 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 value will not i
1a150 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 nclude .**
1a160 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70 65 any changes pe
1a170 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d 74 rformed by sub-t
1a180 72 69 67 67 65 72 73 2c 20 61 73 20 74 68 65 20 riggers, as the
1a190 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
1a1a0 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61 6c ) .** val
1a1b0 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65 64 ue will be saved
1a1c0 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61 66 and restored af
1a1d0 74 65 72 20 65 61 63 68 20 73 75 62 2d 74 72 69 ter each sub-tri
1a1e0 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a gger has run.)^.
1a1f0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 ** </ul>.** .**
1a200 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 ^This means that
1a210 20 69 66 20 74 68 65 20 63 68 61 6e 67 65 73 28 if the changes(
1a220 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 ) SQL function (
1a230 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20 75 or similar) is u
1a240 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 sed.** by the fi
1a250 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 rst INSERT, UPDA
1a260 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 TE or DELETE sta
1a270 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 tement within a
1a280 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 trigger, it .**
1a290 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 returns the valu
1a2a0 65 20 61 73 20 73 65 74 20 77 68 65 6e 20 74 68 e as set when th
1a2b0 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d e calling statem
1a2c0 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75 74 ent began execut
1a2d0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 ing..** ^If it i
1a2e0 73 20 75 73 65 64 20 62 79 20 74 68 65 20 73 65 s used by the se
1a2f0 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75 65 cond or subseque
1a300 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d 65 6e nt such statemen
1a310 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 t within a trigg
1a320 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 er .** program,
1a330 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
1a340 65 64 20 72 65 66 6c 65 63 74 73 20 74 68 65 20 ed reflects the
1a350 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d number of rows m
1a360 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20 0a odified by the .
1a370 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53 45 ** previous INSE
1a380 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 RT, UPDATE or DE
1a390 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 LETE statement w
1a3a0 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74 ithin the same t
1a3b0 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 rigger..**.** Se
1a3c0 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 e also the [sqli
1a3d0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
1a3e0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 s()] interface,
1a3f0 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 the.** [count_ch
1a400 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 anges pragma], a
1a410 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 nd the [changes(
1a420 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e ) SQL function].
1a430 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 .**.** If a sepa
1a440 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 rate thread make
1a450 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 s changes on the
1a460 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 same database c
1a470 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 onnection.** whi
1a480 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e le [sqlite3_chan
1a490 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e ges()] is runnin
1a4a0 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 g then the value
1a4b0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 returned.** is
1a4c0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e unpredictable an
1a4d0 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c d not meaningful
1a4e0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
1a4f0 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 _changes(sqlite3
1a500 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
1a510 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 REF: Total Numbe
1a520 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 r Of Rows Modifi
1a530 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 ed.** METHOD: sq
1a540 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 lite3.**.** ^Thi
1a550 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 s function retur
1a560 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d ns the total num
1a570 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 ber of rows inse
1a580 72 74 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f rted, modified o
1a590 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 r.** deleted by
1a5a0 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 all [INSERT], [U
1a5b0 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 PDATE] or [DELET
1a5c0 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f E] statements co
1a5d0 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 mpleted.** since
1a5e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
1a5f0 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 nnection was ope
1a600 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 ned, including t
1a610 68 6f 73 65 20 65 78 65 63 75 74 65 64 20 61 73 hose executed as
1a620 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67 .** part of trig
1a630 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 ger programs. ^E
1a640 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 xecuting any oth
1a650 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 er type of SQL s
1a660 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 tatement.** does
1a670 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 20 not affect the
1a680 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
1a690 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f y sqlite3_total_
1a6a0 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a changes()..** .*
1a6b0 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20 * ^Changes made
1a6c0 61 73 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 as part of [fore
1a6d0 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d ign key actions]
1a6e0 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e are included in
1a6f0 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 the.** count, b
1a700 75 74 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73 ut those made as
1a710 20 70 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45 part of REPLACE
1a720 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f constraint reso
1a730 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f lution are.** no
1a740 74 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 t. ^Changes to a
1a750 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 view that are i
1a760 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 49 4e ntercepted by IN
1a770 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 STEAD OF trigger
1a780 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f s .** are not co
1a790 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 unted..** .** Se
1a7a0 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 e also the [sqli
1a7b0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 te3_changes()] i
1a7c0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a nterface, the.**
1a7d0 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 [count_changes
1a7e0 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 pragma], and the
1a7f0 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 [total_changes(
1a800 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e ) SQL function].
1a810 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 .**.** If a sepa
1a820 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 rate thread make
1a830 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 s changes on the
1a840 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 same database c
1a850 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 onnection.** whi
1a860 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 le [sqlite3_tota
1a870 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 l_changes()] is
1a880 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 running then the
1a890 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e value.** return
1a8a0 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 ed is unpredicta
1a8b0 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e ble and not mean
1a8c0 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 ingful..*/.int s
1a8d0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 qlite3_total_cha
1a8e0 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a nges(sqlite3*);.
1a8f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1a900 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e Interrupt A Lon
1a910 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a g-Running Query.
1a920 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
1a930 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 e3.**.** ^This f
1a940 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 unction causes a
1a950 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 ny pending datab
1a960 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f ase operation to
1a970 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 abort and.** re
1a980 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c turn at its earl
1a990 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 iest opportunity
1a9a0 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 . This routine i
1a9b0 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 s typically.** c
1a9c0 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 alled in respons
1a9d0 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 e to a user acti
1a9e0 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73 on such as press
1a9f0 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 ing "Cancel".**
1aa00 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 or Ctrl-C where
1aa10 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 the user wants a
1aa20 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 long query oper
1aa30 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a ation to halt.**
1aa40 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a immediately..**
1aa50 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 .** ^It is safe
1aa60 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 to call this rou
1aa70 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 tine from a thre
1aa80 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f ad different fro
1aa90 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 m the.** thread
1aaa0 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c that is currentl
1aab0 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 y running the da
1aac0 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e tabase operation
1aad0 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 . But it.** is
1aae0 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c not safe to call
1aaf0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 this routine wi
1ab00 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 th a [database c
1ab10 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a onnection] that.
1ab20 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 ** is closed or
1ab30 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f might close befo
1ab40 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 re sqlite3_inter
1ab50 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a rupt() returns..
1ab60 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c **.** ^If an SQL
1ab70 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 operation is ve
1ab80 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 ry nearly finish
1ab90 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 ed at the time w
1aba0 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 hen.** sqlite3_i
1abb0 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61 nterrupt() is ca
1abc0 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 lled, then it mi
1abd0 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 ght not have an
1abe0 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 opportunity.** t
1abf0 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 o be interrupted
1ac00 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 and might conti
1ac10 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f nue to completio
1ac20 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c n..**.** ^An SQL
1ac30 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 operation that
1ac40 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 is interrupted w
1ac50 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 ill return [SQLI
1ac60 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a TE_INTERRUPT]..*
1ac70 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 * ^If the interr
1ac80 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 upted SQL operat
1ac90 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 ion is an INSERT
1aca0 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c , UPDATE, or DEL
1acb0 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 ETE.** that is i
1acc0 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 nside an explici
1acd0 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 t transaction, t
1ace0 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 hen the entire t
1acf0 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 ransaction.** wi
1ad00 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 ll be rolled bac
1ad10 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e k automatically.
1ad20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
1ad30 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 te3_interrupt(D)
1ad40 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 call is in effe
1ad50 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 ct until all cur
1ad60 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a rently running.*
1ad70 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 * SQL statements
1ad80 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f on [database co
1ad90 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 nnection] D comp
1ada0 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 lete. ^Any new
1adb0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a SQL statements.*
1adc0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 * that are start
1add0 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c ed after the sql
1ade0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
1adf0 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 call and before
1ae00 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 the .** running
1ae10 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 statements reac
1ae20 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 hes zero are int
1ae30 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74 errupted as if t
1ae40 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 hey had been.**
1ae50 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f running prior to
1ae60 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 the sqlite3_int
1ae70 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 errupt() call.
1ae80 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 ^New SQL stateme
1ae90 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 nts.** that are
1aea0 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 started after th
1aeb0 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d e running statem
1aec0 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 ent count reache
1aed0 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f s zero are.** no
1aee0 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68 t effected by th
1aef0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 e sqlite3_interr
1af00 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c upt()..** ^A cal
1af10 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 l to sqlite3_int
1af20 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f errupt(D) that o
1af30 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 ccurs when there
1af40 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a are no running.
1af50 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
1af60 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 s is a no-op and
1af70 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f has no effect o
1af80 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 n SQL statements
1af90 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 .** that are sta
1afa0 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 rted after the s
1afb0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
1afc0 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e () call returns.
1afd0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 .**.** If the da
1afe0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1aff0 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b n closes while [
1b000 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
1b010 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 t()].** is runni
1b020 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e ng then bad thin
1b030 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 gs will likely h
1b040 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 appen..*/.void s
1b050 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
1b060 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
1b070 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 ** CAPI3REF: Det
1b080 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c ermine If An SQL
1b090 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f Statement Is Co
1b0a0 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 mplete.**.** The
1b0b0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
1b0c0 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f useful during co
1b0d0 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 mmand-line input
1b0e0 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 to determine if
1b0f0 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c the.** currentl
1b100 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 y entered text s
1b110 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 eems to form a c
1b120 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 omplete SQL stat
1b130 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 ement or.** if a
1b140 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 dditional input
1b150 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 is needed before
1b160 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 sending the tex
1b170 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 t into.** SQLite
1b180 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e for parsing. ^
1b190 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
1b1a0 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 eturn 1 if the i
1b1b0 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 nput string.** a
1b1c0 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 ppears to be a c
1b1d0 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 omplete SQL stat
1b1e0 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 ement. ^A state
1b1f0 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 ment is judged t
1b200 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 o be.** complete
1b210 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 if it ends with
1b220 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b a semicolon tok
1b230 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 en and is not a
1b240 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 prefix of a.** w
1b250 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 ell-formed CREAT
1b260 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d E TRIGGER statem
1b270 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e ent. ^Semicolon
1b280 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 s that are embed
1b290 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 ded within.** st
1b2a0 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 ring literals or
1b2b0 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 quoted identifi
1b2c0 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d er names or comm
1b2d0 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 ents are not.**
1b2e0 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 independent toke
1b2f0 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 ns (they are par
1b300 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 t of the token i
1b310 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 n which they are
1b320 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e .** embedded) an
1b330 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f d thus do not co
1b340 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 unt as a stateme
1b350 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 nt terminator.
1b360 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 ^Whitespace.** a
1b370 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 nd comments that
1b380 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 follow the fina
1b390 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 l semicolon are
1b3a0 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e ignored..**.** ^
1b3b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
1b3c0 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 eturn 0 if the s
1b3d0 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f tatement is inco
1b3e0 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a mplete. ^If a.*
1b3f0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * memory allocat
1b400 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 ion fails, then
1b410 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 SQLITE_NOMEM is
1b420 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
1b430 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
1b440 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 do not parse the
1b450 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
1b460 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 thus.** will not
1b470 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 detect syntacti
1b480 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 cally incorrect
1b490 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 SQL..**.** ^(If
1b4a0 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 SQLite has not b
1b4b0 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 een initialized
1b4c0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 using [sqlite3_i
1b4d0 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 nitialize()] pri
1b4e0 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 or .** to invoki
1b4f0 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c ng sqlite3_compl
1b500 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c ete16() then sql
1b510 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
1b520 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 ) is invoked.**
1b530 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 automatically by
1b540 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 sqlite3_complet
1b550 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 e16(). If that
1b560 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 initialization f
1b570 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 ails,.** then th
1b580 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 e return value f
1b590 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 rom sqlite3_comp
1b5a0 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 lete16() will be
1b5b0 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 non-zero.** reg
1b5c0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 ardless of wheth
1b5d0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e er or not the in
1b5e0 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c put SQL is compl
1b5f0 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 ete.)^.**.** The
1b600 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 input to [sqlit
1b610 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d e3_complete()] m
1b620 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 ust be a zero-te
1b630 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d rminated.** UTF-
1b640 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 8 string..**.**
1b650 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 The input to [sq
1b660 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 lite3_complete16
1b670 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 ()] must be a ze
1b680 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ro-terminated.**
1b690 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 UTF-16 string i
1b6a0 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 n native byte or
1b6b0 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 der..*/.int sqli
1b6c0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e te3_complete(con
1b6d0 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 st char *sql);.i
1b6e0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c nt sqlite3_compl
1b6f0 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 ete16(const void
1b700 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 *sql);../*.** C
1b710 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 API3REF: Registe
1b720 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 r A Callback To
1b730 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 Handle SQLITE_BU
1b740 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 SY Errors.** KEY
1b750 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e WORDS: {busy-han
1b760 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b dler callback} {
1b770 62 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a busy handler}.**
1b780 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
1b790 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
1b7a0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 te3_busy_handler
1b7b0 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 (D,X,P) routine
1b7c0 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 sets a callback
1b7d0 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 function X.** th
1b7e0 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f at might be invo
1b7f0 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e ked with argumen
1b800 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 t P whenever.**
1b810 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 an attempt is ma
1b820 64 65 20 74 6f 20 61 63 63 65 73 73 20 61 20 64 de to access a d
1b830 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 73 atabase table as
1b840 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a sociated with.**
1b850 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
1b860 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e ction] D when an
1b870 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 other thread.**
1b880 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 74 or process has t
1b890 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e he table locked.
1b8a0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
1b8b0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 busy_handler() i
1b8c0 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 nterface is used
1b8d0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a to implement.**
1b8e0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 [sqlite3_busy_t
1b8f0 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 imeout()] and [P
1b900 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f RAGMA busy_timeo
1b910 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ut]..**.** ^If t
1b920 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b he busy callback
1b930 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b is NULL, then [
1b940 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 SQLITE_BUSY].**
1b950 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 is returned imme
1b960 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 diately upon enc
1b970 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f ountering the lo
1b980 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 ck. ^If the bus
1b990 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 y callback.** is
1b9a0 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 not NULL, then
1b9b0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 the callback mig
1b9c0 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 ht be invoked wi
1b9d0 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 th two arguments
1b9e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 ..**.** ^The fir
1b9f0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 st argument to t
1ba00 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 he busy handler
1ba10 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 is a copy of the
1ba20 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 void* pointer w
1ba30 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 hich.** is the t
1ba40 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f hird argument to
1ba50 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 sqlite3_busy_ha
1ba60 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 ndler(). ^The s
1ba70 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 econd argument t
1ba80 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 o.** the busy ha
1ba90 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 ndler callback i
1baa0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
1bab0 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 times that the b
1bac0 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a usy handler has.
1bad0 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 ** been invoked
1bae0 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 previously for t
1baf0 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 he same locking
1bb00 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a event. ^If the.
1bb10 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b ** busy callback
1bb20 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e returns 0, then
1bb30 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 no additional a
1bb40 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 ttempts are made
1bb50 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 to.** access th
1bb60 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b e database and [
1bb70 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 SQLITE_BUSY] is
1bb80 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 returned.** to t
1bb90 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a he application..
1bba0 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 ** ^If the callb
1bbb0 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d ack returns non-
1bbc0 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 zero, then anoth
1bbd0 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 er attempt.** is
1bbe0 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 made to access
1bbf0 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 the database and
1bc00 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 the cycle repea
1bc10 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 ts..**.** The pr
1bc20 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 esence of a busy
1bc30 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f handler does no
1bc40 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 t guarantee that
1bc50 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f it will be invo
1bc60 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 ked.** when ther
1bc70 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e e is lock conten
1bc80 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 tion. ^If SQLite
1bc90 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 determines that
1bca0 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 invoking the bu
1bcb0 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f sy.** handler co
1bcc0 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 uld result in a
1bcd0 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c deadlock, it wil
1bce0 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 l go ahead and r
1bcf0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 eturn [SQLITE_BU
1bd00 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 SY].** to the ap
1bd10 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 plication instea
1bd20 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 d of invoking th
1bd30 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c e .** busy handl
1bd40 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 er..** Consider
1bd50 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 a scenario where
1bd60 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 one process is
1bd70 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c holding a read l
1bd80 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 ock that.** it i
1bd90 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d s trying to prom
1bda0 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 ote to a reserve
1bdb0 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 d lock and.** a
1bdc0 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 second process i
1bdd0 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 s holding a rese
1bde0 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 rved lock that i
1bdf0 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 t is trying.** t
1be00 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 o promote to an
1be10 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 exclusive lock.
1be20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 The first proce
1be30 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 ss cannot procee
1be40 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 d.** because it
1be50 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 is blocked by th
1be60 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 e second and the
1be70 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 second process
1be80 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 cannot.** procee
1be90 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 d because it is
1bea0 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 blocked by the f
1beb0 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 irst. If both p
1bec0 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f rocesses.** invo
1bed0 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ke the busy hand
1bee0 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 lers, neither wi
1bef0 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 ll make any prog
1bf00 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 ress. Therefore
1bf10 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 ,.** SQLite retu
1bf20 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 rns [SQLITE_BUSY
1bf30 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 ] for the first
1bf40 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 process, hoping
1bf50 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c that this.** wil
1bf60 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 l induce the fir
1bf70 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 st process to re
1bf80 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c lease its read l
1bf90 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a ock and allow.**
1bfa0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 the second proc
1bfb0 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a ess to proceed..
1bfc0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 **.** ^The defau
1bfd0 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b lt busy callback
1bfe0 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 is NULL..**.**
1bff0 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 ^(There can only
1c000 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 be a single bus
1c010 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 y handler define
1c020 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 d for each.** [d
1c030 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1c040 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 on]. Setting a
1c050 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 new busy handler
1c060 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 clears any.** p
1c070 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 reviously set ha
1c080 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 ndler.)^ ^Note
1c090 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 that calling [sq
1c0a0 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f lite3_busy_timeo
1c0b0 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c ut()].** or eval
1c0c0 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 uating [PRAGMA b
1c0d0 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 usy_timeout=N] w
1c0e0 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a ill change the.*
1c0f0 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61 * busy handler a
1c100 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e nd thus clear an
1c110 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 y previously set
1c120 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a busy handler..*
1c130 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 *.** The busy ca
1c140 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f llback should no
1c150 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f t take any actio
1c160 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 ns which modify
1c170 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 the.** database
1c180 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 connection that
1c190 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 invoked the busy
1c1a0 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 handler. In ot
1c1b0 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 her words,.** th
1c1c0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 e busy handler i
1c1d0 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e s not reentrant.
1c1e0 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f Any such actio
1c1f0 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 ns.** result in
1c200 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 undefined behavi
1c210 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 or..** .** A bus
1c220 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e y handler must n
1c230 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 ot close the dat
1c240 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1c250 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 .** or [prepared
1c260 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 statement] that
1c270 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 invoked the bus
1c280 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e y handler..*/.in
1c290 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 t sqlite3_busy_h
1c2a0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c andler(sqlite3*,
1c2b0 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 int(*)(void*,int
1c2c0 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a ),void*);../*.**
1c2d0 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 CAPI3REF: Set A
1c2e0 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a Busy Timeout.**
1c2f0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
1c300 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 .**.** ^This rou
1c310 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c tine sets a [sql
1c320 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 ite3_busy_handle
1c330 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 r | busy handler
1c340 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a ] that sleeps.**
1c350 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 for a specified
1c360 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 amount of time
1c370 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 when a table is
1c380 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 locked. ^The ha
1c390 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c ndler.** will sl
1c3a0 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d eep multiple tim
1c3b0 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 es until at leas
1c3c0 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f t "ms" milliseco
1c3d0 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a nds of sleeping.
1c3e0 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 ** have accumula
1c3f0 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 ted. ^After at
1c400 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 least "ms" milli
1c410 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 seconds of sleep
1c420 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 ing,.** the hand
1c430 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 ler returns 0 wh
1c440 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 ich causes [sqli
1c450 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 te3_step()] to r
1c460 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 eturn.** [SQLITE
1c470 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 _BUSY]..**.** ^C
1c480 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 alling this rout
1c490 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 ine with an argu
1c4a0 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f ment less than o
1c4b0 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a r equal to zero.
1c4c0 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c ** turns off all
1c4d0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a busy handlers..
1c4e0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 **.** ^(There ca
1c4f0 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 n only be a sing
1c500 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 le busy handler
1c510 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 for a particular
1c520 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
1c530 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 nnection] at any
1c540 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 given moment.
1c550 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 If another busy
1c560 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 handler.** was d
1c570 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b efined (using [
1c580 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e sqlite3_busy_han
1c590 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 dler()]) prior t
1c5a0 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 o calling.** thi
1c5b0 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 s routine, that
1c5c0 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c other busy handl
1c5d0 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e er is cleared.)^
1c5e0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
1c5f0 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 [PRAGMA busy_t
1c600 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 imeout].*/.int s
1c610 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 qlite3_busy_time
1c620 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e out(sqlite3*, in
1c630 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 t ms);../*.** CA
1c640 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 PI3REF: Convenie
1c650 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 nce Routines For
1c660 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 Running Queries
1c670 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
1c680 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 te3.**.** This i
1c690 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 s a legacy inter
1c6a0 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65 face that is pre
1c6b0 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 served for backw
1c6c0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 ards compatibili
1c6d0 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 ty..** Use of th
1c6e0 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 is interface is
1c6f0 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e not recommended.
1c700 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f .**.** Definitio
1c710 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 n: A <b>result t
1c720 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f able</b> is memo
1c730 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 ry data structur
1c740 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 e created by the
1c750 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 .** [sqlite3_get
1c760 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 _table()] interf
1c770 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 ace. A result t
1c780 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 able records the
1c790 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 .** complete que
1c7a0 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 ry results from
1c7b0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 one or more quer
1c7c0 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 ies..**.** The t
1c7d0 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c able conceptuall
1c7e0 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f y has a number o
1c7f0 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d f rows and colum
1c800 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 ns. But.** thes
1c810 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f e numbers are no
1c820 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 t part of the re
1c830 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c sult table itsel
1c840 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d f. These.** num
1c850 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 bers are obtaine
1c860 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c d separately. L
1c870 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 et N be the numb
1c880 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e er of rows.** an
1c890 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 d M be the numbe
1c8a0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a r of columns..**
1c8b0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 .** A result tab
1c8c0 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f le is an array o
1c8d0 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 f pointers to ze
1c8e0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 ro-terminated UT
1c8f0 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 F-8 strings..**
1c900 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a There are (N+1)*
1c910 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 M elements in th
1c920 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 e array. The fi
1c930 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 rst M pointers p
1c940 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d oint.** to zero-
1c950 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e terminated strin
1c960 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e gs that contain
1c970 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 the names of th
1c980 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 e columns..** Th
1c990 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 e remaining entr
1c9a0 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f ies all point to
1c9b0 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 query results.
1c9c0 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 NULL values res
1c9d0 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 ult.** in NULL p
1c9e0 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 ointers. All ot
1c9f0 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 her values are i
1ca00 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 n their UTF-8 ze
1ca10 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ro-terminated.**
1ca20 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e string represen
1ca30 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e tation as return
1ca40 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 ed by [sqlite3_c
1ca50 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a olumn_text()]..*
1ca60 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 *.** A result ta
1ca70 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 ble might consis
1ca80 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 t of one or more
1ca90 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
1caa0 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f ons..** It is no
1cab0 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 t safe to pass a
1cac0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 result table di
1cad0 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 rectly to [sqlit
1cae0 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 e3_free()]..** A
1caf0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 result table sh
1cb00 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 ould be dealloca
1cb10 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ted using [sqlit
1cb20 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d e3_free_table()]
1cb30 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 ..**.** ^(As an
1cb40 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 example of the r
1cb50 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d esult table form
1cb60 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 at, suppose a qu
1cb70 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 ery result.** is
1cb80 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
1cb90 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
1cba0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e pre>.** N
1cbb0 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 ame | Age
1cbc0 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d .** -----
1cbd0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
1cbe0 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 --.** Ali
1cbf0 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a ce | 43.**
1cc00 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 Bob
1cc10 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 | 28.**
1cc20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c Cindy |
1cc30 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 21.** </pre></b
1cc40 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
1cc50 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 There are two c
1cc60 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 olumn (M==2) and
1cc70 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d three rows (N==
1cc80 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 3). Thus the.**
1cc90 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 result table ha
1cca0 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 s 8 entries. Su
1ccb0 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 ppose the result
1ccc0 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 table is stored
1ccd0 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 .** in an array
1cce0 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 names azResult.
1ccf0 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 Then azResult h
1cd00 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e olds this conten
1cd10 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 t:.**.** <blockq
1cd20 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 uote><pre>.**
1cd30 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
1cd40 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 1;0] = "Name";.*
1cd50 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
1cd60 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 t[1] = "Age"
1cd70 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
1cd80 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 sult[2] = "A
1cd90 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 lice";.**
1cda0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d azResult[3]
1cdb0 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 = "43";.**
1cdc0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
1cdd0 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 4] = "Bob";.**
1cde0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
1cdf0 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 91;5] = "28";.**
1ce00 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
1ce10 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 [6] = "Cindy
1ce20 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
1ce30 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 esult[7] = "
1ce40 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 21";.** </pre></
1ce50 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a blockquote>)^.**
1ce60 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1ce70 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e _get_table() fun
1ce80 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 ction evaluates
1ce90 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 one or more.** s
1cea0 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 emicolon-separat
1ceb0 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ed SQL statement
1cec0 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 s in the zero-te
1ced0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a rminated UTF-8.*
1cee0 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 * string of its
1cef0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 2nd parameter an
1cf00 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 d returns a resu
1cf10 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a lt table to the.
1cf20 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e ** pointer given
1cf30 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 in its 3rd para
1cf40 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 meter..**.** Aft
1cf50 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 er the applicati
1cf60 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 on has finished
1cf70 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 with the result
1cf80 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 from sqlite3_get
1cf90 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 _table(),.** it
1cfa0 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65 must pass the re
1cfb0 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 sult table point
1cfc0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 er to sqlite3_fr
1cfd0 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 ee_table() in or
1cfe0 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 der to.** releas
1cff0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 e the memory tha
1d000 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 t was malloced.
1d010 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 Because of the
1d020 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 way the.** [sqli
1d030 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 te3_malloc()] ha
1d040 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c ppens within sql
1d050 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
1d060 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a , the calling.**
1d070 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e function must n
1d080 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b ot try to call [
1d090 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 sqlite3_free()]
1d0a0 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a directly. Only.
1d0b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ** [sqlite3_free
1d0c0 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c _table()] is abl
1d0d0 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 e to release the
1d0e0 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 memory properly
1d0f0 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a and safely..**.
1d100 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 ** The sqlite3_g
1d110 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 et_table() inter
1d120 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e face is implemen
1d130 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 ted as a wrapper
1d140 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 around.** [sqli
1d150 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 te3_exec()]. Th
1d160 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 e sqlite3_get_ta
1d170 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f ble() routine do
1d180 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 es not have acce
1d190 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 ss.** to any int
1d1a0 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 ernal data struc
1d1b0 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e tures of SQLite.
1d1c0 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 It uses only t
1d1d0 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 he public.** int
1d1e0 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 erface defined h
1d1f0 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 ere. As a conse
1d200 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 quence, errors t
1d210 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 hat occur in the
1d220 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 .** wrapper laye
1d230 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 r outside of the
1d240 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 internal [sqlit
1d250 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 e3_exec()] call
1d260 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 are not.** refle
1d270 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 cted in subseque
1d280 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c nt calls to [sql
1d290 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 ite3_errcode()]
1d2a0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 or.** [sqlite3_e
1d2b0 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 rrmsg()]..*/.int
1d2c0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
1d2d0 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 le(. sqlite3 *d
1d2e0 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 b, /* A
1d2f0 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 n open database
1d300 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
1d310 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 *zSql, /* SQ
1d320 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 L to be evaluate
1d330 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 d */. char ***p
1d340 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 azResult, /*
1d350 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 Results of the q
1d360 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 uery */. int *p
1d370 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 nRow,
1d380 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 /* Number of res
1d390 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e ult rows written
1d3a0 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a here */. int *
1d3b0 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 pnColumn,
1d3c0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 /* Number of re
1d3d0 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 sult columns wri
1d3e0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 tten here */. c
1d3f0 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 har **pzErrmsg
1d400 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 /* Error ms
1d410 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a g written here *
1d420 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 /.);.void sqlite
1d430 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 3_free_table(cha
1d440 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a r **result);../*
1d450 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f .** CAPI3REF: Fo
1d460 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 rmatted String P
1d470 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e rinting Function
1d480 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f s.**.** These ro
1d490 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d utines are work-
1d4a0 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 alikes of the "p
1d4b0 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 rintf()" family
1d4c0 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 of functions.**
1d4d0 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 from the standar
1d4e0 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 d C library..**
1d4f0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 75 These routines u
1d500 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f nderstand most o
1d510 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 f the common K&R
1d520 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 formatting opti
1d530 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d ons,.** plus som
1d540 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e e additional non
1d550 2d 73 74 61 6e 64 61 72 64 20 66 6f 72 6d 61 74 -standard format
1d560 73 2c 20 64 65 74 61 69 6c 65 64 20 62 65 6c 6f s, detailed belo
1d570 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 w..** Note that
1d580 73 6f 6d 65 20 6f 66 20 74 68 65 20 6d 6f 72 65 some of the more
1d590 20 6f 62 73 63 75 72 65 20 66 6f 72 6d 61 74 74 obscure formatt
1d5a0 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d ing options from
1d5b0 20 72 65 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 recent.** C-lib
1d5c0 72 61 72 79 20 73 74 61 6e 64 61 72 64 73 20 61 rary standards a
1d5d0 72 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 re omitted from
1d5e0 74 68 69 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 this implementat
1d5f0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ion..**.** ^The
1d600 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
1d610 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d ) and sqlite3_vm
1d620 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 printf() routine
1d630 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a s write their.**
1d640 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 results into me
1d650 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 mory obtained fr
1d660 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
1d670 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 oc()]..** The st
1d680 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 rings returned b
1d690 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 y these two rout
1d6a0 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a ines should be.*
1d6b0 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 * released by [s
1d6c0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 qlite3_free()].
1d6d0 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 ^Both routines
1d6e0 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c return a.** NULL
1d6f0 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c pointer if [sql
1d700 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 ite3_malloc()] i
1d710 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f s unable to allo
1d720 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d cate enough.** m
1d730 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 emory to hold th
1d740 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 e resulting stri
1d750 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 ng..**.** ^(The
1d760 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
1d770 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 () routine is si
1d780 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e milar to "snprin
1d790 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 tf()" from.** th
1d7a0 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 e standard C lib
1d7b0 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c rary. The resul
1d7c0 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 t is written int
1d7d0 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 o the.** buffer
1d7e0 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 supplied as the
1d7f0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
1d800 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 whose size is g
1d810 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 iven by.** the f
1d820 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 irst parameter.
1d830 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 Note that the or
1d840 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 der of the.** fi
1d850 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 rst two paramete
1d860 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 rs is reversed f
1d870 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 rom snprintf().)
1d880 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a ^ This is an.**
1d890 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 historical acci
1d8a0 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 dent that cannot
1d8b0 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 be fixed withou
1d8c0 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 t breaking.** ba
1d8d0 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 ckwards compatib
1d8e0 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 ility. ^(Note a
1d8f0 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 lso that sqlite3
1d900 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 _snprintf().** r
1d910 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
1d920 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 to its buffer i
1d930 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 nstead of the nu
1d940 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 mber of.** chara
1d950 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 cters actually w
1d960 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 ritten into the
1d970 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 buffer.)^ We ad
1d980 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 mit that.** the
1d990 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 number of charac
1d9a0 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 ters written wou
1d9b0 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 ld be a more use
1d9c0 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 ful return.** va
1d9d0 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f lue but we canno
1d9e0 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 t change the imp
1d9f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 lementation of s
1da00 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
1da10 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 ).** now without
1da20 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 breaking compat
1da30 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e ibility..**.** ^
1da40 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 As long as the b
1da50 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 uffer size is gr
1da60 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c eater than zero,
1da70 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
1da80 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 f().** guarantee
1da90 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 s that the buffe
1daa0 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f r is always zero
1dab0 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 -terminated. ^T
1dac0 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 he first.** para
1dad0 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 meter "n" is the
1dae0 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 total size of t
1daf0 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 he buffer, inclu
1db00 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a ding space for.*
1db10 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 * the zero termi
1db20 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c nator. So the l
1db30 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 ongest string th
1db40 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 at can be comple
1db50 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 tely.** written
1db60 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 will be n-1 char
1db70 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 acters..**.** ^T
1db80 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 he sqlite3_vsnpr
1db90 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 intf() routine i
1dba0 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73 s a varargs vers
1dbb0 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 ion of sqlite3_s
1dbc0 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a nprintf()..**.**
1dbd0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
1dbe0 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f all implement so
1dbf0 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f me additional fo
1dc00 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 rmatting.** opti
1dc10 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 ons that are use
1dc20 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 ful for construc
1dc30 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 ting SQL stateme
1dc40 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 nts..** All of t
1dc50 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 he usual printf(
1dc60 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 ) formatting opt
1dc70 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 ions apply. In
1dc80 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a addition, there.
1dc90 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 ** is are "%q",
1dca0 22 25 51 22 2c 20 22 25 77 22 20 61 6e 64 20 22 "%Q", "%w" and "
1dcb0 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a %z" options..**.
1dcc0 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 ** ^(The %q opti
1dcd0 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 on works like %s
1dce0 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 in that it subs
1dcf0 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 titutes a nul-te
1dd00 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 rminated.** stri
1dd10 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 ng from the argu
1dd20 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 ment list. But
1dd30 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 %q also doubles
1dd40 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 every '\'' chara
1dd50 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 cter..** %q is d
1dd60 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 esigned for use
1dd70 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 inside a string
1dd80 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 literal.)^ By d
1dd90 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 oubling each '\'
1dda0 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 '.** character i
1ddb0 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63 t escapes that c
1ddc0 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c haracter and all
1ddd0 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 ows it to be ins
1dde0 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 erted into.** th
1ddf0 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 e string..**.**
1de00 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 For example, ass
1de10 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 ume the string v
1de20 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f ariable zText co
1de30 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 ntains text as f
1de40 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ollows:.**.** <b
1de50 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
1de60 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 ** char *zText
1de70 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20 = "It's a happy
1de80 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e day!";.** </pre>
1de90 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
1dea0 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 .** One can use
1deb0 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 this text in an
1dec0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 SQL statement as
1ded0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 follows:.**.**
1dee0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
1def0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c >.** char *zSQL
1df00 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e = sqlite3_mprin
1df10 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 tf("INSERT INTO
1df20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 table VALUES('%q
1df30 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 ')", zText);.**
1df40 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 sqlite3_exec(db
1df50 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 , zSQL, 0, 0, 0)
1df60 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 ;.** sqlite3_fr
1df70 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 ee(zSQL);.** </p
1df80 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
1df90 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 .**.** Because t
1dfa0 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 he %q format str
1dfb0 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 ing is used, the
1dfc0 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 '\'' character
1dfd0 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 in zText.** is e
1dfe0 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 scaped and the S
1dff0 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 QL generated is
1e000 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a as follows:.**.*
1e010 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
1e020 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 re>.** INSERT I
1e030 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 NTO table1 VALUE
1e040 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79 S('It''s a happy
1e050 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 day!').** </pre
1e060 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
1e070 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 *.** This is cor
1e080 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 rect. Had we us
1e090 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 ed %s instead of
1e0a0 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 %q, the generat
1e0b0 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 ed SQL.** would
1e0c0 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 have looked like
1e0d0 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c this:.**.** <bl
1e0e0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
1e0f0 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 * INSERT INTO t
1e100 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 able1 VALUES('It
1e110 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 's a happy day!'
1e120 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c );.** </pre></bl
1e130 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
1e140 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d This second exam
1e150 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 ple is an SQL sy
1e160 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 ntax error. As
1e170 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 a general rule y
1e180 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 ou should.** alw
1e190 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 ays use %q inste
1e1a0 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e ad of %s when in
1e1b0 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 serting text int
1e1c0 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 o a string liter
1e1d0 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 al..**.** ^(The
1e1e0 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 %Q option works
1e1f0 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 like %q except i
1e200 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 t also adds sing
1e210 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 le quotes around
1e220 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 .** the outside
1e230 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 of the total str
1e240 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c ing. Additional
1e250 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d ly, if the param
1e260 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 eter in the.** a
1e270 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 rgument list is
1e280 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 a NULL pointer,
1e290 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 %Q substitutes t
1e2a0 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 he text "NULL" (
1e2b0 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c without.** singl
1e2c0 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f e quotes).)^ So
1e2d0 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f , for example, o
1e2e0 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a ne could say:.**
1e2f0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
1e300 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a <pre>.** char *
1e310 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d zSQL = sqlite3_m
1e320 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 printf("INSERT I
1e330 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 NTO table VALUES
1e340 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a (%Q)", zText);.*
1e350 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 * sqlite3_exec(
1e360 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 db, zSQL, 0, 0,
1e370 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 0);.** sqlite3_
1e380 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c free(zSQL);.** <
1e390 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
1e3a0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 e>.**.** The cod
1e3b0 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e e above will ren
1e3c0 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 der a correct SQ
1e3d0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 L statement in t
1e3e0 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 he zSQL.** varia
1e3f0 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 ble even if the
1e400 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 zText variable i
1e410 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
1e420 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 ..**.** ^(The "%
1e430 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 w" formatting op
1e440 74 69 6f 6e 20 69 73 20 6c 69 6b 65 20 22 25 71 tion is like "%q
1e450 22 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 " except that it
1e460 20 65 78 70 65 63 74 73 20 74 6f 0a 2a 2a 20 62 expects to.** b
1e470 65 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 e contained with
1e480 69 6e 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 73 in double-quotes
1e490 20 69 6e 73 74 65 61 64 20 6f 66 20 73 69 6e 67 instead of sing
1e4a0 6c 65 20 71 75 6f 74 65 73 2c 20 61 6e 64 20 69 le quotes, and i
1e4b0 74 0a 2a 2a 20 65 73 63 61 70 65 73 20 74 68 65 t.** escapes the
1e4c0 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 20 63 68 double-quote ch
1e4d0 61 72 61 63 74 65 72 20 69 6e 73 74 65 61 64 20 aracter instead
1e4e0 6f 66 20 74 68 65 20 73 69 6e 67 6c 65 2d 71 75 of the single-qu
1e4f0 6f 74 65 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 ote.** character
1e500 2e 29 5e 20 20 54 68 65 20 22 25 77 22 20 66 6f .)^ The "%w" fo
1e510 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 rmatting option
1e520 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 is intended for
1e530 73 61 66 65 6c 79 20 69 6e 73 65 72 74 69 6e 67 safely inserting
1e540 0a 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20 63 6f .** table and co
1e550 6c 75 6d 6e 20 6e 61 6d 65 73 20 69 6e 74 6f 20 lumn names into
1e560 61 20 63 6f 6e 73 74 72 75 63 74 65 64 20 53 51 a constructed SQ
1e570 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a L statement..**.
1e580 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f ** ^(The "%z" fo
1e590 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 rmatting option
1e5a0 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 works like "%s"
1e5b0 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 but with the.**
1e5c0 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 addition that af
1e5d0 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 ter the string h
1e5e0 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 as been read and
1e5f0 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 copied into.**
1e600 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c the result, [sql
1e610 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 ite3_free()] is
1e620 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e called on the in
1e630 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f put string.)^.*/
1e640 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d .char *sqlite3_m
1e650 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 printf(const cha
1e660 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 r*,...);.char *s
1e670 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 qlite3_vmprintf(
1e680 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f const char*, va_
1e690 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c list);.char *sql
1e6a0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e ite3_snprintf(in
1e6b0 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 t,char*,const ch
1e6c0 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 ar*, ...);.char
1e6d0 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e *sqlite3_vsnprin
1e6e0 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e tf(int,char*,con
1e6f0 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 st char*, va_lis
1e700 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
1e710 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f REF: Memory Allo
1e720 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d cation Subsystem
1e730 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 .**.** The SQLit
1e740 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 e core uses thes
1e750 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 e three routines
1e760 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 for all of its
1e770 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 own.** internal
1e780 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
1e790 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 n needs. "Core"
1e7a0 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 in the previous
1e7b0 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 sentence.** does
1e7c0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 not include ope
1e7d0 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 rating-system sp
1e7e0 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 ecific VFS imple
1e7f0 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a mentation. The.
1e800 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 ** Windows VFS u
1e810 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f ses native mallo
1e820 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 c() and free() f
1e830 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f or some operatio
1e840 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ns..**.** ^The s
1e850 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
1e860 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
1e870 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 a pointer to a b
1e880 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 lock.** of memor
1e890 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 y at least N byt
1e8a0 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 es in length, wh
1e8b0 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 ere N is the par
1e8c0 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 ameter..** ^If s
1e8d0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
1e8e0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 is unable to obt
1e8f0 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 ain sufficient f
1e900 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 ree.** memory, i
1e910 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c t returns a NULL
1e920 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 pointer. ^If t
1e930 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 he parameter N t
1e940 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c o.** sqlite3_mal
1e950 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 loc() is zero or
1e960 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 negative then s
1e970 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
1e980 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c returns.** a NUL
1e990 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a L pointer..**.**
1e9a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 ^The sqlite3_ma
1e9b0 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75 74 69 6e lloc64(N) routin
1e9c0 65 20 77 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b e works just lik
1e9d0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c e.** sqlite3_mal
1e9e0 6c 6f 63 28 4e 29 20 65 78 63 65 70 74 20 74 68 loc(N) except th
1e9f0 61 74 20 4e 20 69 73 20 61 6e 20 75 6e 73 69 67 at N is an unsig
1ea00 6e 65 64 20 36 34 2d 62 69 74 20 69 6e 74 65 67 ned 64-bit integ
1ea10 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 er instead.** of
1ea20 20 61 20 73 69 67 6e 65 64 20 33 32 2d 62 69 74 a signed 32-bit
1ea30 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 integer..**.**
1ea40 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 ^Calling sqlite3
1ea50 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70 _free() with a p
1ea60 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c ointer previousl
1ea70 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 y returned.** by
1ea80 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
1ea90 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 ) or sqlite3_rea
1eaa0 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 lloc() releases
1eab0 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a that memory so.*
1eac0 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 * that it might
1ead0 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 be reused. ^The
1eae0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 sqlite3_free()
1eaf0 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 routine is.** a
1eb00 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c no-op if is call
1eb10 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 ed with a NULL p
1eb20 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 ointer. Passing
1eb30 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a a NULL pointer.
1eb40 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 ** to sqlite3_fr
1eb50 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 ee() is harmless
1eb60 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 . After being f
1eb70 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 reed, memory.**
1eb80 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 should neither b
1eb90 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 e read nor writt
1eba0 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e en. Even readin
1ebb0 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 g previously fre
1ebc0 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 ed.** memory mig
1ebd0 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 ht result in a s
1ebe0 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c egmentation faul
1ebf0 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 t or other sever
1ec00 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f e error..** Memo
1ec10 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 ry corruption, a
1ec20 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 segmentation fa
1ec30 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 ult, or other se
1ec40 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 vere error.** mi
1ec50 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 ght result if sq
1ec60 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 lite3_free() is
1ec70 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f called with a no
1ec80 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 n-NULL pointer t
1ec90 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f hat.** was not o
1eca0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c btained from sql
1ecb0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 ite3_malloc() or
1ecc0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
1ecd0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ()..**.** ^The s
1ece0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 qlite3_realloc(X
1ecf0 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 ,N) interface at
1ed00 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 tempts to resize
1ed10 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f a.** prior memo
1ed20 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 ry allocation X
1ed30 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e to be at least N
1ed40 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 bytes..** ^If t
1ed50 68 65 20 58 20 70 61 72 61 6d 65 74 65 72 20 74 he X parameter t
1ed60 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f o sqlite3_reallo
1ed70 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e c(X,N).** is a N
1ed80 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e ULL pointer then
1ed90 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 its behavior is
1eda0 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 identical to ca
1edb0 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 lling.** sqlite3
1edc0 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e _malloc(N)..** ^
1edd0 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 If the N paramet
1ede0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 er to sqlite3_re
1edf0 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65 alloc(X,N) is ze
1ee00 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 ro or.** negativ
1ee10 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 e then the behav
1ee20 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 ior is exactly t
1ee30 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 he same as calli
1ee40 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 ng.** sqlite3_fr
1ee50 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 ee(X)..** ^sqlit
1ee60 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 e3_realloc(X,N)
1ee70 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
1ee80 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c r to a memory al
1ee90 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 location.** of a
1eea0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 t least N bytes
1eeb0 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 in size or NULL
1eec0 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20 if insufficient
1eed0 6d 65 6d 6f 72 79 20 69 73 20 61 76 61 69 6c 61 memory is availa
1eee0 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 ble..** ^If M is
1eef0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 the size of the
1ef00 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f prior allocatio
1ef10 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 n, then min(N,M)
1ef20 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 bytes.** of the
1ef30 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f prior allocatio
1ef40 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 n are copied int
1ef50 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 o the beginning
1ef60 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e of buffer return
1ef70 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 ed.** by sqlite3
1ef80 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e _realloc(X,N) an
1ef90 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f d the prior allo
1efa0 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e cation is freed.
1efb0 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f .** ^If sqlite3_
1efc0 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 realloc(X,N) ret
1efd0 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 urns NULL and N
1efe0 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 is positive, the
1eff0 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61 n the.** prior a
1f000 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74 llocation is not
1f010 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 freed..**.** ^T
1f020 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c he sqlite3_reall
1f030 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74 65 72 66 oc64(X,N) interf
1f040 61 63 65 73 20 77 6f 72 6b 73 20 74 68 65 20 73 aces works the s
1f050 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 ame as.** sqlite
1f060 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 3_realloc(X,N) e
1f070 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 xcept that N is
1f080 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 a 64-bit unsigne
1f090 64 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 d integer instea
1f0a0 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d 62 69 74 d.** of a 32-bit
1f0b0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e signed integer.
1f0c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20 .**.** ^If X is
1f0d0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 a memory allocat
1f0e0 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 6f ion previously o
1f0f0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c btained from sql
1f100 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a ite3_malloc(),.*
1f110 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 * sqlite3_malloc
1f120 36 34 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 64(), sqlite3_re
1f130 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69 alloc(), or sqli
1f140 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c te3_realloc64(),
1f150 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 then.** sqlite3
1f160 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e _msize(X) return
1f170 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 s the size of th
1f180 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 at memory alloca
1f190 74 69 6f 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a tion in bytes..*
1f1a0 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 * ^The value ret
1f1b0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
1f1c0 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67 68 74 20 _msize(X) might
1f1d0 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 be larger than t
1f1e0 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 he number.** of
1f1f0 62 79 74 65 73 20 72 65 71 75 65 73 74 65 64 20 bytes requested
1f200 77 68 65 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63 when X was alloc
1f210 61 74 65 64 2e 20 20 5e 49 66 20 58 20 69 73 20 ated. ^If X is
1f220 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 a NULL pointer t
1f230 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d hen.** sqlite3_m
1f240 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 size(X) returns
1f250 7a 65 72 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e zero. If X poin
1f260 74 73 20 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20 ts to something
1f270 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 that is not.** t
1f280 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 he beginning of
1f290 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
1f2a0 6e 2c 20 6f 72 20 69 66 20 69 74 20 70 6f 69 6e n, or if it poin
1f2b0 74 73 20 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79 ts to a formerly
1f2c0 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79 .** valid memory
1f2d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 allocation that
1f2e0 20 68 61 73 20 6e 6f 77 20 62 65 65 6e 20 66 72 has now been fr
1f2f0 65 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 eed, then the be
1f300 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c havior.** of sql
1f310 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 69 73 ite3_msize(X) is
1f320 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 undefined and p
1f330 6f 73 73 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e ossibly harmful.
1f340 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f .**.** ^The memo
1f350 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ry returned by s
1f360 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c qlite3_malloc(),
1f370 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
1f380 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d (),.** sqlite3_m
1f390 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 64 20 73 alloc64(), and s
1f3a0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 qlite3_realloc64
1f3b0 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 ().** is always
1f3c0 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 aligned to at le
1f3d0 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f ast an 8 byte bo
1f3e0 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a undary, or to a.
1f3f0 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61 ** 4 byte bounda
1f400 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 ry if the [SQLIT
1f410 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 E_4_BYTE_ALIGNED
1f420 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 _MALLOC] compile
1f430 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 -time.** option
1f440 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 is used..**.** I
1f450 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e n SQLite version
1f460 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 3.5.0 and 3.5.1
1f470 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c , it was possibl
1f480 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 e to define.** t
1f490 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d he SQLITE_OMIT_M
1f4a0 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e EMORY_ALLOCATION
1f4b0 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 which would cau
1f4c0 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a se the built-in.
1f4d0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
1f4e0 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 n of these routi
1f4f0 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 nes to be omitte
1f500 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c d. That capabil
1f510 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e ity.** is no lon
1f520 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f ger provided. O
1f530 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d nly built-in mem
1f540 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 ory allocators c
1f550 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a an be used..**.*
1f560 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 * Prior to SQLit
1f570 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 e version 3.7.10
1f580 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 , the Windows OS
1f590 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 interface layer
1f5a0 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 called.** the s
1f5b0 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 ystem malloc() a
1f5c0 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74 nd free() direct
1f5d0 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 ly when converti
1f5e0 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 ng.** filenames
1f5f0 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d between the UTF-
1f600 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 8 encoding used
1f610 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 by SQLite.** and
1f620 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 whatever filena
1f630 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 me encoding is u
1f640 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69 sed by the parti
1f650 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a cular Windows.**
1f660 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 installation.
1f670 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f Memory allocatio
1f680 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20 64 65 n errors were de
1f690 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 tected, but.** t
1f6a0 68 65 79 20 77 65 72 65 20 72 65 70 6f 72 74 65 hey were reporte
1f6b0 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 d back as [SQLIT
1f6c0 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a E_CANTOPEN] or.*
1f6d0 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d * [SQLITE_IOERR]
1f6e0 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 rather than [SQ
1f6f0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a LITE_NOMEM]..**.
1f700 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 ** The pointer a
1f710 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c rguments to [sql
1f720 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 ite3_free()] and
1f730 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f [sqlite3_reallo
1f740 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 c()].** must be
1f750 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 either NULL or e
1f760 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 lse pointers obt
1f770 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 ained from a pri
1f780 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e or.** invocation
1f790 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c of [sqlite3_mal
1f7a0 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 loc()] or [sqlit
1f7b0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 e3_realloc()] th
1f7c0 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 at have.** not y
1f7d0 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 et been released
1f7e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c ..**.** The appl
1f7f0 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 ication must not
1f800 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 read or write a
1f810 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 ny part of.** a
1f820 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 block of memory
1f830 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 after it has bee
1f840 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 n released using
1f850 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 .** [sqlite3_fre
1f860 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 e()] or [sqlite3
1f870 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a _realloc()]..*/.
1f880 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 void *sqlite3_ma
1f890 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 lloc(int);.void
1f8a0 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 *sqlite3_malloc6
1f8b0 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 4(sqlite3_uint64
1f8c0 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 );.void *sqlite3
1f8d0 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 _realloc(void*,
1f8e0 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 int);.void *sqli
1f8f0 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f te3_realloc64(vo
1f900 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e id*, sqlite3_uin
1f910 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 t64);.void sqlit
1f920 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a e3_free(void*);.
1f930 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 73 sqlite3_uint64 s
1f940 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69 qlite3_msize(voi
1f950 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d*);../*.** CAPI
1f960 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 3REF: Memory All
1f970 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 ocator Statistic
1f980 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 s.**.** SQLite p
1f990 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77 rovides these tw
1f9a0 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 o interfaces for
1f9b0 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 reporting on th
1f9c0 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 e status.** of t
1f9d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c he [sqlite3_mall
1f9e0 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f oc()], [sqlite3_
1f9f0 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 free()], and [sq
1fa00 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d lite3_realloc()]
1fa10 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 .** routines, wh
1fa20 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 ich form the bui
1fa30 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c lt-in memory all
1fa40 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 ocation subsyste
1fa50 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 m..**.** ^The [s
1fa60 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 qlite3_memory_us
1fa70 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 ed()] routine re
1fa80 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
1fa90 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 of bytes.** of
1faa0 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 memory currently
1fab0 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 outstanding (ma
1fac0 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 lloced but not f
1fad0 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b reed)..** ^The [
1fae0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 sqlite3_memory_h
1faf0 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 ighwater()] rout
1fb00 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ine returns the
1fb10 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 maximum.** value
1fb20 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d of [sqlite3_mem
1fb30 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 ory_used()] sinc
1fb40 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 e the high-water
1fb50 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 mark.** was las
1fb60 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 t reset. ^The v
1fb70 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 alues returned b
1fb80 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 y [sqlite3_memor
1fb90 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a y_used()] and.**
1fba0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
1fbb0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e _highwater()] in
1fbc0 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 clude any overhe
1fbd0 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 ad.** added by S
1fbe0 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 QLite in its imp
1fbf0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b lementation of [
1fc00 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1fc10 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 ],.** but not ov
1fc20 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20 erhead added by
1fc30 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 the any underlyi
1fc40 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 ng system librar
1fc50 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 y.** routines th
1fc60 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c at [sqlite3_mall
1fc70 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a oc()] may call..
1fc80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 **.** ^The memor
1fc90 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 y high-water mar
1fca0 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 k is reset to th
1fcb0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 e current value
1fcc0 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d of.** [sqlite3_m
1fcd0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 emory_used()] if
1fce0 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 and only if the
1fcf0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
1fd00 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
1fd10 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 _highwater()] is
1fd20 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c true. ^The val
1fd30 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 ue returned.** b
1fd40 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 y [sqlite3_memor
1fd50 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 y_highwater(1)]
1fd60 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 is the high-wate
1fd70 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 r mark.** prior
1fd80 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f to the reset..*/
1fd90 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 .sqlite3_int64 s
1fda0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 qlite3_memory_us
1fdb0 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 ed(void);.sqlite
1fdc0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 3_int64 sqlite3_
1fdd0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
1fde0 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b (int resetFlag);
1fdf0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1fe00 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 : Pseudo-Random
1fe10 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 Number Generator
1fe20 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f .**.** SQLite co
1fe30 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 ntains a high-qu
1fe40 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e ality pseudo-ran
1fe50 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 dom number gener
1fe60 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 ator (PRNG) used
1fe70 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 to.** select ra
1fe80 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f ndom [ROWID | RO
1fe90 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 WIDs] when inser
1fea0 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 ting new records
1feb0 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 into a table th
1fec0 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 at.** already us
1fed0 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 es the largest p
1fee0 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e ossible [ROWID].
1fef0 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c The PRNG is al
1ff00 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 so used for.** t
1ff10 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 he build-in rand
1ff20 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 om() and randomb
1ff30 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 lob() SQL functi
1ff40 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 ons. This inter
1ff50 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 face allows.** a
1ff60 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 pplications to a
1ff70 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 ccess the same P
1ff80 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 RNG for other pu
1ff90 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 rposes..**.** ^A
1ffa0 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f call to this ro
1ffb0 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 utine stores N b
1ffc0 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 ytes of randomne
1ffd0 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 ss into buffer P
1ffe0 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70 61 72 61 ..** ^The P para
1fff0 6d 65 74 65 72 20 63 61 6e 20 62 65 20 61 20 4e meter can be a N
20000 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a ULL pointer..**.
20010 2a 2a 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74 ** ^If this rout
20020 69 6e 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e ine has not been
20030 20 70 72 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c previously call
20040 65 64 20 6f 72 20 69 66 20 74 68 65 20 70 72 65 ed or if the pre
20050 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 vious.** call ha
20060 64 20 4e 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e d N less than on
20070 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e e or a NULL poin
20080 74 65 72 20 66 6f 72 20 50 2c 20 74 68 65 6e 20 ter for P, then
20090 74 68 65 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73 the PRNG is.** s
200a0 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 eeded using rand
200b0 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 20 omness obtained
200c0 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d from the xRandom
200d0 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a ness method of.*
200e0 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 * the default [s
200f0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
20100 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 ct..** ^If the p
20110 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 revious call to
20120 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 64 this routine had
20130 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f an N of 1 or mo
20140 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d re and a.** non-
20150 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74 68 65 20 NULL P then the
20160 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 pseudo-randomnes
20170 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a s is generated.*
20180 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 * internally and
20190 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 without recours
201a0 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 e to the [sqlite
201b0 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 3_vfs] xRandomne
201c0 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f ss.** method..*/
201d0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 .void sqlite3_ra
201e0 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 ndomness(int N,
201f0 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a void *P);../*.**
20200 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 CAPI3REF: Compi
20210 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a le-Time Authoriz
20220 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a ation Callbacks.
20230 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
20240 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 e3.**.** ^This r
20250 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 outine registers
20260 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 an authorizer c
20270 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 allback with a p
20280 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 articular.** [da
20290 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
202a0 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 n], supplied in
202b0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
202c0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 nt..** ^The auth
202d0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
202e0 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 is invoked as SQ
202f0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 L statements are
20300 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a being compiled.
20310 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 ** by [sqlite3_p
20320 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 repare()] or its
20330 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 variants [sqlit
20340 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
20350 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 ,.** [sqlite3_pr
20360 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b epare16()] and [
20370 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
20380 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 6_v2()]. ^At va
20390 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 rious.** points
203a0 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 during the compi
203b0 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 lation process,
203c0 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e as logic is bein
203d0 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 g created.** to
203e0 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 perform various
203f0 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 actions, the aut
20400 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
20410 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a is invoked to.*
20420 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 * see if those a
20430 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 ctions are allow
20440 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 ed. ^The author
20450 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 izer callback sh
20460 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b ould.** return [
20470 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c SQLITE_OK] to al
20480 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 low the action,
20490 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 [SQLITE_IGNORE]
204a0 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a to disallow the.
204b0 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 ** specific acti
204c0 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 on but allow the
204d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
204e0 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 o continue to be
204f0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 .** compiled, or
20500 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 [SQLITE_DENY] t
20510 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 o cause the enti
20520 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 re SQL statement
20530 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 to be.** reject
20540 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 ed with an error
20550 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f . ^If the autho
20560 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 rizer callback r
20570 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 eturns.** any va
20580 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b lue other than [
20590 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 SQLITE_IGNORE],
205a0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 [SQLITE_OK], or
205b0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a [SQLITE_DENY].**
205c0 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 then the [sqlit
205d0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
205e0 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 or equivalent c
205f0 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 all that trigger
20600 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 ed.** the author
20610 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 izer will fail w
20620 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 ith an error mes
20630 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e sage..**.** When
20640 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
20650 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b turns [SQLITE_OK
20660 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 ], that means th
20670 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 e operation.** r
20680 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 equested is ok.
20690 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 ^When the callb
206a0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ack returns [SQL
206b0 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a ITE_DENY], the.*
206c0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
206d0 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 re_v2()] or equi
206e0 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 valent call that
206f0 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a triggered the.*
20700 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c * authorizer wil
20710 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 l fail with an e
20720 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 rror message exp
20730 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 laining that.**
20740 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 access is denied
20750 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 . .**.** ^The fi
20760 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f rst parameter to
20770 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
20780 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f callback is a co
20790 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a py of the third.
207a0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 ** parameter to
207b0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f the sqlite3_set_
207c0 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 authorizer() int
207d0 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 erface. ^The sec
207e0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a ond parameter.**
207f0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
20800 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b is an integer [
20810 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 SQLITE_COPY | ac
20820 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 tion code] that
20830 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 specifies.** the
20840 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 particular acti
20850 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 on to be authori
20860 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 zed. ^The third
20870 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 through sixth pa
20880 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 rameters.** to t
20890 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 he callback are
208a0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
208b0 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e strings that con
208c0 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a tain additional.
208d0 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 ** details about
208e0 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 the action to b
208f0 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a e authorized..**
20900 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 .** ^If the acti
20910 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 on code is [SQLI
20920 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 TE_READ].** and
20930 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 the callback ret
20940 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e urns [SQLITE_IGN
20950 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a ORE] then the.**
20960 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
20970 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 ment] statement
20980 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 is constructed t
20990 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 o substitute.**
209a0 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 a NULL value in
209b0 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 place of the tab
209c0 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 le column that w
209d0 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 ould have.** bee
209e0 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 n read if [SQLIT
209f0 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 E_OK] had been r
20a00 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 eturned. The [S
20a10 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a QLITE_IGNORE].**
20a20 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 return can be u
20a30 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 sed to deny an u
20a40 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63 ntrusted user ac
20a50 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 cess to individu
20a60 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 al.** columns of
20a70 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 a table..** ^If
20a80 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 the action code
20a90 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 is [SQLITE_DELE
20aa0 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c TE] and the call
20ab0 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 back returns.**
20ac0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 [SQLITE_IGNORE]
20ad0 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 then the [DELETE
20ae0 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 ] operation proc
20af0 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 eeds but the.**
20b00 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 [truncate optimi
20b10 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 zation] is disab
20b20 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 led and all rows
20b30 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 are deleted ind
20b40 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a ividually..**.**
20b50 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 An authorizer i
20b60 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c s used when [sql
20b70 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 ite3_prepare | p
20b80 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c reparing].** SQL
20b90 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d statements from
20ba0 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f an untrusted so
20bb0 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 urce, to ensure
20bc0 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 that the SQL sta
20bd0 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f tements.** do no
20be0 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 t try to access
20bf0 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f data they are no
20c00 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 t allowed to see
20c10 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 , or that they d
20c20 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 o not.** try to
20c30 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 execute maliciou
20c40 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 s statements tha
20c50 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 t damage the dat
20c60 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 abase. For.** e
20c70 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 xample, an appli
20c80 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 cation may allow
20c90 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 a user to enter
20ca0 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 arbitrary.** SQ
20cb0 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 L queries for ev
20cc0 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 aluation by a da
20cd0 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 tabase. But the
20ce0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 application doe
20cf0 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 s.** not want th
20d00 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c e user to be abl
20d10 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 e to make arbitr
20d20 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 ary changes to t
20d30 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 he.** database.
20d40 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 An authorizer c
20d50 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 ould then be put
20d60 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 in place while
20d70 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 the.** user-ente
20d80 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 red SQL is being
20d90 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
20da0 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 e | prepared] th
20db0 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 at.** disallows
20dc0 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 everything excep
20dd0 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 t [SELECT] state
20de0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 ments..**.** App
20df0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e lications that n
20e00 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 eed to process S
20e10 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 QL from untruste
20e20 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 d sources.** mig
20e30 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 ht also consider
20e40 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 lowering resour
20e50 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 ce limits using
20e60 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 [sqlite3_limit()
20e70 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e ].** and limitin
20e80 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 g database size
20e90 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 using the [max_p
20ea0 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 age_count] [PRAG
20eb0 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 MA].** in additi
20ec0 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 on to using an a
20ed0 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a uthorizer..**.**
20ee0 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 ^(Only a single
20ef0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 authorizer can
20f00 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 be in place on a
20f10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
20f20 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d tion.** at a tim
20f30 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f e. Each call to
20f40 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 sqlite3_set_aut
20f50 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 horizer override
20f60 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 s the.** previou
20f70 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 s call.)^ ^Disa
20f80 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a ble the authoriz
20f90 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 er by installing
20fa0 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b a NULL callback
20fb0 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 ..** The authori
20fc0 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 zer is disabled
20fd0 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a by default..**.*
20fe0 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 * The authorizer
20ff0 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e callback must n
21000 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 ot do anything t
21010 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a hat will modify.
21020 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
21030 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 connection that
21040 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 invoked the auth
21050 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e orizer callback.
21060 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 .** Note that [s
21070 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
21080 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 2()] and [sqlite
21090 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 3_step()] both m
210a0 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 odify their.** d
210b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
210c0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e ons for the mean
210d0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 ing of "modify"
210e0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 in this paragrap
210f0 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b h..**.** ^When [
21100 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
21110 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f v2()] is used to
21120 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 prepare a state
21130 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 ment, the.** sta
21140 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 tement might be
21150 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 re-prepared duri
21160 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ng [sqlite3_step
21170 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a ()] due to a .**
21180 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 schema change.
21190 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c Hence, the appl
211a0 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 ication should e
211b0 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a nsure that the.*
211c0 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 * correct author
211d0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 izer callback re
211e0 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 mains in place d
211f0 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 uring the [sqlit
21200 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a e3_step()]..**.*
21210 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 * ^Note that the
21220 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
21230 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
21240 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b only during.** [
21250 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
21260 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e )] or its varian
21270 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 ts. Authorizati
21280 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 on is not.** per
21290 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 formed during st
212a0 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 atement evaluati
212b0 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 on in [sqlite3_s
212c0 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a tep()], unless.*
212d0 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 * as stated in t
212e0 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 he previous para
212f0 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 graph, sqlite3_s
21300 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a tep() invokes.**
21310 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
21320 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 _v2() to reprepa
21330 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 re a statement a
21340 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 fter a schema ch
21350 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c ange..*/.int sql
21360 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
21370 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c zer(. sqlite3*,
21380 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 . int (*xAuth)(
21390 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 void*,int,const
213a0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 char*,const char
213b0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f *,const char*,co
213c0 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f nst char*),. vo
213d0 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b id *pUserData.);
213e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
213f0 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 : Authorizer Ret
21400 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 urn Codes.**.**
21410 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 The [sqlite3_set
21420 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 _authorizer | au
21430 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
21440 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 k function] must
21450 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 .** return eithe
21460 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 r [SQLITE_OK] or
21470 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 one of these tw
21480 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f o constants in o
21490 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 rder.** to signa
214a0 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 l SQLite whether
214b0 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 or not the acti
214c0 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e on is permitted.
214d0 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 See the.** [sq
214e0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
214f0 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 izer | authorize
21500 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d r documentation]
21510 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a for additional.
21520 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a ** information..
21530 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 **.** Note that
21540 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 SQLITE_IGNORE is
21550 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20 also used as a
21560 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75 [conflict resolu
21570 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 tion mode].** re
21580 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 turned from the
21590 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e [sqlite3_vtab_on
215a0 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 _conflict()] int
215b0 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 erface..*/.#defi
215c0 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 ne SQLITE_DENY
215d0 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 1 /* Abort th
215e0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
215f0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f with an error */
21600 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
21610 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f IGNORE 2 /* Do
21620 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 n't allow access
21630 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 , but don't gene
21640 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f rate an error */
21650 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
21660 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 : Authorizer Act
21670 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 ion Codes.**.**
21680 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 The [sqlite3_set
21690 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 _authorizer()] i
216a0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 nterface registe
216b0 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 rs a callback fu
216c0 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 nction.** that i
216d0 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 s invoked to aut
216e0 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 horize certain S
216f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 QL statement act
21700 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 ions. The.** se
21710 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 cond parameter t
21720 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 o the callback i
21730 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 s an integer cod
21740 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 e that specifies
21750 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 .** what action
21760 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 is being authori
21770 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 zed. These are
21780 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 the integer acti
21790 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a on codes that.**
217a0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
217b0 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 callback may be
217c0 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 passed..**.** Th
217d0 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 ese action code
217e0 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 values signify w
217f0 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 hat kind of oper
21800 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a ation is to be.*
21810 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 * authorized. T
21820 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 he 3rd and 4th p
21830 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 arameters to the
21840 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a authorization.*
21850 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 * callback funct
21860 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 ion will be para
21870 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 meters or NULL d
21880 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 epending on whic
21890 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f h of these.** co
218a0 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74 des is used as t
218b0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
218c0 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 ter. ^(The 5th
218d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
218e0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 .** authorizer c
218f0 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e allback is the n
21900 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 ame of the datab
21910 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 ase ("main", "te
21920 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 mp",.** etc.) if
21930 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 applicable.)^
21940 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 ^The 6th paramet
21950 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 er to the author
21960 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a izer callback.**
21970 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 is the name of
21980 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 the inner-most t
21990 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 rigger or view t
219a0 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 hat is responsib
219b0 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 le for.** the ac
219c0 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 cess attempt or
219d0 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 NULL if this acc
219e0 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 ess attempt is d
219f0 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 irectly from.**
21a00 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f top-level SQL co
21a10 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a de..*/./********
21a20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
21a30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
21a40 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a *** 3rd ********
21a50 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a **** 4th *******
21a60 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ****/.#define SQ
21a70 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 LITE_CREATE_INDE
21a80 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f X 1 /
21a90 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 * Index Name
21aa0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
21ab0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
21ac0 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 ITE_CREATE_TABLE
21ad0 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 2 /*
21ae0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
21af0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
21b00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
21b10 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 TE_CREATE_TEMP_I
21b20 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 NDEX 3 /*
21b30 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 Index Name
21b40 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
21b50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
21b60 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 E_CREATE_TEMP_TA
21b70 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 BLE 4 /* T
21b80 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
21b90 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
21ba0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
21bb0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 _CREATE_TEMP_TRI
21bc0 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 GGER 5 /* Tr
21bd0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 igger Name Ta
21be0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
21bf0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
21c00 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 CREATE_TEMP_VIEW
21c10 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 6 /* Vie
21c20 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c w Name NUL
21c30 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
21c40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
21c50 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 REATE_TRIGGER
21c60 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 7 /* Trig
21c70 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c ger Name Tabl
21c80 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
21c90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
21ca0 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 EATE_VIEW
21cb0 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 8 /* View
21cc0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
21cd0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
21ce0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c efine SQLITE_DEL
21cf0 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 ETE
21d00 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 9 /* Table
21d10 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
21d20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
21d30 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
21d40 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 _INDEX
21d50 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 10 /* Index N
21d60 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e ame Table N
21d70 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
21d80 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
21d90 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 TABLE
21da0 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 11 /* Table Na
21db0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
21dc0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
21dd0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
21de0 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 EMP_INDEX 1
21df0 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 2 /* Index Nam
21e00 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d e Table Nam
21e10 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
21e20 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 e SQLITE_DROP_TE
21e30 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 MP_TABLE 13
21e40 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
21e50 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
21e60 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
21e70 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d SQLITE_DROP_TEM
21e80 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 P_TRIGGER 14
21e90 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d /* Trigger Nam
21ea0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 e Table Name
21eb0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
21ec0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 SQLITE_DROP_TEMP
21ed0 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 _VIEW 15
21ee0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 /* View Name
21ef0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
21f00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
21f10 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 QLITE_DROP_TRIGG
21f20 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 ER 16
21f30 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 /* Trigger Name
21f40 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
21f50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
21f60 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 LITE_DROP_VIEW
21f70 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 17 /
21f80 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 * View Name
21f90 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
21fa0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
21fb0 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 ITE_INSERT
21fc0 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 18 /*
21fd0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
21fe0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
21ff0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
22000 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 TE_PRAGMA
22010 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 19 /*
22020 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 Pragma Name
22030 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 1st arg or NULL
22040 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
22050 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 E_READ
22060 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 20 /* T
22070 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 able Name C
22080 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a olumn Name *
22090 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
220a0 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 _SELECT
220b0 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 21 /* NU
220c0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 LL NU
220d0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
220e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
220f0 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 TRANSACTION
22100 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 22 /* Ope
22110 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c ration NUL
22120 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
22130 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 #define SQLITE_U
22140 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 PDATE
22150 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 23 /* Tabl
22160 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 e Name Colu
22170 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 mn Name */.#
22180 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 define SQLITE_AT
22190 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 TACH
221a0 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 24 /* Filen
221b0 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 ame NULL
221c0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
221d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 efine SQLITE_DET
221e0 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 ACH
221f0 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 25 /* Databa
22200 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 se Name NULL
22210 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
22220 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 fine SQLITE_ALTE
22230 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 R_TABLE
22240 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 26 /* Databas
22250 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e e Name Table N
22260 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
22270 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 ine SQLITE_REIND
22280 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 EX
22290 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 27 /* Index Na
222a0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
222b0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
222c0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a ne SQLITE_ANALYZ
222d0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 E 2
222e0 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 8 /* Table Nam
222f0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
22300 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
22310 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
22320 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 VTABLE 29
22330 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
22340 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d Module Nam
22350 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 e */.#define
22360 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 SQLITE_DROP_VTA
22370 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 BLE 30
22380 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
22390 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 Module Name
223a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
223b0 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 SQLITE_FUNCTION
223c0 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 31
223d0 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 /* NULL
223e0 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d Function Nam
223f0 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 e */.#define S
22400 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 QLITE_SAVEPOINT
22410 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20 32
22420 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 /* Operation
22430 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d Savepoint Nam
22440 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 e */.#define SQ
22450 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 LITE_COPY
22460 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 0 /
22470 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 * No longer used
22480 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
22490 54 45 5f 52 45 43 55 52 53 49 56 45 20 20 20 20 TE_RECURSIVE
224a0 20 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a 20 33 /*
224b0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
224c0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
224d0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
224e0 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 EF: Tracing And
224f0 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 Profiling Functi
22500 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ons.** METHOD: s
22510 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 qlite3.**.** The
22520 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
22530 64 65 70 72 65 63 61 74 65 64 2e 20 55 73 65 20 deprecated. Use
22540 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 the [sqlite3_tra
22550 63 65 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 ce_v2()] interfa
22560 63 65 0a 2a 2a 20 69 6e 73 74 65 61 64 20 6f 66 ce.** instead of
22570 20 74 68 65 20 72 6f 75 74 69 6e 65 73 20 64 65 the routines de
22580 73 63 72 69 62 65 64 20 68 65 72 65 2e 0a 2a 2a scribed here..**
22590 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
225a0 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c es register call
225b0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 back functions t
225c0 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 hat can be used
225d0 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 for.** tracing a
225e0 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 nd profiling the
225f0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 execution of SQ
22600 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a L statements..**
22610 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 .** ^The callbac
22620 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 k function regis
22630 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 tered by sqlite3
22640 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f _trace() is invo
22650 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 ked at.** variou
22660 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 s times when an
22670 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 SQL statement is
22680 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 being run by [s
22690 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a qlite3_step()]..
226a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
226b0 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b trace() callback
226c0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 is invoked with
226d0 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 a UTF-8 renderi
226e0 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c ng of the.** SQL
226f0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 statement text
22700 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 as the statement
22710 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 first begins ex
22720 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 ecuting..** ^(Ad
22730 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 ditional sqlite3
22740 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 _trace() callbac
22750 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a ks might occur.*
22760 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65 * as each trigge
22770 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 red subprogram i
22780 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 s entered. The
22790 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 callbacks for tr
227a0 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 iggers.** contai
227b0 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f n a UTF-8 SQL co
227c0 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 mment that ident
227d0 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65 ifies the trigge
227e0 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b r.)^.**.** The [
227f0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a SQLITE_TRACE_SIZ
22800 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 E_LIMIT] compile
22810 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e -time option can
22820 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 be used to limi
22830 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 t.** the length
22840 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 of [bound parame
22850 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 ter] expansion i
22860 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 n the output of
22870 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e sqlite3_trace().
22880 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c .**.** ^The call
22890 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 back function re
228a0 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 gistered by sqli
228b0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 te3_profile() is
228c0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 invoked.** as e
228d0 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ach SQL statemen
228e0 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 t finishes. ^Th
228f0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 e profile callba
22900 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 ck contains.** t
22910 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 he original stat
22920 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 ement text and a
22930 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 n estimate of wa
22940 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a ll-clock time.**
22950 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 of how long tha
22960 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b t statement took
22970 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 to run. ^The p
22980 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a rofile callback.
22990 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e ** time is in un
229a0 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e its of nanosecon
229b0 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 ds, however the
229c0 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e current implemen
229d0 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c tation.** is onl
229e0 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c y capable of mil
229f0 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 lisecond resolut
22a00 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c ion so the six l
22a10 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 east significant
22a20 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 .** digits in th
22a30 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 e time are meani
22a40 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 ngless. Future
22a50 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
22a60 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 te.** might prov
22a70 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f ide greater reso
22a80 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 lution on the pr
22a90 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e ofiler callback.
22aa0 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 The.** sqlite3
22ab0 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 _profile() funct
22ac0 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 ion is considere
22ad0 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 d experimental a
22ae0 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 nd is.** subject
22af0 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 to change in fu
22b00 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 ture versions of
22b10 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 SQLite..*/.SQLI
22b20 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f TE_DEPRECATED vo
22b30 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 id *sqlite3_trac
22b40 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 e(sqlite3*,. v
22b50 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 oid(*xTrace)(voi
22b60 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c d*,const char*),
22b70 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f void*);.SQLITE_
22b80 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 DEPRECATED void
22b90 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 *sqlite3_profile
22ba0 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f (sqlite3*,. vo
22bb0 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f id(*xProfile)(vo
22bc0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c id*,const char*,
22bd0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c sqlite3_uint64),
22be0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 void*);../*.**
22bf0 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 54 72 CAPI3REF: SQL Tr
22c00 61 63 65 20 45 76 65 6e 74 20 43 6f 64 65 73 0a ace Event Codes.
22c10 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c ** KEYWORDS: SQL
22c20 49 54 45 5f 54 52 41 43 45 0a 2a 2a 0a 2a 2a 20 ITE_TRACE.**.**
22c30 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 These constants
22c40 69 64 65 6e 74 69 66 79 20 63 6c 61 73 73 65 73 identify classes
22c50 20 6f 66 20 65 76 65 6e 74 73 20 74 68 61 74 20 of events that
22c60 63 61 6e 20 62 65 20 6d 6f 6e 69 74 6f 72 65 64 can be monitored
22c70 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 73 .** using the [s
22c80 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 qlite3_trace_v2(
22c90 29 5d 20 74 72 61 63 69 6e 67 20 6c 6f 67 69 63 )] tracing logic
22ca0 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 . The third arg
22cb0 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c ument.** to [sql
22cc0 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d ite3_trace_v2()]
22cd0 20 69 73 20 61 6e 20 4f 52 2d 65 64 20 63 6f 6d is an OR-ed com
22ce0 62 69 6e 61 74 69 6f 6e 20 6f 66 20 6f 6e 65 20 bination of one
22cf0 6f 72 20 6d 6f 72 65 20 6f 66 0a 2a 2a 20 74 68 or more of.** th
22d00 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 e following cons
22d10 74 61 6e 74 73 2e 20 20 5e 54 68 65 20 66 69 72 tants. ^The fir
22d20 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 st argument to t
22d30 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 he trace callbac
22d40 6b 0a 2a 2a 20 69 73 20 6f 6e 65 20 6f 66 20 74 k.** is one of t
22d50 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e he following con
22d60 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 stants..**.** Ne
22d70 77 20 74 72 61 63 69 6e 67 20 63 6f 6e 73 74 61 w tracing consta
22d80 6e 74 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 nts may be added
22d90 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 in future relea
22da0 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 ses..**.** ^A tr
22db0 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 68 61 73 ace callback has
22dc0 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a four arguments:
22dd0 20 78 43 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 xCallback(T,C,P
22de0 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 ,X)..** ^The T a
22df0 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f rgument is one o
22e00 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 74 79 f the integer ty
22e10 70 65 20 63 6f 64 65 73 20 61 62 6f 76 65 2e 0a pe codes above..
22e20 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65 ** ^The C argume
22e30 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 nt is a copy of
22e40 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e the context poin
22e50 74 65 72 20 70 61 73 73 65 64 20 69 6e 20 61 73 ter passed in as
22e60 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 61 the.** fourth a
22e70 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 rgument to [sqli
22e80 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 2e te3_trace_v2()].
22e90 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20 .** The P and X
22ea0 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f arguments are po
22eb0 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61 inters whose mea
22ec0 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 nings depend on
22ed0 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a T..**.** <dl>.**
22ee0 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f [[SQLITE_TRACE_
22ef0 53 54 4d 54 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 STMT]] <dt>SQLIT
22f00 45 5f 54 52 41 43 45 5f 53 54 4d 54 3c 2f 64 74 E_TRACE_STMT</dt
22f10 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c >.** <dd>^An SQL
22f20 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 63 ITE_TRACE_STMT c
22f30 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
22f40 65 64 20 77 68 65 6e 20 61 20 70 72 65 70 61 72 ed when a prepar
22f50 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 ed statement.**
22f60 66 69 72 73 74 20 62 65 67 69 6e 73 20 72 75 6e first begins run
22f70 6e 69 6e 67 20 61 6e 64 20 70 6f 73 73 69 62 6c ning and possibl
22f80 79 20 61 74 20 6f 74 68 65 72 20 74 69 6d 65 73 y at other times
22f90 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 65 during the.** e
22fa0 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 xecution of the
22fb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
22fc0 6e 74 2c 20 73 75 63 68 20 61 73 20 61 74 20 74 nt, such as at t
22fd0 68 65 20 73 74 61 72 74 20 6f 66 20 65 61 63 68 he start of each
22fe0 0a 2a 2a 20 74 72 69 67 67 65 72 20 73 75 62 70 .** trigger subp
22ff0 72 6f 67 72 61 6d 2e 20 5e 54 68 65 20 50 20 61 rogram. ^The P a
23000 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 rgument is a poi
23010 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b nter to the.** [
23020 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
23030 6e 74 5d 2e 20 5e 54 68 65 20 58 20 61 72 67 75 nt]. ^The X argu
23040 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 ment is a pointe
23050 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 r to a string wh
23060 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 75 6e ich.** is the un
23070 65 78 70 61 6e 64 65 64 20 53 51 4c 20 74 65 78 expanded SQL tex
23080 74 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 t of the prepare
23090 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 20 61 d statement or a
230a0 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 0a 2a n SQL comment .*
230b0 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 * that indicates
230c0 20 74 68 65 20 69 6e 76 6f 63 61 74 69 6f 6e 20 the invocation
230d0 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20 20 5e of a trigger. ^
230e0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e The callback can
230f0 20 63 6f 6d 70 75 74 65 0a 2a 2a 20 74 68 65 20 compute.** the
23100 73 61 6d 65 20 74 65 78 74 20 74 68 61 74 20 77 same text that w
23110 6f 75 6c 64 20 68 61 76 65 20 62 65 65 6e 20 72 ould have been r
23120 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 6c eturned by the l
23130 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 74 egacy [sqlite3_t
23140 72 61 63 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 race()].** inter
23150 66 61 63 65 20 62 79 20 75 73 69 6e 67 20 74 68 face by using th
23160 65 20 58 20 61 72 67 75 6d 65 6e 74 20 77 68 65 e X argument whe
23170 6e 20 58 20 62 65 67 69 6e 73 20 77 69 74 68 20 n X begins with
23180 22 2d 2d 22 20 61 6e 64 20 69 6e 76 6f 6b 69 6e "--" and invokin
23190 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 g.** [sqlite3_ex
231a0 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 5d 20 6f panded_sql(P)] o
231b0 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 therwise..**.**
231c0 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 [[SQLITE_TRACE_P
231d0 52 4f 46 49 4c 45 5d 5d 20 3c 64 74 3e 53 51 4c ROFILE]] <dt>SQL
231e0 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c ITE_TRACE_PROFIL
231f0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 E</dt>.** <dd>^A
23200 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 n SQLITE_TRACE_P
23210 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 ROFILE callback
23220 70 72 6f 76 69 64 65 73 20 61 70 70 72 6f 78 69 provides approxi
23230 6d 61 74 65 6c 79 20 74 68 65 20 73 61 6d 65 0a mately the same.
23240 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 ** information a
23250 73 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 s is provided by
23260 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 the [sqlite3_pr
23270 6f 66 69 6c 65 28 29 5d 20 63 61 6c 6c 62 61 63 ofile()] callbac
23280 6b 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 k..** ^The P arg
23290 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 ument is a point
232a0 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 er to the [prepa
232b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 red statement] a
232c0 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 nd the.** X argu
232d0 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 ment points to a
232e0 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 64-bit integer
232f0 77 68 69 63 68 20 69 73 20 74 68 65 20 65 73 74 which is the est
23300 69 6d 61 74 65 64 20 6f 66 0a 2a 2a 20 74 68 65 imated of.** the
23310 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 number of nanos
23320 65 63 6f 6e 64 20 74 68 61 74 20 74 68 65 20 70 econd that the p
23330 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
23340 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a t took to run..*
23350 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 54 52 * ^The SQLITE_TR
23360 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c ACE_PROFILE call
23370 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
23380 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 when the stateme
23390 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a nt finishes..**.
233a0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 ** [[SQLITE_TRAC
233b0 45 5f 52 4f 57 5d 5d 20 3c 64 74 3e 53 51 4c 49 E_ROW]] <dt>SQLI
233c0 54 45 5f 54 52 41 43 45 5f 52 4f 57 3c 2f 64 74 TE_TRACE_ROW</dt
233d0 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c >.** <dd>^An SQL
233e0 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 63 61 ITE_TRACE_ROW ca
233f0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
23400 64 20 77 68 65 6e 65 76 65 72 20 61 20 70 72 65 d whenever a pre
23410 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 pared.** stateme
23420 6e 74 20 67 65 6e 65 72 61 74 65 73 20 61 20 73 nt generates a s
23430 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 72 65 73 ingle row of res
23440 75 6c 74 2e 20 20 0a 2a 2a 20 5e 54 68 65 20 50 ult. .** ^The P
23450 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 argument is a p
23460 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 70 ointer to the [p
23470 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
23480 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 t] and the.** X
23490 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 argument is unus
234a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 ed..**.** [[SQLI
234b0 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 5d 5d TE_TRACE_CLOSE]]
234c0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 <dt>SQLITE_TRAC
234d0 45 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 E_CLOSE</dt>.**
234e0 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 <dd>^An SQLITE_T
234f0 52 41 43 45 5f 43 4c 4f 53 45 20 63 61 6c 6c 62 RACE_CLOSE callb
23500 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 ack is invoked w
23510 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 0a 2a hen a database.*
23520 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f * connection clo
23530 73 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 ses..** ^The P a
23540 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 rgument is a poi
23550 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 nter to the [dat
23560 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
23570 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 ] object.** and
23580 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69 the X argument i
23590 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 s unused..** </d
235a0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 l>.*/.#define SQ
235b0 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 LITE_TRACE_STMT
235c0 20 20 20 20 20 20 30 78 30 31 0a 23 64 65 66 69 0x01.#defi
235d0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f ne SQLITE_TRACE_
235e0 50 52 4f 46 49 4c 45 20 20 20 20 30 78 30 32 0a PROFILE 0x02.
235f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
23600 52 41 43 45 5f 52 4f 57 20 20 20 20 20 20 20 20 RACE_ROW
23610 30 78 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 0x04.#define SQL
23620 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20 ITE_TRACE_CLOSE
23630 20 20 20 20 20 30 78 30 38 0a 0a 2f 2a 0a 2a 2a 0x08../*.**
23640 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 54 CAPI3REF: SQL T
23650 72 61 63 65 20 48 6f 6f 6b 0a 2a 2a 20 4d 45 54 race Hook.** MET
23660 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
23670 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
23680 74 72 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 trace_v2(D,M,X,P
23690 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 ) interface regi
236a0 73 74 65 72 73 20 61 20 74 72 61 63 65 20 63 61 sters a trace ca
236b0 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 llback.** functi
236c0 6f 6e 20 58 20 61 67 61 69 6e 73 74 20 5b 64 61 on X against [da
236d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
236e0 6e 5d 20 44 2c 20 75 73 69 6e 67 20 70 72 6f 70 n] D, using prop
236f0 65 72 74 79 20 6d 61 73 6b 20 4d 0a 2a 2a 20 61 erty mask M.** a
23700 6e 64 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 nd context point
23710 65 72 20 50 2e 20 20 5e 49 66 20 74 68 65 20 58 er P. ^If the X
23720 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20 callback is.**
23730 4e 55 4c 4c 20 6f 72 20 69 66 20 74 68 65 20 4d NULL or if the M
23740 20 6d 61 73 6b 20 69 73 20 7a 65 72 6f 2c 20 74 mask is zero, t
23750 68 65 6e 20 74 72 61 63 69 6e 67 20 69 73 20 64 hen tracing is d
23760 69 73 61 62 6c 65 64 2e 20 20 54 68 65 0a 2a 2a isabled. The.**
23770 20 4d 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 M argument shou
23780 6c 64 20 62 65 20 74 68 65 20 62 69 74 77 69 73 ld be the bitwis
23790 65 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 e OR-ed combinat
237a0 69 6f 6e 20 6f 66 0a 2a 2a 20 7a 65 72 6f 20 6f ion of.** zero o
237b0 72 20 6d 6f 72 65 20 5b 53 51 4c 49 54 45 5f 54 r more [SQLITE_T
237c0 52 41 43 45 5d 20 63 6f 6e 73 74 61 6e 74 73 2e RACE] constants.
237d0 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 63 61 6c .**.** ^Each cal
237e0 6c 20 74 6f 20 65 69 74 68 65 72 20 73 71 6c 69 l to either sqli
237f0 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20 73 te3_trace() or s
23800 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 qlite3_trace_v2(
23810 29 20 6f 76 65 72 72 69 64 65 73 20 0a 2a 2a 20 ) overrides .**
23820 28 63 61 6e 63 65 6c 73 29 20 61 6e 79 20 70 72 (cancels) any pr
23830 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c ior calls to sql
23840 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20 ite3_trace() or
23850 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 sqlite3_trace_v2
23860 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 58 ()..**.** ^The X
23870 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
23880 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e oked whenever an
23890 79 20 6f 66 20 74 68 65 20 65 76 65 6e 74 73 20 y of the events
238a0 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 0a 2a identified by .*
238b0 2a 20 6d 61 73 6b 20 4d 20 6f 63 63 75 72 2e 20 * mask M occur.
238c0 20 5e 54 68 65 20 69 6e 74 65 67 65 72 20 72 65 ^The integer re
238d0 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 turn value from
238e0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 the callback is
238f0 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 69 67 6e currently.** ign
23900 6f 72 65 64 2c 20 74 68 6f 75 67 68 20 74 68 69 ored, though thi
23910 73 20 6d 61 79 20 63 68 61 6e 67 65 20 69 6e 20 s may change in
23920 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e future releases.
23930 20 20 43 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6d Callback.** im
23940 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 plementations sh
23950 6f 75 6c 64 20 72 65 74 75 72 6e 20 7a 65 72 6f ould return zero
23960 20 74 6f 20 65 6e 73 75 72 65 20 66 75 74 75 72 to ensure futur
23970 65 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e e compatibility.
23980 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 .**.** ^A trace
23990 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
239a0 6b 65 64 20 77 69 74 68 20 66 6f 75 72 20 61 72 ked with four ar
239b0 67 75 6d 65 6e 74 73 3a 20 63 61 6c 6c 62 61 63 guments: callbac
239c0 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e k(T,C,P,X)..** ^
239d0 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69 The T argument i
239e0 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 53 51 s one of the [SQ
239f0 4c 49 54 45 5f 54 52 41 43 45 5d 0a 2a 2a 20 63 LITE_TRACE].** c
23a00 6f 6e 73 74 61 6e 74 73 20 74 6f 20 69 6e 64 69 onstants to indi
23a10 63 61 74 65 20 77 68 79 20 74 68 65 20 63 61 6c cate why the cal
23a20 6c 62 61 63 6b 20 77 61 73 20 69 6e 76 6f 6b 65 lback was invoke
23a30 64 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 d..** ^The C arg
23a40 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79 20 ument is a copy
23a50 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20 70 of the context p
23a60 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 65 20 50 ointer..** The P
23a70 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73 and X arguments
23a80 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68 are pointers wh
23a90 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 ose meanings dep
23aa0 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 end on T..**.**
23ab0 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 The sqlite3_trac
23ac0 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 e_v2() interface
23ad0 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 is intended to
23ae0 72 65 70 6c 61 63 65 20 74 68 65 20 6c 65 67 61 replace the lega
23af0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 cy.** interfaces
23b00 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 [sqlite3_trace(
23b10 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
23b20 70 72 6f 66 69 6c 65 28 29 5d 2c 20 62 6f 74 68 profile()], both
23b30 20 6f 66 20 77 68 69 63 68 0a 2a 2a 20 61 72 65 of which.** are
23b40 20 64 65 70 72 65 63 61 74 65 64 2e 0a 2a 2f 0a deprecated..*/.
23b50 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 63 int sqlite3_trac
23b60 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a e_v2(. sqlite3*
23b70 2c 0a 20 20 75 6e 73 69 67 6e 65 64 20 75 4d 61 ,. unsigned uMa
23b80 73 6b 2c 0a 20 20 69 6e 74 28 2a 78 43 61 6c 6c sk,. int(*xCall
23b90 62 61 63 6b 29 28 75 6e 73 69 67 6e 65 64 2c 76 back)(unsigned,v
23ba0 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a oid*,void*,void*
23bb0 29 2c 0a 20 20 76 6f 69 64 20 2a 70 43 74 78 0a ),. void *pCtx.
23bc0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
23bd0 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 EF: Query Progre
23be0 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 ss Callbacks.**
23bf0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
23c00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
23c10 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 e3_progress_hand
23c20 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 ler(D,N,X,P) int
23c30 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68 erface causes th
23c40 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 e callback.** fu
23c50 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 nction X to be i
23c60 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 nvoked periodica
23c70 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 lly during long
23c80 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f running calls to
23c90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 .** [sqlite3_exe
23ca0 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 c()], [sqlite3_s
23cb0 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 tep()] and [sqli
23cc0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d te3_get_table()]
23cd0 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 for.** database
23ce0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 connection D.
23cf0 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 An example use f
23d00 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 or this.** inter
23d10 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 face is to keep
23d20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 a GUI updated du
23d30 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 ring a large que
23d40 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 ry..**.** ^The p
23d50 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 arameter P is pa
23d60 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 ssed through as
23d70 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 the only paramet
23d80 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 er to the .** ca
23d90 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
23da0 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 X. ^The paramet
23db0 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 72 er N is the appr
23dc0 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f oximate number o
23dd0 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d f .** [virtual m
23de0 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 achine instructi
23df0 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 ons] that are ev
23e00 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 aluated between
23e10 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e successive.** in
23e20 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 vocations of the
23e30 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 callback X. ^I
23e40 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e f N is less than
23e50 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72 one then the pr
23e60 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 ogress.** handle
23e70 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a r is disabled..*
23e80 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e *.** ^Only a sin
23e90 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e gle progress han
23ea0 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 dler may be defi
23eb0 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 ned at one time
23ec0 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 per.** [database
23ed0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 connection]; se
23ee0 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 tting a new prog
23ef0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e ress handler can
23f00 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 cels the.** old
23f10 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 one. ^Setting p
23f20 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 arameter X to NU
23f30 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 LL disables the
23f40 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 progress handler
23f50 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 ..** ^The progre
23f60 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c ss handler is al
23f70 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 so disabled by s
23f80 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 etting N to a va
23f90 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e lue less.** than
23fa0 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 1..**.** ^If th
23fb0 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 e progress callb
23fc0 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d ack returns non-
23fd0 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 zero, the operat
23fe0 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 ion is.** interr
23ff0 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 upted. This fea
24000 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 ture can be used
24010 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a to implement a.
24020 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 ** "Cancel" butt
24030 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 on on a GUI prog
24040 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e ress dialog box.
24050 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 .**.** The progr
24060 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c ess handler call
24070 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f back must not do
24080 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 anything that w
24090 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 ill modify.** th
240a0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
240b0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b ction that invok
240c0 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 ed the progress
240d0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 handler..** Note
240e0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 that [sqlite3_p
240f0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 repare_v2()] and
24100 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
24110 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 ] both modify th
24120 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 eir.** database
24130 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 connections for
24140 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 the meaning of "
24150 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 modify" in this
24160 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f paragraph..**.*/
24170 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 .void sqlite3_pr
24180 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 ogress_handler(s
24190 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e qlite3*, int, in
241a0 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 t(*)(void*), voi
241b0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d*);../*.** CAPI
241c0 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 3REF: Opening A
241d0 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e New Database Con
241e0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 nection.** CONST
241f0 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a RUCTOR: sqlite3.
24200 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 **.** ^These rou
24210 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 tines open an SQ
24220 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69 Lite database fi
24230 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20 le as specified
24240 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e by the .** filen
24250 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 ame argument. ^T
24260 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 he filename argu
24270 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 ment is interpre
24280 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 ted as UTF-8 for
24290 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e .** sqlite3_open
242a0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f () and sqlite3_o
242b0 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 pen_v2() and as
242c0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 UTF-16 in the na
242d0 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 tive byte.** ord
242e0 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f er for sqlite3_o
242f0 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 pen16(). ^(A [da
24300 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
24310 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 n] handle is usu
24320 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 ally.** returned
24330 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 in *ppDb, even
24340 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 if an error occu
24350 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 rs. The only ex
24360 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a ception is that.
24370 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 ** if SQLite is
24380 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 unable to alloca
24390 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c te memory to hol
243a0 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 d the [sqlite3]
243b0 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c object,.** a NUL
243c0 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 L will be writte
243d0 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 n into *ppDb ins
243e0 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 tead of a pointe
243f0 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 r to the [sqlite
24400 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 3].** object.)^
24410 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73 ^(If the databas
24420 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 e is opened (and
24430 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63 /or created) suc
24440 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a cessfully, then.
24450 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 ** [SQLITE_OK] i
24460 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 s returned. Oth
24470 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 erwise an [error
24480 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e code] is return
24490 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 ed.)^ ^The.** [s
244a0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d qlite3_errmsg()]
244b0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 or [sqlite3_err
244c0 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 msg16()] routine
244d0 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f s can be used to
244e0 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e obtain.** an En
244f0 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 glish language d
24500 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 escription of th
24510 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e e error followin
24520 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 g a failure of a
24530 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c ny.** of the sql
24540 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 ite3_open() rout
24550 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ines..**.** ^The
24560 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e default encodin
24570 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 g will be UTF-8
24580 66 6f 72 20 64 61 74 61 62 61 73 65 73 20 63 72 for databases cr
24590 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 eated using.** s
245a0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 qlite3_open() or
245b0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
245c0 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c (). ^The defaul
245d0 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 t encoding for d
245e0 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 atabases.** crea
245f0 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 ted using sqlite
24600 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 3_open16() will
24610 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 be UTF-16 in the
24620 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
24630 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 er..**.** Whethe
24640 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f r or not an erro
24650 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 r occurs when it
24660 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f is opened, reso
24670 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 urces.** associa
24680 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 ted with the [da
24690 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
246a0 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 n] handle should
246b0 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a be released by.
246c0 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f ** passing it to
246d0 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 [sqlite3_close(
246e0 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f )] when it is no
246f0 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 longer required
24700 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
24710 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e te3_open_v2() in
24720 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 terface works li
24730 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 ke sqlite3_open(
24740 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 ).** except that
24750 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 it accepts two
24760 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d additional param
24770 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 eters for additi
24780 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 onal control.**
24790 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 over the new dat
247a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
247b0 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 . ^(The flags p
247c0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 arameter to.** s
247d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
247e0 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 can take one of
247f0 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e .** the followin
24800 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 g three values,
24810 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 optionally combi
24820 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a ned with the .**
24830 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f [SQLITE_OPEN_NO
24840 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f MUTEX], [SQLITE_
24850 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c OPEN_FULLMUTEX],
24860 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 [SQLITE_OPEN_SH
24870 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b AREDCACHE],.** [
24880 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 SQLITE_OPEN_PRIV
24890 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f ATECACHE], and/o
248a0 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 r [SQLITE_OPEN_U
248b0 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a RI] flags:)^.**.
248c0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 ** <dl>.** ^(<dt
248d0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 >[SQLITE_OPEN_RE
248e0 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 ADONLY]</dt>.**
248f0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 <dd>The database
24900 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 is opened in re
24910 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 ad-only mode. I
24920 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 f the database d
24930 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 oes not.** alrea
24940 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 dy exist, an err
24950 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c or is returned.<
24960 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c /dd>)^.**.** ^(<
24970 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f dt>[SQLITE_OPEN_
24980 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a READWRITE]</dt>.
24990 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 ** <dd>The datab
249a0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f ase is opened fo
249b0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 r reading and wr
249c0 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c iting if possibl
249d0 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a e, or reading.**
249e0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c only if the fil
249f0 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 e is write prote
24a00 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 cted by the oper
24a10 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 ating system. I
24a20 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 n either.** case
24a30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 the database mu
24a40 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 st already exist
24a50 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 , otherwise an e
24a60 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 rror is returned
24a70 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e .</dd>)^.**.** ^
24a80 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 (<dt>[SQLITE_OPE
24a90 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b N_READWRITE] | [
24aa0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 SQLITE_OPEN_CREA
24ab0 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TE]</dt>.** <dd>
24ac0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 The database is
24ad0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 opened for readi
24ae0 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 ng and writing,
24af0 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69 and is created i
24b00 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 f.** it does not
24b10 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 already exist.
24b20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 This is the beha
24b30 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 vior that is alw
24b40 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 ays used for.**
24b50 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 sqlite3_open() a
24b60 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 nd sqlite3_open1
24b70 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 6().</dd>)^.** <
24b80 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 /dl>.**.** If th
24b90 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 e 3rd parameter
24ba0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f to sqlite3_open_
24bb0 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 v2() is not one
24bc0 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e of the.** combin
24bd0 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f ations shown abo
24be0 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f ve optionally co
24bf0 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 mbined with othe
24c00 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 r.** [SQLITE_OPE
24c10 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c N_READONLY | SQL
24c20 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d ITE_OPEN_* bits]
24c30 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 .** then the beh
24c40 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e avior is undefin
24c50 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 ed..**.** ^If th
24c60 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e e [SQLITE_OPEN_N
24c70 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 OMUTEX] flag is
24c80 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 set, then the da
24c90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
24ca0 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 n.** opens in th
24cb0 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b e multi-thread [
24cc0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
24cd0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 as long as the s
24ce0 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 ingle-thread.**
24cf0 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 mode has not bee
24d00 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 n set at compile
24d10 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 -time or start-t
24d20 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a ime. ^If the.**
24d30 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 [SQLITE_OPEN_FU
24d40 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 LLMUTEX] flag is
24d50 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 set then the da
24d60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
24d70 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 n opens.** in th
24d80 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 e serialized [th
24d90 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e reading mode] un
24da0 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 less single-thre
24db0 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f ad was.** previo
24dc0 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 usly selected at
24dd0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 compile-time or
24de0 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 start-time..**
24df0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 ^The [SQLITE_OPE
24e00 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 N_SHAREDCACHE] f
24e10 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 lag causes the d
24e20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
24e30 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 on to be.** elig
24e40 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 ible to use [sha
24e50 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c red cache mode],
24e60 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 regardless of w
24e70 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 hether or not sh
24e80 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 ared.** cache is
24e90 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b enabled using [
24ea0 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 sqlite3_enable_s
24eb0 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 hared_cache()].
24ec0 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 ^The.** [SQLITE
24ed0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 _OPEN_PRIVATECAC
24ee0 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 HE] flag causes
24ef0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
24f00 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a nection to not.*
24f10 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e * participate in
24f20 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d [shared cache m
24f30 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 ode] even if it
24f40 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a is enabled..**.*
24f50 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 * ^The fourth pa
24f60 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
24f70 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 e3_open_v2() is
24f80 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a the name of the.
24f90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d ** [sqlite3_vfs]
24fa0 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 object that def
24fb0 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 ines the operati
24fc0 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 ng system interf
24fd0 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 ace that.** the
24fe0 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e new database con
24ff0 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 nection should u
25000 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 se. ^If the fou
25010 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 rth parameter is
25020 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 .** a NULL point
25030 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 er then the defa
25040 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 ult [sqlite3_vfs
25050 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 ] object is used
25060 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
25070 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 filename is ":me
25080 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 mory:", then a p
25090 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 rivate, temporar
250a0 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 y in-memory data
250b0 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 base.** is creat
250c0 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 ed for the conne
250d0 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e ction. ^This in
250e0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 -memory database
250f0 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 will vanish whe
25100 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 n.** the databas
25110 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
25120 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 closed. Future
25130 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
25140 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 te might.** make
25150 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e use of addition
25160 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e al special filen
25170 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 ames that begin
25180 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 with the ":" cha
25190 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 racter..** It is
251a0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 recommended tha
251b0 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 t when a databas
251c0 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 e filename actua
251d0 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 lly does begin w
251e0 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 ith.** a ":" cha
251f0 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c racter you shoul
25200 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c d prefix the fil
25210 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 ename with a pat
25220 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a hname such as.**
25230 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 "./" to avoid a
25240 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 mbiguity..**.**
25250 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 ^If the filename
25260 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 is an empty str
25270 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 ing, then a priv
25280 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a ate, temporary.*
25290 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 * on-disk databa
252a0 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 se will be creat
252b0 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 ed. ^This priva
252c0 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c te database will
252d0 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 be.** automatic
252e0 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 ally deleted as
252f0 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 soon as the data
25300 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
25310 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a is closed..**.**
25320 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 [[URI filenames
25330 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e in sqlite3_open
25340 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c ()]] <h3>URI Fil
25350 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a enames</h3>.**.*
25360 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e * ^If [URI filen
25370 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 ame] interpretat
25380 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 ion is enabled,
25390 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 and the filename
253a0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 argument.** beg
253b0 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 ins with "file:"
253c0 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e , then the filen
253d0 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 ame is interpret
253e0 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 ed as a URI. ^UR
253f0 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e I.** filename in
25400 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 terpretation is
25410 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b enabled if the [
25420 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d SQLITE_OPEN_URI]
25430 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 flag is.** set
25440 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 in the fourth ar
25450 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
25460 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 3_open_v2(), or
25470 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 if it has.** bee
25480 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c n enabled global
25490 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 ly using the [SQ
254a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d LITE_CONFIG_URI]
254b0 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 option with the
254c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
254d0 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 fig()] method or
254e0 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f by the [SQLITE_
254f0 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 USE_URI] compile
25500 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a -time option..**
25510 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 As of SQLite ve
25520 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 rsion 3.7.7, URI
25530 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 filename interp
25540 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e retation is turn
25550 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 ed off.** by def
25560 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 ault, but future
25570 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c releases of SQL
25580 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 ite might enable
25590 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a URI filename.**
255a0 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 interpretation
255b0 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 by default. See
255c0 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 "[URI filenames
255d0 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 ]" for additiona
255e0 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e l.** information
255f0 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 ..**.** URI file
25600 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 names are parsed
25610 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 according to RF
25620 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 C 3986. ^If the
25630 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a URI contains an.
25640 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 ** authority, th
25650 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 en it must be ei
25660 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 ther an empty st
25670 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 ring or the stri
25680 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 ng .** "localhos
25690 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 t". ^If the auth
256a0 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 ority is not an
256b0 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 empty string or
256c0 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 "localhost", an
256d0 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 .** error is ret
256e0 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c urned to the cal
256f0 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 ler. ^The fragme
25700 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 nt component of
25710 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 a URI, if .** pr
25720 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 esent, is ignore
25730 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 d..**.** ^SQLite
25740 20 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63 uses the path c
25750 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 omponent of the
25760 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 URI as the name
25770 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 of the disk file
25780 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 .** which contai
25790 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e ns the database.
257a0 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65 ^If the path be
257b0 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 gins with a '/'
257c0 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 character, .** t
257d0 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 hen it is interp
257e0 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f reted as an abso
257f0 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 lute path. ^If t
25800 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 he path does not
25810 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 begin .** with
25820 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 a '/' (meaning t
25830 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 hat the authorit
25840 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 y section is omi
25850 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 tted from the UR
25860 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 I).** then the p
25870 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 ath is interpret
25880 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 ed as a relative
25890 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 path. .** ^(On
258a0 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 windows, the fir
258b0 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 st component of
258c0 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 an absolute path
258d0 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 .** is a drive
258e0 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 specification (e
258f0 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a .g. "C:").)^.**.
25900 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 ** [[core URI qu
25910 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d ery parameters]]
25920 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f .** The query co
25930 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 mponent of a URI
25940 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 may contain par
25950 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65 ameters that are
25960 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 interpreted.**
25970 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 either by SQLite
25980 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 itself, or by a
25990 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 [VFS | custom V
259a0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f FS implementatio
259b0 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e n]..** SQLite an
259c0 64 20 69 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b d its built-in [
259d0 56 46 53 65 73 5d 20 69 6e 74 65 72 70 72 65 74 VFSes] interpret
259e0 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e the.** followin
259f0 67 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 g query paramete
25a00 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a rs:.**.** <ul>.*
25a10 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c * <li> <b>vfs<
25a20 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 /b>: ^The "vfs"
25a30 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 parameter may be
25a40 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 used to specify
25a50 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 the name of.**
25a60 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 a VFS object
25a70 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 that provides t
25a80 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 he operating sys
25a90 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 tem interface th
25aa0 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 at should.**
25ab0 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 be used to acce
25ac0 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ss the database
25ad0 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 file on disk. ^I
25ae0 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 f this option is
25af0 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 set to.** a
25b00 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 n empty string t
25b10 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f he default VFS o
25b20 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e bject is used. ^
25b30 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e Specifying an un
25b40 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 known.** VFS
25b50 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 is an error. ^I
25b60 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 f sqlite3_open_v
25b70 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 2() is used and
25b80 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 the vfs option i
25b90 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 s.** present
25ba0 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 , then the VFS s
25bb0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 pecified by the
25bc0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 option takes pre
25bd0 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 cedence over.**
25be0 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 the value pa
25bf0 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 ssed as the four
25c00 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
25c10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
25c20 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 )..**.** <li>
25c30 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 <b>mode</b>: ^(T
25c40 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 he mode paramete
25c50 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 r may be set to
25c60 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 either "ro", "rw
25c70 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c ",.** "rwc",
25c80 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 or "memory". At
25c90 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 tempting to set
25ca0 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 it to any other
25cb0 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 value is.**
25cc0 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 an error)^. .**
25cd0 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 ^If "ro" is
25ce0 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 specified, then
25cf0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 the database is
25d00 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d opened for read-
25d10 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 only .** acc
25d20 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 ess, just as if
25d30 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e the [SQLITE_OPEN
25d40 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 _READONLY] flag
25d50 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 had been set in
25d60 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 the .** thir
25d70 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 d argument to sq
25d80 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e lite3_open_v2().
25d90 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 ^If the mode op
25da0 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a tion is set to .
25db0 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 ** "rw", the
25dc0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 n the database i
25dd0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 s opened for rea
25de0 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 d-write (but not
25df0 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 create) .**
25e00 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 access, as if S
25e10 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
25e20 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 RITE (but not SQ
25e30 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
25e40 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 ) had .** be
25e50 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 en set. ^Value "
25e60 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 rwc" is equivale
25e70 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f nt to setting bo
25e80 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 th .** SQLIT
25e90 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 E_OPEN_READWRITE
25ea0 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e and SQLITE_OPEN
25eb0 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68 _CREATE. ^If th
25ec0 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 e mode option is
25ed0 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22 .** set to "
25ee0 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70 memory" then a p
25ef0 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 ure [in-memory d
25f00 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65 atabase] that ne
25f10 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 ver reads.**
25f20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20 or writes from
25f30 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 disk is used. ^I
25f40 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f t is an error to
25f50 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 specify a value
25f60 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 for.** the
25f70 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 mode parameter t
25f80 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73 74 hat is less rest
25f90 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 rictive than tha
25fa0 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a t specified by.*
25fb0 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73 20 * the flags
25fc0 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74 68 passed in the th
25fd0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ird parameter to
25fe0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
25ff0 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e ()..**.** <li>
26000 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e <b>cache</b>: ^
26010 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 The cache parame
26020 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 ter may be set t
26030 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64 o either "shared
26040 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 " or.** "pri
26050 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 vate". ^Setting
26060 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 it to "shared" i
26070 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 s equivalent to
26080 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 setting the.**
26090 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 SQLITE_OPEN_S
260a0 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69 HAREDCACHE bit i
260b0 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 n the flags argu
260c0 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a ment passed to.*
260d0 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 * sqlite3_op
260e0 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e en_v2(). ^Settin
260f0 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61 g the cache para
26100 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 meter to "privat
26110 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 e" is .** eq
26120 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 uivalent to sett
26130 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f ing the SQLITE_O
26140 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 PEN_PRIVATECACHE
26150 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 bit..** ^If
26160 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
26170 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 () is used and t
26180 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d he "cache" param
26190 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 eter is present
261a0 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 in.** a URI
261b0 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 filename, its va
261c0 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e lue overrides an
261d0 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 75 65 y behavior reque
261e0 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a sted by setting.
261f0 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 ** SQLITE_OP
26200 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 EN_PRIVATECACHE
26210 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 or SQLITE_OPEN_S
26220 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e HAREDCACHE flag.
26230 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e .**.** <li> <b>
26240 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 psow</b>: ^The p
26250 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20 69 6e sow parameter in
26260 64 69 63 61 74 65 73 20 77 68 65 74 68 65 72 20 dicates whether
26270 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 or not the.**
26280 20 20 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65 [powersafe ove
26290 72 77 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79 rwrite] property
262a0 20 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f does or does no
262b0 74 20 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a t apply to the.*
262c0 2a 20 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65 * storage me
262d0 64 69 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65 dia on which the
262e0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 72 database file r
262f0 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c esides..**.** <
26300 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 li> <b>nolock</b
26310 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 >: ^The nolock p
26320 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f arameter is a bo
26330 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 61 72 61 olean query para
26340 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 meter.** whi
26350 63 68 20 69 66 20 73 65 74 20 64 69 73 61 62 6c ch if set disabl
26360 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 es file locking
26370 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 in rollback jour
26380 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 nal modes. This
26390 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 65 66 75 .** is usefu
263a0 6c 20 66 6f 72 20 61 63 63 65 73 73 69 6e 67 20 l for accessing
263b0 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 61 20 a database on a
263c0 66 69 6c 65 73 79 73 74 65 6d 20 74 68 61 74 20 filesystem that
263d0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 does not.**
263e0 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e support locking.
263f0 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 Caution: Data
26400 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 base corruption
26410 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 might result if
26420 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f two.** or mo
26430 72 65 20 70 72 6f 63 65 73 73 65 73 20 77 72 69 re processes wri
26440 74 65 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 te to the same d
26450 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e 79 20 atabase and any
26460 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 one of those.**
26470 20 20 20 20 70 72 6f 63 65 73 73 65 73 20 75 73 processes us
26480 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a es nolock=1..**.
26490 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 ** <li> <b>immu
264a0 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 table</b>: ^The
264b0 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 6d 65 immutable parame
264c0 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e ter is a boolean
264d0 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 query.** pa
264e0 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 6e 64 rameter that ind
264f0 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20 icates that the
26500 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 database file is
26510 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 stored on.**
26520 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 read-only medi
26530 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 a. ^When immuta
26540 62 6c 65 20 69 73 20 73 65 74 2c 20 53 51 4c 69 ble is set, SQLi
26550 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 te assumes that
26560 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 the.** datab
26570 61 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 ase file cannot
26580 62 65 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e be changed, even
26590 20 62 79 20 61 20 70 72 6f 63 65 73 73 20 77 69 by a process wi
265a0 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 th higher.**
265b0 20 70 72 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 privilege, and
265c0 73 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 so the database
265d0 69 73 20 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f is opened read-o
265e0 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b nly and all lock
265f0 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 ing.** and c
26600 68 61 6e 67 65 20 64 65 74 65 63 74 69 6f 6e 20 hange detection
26610 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 43 61 is disabled. Ca
26620 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 ution: Setting t
26630 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 he immutable.**
26640 20 20 20 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 property on
26650 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 a database file
26660 74 68 61 74 20 64 6f 65 73 20 69 6e 20 66 61 63 that does in fac
26670 74 20 63 68 61 6e 67 65 20 63 61 6e 20 72 65 73 t change can res
26680 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e ult.** in in
26690 63 6f 72 72 65 63 74 20 71 75 65 72 79 20 72 65 correct query re
266a0 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 sults and/or [SQ
266b0 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 LITE_CORRUPT] er
266c0 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 rors..** See
266d0 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 also: [SQLITE_I
266e0 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e OCAP_IMMUTABLE].
266f0 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f .** .** </
26700 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 ul>.**.** ^Speci
26710 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e fying an unknown
26720 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 parameter in th
26730 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e e query componen
26740 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f t of a URI is no
26750 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 t an.** error.
26760 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 Future versions
26770 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 of SQLite might
26780 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 understand addit
26790 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 ional query.** p
267a0 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 arameters. See
267b0 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 "[query paramete
267c0 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 rs with special
267d0 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 meaning to SQLit
267e0 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 e]" for.** addit
267f0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f ional informatio
26800 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 n..**.** [[URI f
26810 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 ilename examples
26820 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e ]] <h3>URI filen
26830 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 ame examples</h3
26840 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 >.**.** <table b
26850 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d order="1" align=
26860 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 center cellpaddi
26870 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 ng=5>.** <tr><th
26880 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 > URI filenames
26890 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 <th> Results.**
268a0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 <tr><td> file:da
268b0 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 ta.db <td> .**
268c0 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 Open the
268d0 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 file "data.db"
268e0 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 in the current d
268f0 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 irectory..** <tr
26900 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 ><td> file:/home
26910 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 /fred/data.db<br
26920 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 >.** fi
26930 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f le:///home/fred/
26940 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a data.db <br> .**
26950 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f file:/
26960 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f /localhost/home/
26970 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 fred/data.db <br
26980 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 > <td> .**
26990 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 Open the dat
269a0 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d abase file "/hom
269b0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e e/fred/data.db".
269c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c .** <tr><td> fil
269d0 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d e://darkstar/hom
269e0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c e/fred/data.db <
269f0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 td> .**
26a00 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b An error. "dark
26a10 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 star" is not a r
26a20 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 ecognized author
26a30 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 ity..** <tr><td
26a40 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 style="white-spa
26a50 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 ce:nowrap"> .**
26a60 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f file://
26a70 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 /C:/Documents%20
26a80 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 and%20Settings/f
26a90 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 red/Desktop/data
26aa0 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 .db.** <td>
26ab0 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 Windows only: Op
26ac0 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 en the file "dat
26ad0 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 a.db" on fred's
26ae0 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 desktop on drive
26af0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e .** C:.
26b00 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 Note that the %
26b10 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 20 escaping in t
26b20 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e his example is n
26b30 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 ot strictly .**
26b40 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 necessa
26b50 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 ry - space chara
26b60 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 cters can be use
26b70 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 d literally.**
26b80 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 in URI f
26b90 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 ilenames..** <tr
26ba0 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e ><td> file:data.
26bb0 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 db?mode=ro&cache
26bc0 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a =private <td> .*
26bd0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 * Open
26be0 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 file "data.db" i
26bf0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 n the current di
26c00 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 rectory for read
26c10 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a -only access..**
26c20 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64 Regard
26c30 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 less of whether
26c40 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 or not shared-ca
26c50 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 che mode is enab
26c60 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 led by.**
26c70 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 default, use
26c80 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e a private cache.
26c90 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c .** <tr><td> fil
26ca0 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 e:/home/fred/dat
26cb0 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f a.db?vfs=unix-do
26cc0 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 tfile <td>.**
26cd0 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 Open file
26ce0 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 "/home/fred/dat
26cf0 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 a.db". Use the s
26d00 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 pecial VFS "unix
26d10 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 -dotfile".**
26d20 20 20 20 20 20 20 74 68 61 74 20 75 73 65 73 20 that uses
26d30 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 dot-files in pla
26d40 63 65 20 6f 66 20 70 6f 73 69 78 20 61 64 76 69 ce of posix advi
26d50 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a sory locking..**
26d60 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 <tr><td> file:d
26d70 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 ata.db?mode=read
26d80 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 only <td> .**
26d90 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e An error.
26da0 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e "readonly" is n
26db0 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f ot a valid optio
26dc0 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 n for the "mode"
26dd0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c parameter..** <
26de0 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 /table>.**.** ^U
26df0 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 RI hexadecimal e
26e00 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 scape sequences
26e10 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 (%HH) are suppor
26e20 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 ted within the p
26e30 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 ath and.** query
26e40 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 components of a
26e50 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 URI. A hexadeci
26e60 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 mal escape seque
26e70 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 nce consists of
26e80 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 a.** percent sig
26e90 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 n - "%" - follow
26ea0 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 ed by exactly tw
26eb0 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 o hexadecimal di
26ec0 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 gits .** specify
26ed0 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c ing an octet val
26ee0 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 ue. ^Before the
26ef0 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f path or query co
26f00 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a mponents of a.**
26f10 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 URI filename ar
26f20 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 e interpreted, t
26f30 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 hey are encoded
26f40 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 using UTF-8 and
26f50 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 all .** hexadeci
26f60 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 mal escape seque
26f70 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 nces replaced by
26f80 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 a single byte c
26f90 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a ontaining the.**
26fa0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f corresponding o
26fb0 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 ctet. If this pr
26fc0 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 ocess generates
26fd0 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 an invalid UTF-8
26fe0 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 encoding,.** th
26ff0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e e results are un
27000 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c defined..**.** <
27010 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 b>Note to Window
27020 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 s users:</b> Th
27030 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 e encoding used
27040 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 for the filename
27050 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 argument.** of
27060 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 sqlite3_open() a
27070 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f nd sqlite3_open_
27080 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 v2() must be UTF
27090 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 -8, not whatever
270a0 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 .** codepage is
270b0 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 currently define
270c0 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f d. Filenames co
270d0 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 ntaining interna
270e0 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 tional.** charac
270f0 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e ters must be con
27100 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 verted to UTF-8
27110 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 prior to passing
27120 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 them into.** sq
27130 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 lite3_open() or
27140 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
27150 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 )..**.** <b>Note
27160 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 to Windows Runt
27170 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 ime users:</b>
27180 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 The temporary di
27190 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 rectory must be
271a0 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 set.** prior to
271b0 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f calling sqlite3_
271c0 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 open() or sqlite
271d0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 3_open_v2(). Ot
271e0 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 herwise, various
271f0 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 .** features tha
27200 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73 t require the us
27210 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 e of temporary f
27220 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a iles may fail..*
27230 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
27240 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 sqlite3_temp_dir
27250 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 ectory].*/.int s
27260 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 qlite3_open(. c
27270 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e onst char *filen
27280 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 ame, /* Databa
27290 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 se filename (UTF
272a0 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 -8) */. sqlite3
272b0 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 **ppDb
272c0 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 /* OUT: SQLite
272d0 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a db handle */.);.
272e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e int sqlite3_open
272f0 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 16(. const void
27300 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a *filename, /*
27310 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 Database filena
27320 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 me (UTF-16) */.
27330 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 sqlite3 **ppDb
27340 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a /* OUT:
27350 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c SQLite db handl
27360 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 e */.);.int sqli
27370 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 te3_open_v2(. c
27380 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e onst char *filen
27390 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 ame, /* Databa
273a0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 se filename (UTF
273b0 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 -8) */. sqlite3
273c0 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 **ppDb,
273d0 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 /* OUT: SQLite
273e0 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 db handle */. i
273f0 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 nt flags,
27400 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 /* Flags
27410 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
27420 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 *zVfs /*
27430 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 Name of VFS modu
27440 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a le to use */.);.
27450 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
27460 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 Obtain Values F
27470 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 or URI Parameter
27480 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 s.**.** These ar
27490 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e e utility routin
274a0 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 es, useful to VF
274b0 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e S implementation
274c0 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a s, that check.**
274d0 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 to see if a dat
274e0 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 abase file was a
274f0 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 URI that contai
27500 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71 ned a specific q
27510 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 uery .** paramet
27520 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 er, and if so ob
27530 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 tains the value
27540 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61 of that query pa
27550 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 rameter..**.** I
27560 66 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62 f F is the datab
27570 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 ase filename poi
27580 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f nter passed into
27590 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 the xOpen() met
275a0 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 hod of .** a VFS
275b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
275c0 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 when the flags p
275d0 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 arameter to xOpe
275e0 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a n() has one or .
275f0 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b ** more of the [
27600 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d SQLITE_OPEN_URI]
27610 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e or [SQLITE_OPEN
27620 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 _MAIN_DB] bits s
27630 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 et and.** P is t
27640 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 he name of the q
27650 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 uery parameter,
27660 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f then.** sqlite3_
27670 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c uri_parameter(F,
27680 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 P) returns the v
27690 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a alue of the P.**
276a0 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 parameter if it
276b0 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c exists or a NUL
276c0 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 L pointer if P d
276d0 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 oes not appear a
276e0 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 s a .** query pa
276f0 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 rameter on F. I
27700 66 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70 f P is a query p
27710 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a arameter of F.**
27720 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 has no explicit
27730 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c value, then sql
27740 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 ite3_uri_paramet
27750 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a er(F,P) returns.
27760 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ** a pointer to
27770 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e an empty string.
27780 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
27790 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 e3_uri_boolean(F
277a0 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 ,P,B) routine as
277b0 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 sumes that P is
277c0 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 a boolean.** par
277d0 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 ameter and retur
277e0 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 ns true (1) or f
277f0 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 alse (0) accordi
27800 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a ng to the value.
27810 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 ** of P. The sq
27820 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 lite3_uri_boolea
27830 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 n(F,P,B) routine
27840 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 returns true (1
27850 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 ) if the.** valu
27860 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d e of query param
27870 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 eter P is one of
27880 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 "yes", "true",
27890 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a or "on" in any.*
278a0 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 * case or if the
278b0 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 value begins wi
278c0 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 th a non-zero nu
278d0 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 mber. The .** s
278e0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 qlite3_uri_boole
278f0 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e an(F,P,B) routin
27900 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 es returns false
27910 20 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 (0) if the valu
27920 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 e of.** query pa
27930 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 rameter P is one
27940 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 of "no", "false
27950 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 ", or "off" in a
27960 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 ny case or.** if
27970 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e the value begin
27980 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 s with a numeric
27990 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 zero. If P is
279a0 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 not a query.** p
279b0 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 arameter on F or
279c0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 if the value of
279d0 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d P is does not m
279e0 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a atch any of the.
279f0 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 ** above, then s
27a00 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 qlite3_uri_boole
27a10 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e an(F,P,B) return
27a20 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 s (B!=0)..**.**
27a30 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f The sqlite3_uri_
27a40 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 int64(F,P,D) rou
27a50 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 tine converts th
27a60 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 e value of P int
27a70 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 o a.** 64-bit si
27a80 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 gned integer and
27a90 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e returns that in
27aa0 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 teger, or D if P
27ab0 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 does not.** exi
27ac0 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 st. If the valu
27ad0 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 e of P is someth
27ae0 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 ing other than a
27af0 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a n integer, then.
27b00 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 ** zero is retur
27b10 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 ned..** .** If F
27b20 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
27b30 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 er, then sqlite3
27b40 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 _uri_parameter(F
27b50 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c ,P) returns NULL
27b60 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f and.** sqlite3_
27b70 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c uri_boolean(F,P,
27b80 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 B) returns B. I
27b90 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c f F is not a NUL
27ba0 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a L pointer and.**
27bb0 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 is not a databa
27bc0 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 se file pathname
27bd0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 pointer that SQ
27be0 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f Lite passed into
27bf0 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 the xOpen.** VF
27c00 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 S method, then t
27c10 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 he behavior of t
27c20 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 his routine is u
27c30 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f ndefined and pro
27c40 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 bably.** undesir
27c50 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 able..*/.const c
27c60 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 har *sqlite3_uri
27c70 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 _parameter(const
27c80 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 char *zFilename
27c90 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 , const char *zP
27ca0 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 aram);.int sqlit
27cb0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 e3_uri_boolean(c
27cc0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 onst char *zFile
27cd0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 , const char *zP
27ce0 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 aram, int bDefau
27cf0 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 lt);.sqlite3_int
27d00 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 64 sqlite3_uri_i
27d10 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a nt64(const char*
27d20 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 , const char*, s
27d30 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a qlite3_int64);..
27d40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
27d50 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 Error Codes And
27d60 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54 Messages.** MET
27d70 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
27d80 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 ** ^If the most
27d90 72 65 63 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a recent sqlite3_*
27da0 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 API call associ
27db0 61 74 65 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64 ated with .** [d
27dc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
27dd0 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c 20 74 68 on] D failed, th
27de0 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 en the sqlite3_e
27df0 72 72 63 6f 64 65 28 44 29 20 69 6e 74 65 72 66 rrcode(D) interf
27e00 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 ace.** returns t
27e10 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 he numeric [resu
27e20 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 lt code] or [ext
27e30 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
27e40 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41 e] for that.** A
27e50 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 PI call..** If t
27e60 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 he most recent A
27e70 50 49 20 63 61 6c 6c 20 77 61 73 20 73 75 63 63 PI call was succ
27e80 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 essful,.** then
27e90 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
27ea0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 from sqlite3_er
27eb0 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 rcode() is undef
27ec0 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 ined..** ^The sq
27ed0 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 lite3_extended_e
27ee0 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 rrcode().** inte
27ef0 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d rface is the sam
27f00 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 e except that it
27f10 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 always returns
27f20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 the .** [extende
27f30 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 d result code] e
27f40 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 ven when extende
27f50 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 d result codes a
27f60 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a re.** disabled..
27f70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
27f80 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 e3_errmsg() and
27f90 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 sqlite3_errmsg16
27fa0 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 () return Englis
27fb0 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 h-language.** te
27fc0 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 xt that describe
27fd0 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 s the error, as
27fe0 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 either UTF-8 or
27ff0 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 UTF-16 respectiv
28000 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 ely..** ^(Memory
28010 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 to hold the err
28020 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e or message strin
28030 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 g is managed int
28040 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 ernally..** The
28050 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 application does
28060 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 not need to wor
28070 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 ry about freeing
28080 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 the result..**
28090 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 However, the err
280a0 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 or string might
280b0 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f be overwritten o
280c0 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 r deallocated by
280d0 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 .** subsequent c
280e0 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 alls to other SQ
280f0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 Lite interface f
28100 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a unctions.)^.**.*
28110 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 * ^The sqlite3_e
28120 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 rrstr() interfac
28130 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e e returns the En
28140 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 glish-language t
28150 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 ext.** that desc
28160 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c ribes the [resul
28170 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d t code], as UTF-
28180 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 8..** ^(Memory t
28190 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 o hold the error
281a0 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 message string
281b0 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 is managed inter
281c0 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 nally.** and mus
281d0 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 t not be freed b
281e0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f y the applicatio
281f0 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 n)^..**.** When
28200 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b the serialized [
28210 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
28220 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 is in use, it mi
28230 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 ght be the.** ca
28240 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 se that a second
28250 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e error occurs on
28260 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 a separate thre
28270 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a ad in between.**
28280 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 the time of the
28290 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 first error and
282a0 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 the call to the
282b0 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a se interfaces..*
282c0 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 * When that happ
282d0 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 ens, the second
282e0 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 error will be re
282f0 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 ported since the
28300 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 se.** interfaces
28310 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 always report t
28320 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 he most recent r
28330 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 esult. To avoid
28340 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 .** this, each t
28350 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e hread can obtain
28360 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f exclusive use o
28370 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 f the [database
28380 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a connection] D.**
28390 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 by invoking [sq
283a0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 lite3_mutex_ente
283b0 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d r]([sqlite3_db_m
283c0 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 utex](D)) before
283d0 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f beginning.** to
283e0 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b use D and invok
283f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 ing [sqlite3_mut
28400 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 ex_leave]([sqlit
28410 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 e3_db_mutex](D))
28420 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 after.** all ca
28430 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 lls to the inter
28440 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 faces listed her
28450 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e e are completed.
28460 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 .**.** If an int
28470 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 erface fails wit
28480 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c h SQLITE_MISUSE,
28490 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 that means the
284a0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 interface.** was
284b0 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 invoked incorre
284c0 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c ctly by the appl
284d0 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 ication. In tha
284e0 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 t case, the.** e
284f0 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 rror code and me
28500 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 ssage may or may
28510 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a not be set..*/.
28520 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 int sqlite3_errc
28530 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 ode(sqlite3 *db)
28540 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 ;.int sqlite3_ex
28550 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 tended_errcode(s
28560 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e qlite3 *db);.con
28570 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
28580 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a _errmsg(sqlite3*
28590 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
285a0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 qlite3_errmsg16(
285b0 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 sqlite3*);.const
285c0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 char *sqlite3_e
285d0 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a rrstr(int);../*.
285e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 65 ** CAPI3REF: Pre
285f0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 pared Statement
28600 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 Object.** KEYWOR
28610 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 DS: {prepared st
28620 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 atement} {prepar
28630 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a ed statements}.*
28640 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 *.** An instance
28650 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 of this object
28660 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e represents a sin
28670 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e gle SQL statemen
28680 74 20 74 68 61 74 0a 2a 2a 20 68 61 73 20 62 65 t that.** has be
28690 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f en compiled into
286a0 20 62 69 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64 binary form and
286b0 20 69 73 20 72 65 61 64 79 20 74 6f 20 62 65 20 is ready to be
286c0 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a evaluated..**.**
286d0 20 54 68 69 6e 6b 20 6f 66 20 65 61 63 68 20 53 Think of each S
286e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 QL statement as
286f0 61 20 73 65 70 61 72 61 74 65 20 63 6f 6d 70 75 a separate compu
28700 74 65 72 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 ter program. Th
28710 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 e.** original SQ
28720 4c 20 74 65 78 74 20 69 73 20 73 6f 75 72 63 65 L text is source
28730 20 63 6f 64 65 2e 20 20 41 20 70 72 65 70 61 72 code. A prepar
28740 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a ed statement obj
28750 65 63 74 20 0a 2a 2a 20 69 73 20 74 68 65 20 63 ect .** is the c
28760 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74 20 63 ompiled object c
28770 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75 ode. All SQL mu
28780 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 st be converted
28790 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72 into a.** prepar
287a0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 62 65 66 ed statement bef
287b0 6f 72 65 20 69 74 20 63 61 6e 20 62 65 20 72 75 ore it can be ru
287c0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 n..**.** The lif
287d0 65 2d 63 79 63 6c 65 20 6f 66 20 61 20 70 72 65 e-cycle of a pre
287e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
287f0 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c 79 20 67 object usually g
28800 6f 65 73 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a oes like this:.*
28810 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ol>.** <li
28820 3e 20 43 72 65 61 74 65 20 74 68 65 20 70 72 65 > Create the pre
28830 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
28840 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 object using [sq
28850 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
28860 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e ()]..** <li> Bin
28870 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 70 61 72 d values to [par
28880 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 ameters] using t
28890 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
288a0 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 *().** inte
288b0 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 rfaces..** <li>
288c0 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 Run the SQL by c
288d0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
288e0 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d step()] one or m
288f0 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c ore times..** <l
28900 69 3e 20 52 65 73 65 74 20 74 68 65 20 70 72 65 i> Reset the pre
28910 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
28920 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 using [sqlite3_r
28930 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 eset()] then go
28940 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 back.** to
28950 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 step 2. Do this
28960 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 zero or more ti
28970 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 mes..** <li> Des
28980 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 troy the object
28990 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 using [sqlite3_f
289a0 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c inalize()]..** <
289b0 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 /ol>.*/.typedef
289c0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 struct sqlite3_s
289d0 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 tmt sqlite3_stmt
289e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
289f0 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 F: Run-time Limi
28a00 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 ts.** METHOD: sq
28a10 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 lite3.**.** ^(Th
28a20 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c is interface all
28a30 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 ows the size of
28a40 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 various construc
28a50 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 ts to be limited
28a60 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 .** on a connect
28a70 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f ion by connectio
28a80 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 n basis. The fi
28a90 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 rst parameter is
28aa0 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 the.** [databas
28ab0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 e connection] wh
28ac0 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 ose limit is to
28ad0 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 be set or querie
28ae0 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e d. The.** secon
28af0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f d parameter is o
28b00 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 ne of the [limit
28b10 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 categories] tha
28b20 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c t define a.** cl
28b30 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 ass of construct
28b40 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d s to be size lim
28b50 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 ited. The third
28b60 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
28b70 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 e.** new limit f
28b80 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 or that construc
28b90 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 t.)^.**.** ^If t
28ba0 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 he new limit is
28bb0 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 a negative numbe
28bc0 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 r, the limit is
28bd0 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 unchanged..** ^(
28be0 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63 For each limit c
28bf0 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c ategory SQLITE_L
28c00 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e IMIT_<i>NAME</i>
28c10 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 there is a .**
28c20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 [limits | hard u
28c30 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 pper bound].** s
28c40 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 et at compile-ti
28c50 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f me by a C prepro
28c60 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c cessor macro cal
28c70 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c led.** [limits |
28c80 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e SQLITE_MAX_<i>N
28c90 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 AME</i>]..** (Th
28ca0 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 e "_LIMIT_" in t
28cb0 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 he name is chang
28cc0 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 ed to "_MAX_".))
28cd0 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 ^.** ^Attempts t
28ce0 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d o increase a lim
28cf0 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 it above its har
28d00 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 d upper bound ar
28d10 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 e.** silently tr
28d20 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 uncated to the h
28d30 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e ard upper bound.
28d40 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 .**.** ^Regardle
28d50 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 ss of whether or
28d60 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77 not the limit w
28d70 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 as changed, the
28d80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d .** [sqlite3_lim
28d90 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 it()] interface
28da0 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f returns the prio
28db0 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c r value of the l
28dc0 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c imit..** ^Hence,
28dd0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72 to find the cur
28de0 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20 rent value of a
28df0 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68 limit without ch
28e00 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 anging it,.** si
28e10 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 mply invoke this
28e20 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20 interface with
28e30 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
28e40 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a ter set to -1..*
28e50 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 *.** Run-time li
28e60 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 mits are intende
28e70 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 d for use in app
28e80 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d lications that m
28e90 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 anage.** both th
28ea0 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c eir own internal
28eb0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c database and al
28ec0 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61 so databases tha
28ed0 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 t are controlled
28ee0 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 .** by untrusted
28ef0 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 external source
28f00 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 s. An example a
28f10 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 pplication might
28f20 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f be a.** web bro
28f30 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74 wser that has it
28f40 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 s own databases
28f50 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 for storing hist
28f60 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 ory and.** separ
28f70 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f ate databases co
28f80 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 ntrolled by Java
28f90 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 Script applicati
28fa0 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a ons downloaded.*
28fb0 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e * off the Intern
28fc0 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 et. The interna
28fd0 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 l databases can
28fe0 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 be given the.**
28ff0 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c large, default l
29000 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 imits. Database
29010 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 s managed by ext
29020 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 ernal sources ca
29030 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 n.** be given mu
29040 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 ch smaller limit
29050 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 s designed to pr
29060 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f event a denial o
29070 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 f service.** att
29080 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 ack. Developers
29090 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 might also want
290a0 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c to use the [sql
290b0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
290c0 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 zer()].** interf
290d0 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 ace to further c
290e0 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 ontrol untrusted
290f0 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 SQL. The size
29100 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a of the database.
29110 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e ** created by an
29120 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 untrusted scrip
29130 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e t can be contain
29140 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 ed using the.**
29150 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d [max_page_count]
29160 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a [PRAGMA]..**.**
29170 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 New run-time li
29180 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d mit categories m
29190 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 ay be added in f
291a0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a uture releases..
291b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c */.int sqlite3_l
291c0 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 imit(sqlite3*, i
291d0 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 nt id, int newVa
291e0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 l);../*.** CAPI3
291f0 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 REF: Run-Time Li
29200 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a mit Categories.*
29210 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d * KEYWORDS: {lim
29220 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c it category} {*l
29230 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d imit categories}
29240 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e .**.** These con
29250 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 stants define va
29260 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 rious performanc
29270 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 e limits.** that
29280 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 can be lowered
29290 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e at run-time usin
292a0 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 g [sqlite3_limit
292b0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f ()]..** The syno
292c0 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e psis of the mean
292d0 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 ings of the vari
292e0 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 ous limits is sh
292f0 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 own below..** Ad
29300 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 ditional informa
29310 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c tion is availabl
29320 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c e at [limits | L
29330 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d imits in SQLite]
29340 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 ..**.** <dl>.**
29350 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c [[SQLITE_LIMIT_L
29360 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 ENGTH]] ^(<dt>SQ
29370 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 LITE_LIMIT_LENGT
29380 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 H</dt>.** <dd>Th
29390 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f e maximum size o
293a0 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 f any string or
293b0 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f BLOB or table ro
293c0 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e w, in bytes.<dd>
293d0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
293e0 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 E_LIMIT_SQL_LENG
293f0 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 TH]] ^(<dt>SQLIT
29400 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 E_LIMIT_SQL_LENG
29410 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 TH</dt>.** <dd>T
29420 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 he maximum lengt
29430 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 h of an SQL stat
29440 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e ement, in bytes.
29450 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b </dd>)^.**.** [[
29460 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c SQLITE_LIMIT_COL
29470 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 UMN]] ^(<dt>SQLI
29480 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c TE_LIMIT_COLUMN<
29490 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
294a0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
294b0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 f columns in a t
294c0 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 able definition
294d0 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 or in the.** res
294e0 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 ult set of a [SE
294f0 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 LECT] or the max
29500 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 imum number of c
29510 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 olumns in an ind
29520 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f ex.** or in an O
29530 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 RDER BY or GROUP
29540 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e BY clause.</dd>
29550 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
29560 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 E_LIMIT_EXPR_DEP
29570 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 TH]] ^(<dt>SQLIT
29580 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 E_LIMIT_EXPR_DEP
29590 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 TH</dt>.** <dd>T
295a0 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 he maximum depth
295b0 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72 of the parse tr
295c0 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 ee on any expres
295d0 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a sion.</dd>)^.**.
295e0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
295f0 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 T_COMPOUND_SELEC
29600 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 T]] ^(<dt>SQLITE
29610 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f _LIMIT_COMPOUND_
29620 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c SELECT</dt>.** <
29630 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e dd>The maximum n
29640 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 umber of terms i
29650 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c n a compound SEL
29660 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f ECT statement.</
29670 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 dd>)^.**.** [[SQ
29680 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f LITE_LIMIT_VDBE_
29690 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 OP]] ^(<dt>SQLIT
296a0 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c E_LIMIT_VDBE_OP<
296b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
296c0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
296d0 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 f instructions i
296e0 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 n a virtual mach
296f0 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 ine program.** u
29700 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 sed to implement
29710 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e an SQL statemen
29720 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 t. This limit i
29730 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a s not currently.
29740 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f ** enforced, tho
29750 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 ugh that might b
29760 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 e added in some
29770 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f future release o
29780 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 f.** SQLite.</dd
29790 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 >)^.**.** [[SQLI
297a0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f TE_LIMIT_FUNCTIO
297b0 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 N_ARG]] ^(<dt>SQ
297c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 LITE_LIMIT_FUNCT
297d0 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 ION_ARG</dt>.**
297e0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
297f0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 number of argume
29800 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f nts on a functio
29810 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 n.</dd>)^.**.**
29820 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 [[SQLITE_LIMIT_A
29830 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e TTACHED]] ^(<dt>
29840 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 SQLITE_LIMIT_ATT
29850 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ACHED</dt>.** <d
29860 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 d>The maximum nu
29870 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 mber of [ATTACH
29880 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 | attached datab
29890 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a ases].)^</dd>.**
298a0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d .** [[SQLITE_LIM
298b0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f IT_LIKE_PATTERN_
298c0 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 LENGTH]].** ^(<d
298d0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c t>SQLITE_LIMIT_L
298e0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 IKE_PATTERN_LENG
298f0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 TH</dt>.** <dd>T
29900 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 he maximum lengt
29910 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e h of the pattern
29920 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
29930 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 [LIKE] or.** [G
29940 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c LOB] operators.<
29950 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 /dd>)^.**.** [[S
29960 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 QLITE_LIMIT_VARI
29970 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a ABLE_NUMBER]].**
29980 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
29990 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d MIT_VARIABLE_NUM
299a0 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e BER</dt>.** <dd>
299b0 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 The maximum inde
299c0 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 x number of any
299d0 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 [parameter] in a
299e0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e n SQL statement.
299f0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
29a00 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f E_LIMIT_TRIGGER_
29a10 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 DEPTH]] ^(<dt>SQ
29a20 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 LITE_LIMIT_TRIGG
29a30 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a ER_DEPTH</dt>.**
29a40 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
29a50 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 depth of recurs
29a60 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 ion for triggers
29a70 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b .</dd>)^.**.** [
29a80 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f [SQLITE_LIMIT_WO
29a90 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e RKER_THREADS]] ^
29aa0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
29ab0 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 T_WORKER_THREADS
29ac0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
29ad0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
29ae0 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f 72 of auxiliary wor
29af0 6b 65 72 20 74 68 72 65 61 64 73 20 74 68 61 74 ker threads that
29b00 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 a single.** [pr
29b10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
29b20 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 64 ] may start.</dd
29b30 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a >)^.** </dl>.*/.
29b40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
29b50 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 IMIT_LENGTH
29b60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
29b70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
29b80 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 LIMIT_SQL_LENGTH
29b90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
29ba0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
29bb0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 _LIMIT_COLUMN
29bc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
29bd0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
29be0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 E_LIMIT_EXPR_DEP
29bf0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TH
29c00 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 3.#define SQLI
29c10 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e TE_LIMIT_COMPOUN
29c20 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 D_SELECT
29c30 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 4.#define SQL
29c40 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f ITE_LIMIT_VDBE_O
29c50 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 P
29c60 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 5.#define SQ
29c70 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 LITE_LIMIT_FUNCT
29c80 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 ION_ARG
29c90 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 6.#define S
29ca0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 QLITE_LIMIT_ATTA
29cb0 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20 CHED
29cc0 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 7.#define
29cd0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b SQLITE_LIMIT_LIK
29ce0 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 E_PATTERN_LENGTH
29cf0 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 8.#define
29d00 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 SQLITE_LIMIT_VA
29d10 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 RIABLE_NUMBER
29d20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 9.#defin
29d30 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 e SQLITE_LIMIT_T
29d40 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 RIGGER_DEPTH
29d50 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 10.#defi
29d60 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
29d70 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20 WORKER_THREADS
29d80 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 11../*.
29d90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d ** CAPI3REF: Com
29da0 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 piling An SQL St
29db0 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f atement.** KEYWO
29dc0 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d RDS: {SQL statem
29dd0 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a ent compiler}.**
29de0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
29df0 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a .** CONSTRUCTOR:
29e00 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
29e10 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 .** To execute a
29e20 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 n SQL query, it
29e30 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f must first be co
29e40 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 mpiled into a by
29e50 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 te-code.** progr
29e60 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 am using one of
29e70 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a these routines..
29e80 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
29e90 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 argument, "db",
29ea0 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 is a [database c
29eb0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 onnection] obtai
29ec0 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 ned from a.** pr
29ed0 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 ior successful c
29ee0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
29ef0 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 open()], [sqlite
29f00 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 3_open_v2()] or.
29f10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ** [sqlite3_open
29f20 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 16()]. The data
29f30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
29f40 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 must not have be
29f50 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a en closed..**.**
29f60 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 The second argu
29f70 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 ment, "zSql", is
29f80 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 the statement t
29f90 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 o be compiled, e
29fa0 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 ncoded.** as eit
29fb0 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 her UTF-8 or UTF
29fc0 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 -16. The sqlite
29fd0 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 3_prepare() and
29fe0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
29ff0 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 v2().** interfac
2a000 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e es use UTF-8, an
2a010 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 d sqlite3_prepar
2a020 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 e16() and sqlite
2a030 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
2a040 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a .** use UTF-16..
2a050 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 **.** ^If the nB
2a060 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 yte argument is
2a070 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 7a negative, then z
2a080 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 Sql is read up t
2a090 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a o the.** first z
2a0a0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 ero terminator.
2a0b0 5e 49 66 20 6e 42 79 74 65 20 69 73 20 70 6f 73 ^If nByte is pos
2a0c0 69 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 itive, then it i
2a0d0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 s the.** number
2a0e0 6f 66 20 62 79 74 65 73 20 72 65 61 64 20 66 72 of bytes read fr
2a0f0 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42 om zSql. ^If nB
2a100 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 yte is zero, the
2a110 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a n no prepared.**
2a120 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 67 65 statement is ge
2a130 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74 nerated..** If t
2a140 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 he caller knows
2a150 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 that the supplie
2a160 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d d string is nul-
2a170 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e terminated, then
2a180 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61 20 73 .** there is a s
2a190 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65 mall performance
2a1a0 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 70 61 advantage to pa
2a1b0 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 ssing an nByte p
2a1c0 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a arameter that.**
2a1d0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
2a1e0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 f bytes in the i
2a1f0 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 nput string <i>i
2a200 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 ncluding</i>.**
2a210 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 the nul-terminat
2a220 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a or..**.** ^If pz
2a230 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c Tail is not NULL
2a240 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 then *pzTail is
2a250 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 made to point t
2a260 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 o the first byte
2a270 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 .** past the end
2a280 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51 of the first SQ
2a290 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a L statement in z
2a2a0 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 Sql. These rout
2a2b0 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d ines only.** com
2a2c0 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 pile the first s
2a2d0 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c tatement in zSql
2a2e0 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 , so *pzTail is
2a2f0 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f left pointing to
2a300 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 .** what remains
2a310 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a uncompiled..**.
2a320 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c ** ^*ppStmt is l
2a330 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 eft pointing to
2a340 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 a compiled [prep
2a350 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2a360 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 that can be.** e
2a370 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 xecuted using [s
2a380 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 qlite3_step()].
2a390 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e ^If there is an
2a3a0 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 error, *ppStmt
2a3b0 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c is set.** to NUL
2a3c0 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 L. ^If the inpu
2a3d0 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 t text contains
2a3e0 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 no SQL (if the i
2a3f0 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 nput is an empty
2a400 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 .** string or a
2a410 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 comment) then *p
2a420 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 pStmt is set to
2a430 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c NULL..** The cal
2a440 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 ling procedure i
2a450 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f s responsible fo
2a460 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 r deleting the c
2a470 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 ompiled.** SQL s
2a480 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b tatement using [
2a490 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
2a4a0 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 ()] after it has
2a4b0 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 finished with i
2a4c0 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 t..** ppStmt may
2a4d0 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a not be NULL..**
2a4e0 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c .** ^On success,
2a4f0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 the sqlite3_pre
2a500 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 pare() family of
2a510 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
2a520 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a [SQLITE_OK];.**
2a530 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 otherwise an [e
2a540 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 rror code] is re
2a550 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 turned..**.** Th
2a560 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 e sqlite3_prepar
2a570 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 e_v2() and sqlit
2a580 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
2a590 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 ) interfaces are
2a5a0 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 .** recommended
2a5b0 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 for all new prog
2a5c0 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c rams. The two ol
2a5d0 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 der interfaces a
2a5e0 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 re retained.** f
2a5f0 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d or backwards com
2a600 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 patibility, but
2a610 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 their use is dis
2a620 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e couraged..** ^In
2a630 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 the "v2" interf
2a640 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 aces, the prepar
2a650 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 ed statement.**
2a660 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 that is returned
2a670 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 (the [sqlite3_s
2a680 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e tmt] object) con
2a690 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 tains a copy of
2a6a0 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 the.** original
2a6b0 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 SQL text. This c
2a6c0 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 auses the [sqlit
2a6d0 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 e3_step()] inter
2a6e0 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 face to.** behav
2a6f0 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e e differently in
2a700 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a three ways:.**.
2a710 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a ** <ol>.** <li>.
2a720 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 ** ^If the datab
2a730 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 ase schema chang
2a740 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 es, instead of r
2a750 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 eturning [SQLITE
2a760 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a _SCHEMA] as it.*
2a770 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f * always used to
2a780 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 do, [sqlite3_st
2a790 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d ep()] will autom
2a7a0 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 atically recompi
2a7b0 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 le the SQL.** st
2a7c0 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 atement and try
2a7d0 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e to run it again.
2a7e0 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c As many as [SQL
2a7f0 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 ITE_MAX_SCHEMA_R
2a800 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 ETRY].** retries
2a810 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f will occur befo
2a820 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 re sqlite3_step(
2a830 29 20 67 69 76 65 73 20 75 70 20 61 6e 64 20 72 ) gives up and r
2a840 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e eturns an error.
2a850 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 .** </li>.**.**
2a860 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e <li>.** ^When an
2a870 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b error occurs, [
2a880 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
2a890 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 will return one
2a8a0 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a of the detailed.
2a8b0 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d ** [error codes]
2a8c0 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 or [extended er
2a8d0 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 ror codes]. ^Th
2a8e0 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f e legacy behavio
2a8f0 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 r was that.** [s
2a900 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 qlite3_step()] w
2a910 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e ould only return
2a920 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 a generic [SQLI
2a930 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 TE_ERROR] result
2a940 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 code.** and the
2a950 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 application wou
2a960 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 ld have to make
2a970 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f a second call to
2a980 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2a990 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 )].** in order t
2a9a0 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 o find the under
2a9b0 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 lying cause of t
2a9c0 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 he problem. With
2a9d0 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 the "v2" prepar
2a9e0 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c e.** interfaces,
2a9f0 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 the underlying
2aa00 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 reason for the e
2aa10 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 rror is returned
2aa20 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a immediately..**
2aa30 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 </li>.**.** <li
2aa40 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 >.** ^If the spe
2aa50 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e cific value boun
2aa60 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 d to [parameter
2aa70 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 | host parameter
2aa80 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 ] in the .** WHE
2aa90 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 RE clause might
2aaa0 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 influence the ch
2aab0 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c oice of query pl
2aac0 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 an for a stateme
2aad0 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 nt,.** then the
2aae0 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 statement will b
2aaf0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 e automatically
2ab00 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 recompiled, as i
2ab10 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e f there had been
2ab20 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 .** a schema ch
2ab30 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 ange, on the fir
2ab40 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 st [sqlite3_ste
2ab50 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 p()] call follow
2ab60 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a ing any change.*
2ab70 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 * to the [sqlite
2ab80 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 3_bind_text | bi
2ab90 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 ndings] of that
2aba0 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a [parameter]. .**
2abb0 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76 ^The specific v
2abc0 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c alue of WHERE-cl
2abd0 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d ause [parameter]
2abe0 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 might influence
2abf0 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 the .** choice
2ac00 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 of query plan if
2ac10 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 the parameter i
2ac20 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 s the left-hand
2ac30 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d side of a [LIKE]
2ac40 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 .** or [GLOB] op
2ac50 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 erator or if the
2ac60 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f parameter is co
2ac70 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 mpared to an ind
2ac80 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 exed column.** a
2ac90 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 nd the [SQLITE_E
2aca0 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d NABLE_STAT3] com
2acb0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
2acc0 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 is enabled..**
2acd0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a </li>.** </ol>.*
2ace0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 /.int sqlite3_pr
2acf0 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 epare(. sqlite3
2ad00 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
2ad10 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e /* Database han
2ad20 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 dle */. const c
2ad30 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 har *zSql,
2ad40 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e /* SQL statemen
2ad50 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 t, UTF-8 encoded
2ad60 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c */. int nByte,
2ad70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
2ad80 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 Maximum length
2ad90 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 of zSql in bytes
2ada0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 . */. sqlite3_s
2adb0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f tmt **ppStmt, /
2adc0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 * OUT: Statement
2add0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
2ade0 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c st char **pzTail
2adf0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 /* OUT: Poi
2ae00 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 nter to unused p
2ae10 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a ortion of zSql *
2ae20 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 /.);.int sqlite3
2ae30 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 _prepare_v2(. s
2ae40 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
2ae50 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
2ae60 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 se handle */. c
2ae70 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c onst char *zSql,
2ae80 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 /* SQL st
2ae90 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 atement, UTF-8 e
2aea0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 ncoded */. int
2aeb0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 nByte,
2aec0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c /* Maximum l
2aed0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e ength of zSql in
2aee0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c bytes. */. sql
2aef0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 ite3_stmt **ppSt
2af00 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 mt, /* OUT: Sta
2af10 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f tement handle */
2af20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a . const char **
2af30 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 pzTail /* OU
2af40 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e T: Pointer to un
2af50 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 used portion of
2af60 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 zSql */.);.int s
2af70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
2af80 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
2af90 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 /* D
2afa0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a atabase handle *
2afb0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a /. const void *
2afc0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 zSql, /* S
2afd0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 QL statement, UT
2afe0 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a F-16 encoded */.
2aff0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 int nByte,
2b000 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 /* Max
2b010 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a imum length of z
2b020 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f Sql in bytes. */
2b030 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 . sqlite3_stmt
2b040 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 **ppStmt, /* OU
2b050 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e T: Statement han
2b060 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 dle */. const v
2b070 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 oid **pzTail
2b080 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 /* OUT: Pointer
2b090 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 to unused porti
2b0a0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b on of zSql */.);
2b0b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 .int sqlite3_pre
2b0c0 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c pare16_v2(. sql
2b0d0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
2b0e0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
2b0f0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
2b100 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 st void *zSql,
2b110 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 /* SQL stat
2b120 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e ement, UTF-16 en
2b130 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e coded */. int n
2b140 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 Byte,
2b150 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 /* Maximum le
2b160 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 ngth of zSql in
2b170 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 bytes. */. sqli
2b180 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d te3_stmt **ppStm
2b190 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 t, /* OUT: Stat
2b1a0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a ement handle */.
2b1b0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 const void **p
2b1c0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 zTail /* OUT
2b1d0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 : Pointer to unu
2b1e0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a sed portion of z
2b1f0 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a Sql */.);../*.**
2b200 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 CAPI3REF: Retri
2b210 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 eving Statement
2b220 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 SQL.** METHOD: s
2b230 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a qlite3_stmt.**.*
2b240 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 * ^The sqlite3_s
2b250 71 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 ql(P) interface
2b260 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
2b270 72 20 74 6f 20 61 20 63 6f 70 79 20 6f 66 20 74 r to a copy of t
2b280 68 65 20 55 54 46 2d 38 0a 2a 2a 20 53 51 4c 20 he UTF-8.** SQL
2b290 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 text used to cre
2b2a0 61 74 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 ate [prepared st
2b2b0 61 74 65 6d 65 6e 74 5d 20 50 20 69 66 20 50 20 atement] P if P
2b2c0 77 61 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 was.** created b
2b2d0 79 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 y either [sqlite
2b2e0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
2b2f0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 or [sqlite3_prep
2b300 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 20 are16_v2()]..**
2b310 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70 ^The sqlite3_exp
2b320 61 6e 64 65 64 5f 73 71 6c 28 50 29 20 69 6e 74 anded_sql(P) int
2b330 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
2b340 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 55 54 pointer to a UT
2b350 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f F-8.** string co
2b360 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 53 51 4c ntaining the SQL
2b370 20 74 65 78 74 20 6f 66 20 70 72 65 70 61 72 65 text of prepare
2b380 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 77 69 d statement P wi
2b390 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64 20 70 61 72 th.** [bound par
2b3a0 61 6d 65 74 65 72 73 5d 20 65 78 70 61 6e 64 65 ameters] expande
2b3b0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 d..**.** ^(For e
2b3c0 78 61 6d 70 6c 65 2c 20 69 66 20 61 20 70 72 65 xample, if a pre
2b3d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
2b3e0 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 is created using
2b3f0 20 74 68 65 20 53 51 4c 0a 2a 2a 20 74 65 78 74 the SQL.** text
2b400 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 "SELECT $abc,:x
2b410 79 7a 22 20 61 6e 64 20 69 66 20 70 61 72 61 6d yz" and if param
2b420 65 74 65 72 20 24 61 62 63 20 69 73 20 62 6f 75 eter $abc is bou
2b430 6e 64 20 74 6f 20 69 6e 74 65 67 65 72 20 32 33 nd to integer 23
2b440 34 35 0a 2a 2a 20 61 6e 64 20 70 61 72 61 6d 65 45.** and parame
2b450 74 65 72 20 3a 78 79 7a 20 69 73 20 75 6e 62 6f ter :xyz is unbo
2b460 75 6e 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 und, then sqlite
2b470 33 5f 73 71 6c 28 29 20 77 69 6c 6c 20 72 65 74 3_sql() will ret
2b480 75 72 6e 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 urn.** the origi
2b490 6e 61 6c 20 73 74 72 69 6e 67 2c 20 22 53 45 4c nal string, "SEL
2b4a0 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 62 ECT $abc,:xyz" b
2b4b0 75 74 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e ut sqlite3_expan
2b4c0 64 65 64 5f 73 71 6c 28 29 0a 2a 2a 20 77 69 6c ded_sql().** wil
2b4d0 6c 20 72 65 74 75 72 6e 20 22 53 45 4c 45 43 54 l return "SELECT
2b4e0 20 32 33 34 35 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a 2345,NULL".)^.*
2b4f0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
2b500 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 3_expanded_sql()
2b510 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
2b520 6e 73 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 ns NULL if insuf
2b530 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 0a 2a ficient memory.*
2b540 2a 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 74 * is available t
2b550 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c o hold the resul
2b560 74 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 73 t, or if the res
2b570 75 6c 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64 ult would exceed
2b580 20 74 68 65 0a 2a 2a 20 74 68 65 20 6d 61 78 69 the.** the maxi
2b590 6d 75 6d 20 73 74 72 69 6e 67 20 6c 65 6e 67 74 mum string lengt
2b5a0 68 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 h determined by
2b5b0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 the [SQLITE_LIMI
2b5c0 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a T_LENGTH]..**.**
2b5d0 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 ^The [SQLITE_TR
2b5e0 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 ACE_SIZE_LIMIT]
2b5f0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
2b600 69 6f 6e 20 6c 69 6d 69 74 73 20 74 68 65 20 73 ion limits the s
2b610 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f 75 6e 64 20 ize of.** bound
2b620 70 61 72 61 6d 65 74 65 72 20 65 78 70 61 6e 73 parameter expans
2b630 69 6f 6e 73 2e 20 20 5e 54 68 65 20 5b 53 51 4c ions. ^The [SQL
2b640 49 54 45 5f 4f 4d 49 54 5f 54 52 41 43 45 5d 20 ITE_OMIT_TRACE]
2b650 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 compile-time.**
2b660 6f 70 74 69 6f 6e 20 63 61 75 73 65 73 20 73 71 option causes sq
2b670 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 lite3_expanded_s
2b680 71 6c 28 29 20 74 6f 20 61 6c 77 61 79 73 20 72 ql() to always r
2b690 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a eturn NULL..**.*
2b6a0 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20 72 65 * ^The string re
2b6b0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 turned by sqlite
2b6c0 33 5f 73 71 6c 28 50 29 20 69 73 20 6d 61 6e 61 3_sql(P) is mana
2b6d0 67 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 6e ged by SQLite an
2b6e0 64 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 d is.** automati
2b6f0 63 61 6c 6c 79 20 66 72 65 65 64 20 77 68 65 6e cally freed when
2b700 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 the prepared st
2b710 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c atement is final
2b720 69 7a 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 74 ized..** ^The st
2b730 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 ring returned by
2b740 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 sqlite3_expande
2b750 64 5f 73 71 6c 28 50 29 2c 20 6f 6e 20 74 68 65 d_sql(P), on the
2b760 20 6f 74 68 65 72 20 68 61 6e 64 2c 0a 2a 2a 20 other hand,.**
2b770 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d is obtained from
2b780 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
2b790 28 29 5d 20 61 6e 64 20 6d 75 73 74 20 62 65 20 ()] and must be
2b7a0 66 72 65 65 20 62 79 20 74 68 65 20 61 70 70 6c free by the appl
2b7b0 69 63 61 74 69 6f 6e 0a 2a 2a 20 62 79 20 70 61 ication.** by pa
2b7c0 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c ssing it to [sql
2b7d0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f ite3_free()]..*/
2b7e0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
2b7f0 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 ite3_sql(sqlite3
2b800 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 63 _stmt *pStmt);.c
2b810 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 78 70 har *sqlite3_exp
2b820 61 6e 64 65 64 5f 73 71 6c 28 73 71 6c 69 74 65 anded_sql(sqlite
2b830 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
2b840 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2b850 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e Determine If An
2b860 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 SQL Statement W
2b870 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61 rites The Databa
2b880 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 se.** METHOD: sq
2b890 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a lite3_stmt.**.**
2b8a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 ^The sqlite3_st
2b8b0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 mt_readonly(X) i
2b8c0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
2b8d0 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 true (non-zero)
2b8e0 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 if.** and only
2b8f0 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 if the [prepared
2b900 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 statement] X ma
2b910 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 kes no direct ch
2b920 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 anges to.** the
2b930 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 content of the d
2b940 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a atabase file..**
2b950 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 .** Note that [a
2b960 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
2b970 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 ed SQL functions
2b980 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c ] or.** [virtual
2b990 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 tables] might c
2b9a0 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 hange the databa
2b9b0 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 se indirectly as
2b9c0 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 a side effect.
2b9d0 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 .** ^(For examp
2b9e0 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 le, if an applic
2b9f0 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 ation defines a
2ba00 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 function "eval()
2ba10 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 " that .** calls
2ba20 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 [sqlite3_exec()
2ba30 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c ], then the foll
2ba40 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d owing SQL statem
2ba50 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 ent would.** cha
2ba60 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 nge the database
2ba70 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 file through si
2ba80 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a de-effects:.**.*
2ba90 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
2baa0 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 re>.** SELECT
2bab0 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 eval('DELETE FR
2bac0 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b OM t1') FROM t2;
2bad0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
2bae0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 kquote>.**.** Bu
2baf0 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 t because the [S
2bb00 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 ELECT] statement
2bb10 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 does not change
2bb20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
2bb30 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 le.** directly,
2bb40 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 sqlite3_stmt_rea
2bb50 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 donly() would st
2bb60 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e ill return true.
2bb70 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 )^.**.** ^Transa
2bb80 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 ction control st
2bb90 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 atements such as
2bba0 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 [BEGIN], [COMMI
2bbb0 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a T], [ROLLBACK],.
2bbc0 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 ** [SAVEPOINT],
2bbd0 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 and [RELEASE] ca
2bbe0 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 use sqlite3_stmt
2bbf0 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 _readonly() to r
2bc00 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 eturn true,.** s
2bc10 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 ince the stateme
2bc20 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 nts themselves d
2bc30 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d o not actually m
2bc40 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 odify the databa
2bc50 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 se but.** rather
2bc60 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 they control th
2bc70 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e e timing of when
2bc80 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 other statement
2bc90 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a s modify the .**
2bca0 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 database. ^The
2bcb0 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 [ATTACH] and [D
2bcc0 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 ETACH] statement
2bcd0 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 s also cause.**
2bce0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 sqlite3_stmt_rea
2bcf0 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 donly() to retur
2bd00 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 n true since, wh
2bd10 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d ile those statem
2bd20 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 ents.** change t
2bd30 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e he configuration
2bd40 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63 of a database c
2bd50 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 onnection, they
2bd60 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 do not make .**
2bd70 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 changes to the c
2bd80 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 ontent of the da
2bd90 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 tabase files on
2bda0 64 69 73 6b 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 disk..** ^The sq
2bdb0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f lite3_stmt_reado
2bdc0 6e 6c 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 nly() interface
2bdd0 72 65 74 75 72 6e 73 20 74 72 75 65 20 66 6f 72 returns true for
2bde0 20 5b 42 45 47 49 4e 5d 20 73 69 6e 63 65 0a 2a [BEGIN] since.*
2bdf0 2a 20 5b 42 45 47 49 4e 5d 20 6d 65 72 65 6c 79 * [BEGIN] merely
2be00 20 73 65 74 73 20 69 6e 74 65 72 6e 61 6c 20 66 sets internal f
2be10 6c 61 67 73 2c 20 62 75 74 20 74 68 65 20 5b 42 lags, but the [B
2be20 45 47 49 4e 7c 42 45 47 49 4e 20 49 4d 4d 45 44 EGIN|BEGIN IMMED
2be30 49 41 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b 42 45 IATE] and.** [BE
2be40 47 49 4e 7c 42 45 47 49 4e 20 45 58 43 4c 55 53 GIN|BEGIN EXCLUS
2be50 49 56 45 5d 20 63 6f 6d 6d 61 6e 64 73 20 64 6f IVE] commands do
2be60 20 74 6f 75 63 68 20 74 68 65 20 64 61 74 61 62 touch the datab
2be70 61 73 65 20 61 6e 64 20 73 6f 0a 2a 2a 20 73 71 ase and so.** sq
2be80 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f lite3_stmt_reado
2be90 6e 6c 79 28 29 20 72 65 74 75 72 6e 73 20 66 61 nly() returns fa
2bea0 6c 73 65 20 66 6f 72 20 74 68 6f 73 65 20 63 6f lse for those co
2beb0 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 mmands..*/.int s
2bec0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 qlite3_stmt_read
2bed0 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d only(sqlite3_stm
2bee0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
2bef0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 * CAPI3REF: Dete
2bf00 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61 rmine If A Prepa
2bf10 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61 red Statement Ha
2bf20 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20 s Been Reset.**
2bf30 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f METHOD: sqlite3_
2bf40 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 stmt.**.** ^The
2bf50 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 sqlite3_stmt_bus
2bf60 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 y(S) interface r
2bf70 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e eturns true (non
2bf80 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a -zero) if the.**
2bf90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2bfa0 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e ment] S has been
2bfb0 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 stepped at leas
2bfc0 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a t once using .**
2bfd0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 [sqlite3_step(S
2bfe0 29 5d 20 62 75 74 20 68 61 73 20 6e 65 69 74 68 )] but has neith
2bff0 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 er run to comple
2c000 74 69 6f 6e 20 28 72 65 74 75 72 6e 65 64 0a 2a tion (returned.*
2c010 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 * [SQLITE_DONE]
2c020 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 74 from [sqlite3_st
2c030 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 ep(S)]) nor.** b
2c040 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 een reset using
2c050 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 [sqlite3_reset(S
2c060 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 )]. ^The sqlite
2c070 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 3_stmt_busy(S).*
2c080 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 * interface retu
2c090 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 rns false if S i
2c0a0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
2c0b0 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 . If S is not a
2c0c0 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 .** NULL pointe
2c0d0 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 r and is not a p
2c0e0 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 ointer to a vali
2c0f0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
2c100 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 ement].** object
2c110 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 , then the behav
2c120 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ior is undefined
2c130 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e and probably un
2c140 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a desirable..**.**
2c150 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 This interface
2c160 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 can be used in c
2c170 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 ombination [sqli
2c180 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d te3_next_stmt()]
2c190 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c .** to locate al
2c1a0 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 l prepared state
2c1b0 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 ments associated
2c1c0 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65 with a database
2c1d0 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 .** connection
2c1e0 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 that are in need
2c1f0 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e of being reset.
2c200 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 This can be us
2c210 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 ed,.** for examp
2c220 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 le, in diagnosti
2c230 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 c routines to se
2c240 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 arch for prepare
2c250 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 d .** statements
2c260 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e that are holdin
2c270 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 g a transaction
2c280 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c open..*/.int sql
2c290 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 ite3_stmt_busy(s
2c2a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a qlite3_stmt*);..
2c2b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2c2c0 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 Dynamically Type
2c2d0 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a d Value Object.*
2c2e0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f * KEYWORDS: {pro
2c2f0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
2c300 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 alue} {unprotect
2c310 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
2c320 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 }.**.** SQLite u
2c330 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f ses the sqlite3_
2c340 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 value object to
2c350 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 represent all va
2c360 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e lues.** that can
2c370 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 be stored in a
2c380 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 database table.
2c390 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 SQLite uses dyna
2c3a0 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f mic typing.** fo
2c3b0 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 r the values it
2c3c0 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 stores. ^Values
2c3d0 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 stored in sqlit
2c3e0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
2c3f0 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 .** can be integ
2c400 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f ers, floating po
2c410 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 int values, stri
2c420 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e ngs, BLOBs, or N
2c430 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 ULL..**.** An sq
2c440 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
2c450 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 ct may be either
2c460 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 "protected" or
2c470 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a "unprotected"..*
2c480 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 * Some interface
2c490 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 s require a prot
2c4a0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
2c4b0 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 lue. Other inte
2c4c0 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 rfaces.** will a
2c4d0 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 ccept either a p
2c4e0 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 rotected or an u
2c4f0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
2c500 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 e3_value..** Eve
2c510 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 ry interface tha
2c520 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 t accepts sqlite
2c530 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 3_value argument
2c540 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 s specifies.** w
2c550 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 hether or not it
2c560 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 requires a prot
2c570 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
2c580 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 lue. The.** [sq
2c590 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 lite3_value_dup(
2c5a0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e )] interface can
2c5b0 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f 6e 73 be used to cons
2c5c0 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20 truct a new .**
2c5d0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
2c5e0 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20 3_value from an
2c5f0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
2c600 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a te3_value..**.**
2c610 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 The terms "prot
2c620 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 ected" and "unpr
2c630 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 otected" refer t
2c640 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 o whether or not
2c650 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 .** a mutex is h
2c660 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 eld. An interna
2c670 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 l mutex is held
2c680 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a for a protected.
2c690 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ** sqlite3_value
2c6a0 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d object but no m
2c6b0 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 utex is held for
2c6c0 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a an unprotected.
2c6d0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ** sqlite3_value
2c6e0 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c object. If SQL
2c6f0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
2c700 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 to be single-thr
2c710 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b eaded.** (with [
2c720 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
2c730 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 E=0] and with [s
2c740 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 qlite3_threadsaf
2c750 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 e()] returning 0
2c760 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 ).** or if SQLit
2c770 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 e is run in one
2c780 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 of reduced mutex
2c790 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 modes .** [SQLI
2c7a0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 TE_CONFIG_SINGLE
2c7b0 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 THREAD] or [SQLI
2c7c0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 TE_CONFIG_MULTIT
2c7d0 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 HREAD].** then t
2c7e0 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 here is no disti
2c7f0 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 nction between p
2c800 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 rotected and unp
2c810 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 rotected.** sqli
2c820 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
2c830 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 s and they can b
2c840 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e e used interchan
2c850 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 geably. However
2c860 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d ,.** for maximum
2c870 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 code portabilit
2c880 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e y it is recommen
2c890 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 ded that applica
2c8a0 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d tions.** still m
2c8b0 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 ake the distinct
2c8c0 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 ion between prot
2c8d0 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 ected and unprot
2c8e0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ected.** sqlite3
2c8f0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 _value objects e
2c900 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 ven when not str
2c910 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a ictly required..
2c920 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2c930 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
2c940 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64 that are passed
2c950 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 as parameters i
2c960 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 nto the.** imple
2c970 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 mentation of [ap
2c980 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
2c990 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d d SQL functions]
2c9a0 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a are protected..
2c9b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2c9c0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 value object ret
2c9d0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c urned by.** [sql
2c9e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 ite3_column_valu
2c9f0 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 e()] is unprotec
2ca00 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 ted..** Unprotec
2ca10 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
2ca20 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e e objects may on
2ca30 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a ly be used with.
2ca40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 ** [sqlite3_resu
2ca50 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 lt_value()] and
2ca60 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 [sqlite3_bind_va
2ca70 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b lue()]..** The [
2ca80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c sqlite3_value_bl
2ca90 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c ob | sqlite3_val
2caa0 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c ue_type()] famil
2cab0 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 y of.** interfac
2cac0 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 es require prote
2cad0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
2cae0 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 ue objects..*/.t
2caf0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 ypedef struct Me
2cb00 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b m sqlite3_value;
2cb10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2cb20 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 : SQL Function C
2cb30 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a ontext Object.**
2cb40 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 .** The context
2cb50 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 in which an SQL
2cb60 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 function execute
2cb70 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 s is stored in a
2cb80 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e n.** sqlite3_con
2cb90 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 text object. ^A
2cba0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 pointer to an s
2cbb0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f qlite3_context o
2cbc0 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 bject.** is alwa
2cbd0 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 ys first paramet
2cbe0 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 er to [applicati
2cbf0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
2cc00 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 unctions]..** Th
2cc10 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
2cc20 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 fined SQL functi
2cc30 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f on implementatio
2cc40 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 n will pass this
2cc50 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f .** pointer thro
2cc60 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 ugh into calls t
2cc70 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c o [sqlite3_resul
2cc80 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f t_int | sqlite3_
2cc90 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 result()],.** [s
2cca0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
2ccb0 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 _context()], [sq
2ccc0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 lite3_user_data(
2ccd0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
2cce0 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c context_db_handl
2ccf0 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 e()], [sqlite3_g
2cd00 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a et_auxdata()],.*
2cd10 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 * and/or [sqlite
2cd20 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 3_set_auxdata()]
2cd30 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
2cd40 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 uct sqlite3_cont
2cd50 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ext sqlite3_cont
2cd60 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ext;../*.** CAPI
2cd70 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 3REF: Binding Va
2cd80 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 lues To Prepared
2cd90 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b Statements.** K
2cda0 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 EYWORDS: {host p
2cdb0 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 arameter} {host
2cdc0 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 parameters} {hos
2cdd0 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 t parameter name
2cde0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b }.** KEYWORDS: {
2cdf0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b SQL parameter} {
2ce00 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 SQL parameters}
2ce10 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 {parameter bindi
2ce20 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ng}.** METHOD: s
2ce30 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a qlite3_stmt.**.*
2ce40 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 * ^(In the SQL s
2ce50 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e tatement text in
2ce60 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f put to [sqlite3_
2ce70 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e prepare_v2()] an
2ce80 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a d its variants,.
2ce90 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 ** literals may
2cea0 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 be replaced by a
2ceb0 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 [parameter] tha
2cec0 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 t matches one of
2ced0 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 following.** te
2cee0 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c mplates:.**.** <
2cef0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a ul>.** <li> ?.*
2cf00 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 * <li> ?NNN.**
2cf10 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c <li> :VVV.** <l
2cf20 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e i> @VVV.** <li>
2cf30 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a $VVV.** </ul>.
2cf40 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d **.** In the tem
2cf50 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e plates above, NN
2cf60 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 N represents an
2cf70 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c integer literal,
2cf80 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 .** and VVV repr
2cf90 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e esents an alphan
2cfa0 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 umeric identifie
2cfb0 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 r.)^ ^The value
2cfc0 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 s of these.** pa
2cfd0 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 rameters (also c
2cfe0 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 alled "host para
2cff0 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 meter names" or
2d000 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 "SQL parameters"
2d010 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 ).** can be set
2d020 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 using the sqlite
2d030 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 3_bind_*() routi
2d040 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 nes defined here
2d050 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 ..**.** ^The fir
2d060 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 st argument to t
2d070 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
2d080 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 *() routines is
2d090 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e always.** a poin
2d0a0 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 ter to the [sqli
2d0b0 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 te3_stmt] object
2d0c0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a returned from.*
2d0d0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
2d0e0 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 re_v2()] or its
2d0f0 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 variants..**.**
2d100 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 ^The second argu
2d110 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 ment is the inde
2d120 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 x of the SQL par
2d130 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 ameter to be set
2d140 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f ..** ^The leftmo
2d150 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 st SQL parameter
2d160 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 has an index of
2d170 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 1. ^When the s
2d180 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c ame named.** SQL
2d190 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 parameter is us
2d1a0 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 ed more than onc
2d1b0 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 e, second and su
2d1c0 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 bsequent.** occu
2d1d0 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 rrences have the
2d1e0 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 same index as t
2d1f0 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 he first occurre
2d200 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 nce..** ^The ind
2d210 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 ex for named par
2d220 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c ameters can be l
2d230 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 ooked up using t
2d240 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 he.** [sqlite3_b
2d250 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e ind_parameter_in
2d260 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 dex()] API if de
2d270 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 sired. ^The ind
2d280 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 ex.** for "?NNN"
2d290 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 parameters is t
2d2a0 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e he value of NNN.
2d2b0 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c .** ^The NNN val
2d2c0 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 ue must be betwe
2d2d0 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 en 1 and the [sq
2d2e0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a lite3_limit()].*
2d2f0 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c * parameter [SQL
2d300 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 ITE_LIMIT_VARIAB
2d310 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 LE_NUMBER] (defa
2d320 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e ult value: 999).
2d330 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 .**.** ^The thir
2d340 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
2d350 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 e value to bind
2d360 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 to the parameter
2d370 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 ..** ^If the thi
2d380 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
2d390 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
2d3a0 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 t() or sqlite3_b
2d3b0 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 ind_text16().**
2d3c0 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f or sqlite3_bind_
2d3d0 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c blob() is a NULL
2d3e0 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 pointer then th
2d3f0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
2d400 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 er.** is ignored
2d410 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73 and the end res
2d420 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65 20 ult is the same
2d430 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f as sqlite3_bind_
2d440 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 null()..**.** ^(
2d450 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 In those routine
2d460 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f s that have a fo
2d470 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 urth argument, i
2d480 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a ts value is the.
2d490 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 ** number of byt
2d4a0 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 es in the parame
2d4b0 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 ter. To be clea
2d4c0 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 r: the value is
2d4d0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 the.** number of
2d4e0 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e <u>bytes</u> in
2d4f0 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 the value, not
2d500 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 the number of ch
2d510 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e aracters.)^.** ^
2d520 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 If the fourth pa
2d530 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
2d540 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f e3_bind_text() o
2d550 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 r sqlite3_bind_t
2d560 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 ext16().** is ne
2d570 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 gative, then the
2d580 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 length of the s
2d590 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 tring is.** the
2d5a0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
2d5b0 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 up to the first
2d5c0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e zero terminator.
2d5d0 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 .** If the fourt
2d5e0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 h parameter to s
2d5f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
2d600 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 () is negative,
2d610 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 then.** the beha
2d620 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 vior is undefine
2d630 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e d..** If a non-n
2d640 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 egative fourth p
2d650 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 arameter is prov
2d660 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f ided to sqlite3_
2d670 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f bind_text().** o
2d680 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 r sqlite3_bind_t
2d690 65 78 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74 ext16() or sqlit
2d6a0 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 e3_bind_text64()
2d6b0 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 then.** that pa
2d6c0 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 rameter must be
2d6d0 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a the byte offset.
2d6e0 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c ** where the NUL
2d6f0 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c terminator woul
2d700 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 d occur assuming
2d710 20 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 the string were
2d720 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 NUL.** terminat
2d730 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 ed. If any NUL
2d740 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 characters occur
2d750 20 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 at byte offsets
2d760 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 less than .** t
2d770 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 he value of the
2d780 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
2d790 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 then the result
2d7a0 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 ing string value
2d7b0 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e will.** contain
2d7c0 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 embedded NULs.
2d7d0 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 The result of e
2d7e0 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c xpressions invol
2d7f0 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 ving strings.**
2d800 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 with embedded NU
2d810 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e Ls is undefined.
2d820 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 .**.** ^The fift
2d830 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 h argument to th
2d840 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e e BLOB and strin
2d850 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 g binding interf
2d860 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 aces.** is a des
2d870 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 tructor used to
2d880 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 dispose of the B
2d890 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 LOB or.** string
2d8a0 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 after SQLite ha
2d8b0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 s finished with
2d8c0 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 it. ^The destru
2d8d0 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a ctor is called.*
2d8e0 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 * to dispose of
2d8f0 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 the BLOB or stri
2d900 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 ng even if the c
2d910 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20 all to bind API
2d920 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 fails..** ^If th
2d930 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 e fifth argument
2d940 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 is.** the speci
2d950 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 al value [SQLITE
2d960 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 _STATIC], then S
2d970 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 QLite assumes th
2d980 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d at the.** inform
2d990 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 ation is in stat
2d9a0 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 ic, unmanaged sp
2d9b0 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 ace and does not
2d9c0 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 need to be free
2d9d0 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 d..** ^If the fi
2d9e0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 fth argument has
2d9f0 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 the value [SQLI
2da00 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 TE_TRANSIENT], t
2da10 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 hen.** SQLite ma
2da20 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 kes its own priv
2da30 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 ate copy of the
2da40 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 data immediately
2da50 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 , before.** the
2da60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 sqlite3_bind_*()
2da70 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
2da80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 ..**.** ^The six
2da90 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 th argument to s
2daa0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
2dab0 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 64() must be one
2dac0 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 of.** [SQLITE_U
2dad0 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 TF8], [SQLITE_UT
2dae0 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 F16], [SQLITE_UT
2daf0 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 F16BE], or [SQLI
2db00 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 TE_UTF16LE].** t
2db10 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 65 6e o specify the en
2db20 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65 coding of the te
2db30 78 74 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 xt in the third
2db40 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a parameter. If.*
2db50 2a 20 74 68 65 20 73 69 78 74 68 20 61 72 67 75 * the sixth argu
2db60 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f ment to sqlite3_
2db70 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73 bind_text64() is
2db80 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a not one of the.
2db90 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 ** allowed value
2dba0 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f s shown above, o
2dbb0 72 20 69 66 20 74 68 65 20 74 65 78 74 20 65 6e r if the text en
2dbc0 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 coding is differ
2dbd0 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 ent.** from the
2dbe0 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 encoding specifi
2dbf0 65 64 20 62 79 20 74 68 65 20 73 69 78 74 68 20 ed by the sixth
2dc00 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 parameter, then
2dc10 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 the behavior.**
2dc20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a is undefined..**
2dc30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2dc40 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 _bind_zeroblob()
2dc50 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 routine binds a
2dc60 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 BLOB of length
2dc70 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c N that.** is fil
2dc80 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e led with zeroes.
2dc90 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 ^A zeroblob us
2dca0 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e es a fixed amoun
2dcb0 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 t of memory.** (
2dcc0 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 just an integer
2dcd0 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 to hold its size
2dce0 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 ) while it is be
2dcf0 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a ing processed..*
2dd00 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 * Zeroblobs are
2dd10 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 intended to serv
2dd20 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 e as placeholder
2dd30 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 s for BLOBs whos
2dd40 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 e.** content is
2dd50 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 later written us
2dd60 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
2dd70 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 blob_open | incr
2dd80 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f emental BLOB I/O
2dd90 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e ] routines..** ^
2dda0 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 A negative value
2ddb0 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f for the zeroblo
2ddc0 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a b results in a z
2ddd0 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e ero-length BLOB.
2dde0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f .**.** ^If any o
2ddf0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 f the sqlite3_bi
2de00 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 nd_*() routines
2de10 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 are called with
2de20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a a NULL pointer.*
2de30 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 * for the [prepa
2de40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f red statement] o
2de50 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65 r with a prepare
2de60 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 d statement for
2de70 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 which.** [sqlite
2de80 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 3_step()] has be
2de90 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 en called more r
2dea0 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 ecently than [sq
2deb0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a lite3_reset()],.
2dec0 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c ** then the call
2ded0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 will return [SQ
2dee0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 LITE_MISUSE]. I
2def0 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 f any sqlite3_bi
2df00 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 nd_().** routine
2df10 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 is passed a [pr
2df20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2df30 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 ] that has been
2df40 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a finalized, the.*
2df50 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 * result is unde
2df60 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 fined and probab
2df70 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a ly harmful..**.*
2df80 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 * ^Bindings are
2df90 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 not cleared by t
2dfa0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 he [sqlite3_rese
2dfb0 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a t()] routine..**
2dfc0 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 ^Unbound parame
2dfd0 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 ters are interpr
2dfe0 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a eted as NULL..**
2dff0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2e000 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 _bind_* routines
2e010 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
2e020 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f OK] on success o
2e030 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 r an.** [error c
2e040 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 ode] if anything
2e050 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 goes wrong..**
2e060 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d ^[SQLITE_TOOBIG]
2e070 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e might be return
2e080 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f ed if the size o
2e090 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c f a string or BL
2e0a0 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 OB.** exceeds li
2e0b0 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20 mits imposed by
2e0c0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 [sqlite3_limit](
2e0d0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 [SQLITE_LIMIT_LE
2e0e0 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 NGTH]) or.** [SQ
2e0f0 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d LITE_MAX_LENGTH]
2e100 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 ..** ^[SQLITE_RA
2e110 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 NGE] is returned
2e120 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 if the paramete
2e130 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 r.** index is ou
2e140 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 t of range. ^[S
2e150 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 QLITE_NOMEM] is
2e160 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c returned if mall
2e170 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a oc() fails..**.*
2e180 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
2e190 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2e1a0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a ter_count()],.**
2e1b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
2e1c0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d arameter_name()]
2e1d0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 , and [sqlite3_b
2e1e0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e ind_parameter_in
2e1f0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 dex()]..*/.int s
2e200 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
2e210 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2e220 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a int, const void*
2e230 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 , int n, void(*)
2e240 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 (void*));.int sq
2e250 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 lite3_bind_blob6
2e260 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 4(sqlite3_stmt*,
2e270 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 int, const void
2e280 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 *, sqlite3_uint6
2e290 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 4,.
2e2a0 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 void(
2e2b0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 *)(void*));.int
2e2c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 sqlite3_bind_dou
2e2d0 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ble(sqlite3_stmt
2e2e0 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b *, int, double);
2e2f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
2e300 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 d_int(sqlite3_st
2e310 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a mt*, int, int);.
2e320 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
2e330 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 _int64(sqlite3_s
2e340 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 tmt*, int, sqlit
2e350 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 e3_int64);.int s
2e360 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c qlite3_bind_null
2e370 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2e380 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 int);.int sqlite
2e390 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 3_bind_text(sqli
2e3a0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f te3_stmt*,int,co
2e3b0 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f nst char*,int,vo
2e3c0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 id(*)(void*));.i
2e3d0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
2e3e0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 text16(sqlite3_s
2e3f0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
2e400 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 void*, int, voi
2e410 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e d(*)(void*));.in
2e420 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 t sqlite3_bind_t
2e430 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 ext64(sqlite3_st
2e440 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 mt*, int, const
2e450 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 char*, sqlite3_u
2e460 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 int64,.
2e470 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2e480 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 void(*)(void*),
2e490 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e unsigned char en
2e4a0 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c coding);.int sql
2e4b0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 ite3_bind_value(
2e4c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2e4d0 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 nt, const sqlite
2e4e0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 3_value*);.int s
2e4f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f qlite3_bind_zero
2e500 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d blob(sqlite3_stm
2e510 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b t*, int, int n);
2e520 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
2e530 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c d_zeroblob64(sql
2e540 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
2e550 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 sqlite3_uint64)
2e560 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2e570 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c F: Number Of SQL
2e580 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d Parameters.** M
2e590 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 ETHOD: sqlite3_s
2e5a0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 tmt.**.** ^This
2e5b0 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 routine can be u
2e5c0 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 sed to find the
2e5d0 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 number of [SQL p
2e5e0 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e arameters].** in
2e5f0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
2e600 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 tement]. SQL pa
2e610 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b rameters are tok
2e620 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f ens of the.** fo
2e630 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 rm "?", "?NNN",
2e640 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 ":AAA", "$AAA",
2e650 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73 or "@AAA" that s
2e660 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 erve as.** place
2e670 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 holders for valu
2e680 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c es that are [sql
2e690 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c ite3_bind_blob |
2e6a0 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 bound].** to th
2e6b0 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 e parameters at
2e6c0 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a a later time..**
2e6d0 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 .** ^(This routi
2e6e0 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 ne actually retu
2e6f0 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 rns the index of
2e700 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 the largest (ri
2e710 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 ghtmost).** para
2e720 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 meter. For all f
2e730 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e orms except ?NNN
2e740 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 , this will corr
2e750 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a espond to the.**
2e760 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 number of uniqu
2e770 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 e parameters. I
2e780 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 f parameters of
2e790 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 the ?NNN form ar
2e7a0 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 e used,.** there
2e7b0 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 may be gaps in
2e7c0 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a the list.)^.**.*
2e7d0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
2e7e0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 ite3_bind_blob|s
2e7f0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a qlite3_bind()],.
2e800 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
2e810 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 _parameter_name(
2e820 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 )], and.** [sqli
2e830 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
2e840 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a er_index()]..*/.
2e850 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
2e860 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 _parameter_count
2e870 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b (sqlite3_stmt*);
2e880 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2e890 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 : Name Of A Host
2e8a0 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 Parameter.** ME
2e8b0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 THOD: sqlite3_st
2e8c0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 mt.**.** ^The sq
2e8d0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
2e8e0 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 eter_name(P,N) i
2e8f0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
2e900 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 .** the name of
2e910 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 the N-th [SQL pa
2e920 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 rameter] in the
2e930 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2e940 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c ent] P..** ^(SQL
2e950 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 parameters of t
2e960 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f he form "?NNN" o
2e970 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 r ":AAA" or "@AA
2e980 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 A" or "$AAA".**
2e990 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 have a name whic
2e9a0 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 h is the string
2e9b0 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 "?NNN" or ":AAA"
2e9c0 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 or "@AAA" or "$
2e9d0 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 AAA".** respecti
2e9e0 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 vely..** In othe
2e9f0 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 r words, the ini
2ea00 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 tial ":" or "$"
2ea10 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a or "@" or "?".**
2ea20 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 is included as
2ea30 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 part of the name
2ea40 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 .)^.** ^Paramete
2ea50 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 rs of the form "
2ea60 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c ?" without a fol
2ea70 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 lowing integer h
2ea80 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 ave no name.** a
2ea90 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20 nd are referred
2eaa0 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 to as "nameless"
2eab0 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 or "anonymous p
2eac0 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a arameters"..**.*
2ead0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 * ^The first hos
2eae0 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 t parameter has
2eaf0 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e an index of 1, n
2eb00 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 ot 0..**.** ^If
2eb10 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f the value N is o
2eb20 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 ut of range or i
2eb30 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d f the N-th param
2eb40 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c eter is.** namel
2eb50 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 ess, then NULL i
2eb60 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 s returned. ^Th
2eb70 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e e returned strin
2eb80 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 g is.** always i
2eb90 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 n UTF-8 encoding
2eba0 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d even if the nam
2ebb0 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 ed parameter was
2ebc0 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 .** originally s
2ebd0 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d pecified as UTF-
2ebe0 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 16 in [sqlite3_p
2ebf0 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a repare16()] or.*
2ec00 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
2ec10 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a re16_v2()]..**.*
2ec20 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
2ec30 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 ite3_bind_blob|s
2ec40 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a qlite3_bind()],.
2ec50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
2ec60 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 _parameter_count
2ec70 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
2ec80 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2ec90 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f ter_index()]..*/
2eca0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
2ecb0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2ecc0 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 ter_name(sqlite3
2ecd0 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f _stmt*, int);../
2ece0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 *.** CAPI3REF: I
2ecf0 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 ndex Of A Parame
2ed00 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e ter With A Given
2ed10 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a Name.** METHOD:
2ed20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
2ed30 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 .** ^Return the
2ed40 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 index of an SQL
2ed50 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 parameter given
2ed60 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a its name. ^The.
2ed70 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 ** index value r
2ed80 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 eturned is suita
2ed90 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 ble for use as t
2eda0 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 he second.** par
2edb0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 ameter to [sqlit
2edc0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c e3_bind_blob|sql
2edd0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e ite3_bind()]. ^
2ede0 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 A zero.** is ret
2edf0 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 urned if no matc
2ee00 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 hing parameter i
2ee10 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 s found. ^The p
2ee20 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 arameter.** name
2ee30 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 must be given i
2ee40 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 n UTF-8 even if
2ee50 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 the original sta
2ee60 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 tement.** was pr
2ee70 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d epared from UTF-
2ee80 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 16 text using [s
2ee90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
2eea0 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 _v2()]..**.** Se
2eeb0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
2eec0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 _bind_blob|sqlit
2eed0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b e3_bind()],.** [
2eee0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
2eef0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c ameter_count()],
2ef00 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
2ef10 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
2ef20 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 name()]..*/.int
2ef30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
2ef40 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c ameter_index(sql
2ef50 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 ite3_stmt*, cons
2ef60 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a t char *zName);.
2ef70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2ef80 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 Reset All Bindi
2ef90 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 ngs On A Prepare
2efa0 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d d Statement.** M
2efb0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 ETHOD: sqlite3_s
2efc0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 tmt.**.** ^Contr
2efd0 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 ary to the intui
2efe0 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 tion of many, [s
2eff0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
2f000 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a does not reset.*
2f010 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 * the [sqlite3_b
2f020 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 ind_blob | bindi
2f030 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 ngs] on a [prepa
2f040 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a red statement]..
2f050 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 ** ^Use this rou
2f060 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c tine to reset al
2f070 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 l host parameter
2f080 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e s to NULL..*/.in
2f090 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f t sqlite3_clear_
2f0a0 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 bindings(sqlite3
2f0b0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 _stmt*);../*.**
2f0c0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 CAPI3REF: Number
2f0d0 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 Of Columns In A
2f0e0 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d Result Set.** M
2f0f0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 ETHOD: sqlite3_s
2f100 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 tmt.**.** ^Retur
2f110 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 n the number of
2f120 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 columns in the r
2f130 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e esult set return
2f140 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 ed by the.** [pr
2f150 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2f160 5d 2e 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74 ]. ^If this rout
2f170 69 6e 65 20 72 65 74 75 72 6e 73 20 30 2c 20 74 ine returns 0, t
2f180 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 0a 2a hat means the .*
2f190 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 * [prepared stat
2f1a0 65 6d 65 6e 74 5d 20 72 65 74 75 72 6e 73 20 6e ement] returns n
2f1b0 6f 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d o data (for exam
2f1c0 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 ple an [UPDATE])
2f1d0 2e 0a 2a 2a 20 5e 48 6f 77 65 76 65 72 2c 20 6a ..** ^However, j
2f1e0 75 73 74 20 62 65 63 61 75 73 65 20 74 68 69 73 ust because this
2f1f0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
2f200 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 a positive numb
2f210 65 72 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 6d er does not.** m
2f220 65 61 6e 20 74 68 61 74 20 6f 6e 65 20 6f 72 20 ean that one or
2f230 6d 6f 72 65 20 72 6f 77 73 20 6f 66 20 64 61 74 more rows of dat
2f240 61 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e a will be return
2f250 65 64 2e 20 20 5e 41 20 53 45 4c 45 43 54 20 73 ed. ^A SELECT s
2f260 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 69 6c 6c tatement.** will
2f270 20 61 6c 77 61 79 73 20 68 61 76 65 20 61 20 70 always have a p
2f280 6f 73 69 74 69 76 65 20 73 71 6c 69 74 65 33 5f ositive sqlite3_
2f290 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 20 62 column_count() b
2f2a0 75 74 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 ut depending on
2f2b0 74 68 65 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 the.** WHERE cla
2f2c0 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 use constraints
2f2d0 61 6e 64 20 74 68 65 20 74 61 62 6c 65 20 63 6f and the table co
2f2e0 6e 74 65 6e 74 2c 20 69 74 20 6d 69 67 68 74 20 ntent, it might
2f2f0 72 65 74 75 72 6e 20 6e 6f 20 72 6f 77 73 2e 0a return no rows..
2f300 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
2f310 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f [sqlite3_data_co
2f320 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 unt()].*/.int sq
2f330 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 lite3_column_cou
2f340 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 nt(sqlite3_stmt
2f350 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *pStmt);../*.**
2f360 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e CAPI3REF: Column
2f370 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 Names In A Resu
2f380 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 lt Set.** METHOD
2f390 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a : sqlite3_stmt.*
2f3a0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 *.** ^These rout
2f3b0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 ines return the
2f3c0 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f name assigned to
2f3d0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f a particular co
2f3e0 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 lumn.** in the r
2f3f0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b esult set of a [
2f400 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
2f410 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 t. ^The sqlite3
2f420 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a _column_name().*
2f430 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 * interface retu
2f440 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
2f450 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
2f460 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a ed UTF-8 string.
2f470 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 ** and sqlite3_c
2f480 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 olumn_name16() r
2f490 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
2f4a0 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 to a zero-termi
2f4b0 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 nated.** UTF-16
2f4c0 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 string. ^The fi
2f4d0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 rst parameter is
2f4e0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
2f4f0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 tatement].** tha
2f500 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 t implements the
2f510 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d [SELECT] statem
2f520 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 ent. ^The second
2f530 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
2f540 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 e.** column numb
2f550 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f er. ^The leftmo
2f560 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d st column is num
2f570 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ber 0..**.** ^Th
2f580 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e e returned strin
2f590 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c g pointer is val
2f5a0 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 id until either
2f5b0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
2f5c0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 atement].** is d
2f5d0 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c estroyed by [sql
2f5e0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
2f5f0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 or until the st
2f600 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d atement is autom
2f610 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 atically.** repr
2f620 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 epared by the fi
2f630 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c rst call to [sql
2f640 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 ite3_step()] for
2f650 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 a particular ru
2f660 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 n.** or until th
2f670 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a e next call to.*
2f680 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e * sqlite3_column
2f690 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 _name() or sqlit
2f6a0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 e3_column_name16
2f6b0 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 () on the same c
2f6c0 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 olumn..**.** ^If
2f6d0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
2f6e0 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 ) fails during t
2f6f0 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 he processing of
2f700 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a either routine.
2f710 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 ** (for example
2f720 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 during a convers
2f730 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 ion from UTF-8 t
2f740 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 o UTF-16) then a
2f750 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 .** NULL pointer
2f760 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
2f770 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 .** ^The name of
2f780 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e a result column
2f790 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 is the value of
2f7a0 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 the "AS" clause
2f7b0 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c for.** that col
2f7c0 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 umn, if there is
2f7d0 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 an AS clause.
2f7e0 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 If there is no A
2f7f0 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e S clause.** then
2f800 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
2f810 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 column is unspe
2f820 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 cified and may c
2f830 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e hange from.** on
2f840 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c e release of SQL
2f850 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e ite to the next.
2f860 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a .*/.const char *
2f870 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e sqlite3_column_n
2f880 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ame(sqlite3_stmt
2f890 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 *, int N);.const
2f8a0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 void *sqlite3_c
2f8b0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c olumn_name16(sql
2f8c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
2f8d0 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 N);../*.** CAPI3
2f8e0 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 REF: Source Of D
2f8f0 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 ata In A Query R
2f900 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a esult.** METHOD:
2f910 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
2f920 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 .** ^These routi
2f930 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 nes provide a me
2f940 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 ans to determine
2f950 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 the database, t
2f960 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 able, and.** tab
2f970 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 le column that i
2f980 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 s the origin of
2f990 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 a particular res
2f9a0 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a ult column in.**
2f9b0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d [SELECT] statem
2f9c0 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d ent..** ^The nam
2f9d0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 e of the databas
2f9e0 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f e or table or co
2f9f0 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 lumn can be retu
2fa00 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 rned as.** eithe
2fa10 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 r a UTF-8 or UTF
2fa20 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 -16 string. ^Th
2fa30 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 e _database_ rou
2fa40 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 tines return.**
2fa50 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d the database nam
2fa60 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 e, the _table_ r
2fa70 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 outines return t
2fa80 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 he table name, a
2fa90 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e nd.** the origin
2faa0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 _ routines retur
2fab0 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d n the column nam
2fac0 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 e..** ^The retur
2fad0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 ned string is va
2fae0 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 lid until the [p
2faf0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2fb00 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a t] is destroyed.
2fb10 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ** using [sqlite
2fb20 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 3_finalize()] or
2fb30 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 until the state
2fb40 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 ment is automati
2fb50 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 cally.** reprepa
2fb60 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 red by the first
2fb70 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
2fb80 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 3_step()] for a
2fb90 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a particular run.*
2fba0 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 * or until the s
2fbb0 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 ame information
2fbc0 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 is requested.**
2fbd0 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 again in a diffe
2fbe0 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a rent encoding..*
2fbf0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 *.** ^The names
2fc00 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 returned are the
2fc10 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 original un-ali
2fc20 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 ased names of th
2fc30 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 e.** database, t
2fc40 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e able, and column
2fc50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 ..**.** ^The fir
2fc60 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 st argument to t
2fc70 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 hese interfaces
2fc80 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 is a [prepared s
2fc90 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 tatement]..** ^T
2fca0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 hese functions r
2fcb0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f eturn informatio
2fcc0 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 n about the Nth
2fcd0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 result column re
2fce0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 turned by.** the
2fcf0 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 statement, wher
2fd00 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e e N is the secon
2fd10 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d d function argum
2fd20 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 ent..** ^The lef
2fd30 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 t-most column is
2fd40 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 column 0 for th
2fd50 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a ese routines..**
2fd60 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 .** ^If the Nth
2fd70 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 column returned
2fd80 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 by the statement
2fd90 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f is an expressio
2fda0 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 n or.** subquery
2fdb0 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f and is not a co
2fdc0 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e lumn value, then
2fdd0 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 all of these fu
2fde0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a nctions return.*
2fdf0 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 * NULL. ^These
2fe00 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c routine might al
2fe10 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 so return NULL i
2fe20 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 f a memory alloc
2fe30 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f ation error.** o
2fe40 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 ccurs. ^Otherwi
2fe50 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 se, they return
2fe60 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
2fe70 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 attached databas
2fe80 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 e, table,.** or
2fe90 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 column that quer
2fea0 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 y result column
2feb0 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 was extracted fr
2fec0 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 om..**.** ^As wi
2fed0 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c th all other SQL
2fee0 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 ite APIs, those
2fef0 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 whose names end
2ff00 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e with "16" return
2ff10 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 .** UTF-16 encod
2ff20 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 ed strings and t
2ff30 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f he other functio
2ff40 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e ns return UTF-8.
2ff50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 .**.** ^These AP
2ff60 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 Is are only avai
2ff70 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 lable if the lib
2ff80 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 rary was compile
2ff90 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 d with the.** [S
2ffa0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c QLITE_ENABLE_COL
2ffb0 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d UMN_METADATA] C-
2ffc0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d preprocessor sym
2ffd0 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 bol..**.** If tw
2ffe0 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 o or more thread
2fff0 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f s call one or mo
30000 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 re of these rout
30010 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 ines against the
30020 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 same.** prepare
30030 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 d statement and
30040 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 column at the sa
30050 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 me time then the
30060 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 results are.**
30070 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
30080 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 If two or more
30090 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 threads call one
300a0 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c or more.** [sql
300b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 ite3_column_data
300c0 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 base_name | colu
300d0 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 mn metadata inte
300e0 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 rfaces].** for t
300f0 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 he same [prepare
30100 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 d statement] and
30110 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a result column.*
30120 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 * at the same ti
30130 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 me then the resu
30140 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 lts are undefine
30150 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 d..*/.const char
30160 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
30170 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 _database_name(s
30180 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
30190 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
301a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 qlite3_column_da
301b0 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 tabase_name16(sq
301c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
301d0 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 ;.const char *sq
301e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 lite3_column_tab
301f0 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f le_name(sqlite3_
30200 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 stmt*,int);.cons
30210 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
30220 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d column_table_nam
30230 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 e16(sqlite3_stmt
30240 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 *,int);.const ch
30250 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ar *sqlite3_colu
30260 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 mn_origin_name(s
30270 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
30280 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
30290 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 qlite3_column_or
302a0 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 igin_name16(sqli
302b0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
302c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
302d0 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 Declared Dataty
302e0 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 pe Of A Query Re
302f0 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 sult.** METHOD:
30300 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a sqlite3_stmt.**.
30310 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 ** ^(The first p
30320 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 arameter is a [p
30330 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
30340 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 t]..** If this s
30350 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 tatement is a [S
30360 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 ELECT] statement
30370 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c and the Nth col
30380 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 umn of the.** re
30390 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 turned result se
303a0 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 t of that [SELEC
303b0 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f T] is a table co
303c0 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 lumn (not an.**
303d0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 expression or su
303e0 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 bquery) then the
303f0 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f declared type o
30400 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 f the table.** c
30410 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 olumn is returne
30420 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 d.)^ ^If the Nt
30430 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 h column of the
30440 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e result set is an
30450 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f .** expression o
30460 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e r subquery, then
30470 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
30480 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 is returned..**
30490 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 ^The returned st
304a0 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 ring is always U
304b0 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a TF-8 encoded..**
304c0 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c .** ^(For exampl
304d0 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 e, given the dat
304e0 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a abase schema:.**
304f0 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 .** CREATE TABLE
30500 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b t1(c1 VARIANT);
30510 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 .**.** and the f
30520 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 ollowing stateme
30530 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 nt to be compile
30540 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 d:.**.** SELECT
30550 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 c1 + 1, c1 FROM
30560 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 t1;.**.** this r
30570 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 outine would ret
30580 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 urn the string "
30590 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 VARIANT" for the
305a0 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a second result.*
305b0 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c * column (i==1),
305c0 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e and a NULL poin
305d0 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 ter for the firs
305e0 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 t result column
305f0 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 (i==0).)^.**.**
30600 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e ^SQLite uses dyn
30610 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 amic run-time ty
30620 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 ping. ^So just
30630 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e because a column
30640 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 .** is declared
30650 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 to contain a par
30660 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 ticular type doe
30670 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 s not mean that
30680 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 the.** data stor
30690 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d ed in that colum
306a0 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c n is of the decl
306b0 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 ared type. SQLi
306c0 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c te is.** strongl
306d0 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 y typed, but the
306e0 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d typing is dynam
306f0 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 ic not static.
30700 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f ^Type.** is asso
30710 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 ciated with indi
30720 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e vidual values, n
30730 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 ot with the cont
30740 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 ainers.** used t
30750 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c o hold those val
30760 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 ues..*/.const ch
30770 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ar *sqlite3_colu
30780 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 mn_decltype(sqli
30790 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
307a0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
307b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 te3_column_declt
307c0 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ype16(sqlite3_st
307d0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a mt*,int);../*.**
307e0 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 CAPI3REF: Evalu
307f0 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 ate An SQL State
30800 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 ment.** METHOD:
30810 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a sqlite3_stmt.**.
30820 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 ** After a [prep
30830 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
30840 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 has been prepare
30850 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a d using either.*
30860 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
30870 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c re_v2()] or [sql
30880 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
30890 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 2()] or one of t
308a0 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 he legacy.** int
308b0 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 erfaces [sqlite3
308c0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b _prepare()] or [
308d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
308e0 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 6()], this funct
308f0 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 ion.** must be c
30900 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 alled one or mor
30910 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 e times to evalu
30920 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e ate the statemen
30930 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 t..**.** The det
30940 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 ails of the beha
30950 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 vior of the sqli
30960 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 te3_step() inter
30970 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f face depend.** o
30980 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 n whether the st
30990 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 atement was prep
309a0 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e ared using the n
309b0 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 ewer "v2" interf
309c0 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ace.** [sqlite3_
309d0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e prepare_v2()] an
309e0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 d [sqlite3_prepa
309f0 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 re16_v2()] or th
30a00 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a e older legacy.*
30a10 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c * interface [sql
30a20 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
30a30 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 and [sqlite3_pre
30a40 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 pare16()]. The
30a50 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 use of the.** ne
30a60 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 w "v2" interface
30a70 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
30a80 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 for new applicat
30a90 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 ions but the leg
30aa0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 acy.** interface
30ab0 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 will continue t
30ac0 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a o be supported..
30ad0 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 **.** ^In the le
30ae0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 gacy interface,
30af0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
30b00 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 will be either
30b10 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a [SQLITE_BUSY],.*
30b20 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c * [SQLITE_DONE],
30b30 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b [SQLITE_ROW], [
30b40 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f SQLITE_ERROR], o
30b50 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 r [SQLITE_MISUSE
30b60 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 ]..** ^With the
30b70 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 "v2" interface,
30b80 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 any of the other
30b90 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 [result codes]
30ba0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 or.** [extended
30bb0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 result codes] mi
30bc0 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 ght be returned
30bd0 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e as well..**.** ^
30be0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 [SQLITE_BUSY] me
30bf0 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 ans that the dat
30c00 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 abase engine was
30c10 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 unable to acqui
30c20 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 re the.** databa
30c30 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 se locks it need
30c40 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e s to do its job.
30c50 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d ^If the statem
30c60 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 ent is a [COMMIT
30c70 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f ].** or occurs o
30c80 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 utside of an exp
30c90 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f licit transactio
30ca0 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 n, then you can
30cb0 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 retry the.** sta
30cc0 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 tement. If the
30cd0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 statement is not
30ce0 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 a [COMMIT] and
30cf0 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e occurs within an
30d00 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 .** explicit tra
30d10 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f nsaction then yo
30d20 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 u should rollbac
30d30 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f k the transactio
30d40 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 n before.** cont
30d50 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b inuing..**.** ^[
30d60 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 SQLITE_DONE] mea
30d70 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 ns that the stat
30d80 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 ement has finish
30d90 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 ed executing.**
30da0 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 successfully. s
30db0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 qlite3_step() sh
30dc0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c ould not be call
30dd0 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 ed again on this
30de0 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 virtual.** mach
30df0 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 ine without firs
30e00 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 t calling [sqlit
30e10 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 e3_reset()] to r
30e20 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c eset the virtual
30e30 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b .** machine back
30e40 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 to its initial
30e50 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 state..**.** ^If
30e60 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
30e70 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 nt being execute
30e80 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 d returns any da
30e90 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 ta, then [SQLITE
30ea0 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 _ROW].** is retu
30eb0 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 rned each time a
30ec0 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 new row of data
30ed0 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 is ready for pr
30ee0 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a ocessing by the.
30ef0 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 ** caller. The v
30f00 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 alues may be acc
30f10 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 essed using the
30f20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 [column access f
30f30 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 unctions]..** sq
30f40 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 lite3_step() is
30f50 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 called again to
30f60 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 retrieve the nex
30f70 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a t row of data..*
30f80 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 *.** ^[SQLITE_ER
30f90 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 ROR] means that
30fa0 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 a run-time error
30fb0 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 (such as a cons
30fc0 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 traint.** violat
30fd0 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 ion) has occurre
30fe0 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 d. sqlite3_step
30ff0 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 () should not be
31000 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e called again on
31010 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 .** the VM. More
31020 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 information may
31030 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c be found by cal
31040 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 ling [sqlite3_er
31050 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 rmsg()]..** ^Wit
31060 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 h the legacy int
31070 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 erface, a more s
31080 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f pecific error co
31090 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c de (for example,
310a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 .** [SQLITE_INTE
310b0 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f RRUPT], [SQLITE_
310c0 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 SCHEMA], [SQLITE
310d0 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 _CORRUPT], and s
310e0 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 o forth).** can
310f0 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 be obtained by c
31100 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
31110 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a reset()] on the.
31120 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
31130 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 tement]. ^In th
31140 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 e "v2" interface
31150 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 ,.** the more sp
31160 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 ecific error cod
31170 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 e is returned di
31180 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 rectly by sqlite
31190 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 3_step()..**.**
311a0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 [SQLITE_MISUSE]
311b0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 means that the t
311c0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 his routine was
311d0 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 called inappropr
311e0 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 iately..** Perha
311f0 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 ps it was called
31200 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 on a [prepared
31210 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 statement] that
31220 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 has.** already b
31230 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e een [sqlite3_fin
31240 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 alize | finalize
31250 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 d] or on one tha
31260 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 t had.** previou
31270 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 sly returned [SQ
31280 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b LITE_ERROR] or [
31290 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f SQLITE_DONE]. O
312a0 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 r it could.** be
312b0 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 the case that t
312c0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 he same database
312d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 connection is b
312e0 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f eing used by two
312f0 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 or.** more thre
31300 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 ads at the same
31310 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a moment in time..
31320 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 **.** For all ve
31330 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
31340 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 up to and inclu
31350 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 ding 3.6.23.1, a
31360 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c call to.** [sql
31370 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 ite3_reset()] wa
31380 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72 s required after
31390 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
313a0 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e returned anythin
313b0 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 g.** other than
313c0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 [SQLITE_ROW] bef
313d0 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 ore any subseque
313e0 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 nt invocation of
313f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 .** sqlite3_step
31400 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 (). Failure to
31410 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 reset the prepar
31420 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 ed statement usi
31430 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ng .** [sqlite3_
31440 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 reset()] would r
31450 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c esult in an [SQL
31460 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 ITE_MISUSE] retu
31470 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 rn from.** sqlit
31480 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 e3_step(). But
31490 61 66 74 65 72 20 5b 76 65 72 73 69 6f 6e 20 33 after [version 3
314a0 2e 36 2e 32 33 2e 31 5d 20 28 5b 64 61 74 65 6f .6.23.1] ([dateo
314b0 66 3a 33 2e 36 2e 32 33 2e 31 5d 2c 0a 2a 2a 20 f:3.6.23.1],.**
314c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 sqlite3_step() b
314d0 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 egan.** calling
314e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
314f0 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 ] automatically
31500 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 in this circumst
31510 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 ance rather.** t
31520 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 han returning [S
31530 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 QLITE_MISUSE].
31540 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 This is not cons
31550 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 idered a compati
31560 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 bility.** break
31570 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c because any appl
31580 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 ication that eve
31590 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 r receives an SQ
315a0 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f LITE_MISUSE erro
315b0 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 r.** is broken b
315c0 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 y definition. T
315d0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f he [SQLITE_OMIT_
315e0 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 AUTORESET] compi
315f0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a le-time option.*
31600 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f * can be used to
31610 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 restore the leg
31620 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a acy behavior..**
31630 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 .** <b>Goofy Int
31640 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 erface Alert:</b
31650 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 > In the legacy
31660 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 interface, the s
31670 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a qlite3_step().**
31680 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 API always retu
31690 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 rns a generic er
316a0 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 ror code, [SQLIT
316b0 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 E_ERROR], follow
316c0 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 ing any.** error
316d0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c other than [SQL
316e0 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 ITE_BUSY] and [S
316f0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 QLITE_MISUSE].
31700 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a You must call.**
31710 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
31720 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 )] or [sqlite3_f
31730 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 inalize()] in or
31740 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 der to find one
31750 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 of the.** specif
31760 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d ic [error codes]
31770 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 that better des
31780 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 cribes the error
31790 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 ..** We admit th
317a0 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f at this is a goo
317b0 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 fy design. The
317c0 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e problem has been
317d0 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 fixed.** with t
317e0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 he "v2" interfac
317f0 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 e. If you prepa
31800 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 re all of your S
31810 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a QL statements.**
31820 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 using either [s
31830 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
31840 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 2()] or [sqlite3
31850 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
31860 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 instead.** of t
31870 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 he legacy [sqlit
31880 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e e3_prepare()] an
31890 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 d [sqlite3_prepa
318a0 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 re16()] interfac
318b0 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 es,.** then the
318c0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 more specific [e
318d0 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 rror codes] are
318e0 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c returned directl
318f0 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f y.** by sqlite3_
31900 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 step(). The use
31910 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 of the "v2" int
31920 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d erface is recomm
31930 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ended..*/.int sq
31940 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 lite3_step(sqlit
31950 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a e3_stmt*);../*.*
31960 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 * CAPI3REF: Numb
31970 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
31980 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a a result set.**
31990 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
319a0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 _stmt.**.** ^The
319b0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f sqlite3_data_co
319c0 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 unt(P) interface
319d0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
319e0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 ber of columns i
319f0 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 n the.** current
31a00 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 row of the resu
31a10 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 lt set of [prepa
31a20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 red statement] P
31a30 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 ..** ^If prepare
31a40 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f d statement P do
31a50 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 es not have resu
31a60 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 lts ready to ret
31a70 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c urn.** (via call
31a80 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 s to the [sqlite
31a90 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 3_column_int | s
31aa0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 qlite3_column_*(
31ab0 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 )] of.** interfa
31ac0 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 ces) then sqlite
31ad0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 3_data_count(P)
31ae0 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 returns 0..** ^T
31af0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f he sqlite3_data_
31b00 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 count(P) routine
31b10 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 also returns 0
31b20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 if P is a NULL p
31b30 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 ointer..** ^The
31b40 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 sqlite3_data_cou
31b50 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 nt(P) routine re
31b60 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 turns 0 if the p
31b70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a revious call to.
31b80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ** [sqlite3_step
31b90 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 ](P) returned [S
31ba0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 QLITE_DONE]. ^T
31bb0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f he sqlite3_data_
31bc0 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c count(P).** will
31bd0 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f return non-zero
31be0 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c if previous cal
31bf0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 l to [sqlite3_st
31c00 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a ep](P) returned.
31c10 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c ** [SQLITE_ROW],
31c20 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 except in the c
31c30 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 ase of the [PRAG
31c40 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 MA incremental_v
31c50 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 acuum].** where
31c60 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e it always return
31c70 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 s zero since eac
31c80 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d h step of that m
31c90 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 ulti-step.** pra
31ca0 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f gma returns 0 co
31cb0 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a lumns of data..*
31cc0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
31cd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 sqlite3_column_c
31ce0 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 ount()].*/.int s
31cf0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
31d00 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a t(sqlite3_stmt *
31d10 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 pStmt);../*.** C
31d20 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 API3REF: Fundame
31d30 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a ntal Datatypes.*
31d40 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 * KEYWORDS: SQLI
31d50 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 TE_TEXT.**.** ^(
31d60 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 Every value in S
31d70 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 QLite has one of
31d80 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 five fundamenta
31d90 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a l datatypes:.**.
31da0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
31db0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 64-bit signed in
31dc0 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 teger.** <li> 64
31dd0 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 -bit IEEE floati
31de0 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a ng point number.
31df0 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a ** <li> string.*
31e00 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c * <li> BLOB.** <
31e10 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c li> NULL.** </ul
31e20 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 >)^.**.** These
31e30 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f constants are co
31e40 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 des for each of
31e50 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a those types..**.
31e60 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 ** Note that the
31e70 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e SQLITE_TEXT con
31e80 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 stant was also u
31e90 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 sed in SQLite ve
31ea0 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 rsion 2.** for a
31eb0 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 completely diff
31ec0 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 erent meaning.
31ed0 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 Software that li
31ee0 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 nks against both
31ef0 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 .** SQLite versi
31f00 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 on 2 and SQLite
31f10 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 version 3 should
31f20 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 use SQLITE3_TEX
31f30 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 T, not.** SQLITE
31f40 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e _TEXT..*/.#defin
31f50 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 e SQLITE_INTEGER
31f60 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 1.#define SQLI
31f70 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 TE_FLOAT 2.#d
31f80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f efine SQLITE_BLO
31f90 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 B 4.#define
31fa0 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 SQLITE_NULL
31fb0 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 5.#ifdef SQLITE_
31fc0 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c TEXT.# undef SQL
31fd0 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 ITE_TEXT.#else.#
31fe0 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 define SQLITE_T
31ff0 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 EXT 3.#endif
32000 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 .#define SQLITE3
32010 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a _TEXT 3../*.
32020 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 ** CAPI3REF: Res
32030 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 ult Values From
32040 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f A Query.** KEYWO
32050 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 RDS: {column acc
32060 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a ess functions}.*
32070 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
32080 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 3_stmt.**.** ^Th
32090 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 ese routines ret
320a0 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 urn information
320b0 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 about a single c
320c0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 olumn of the cur
320d0 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 rent.** result r
320e0 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 ow of a query.
320f0 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 ^In every case t
32100 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
32110 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a t is a pointer.*
32120 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 * to the [prepar
32130 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
32140 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c at is being eval
32150 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 uated (the [sqli
32160 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 te3_stmt*].** th
32170 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 at was returned
32180 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 from [sqlite3_pr
32190 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f epare_v2()] or o
321a0 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e ne of its varian
321b0 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 ts).** and the s
321c0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 econd argument i
321d0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 s the index of t
321e0 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 he column for wh
321f0 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a ich information.
32200 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 ** should be ret
32210 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 urned. ^The left
32220 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 most column of t
32230 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 he result set ha
32240 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a s the index 0..*
32250 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 * ^The number of
32260 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 columns in the
32270 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 result can be de
32280 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a termined using.*
32290 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
322a0 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a n_count()]..**.*
322b0 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 * If the SQL sta
322c0 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 tement does not
322d0 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 currently point
322e0 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 to a valid row,
322f0 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c or if the.** col
32300 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 umn index is out
32310 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 of range, the r
32320 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e esult is undefin
32330 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 ed..** These rou
32340 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 tines may only b
32350 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 e called when th
32360 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 e most recent ca
32370 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ll to.** [sqlite
32380 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 3_step()] has re
32390 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 turned [SQLITE_R
323a0 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a OW] and neither.
323b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ** [sqlite3_rese
323c0 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 t()] nor [sqlite
323d0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 3_finalize()] ha
323e0 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 ve been called s
323f0 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 ubsequently..**
32400 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 If any of these
32410 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c routines are cal
32420 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 led after [sqlit
32430 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a e3_reset()] or.*
32440 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c * [sqlite3_final
32450 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 ize()] or after
32460 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
32470 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a has returned.**
32480 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 something other
32490 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f than [SQLITE_RO
324a0 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 W], the results
324b0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a are undefined..*
324c0 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 * If [sqlite3_st
324d0 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 ep()] or [sqlite
324e0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 3_reset()] or [s
324f0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
32500 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 )].** are called
32510 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e from a differen
32520 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 t thread while a
32530 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ny of these rout
32540 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 ines.** are pend
32550 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 ing, then the re
32560 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 sults are undefi
32570 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ned..**.** ^The
32580 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
32590 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 ype() routine re
325a0 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 turns the.** [SQ
325b0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 LITE_INTEGER | d
325c0 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f atatype code] fo
325d0 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 r the initial da
325e0 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 ta type.** of th
325f0 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e e result column.
32600 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 ^The returned
32610 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 value is one of
32620 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d [SQLITE_INTEGER]
32630 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f ,.** [SQLITE_FLO
32640 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 AT], [SQLITE_TEX
32650 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 T], [SQLITE_BLOB
32660 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 ], or [SQLITE_NU
32670 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a LL]. The value.
32680 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ** returned by s
32690 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 qlite3_column_ty
326a0 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 pe() is only mea
326b0 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 ningful if no ty
326c0 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e pe.** conversion
326d0 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 s have occurred
326e0 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c as described bel
326f0 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 ow. After a typ
32700 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a e conversion,.**
32710 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
32720 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 ned by sqlite3_c
32730 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 olumn_type() is
32740 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 undefined. Futu
32750 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f re.** versions o
32760 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 f SQLite may cha
32770 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 nge the behavior
32780 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 of sqlite3_colu
32790 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c mn_type().** fol
327a0 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f lowing a type co
327b0 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 nversion..**.**
327c0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
327d0 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d s a BLOB or UTF-
327e0 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 8 string then th
327f0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
32800 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 _bytes().** rout
32810 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ine returns the
32820 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
32830 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 in that BLOB or
32840 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 string..** ^If t
32850 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 he result is a U
32860 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 TF-16 string, th
32870 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
32880 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 n_bytes() conver
32890 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 ts.** the string
328a0 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 to UTF-8 and th
328b0 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e en returns the n
328c0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a umber of bytes..
328d0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c ** ^If the resul
328e0 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 t is a numeric v
328f0 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 alue then sqlite
32900 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
32910 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 uses.** [sqlite
32920 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 3_snprintf()] to
32930 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 convert that va
32940 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 lue to a UTF-8 s
32950 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e tring and return
32960 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 s.** the number
32970 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 of bytes in that
32980 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 string..** ^If
32990 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 the result is NU
329a0 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 LL, then sqlite3
329b0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 _column_bytes()
329c0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a returns zero..**
329d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
329e0 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 lt is a BLOB or
329f0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 UTF-16 string th
32a00 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 en the sqlite3_c
32a10 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a olumn_bytes16().
32a20 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 ** routine retur
32a30 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
32a40 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 bytes in that B
32a50 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a LOB or string..*
32a60 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 * ^If the result
32a70 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 is a UTF-8 stri
32a80 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ng, then sqlite3
32a90 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
32aa0 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 ) converts.** th
32ab0 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d e string to UTF-
32ac0 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 16 and then retu
32ad0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
32ae0 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 f bytes..** ^If
32af0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 the result is a
32b00 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 numeric value th
32b10 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
32b20 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 n_bytes16() uses
32b30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 .** [sqlite3_snp
32b40 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 rintf()] to conv
32b50 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 ert that value t
32b60 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e o a UTF-16 strin
32b70 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a g and returns.**
32b80 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
32b90 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 ytes in that str
32ba0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ing..** ^If the
32bb0 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 result is NULL,
32bc0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
32bd0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 umn_bytes16() re
32be0 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a turns zero..**.*
32bf0 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 * ^The values re
32c00 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
32c10 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
32c20 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 )] and .** [sqli
32c30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
32c40 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 16()] do not inc
32c50 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 lude the zero te
32c60 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 rminators at the
32c70 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 end.** of the s
32c80 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 tring. ^For cla
32c90 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 rity: the values
32ca0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 returned by.**
32cb0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
32cc0 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 bytes()] and [sq
32cd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
32ce0 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 es16()] are the
32cf0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 number of.** byt
32d00 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 es in the string
32d10 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 , not the number
32d20 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a of characters..
32d30 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 **.** ^Strings r
32d40 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
32d50 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
32d60 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
32d70 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a umn_text16(),.**
32d80 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 even empty stri
32d90 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 ngs, are always
32da0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e zero-terminated.
32db0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a ^The return.**
32dc0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 value from sqli
32dd0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
32de0 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e ) for a zero-len
32df0 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 gth BLOB is a NU
32e00 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
32e10 2a 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 * <b>Warning:</b
32e20 3e 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 > ^The object re
32e30 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
32e40 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 e3_column_value(
32e50 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 )] is an.** [unp
32e60 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
32e70 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 _value] object.
32e80 20 49 6e 20 61 20 6d 75 6c 74 69 74 68 72 65 61 In a multithrea
32e90 64 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c ded environment,
32ea0 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 .** an unprotect
32eb0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
32ec0 20 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 object may only
32ed0 20 62 65 20 75 73 65 64 20 73 61 66 65 6c 79 20 be used safely
32ee0 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 with.** [sqlite3
32ef0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 _bind_value()] a
32f00 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 nd [sqlite3_resu
32f10 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 lt_value()]..**
32f20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 If the [unprotec
32f30 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
32f40 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e e] object return
32f50 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 ed by.** [sqlite
32f60 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 3_column_value()
32f70 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 ] is used in any
32f80 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c other way, incl
32f90 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 uding calls.** t
32fa0 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 o routines like
32fb0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 [sqlite3_value_i
32fc0 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f nt()], [sqlite3_
32fd0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a value_text()],.*
32fe0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 * or [sqlite3_va
32ff0 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 lue_bytes()], th
33000 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 6e 6f e behavior is no
33010 74 20 74 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a t threadsafe..**
33020 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
33030 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f es attempt to co
33040 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 nvert the value
33050 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 where appropriat
33060 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d e. ^For.** exam
33070 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 ple, if the inte
33080 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 rnal representat
33090 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 ion is FLOAT and
330a0 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a a text result.*
330b0 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 * is requested,
330c0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 [sqlite3_snprint
330d0 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 f()] is used int
330e0 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f ernally to perfo
330f0 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 rm the.** conver
33100 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c sion automatical
33110 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f ly. ^(The follo
33120 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 wing table detai
33130 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f ls the conversio
33140 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 ns.** that are a
33150 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 pplied:.**.** <b
33160 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 lockquote>.** <t
33170 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e able border="1">
33180 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 .** <tr><th> Int
33190 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 ernal<br>Type <t
331a0 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e h> Requested<br>
331b0 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 Type <th> Conve
331c0 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e rsion.**.** <tr>
331d0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 <td> NULL <t
331e0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 d> INTEGER <td
331f0 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a > Result is 0.**
33200 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 <tr><td> NULL
33210 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 <td> FLOAT
33220 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 <td> Result is
33230 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 0.0.** <tr><td>
33240 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 NULL <td>
33250 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 TEXT <td> Re
33260 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 sult is a NULL p
33270 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 ointer.** <tr><t
33280 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e d> NULL <td>
33290 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 BLOB <td>
332a0 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c Result is a NULL
332b0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e pointer.** <tr>
332c0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 <td> INTEGER <t
332d0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 d> FLOAT <td
332e0 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 > Convert from i
332f0 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a nteger to float.
33300 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 ** <tr><td> INTE
33310 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 GER <td> TEXT
33320 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 <td> ASCII r
33330 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 endering of the
33340 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c integer.** <tr><
33350 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 td> INTEGER <td
33360 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e > BLOB <td>
33370 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 Same as INTEGER
33380 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 ->TEXT.** <tr><t
33390 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e d> FLOAT <td>
333a0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 INTEGER <td>
333b0 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 [CAST] to INTEGE
333c0 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 R.** <tr><td> F
333d0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 LOAT <td> TE
333e0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 XT <td> ASCII
333f0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 rendering of th
33400 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c e float.** <tr><
33410 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 td> FLOAT <td
33420 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e > BLOB <td>
33430 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a [CAST] to BLOB.
33440 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 ** <tr><td> TEX
33450 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 T <td> INTEGE
33460 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 R <td> [CAST]
33470 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 to INTEGER.** <t
33480 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 r><td> TEXT
33490 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c <td> FLOAT <
334a0 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 td> [CAST] to RE
334b0 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 AL.** <tr><td>
334c0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 TEXT <td> B
334d0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 LOB <td> No c
334e0 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 hange.** <tr><td
334f0 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 > BLOB <td>
33500 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b INTEGER <td> [
33510 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 CAST] to INTEGER
33520 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c .** <tr><td> BL
33530 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 OB <td> FLOA
33540 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d T <td> [CAST]
33550 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e to REAL.** <tr>
33560 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 <td> BLOB <t
33570 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 d> TEXT <td
33580 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 > Add a zero ter
33590 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 minator if neede
335a0 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a d.** </table>.**
335b0 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e </blockquote>)^
335c0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 .**.** Note that
335d0 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 when type conve
335e0 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f rsions occur, po
335f0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 inters returned
33600 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c by prior.** call
33610 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c s to sqlite3_col
33620 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 umn_blob(), sqli
33630 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
33640 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c ), and/or.** sql
33650 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
33660 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 16() may be inva
33670 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 lidated..** Type
33680 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 conversions and
33690 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 pointer invalid
336a0 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 ations might occ
336b0 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c ur.** in the fol
336c0 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a lowing cases:.**
336d0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
336e0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e The initial con
336f0 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 tent is a BLOB a
33700 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
33710 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 n_text() or.**
33720 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 sqlite3_colu
33730 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 mn_text16() is c
33740 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 alled. A zero-t
33750 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a erminator might.
33760 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 ** need to
33770 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 be added to the
33780 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 string.</li>.**
33790 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c <li> The initial
337a0 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d content is UTF-
337b0 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 8 text and sqlit
337c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
337d0 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 6() or.** s
337e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
337f0 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 xt16() is called
33800 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d . The content m
33810 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 ust be converted
33820 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d .** to UTF-
33830 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 16.</li>.** <li>
33840 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e The initial con
33850 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 tent is UTF-16 t
33860 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f ext and sqlite3_
33870 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f column_bytes() o
33880 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 r.** sqlite
33890 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 3_column_text()
338a0 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 is called. The
338b0 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 content must be
338c0 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 converted.**
338d0 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e to UTF-8.</li>
338e0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
338f0 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 ^Conversions bet
33900 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e ween UTF-16be an
33910 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 d UTF-16le are a
33920 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c lways done in pl
33930 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f ace and do.** no
33940 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 t invalidate a p
33950 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 rior pointer, th
33960 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 ough of course t
33970 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 he content of th
33980 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 e buffer.** that
33990 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 the prior point
339a0 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 er references wi
339b0 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 ll have been mod
339c0 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 ified. Other ki
339d0 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 nds.** of conver
339e0 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e sion are done in
339f0 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 place when it i
33a00 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 s possible, but
33a10 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a sometimes they.*
33a20 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 * are not possib
33a30 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 le and in those
33a40 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e cases prior poin
33a50 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 ters are invalid
33a60 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ated..**.** The
33a70 73 61 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73 safest policy is
33a80 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 to invoke these
33a90 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 routines.** in
33aa0 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f one of the follo
33ab0 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a wing ways:.**.**
33ac0 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 <ul>.** <li>sq
33ad0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
33ae0 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 t() followed by
33af0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
33b00 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 ytes()</li>.**
33b10 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 <li>sqlite3_colu
33b20 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 mn_blob() follow
33b30 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f ed by sqlite3_co
33b40 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 lumn_bytes()</li
33b50 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 >.** <li>sqlite
33b60 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
33b70 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 ) followed by sq
33b80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
33b90 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c es16()</li>.** <
33ba0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 /ul>.**.** In ot
33bb0 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 her words, you s
33bc0 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 hould call sqlit
33bd0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
33be0 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c ,.** sqlite3_col
33bf0 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 umn_blob(), or s
33c00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
33c10 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 xt16() first to
33c20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 force the result
33c30 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 .** into the des
33c40 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 ired format, the
33c50 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 n invoke sqlite3
33c60 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 _column_bytes()
33c70 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f or.** sqlite3_co
33c80 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 lumn_bytes16() t
33c90 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 o find the size
33ca0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 of the result.
33cb0 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 Do not mix calls
33cc0 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 .** to sqlite3_c
33cd0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 olumn_text() or
33ce0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
33cf0 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 lob() with calls
33d00 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 to.** sqlite3_c
33d10 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c olumn_bytes16(),
33d20 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 and do not mix
33d30 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
33d40 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
33d50 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 .** with calls t
33d60 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e o sqlite3_column
33d70 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 _bytes()..**.**
33d80 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 ^The pointers re
33d90 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 turned are valid
33da0 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f until a type co
33db0 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 nversion occurs
33dc0 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 as.** described
33dd0 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 above, or until
33de0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
33df0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 or [sqlite3_res
33e00 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c et()] or.** [sql
33e10 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
33e20 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 is called. ^Th
33e30 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 e memory space u
33e40 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 sed to hold stri
33e50 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 ngs.** and BLOBs
33e60 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 is freed automa
33e70 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d tically. Do <em
33e80 3e 6e 6f 74 3c 2f 65 6d 3e 20 70 61 73 73 20 74 >not</em> pass t
33e90 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 he pointers retu
33ea0 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 rned.** from [sq
33eb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
33ec0 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 b()], [sqlite3_c
33ed0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 olumn_text()], e
33ee0 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c tc. into.** [sql
33ef0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a ite3_free()]..**
33f00 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 .** ^(If a memor
33f10 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 y allocation err
33f20 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 or occurs during
33f30 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 the evaluation
33f40 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 of any.** of the
33f50 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 se routines, a d
33f60 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 efault value is
33f70 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 returned. The d
33f80 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 efault value.**
33f90 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e is either the in
33fa0 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f teger 0, the flo
33fb0 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 ating point numb
33fc0 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c er 0.0, or a NUL
33fd0 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 L.** pointer. S
33fe0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 ubsequent calls
33ff0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 to [sqlite3_errc
34000 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 ode()] will retu
34010 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f rn.** [SQLITE_NO
34020 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 MEM].)^.*/.const
34030 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 void *sqlite3_c
34040 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 olumn_blob(sqlit
34050 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
34060 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ol);.int sqlite3
34070 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 _column_bytes(sq
34080 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
34090 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 iCol);.int sqli
340a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
340b0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
340c0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 , int iCol);.dou
340d0 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ble sqlite3_colu
340e0 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 mn_double(sqlite
340f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
34100 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f l);.int sqlite3_
34110 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 column_int(sqlit
34120 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
34130 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 ol);.sqlite3_int
34140 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 64 sqlite3_colum
34150 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f n_int64(sqlite3_
34160 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
34170 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 ;.const unsigned
34180 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 char *sqlite3_c
34190 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 olumn_text(sqlit
341a0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
341b0 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 ol);.const void
341c0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
341d0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 text16(sqlite3_s
341e0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
341f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c .int sqlite3_col
34200 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 umn_type(sqlite3
34210 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
34220 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 );.sqlite3_value
34230 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
34240 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 _value(sqlite3_s
34250 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
34260 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
34270 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 : Destroy A Prep
34280 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f ared Statement O
34290 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52 55 43 bject.** DESTRUC
342a0 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d TOR: sqlite3_stm
342b0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c t.**.** ^The sql
342c0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 ite3_finalize()
342d0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c function is call
342e0 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b ed to delete a [
342f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
34300 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 nt]..** ^If the
34310 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c most recent eval
34320 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 uation of the st
34330 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 atement encounte
34340 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a red no errors.**
34350 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65 or if the state
34360 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 ment is never be
34370 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 en evaluated, th
34380 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c en sqlite3_final
34390 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a ize() returns.**
343a0 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 SQLITE_OK. ^If
343b0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
343c0 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 evaluation of s
343d0 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 tatement S faile
343e0 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 d, then.** sqlit
343f0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 e3_finalize(S) r
34400 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f eturns the appro
34410 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f priate [error co
34420 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e de] or.** [exten
34430 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e ded error code].
34440 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
34450 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 te3_finalize(S)
34460 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 routine can be c
34470 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 alled at any poi
34480 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 nt during.** the
34490 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b life cycle of [
344a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
344b0 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 nt] S:.** before
344c0 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 statement S is
344d0 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 ever evaluated,
344e0 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 after.** one or
344f0 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 more calls to [s
34500 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c qlite3_reset()],
34510 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 or after any ca
34520 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 ll.** to [sqlite
34530 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 3_step()] regard
34540 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 less of whether
34550 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 or not the state
34560 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 ment has.** comp
34570 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e leted execution.
34580 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 .**.** ^Invoking
34590 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a sqlite3_finaliz
345a0 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f e() on a NULL po
345b0 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c inter is a harml
345c0 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a ess no-op..**.**
345d0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
345e0 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 must finalize e
345f0 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 very [prepared s
34600 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 tatement] in ord
34610 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 er to avoid.** r
34620 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 esource leaks.
34630 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 It is a grievous
34640 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 error for the a
34650 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 pplication to tr
34660 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 y to use.** a pr
34670 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
34680 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 after it has be
34690 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 en finalized. A
346a0 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 ny use of a prep
346b0 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e ared.** statemen
346c0 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 t after it has b
346d0 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 een finalized ca
346e0 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 n result in unde
346f0 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 fined and.** und
34700 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f esirable behavio
34710 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75 r such as segfau
34720 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 lts and heap cor
34730 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 ruption..*/.int
34740 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
34750 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 (sqlite3_stmt *p
34760 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Stmt);../*.** CA
34770 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 PI3REF: Reset A
34780 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 Prepared Stateme
34790 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 nt Object.** MET
347a0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d HOD: sqlite3_stm
347b0 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 t.**.** The sqli
347c0 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 te3_reset() func
347d0 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 tion is called t
347e0 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 o reset a [prepa
347f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a red statement].*
34800 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f * object back to
34810 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 its initial sta
34820 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 te, ready to be
34830 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 re-executed..**
34840 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 ^Any SQL stateme
34850 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 nt variables tha
34860 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 t had values bou
34870 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 nd to them using
34880 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 .** the [sqlite3
34890 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c _bind_blob | sql
348a0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 ite3_bind_*() AP
348b0 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 I] retain their
348c0 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b values..** Use [
348d0 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 sqlite3_clear_bi
348e0 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 ndings()] to res
348f0 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e et the bindings.
34900 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c .**.** ^The [sql
34910 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 ite3_reset(S)] i
34920 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 nterface resets
34930 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
34940 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 atement] S.** ba
34950 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e ck to the beginn
34960 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 ing of its progr
34970 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 am..**.** ^If th
34980 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 e most recent ca
34990 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ll to [sqlite3_s
349a0 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a tep(S)] for the.
349b0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
349c0 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e tement] S return
349d0 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 ed [SQLITE_ROW]
349e0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d or [SQLITE_DONE]
349f0 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 ,.** or if [sqli
34a00 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 te3_step(S)] has
34a10 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 never before be
34a20 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a en called on S,.
34a30 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 ** then [sqlite3
34a40 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 _reset(S)] retur
34a50 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a ns [SQLITE_OK]..
34a60 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f **.** ^If the mo
34a70 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 st recent call t
34a80 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 o [sqlite3_step(
34a90 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b S)] for the.** [
34aa0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
34ab0 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 nt] S indicated
34ac0 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a an error, then.*
34ad0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 * [sqlite3_reset
34ae0 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 (S)] returns an
34af0 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 appropriate [err
34b00 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 or code]..**.**
34b10 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 ^The [sqlite3_re
34b20 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 set(S)] interfac
34b30 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 e does not chang
34b40 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 e the values.**
34b50 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f of any [sqlite3_
34b60 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e bind_blob|bindin
34b70 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 gs] on the [prep
34b80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
34b90 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 S..*/.int sqlite
34ba0 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 3_reset(sqlite3_
34bb0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f stmt *pStmt);../
34bc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
34bd0 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e reate Or Redefin
34be0 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a e SQL Functions.
34bf0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 ** KEYWORDS: {fu
34c00 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 nction creation
34c10 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 routines}.** KEY
34c20 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 WORDS: {applicat
34c30 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
34c40 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 function}.** KEY
34c50 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 WORDS: {applicat
34c60 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
34c70 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 functions}.** ME
34c80 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a THOD: sqlite3.**
34c90 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 .** ^These funct
34ca0 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 ions (collective
34cb0 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e ly known as "fun
34cc0 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 ction creation r
34cd0 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 outines").** are
34ce0 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c used to add SQL
34cf0 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 functions or ag
34d00 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 gregates or to r
34d10 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 edefine the beha
34d20 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 vior.** of exist
34d30 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ing SQL function
34d40 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e s or aggregates.
34d50 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 The only diffe
34d60 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a rences between.*
34d70 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * these routines
34d80 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65 6e are the text en
34d90 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 coding expected
34da0 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e for.** the secon
34db0 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 d parameter (the
34dc0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e name of the fun
34dd0 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 ction being crea
34de0 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 ted).** and the
34df0 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 presence or abse
34e00 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 nce of a destruc
34e10 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 tor callback for
34e20 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 .** the applicat
34e30 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 ion data pointer
34e40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 ..**.** ^The fir
34e50 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 st parameter is
34e60 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
34e70 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 nnection] to whi
34e80 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 ch the SQL.** fu
34e90 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 nction is to be
34ea0 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 added. ^If an a
34eb0 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 pplication uses
34ec0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 more than one da
34ed0 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 tabase.** connec
34ee0 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 tion then applic
34ef0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
34f00 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 L functions must
34f10 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 be added.** to
34f20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f each database co
34f30 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 nnection separat
34f40 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ely..**.** ^The
34f50 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
34f60 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 is the name of
34f70 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
34f80 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f to be created o
34f90 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 r.** redefined.
34fa0 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 ^The length of
34fb0 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 the name is limi
34fc0 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 ted to 255 bytes
34fd0 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 in a UTF-8.** r
34fe0 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 epresentation, e
34ff0 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 xclusive of the
35000 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e zero-terminator.
35010 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 ^Note that the
35020 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 name.** length
35030 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d limit is in UTF-
35040 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 8 bytes, not cha
35050 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d racters nor UTF-
35060 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 16 bytes. .** ^
35070 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 Any attempt to c
35080 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e reate a function
35090 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e with a longer n
350a0 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 ame.** will resu
350b0 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 lt in [SQLITE_MI
350c0 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 SUSE] being retu
350d0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 rned..**.** ^The
350e0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
350f0 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 (nArg).** is th
35100 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 e number of argu
35110 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 ments that the S
35120 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a QL function or.*
35130 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 * aggregate take
35140 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 s. ^If this para
35150 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 meter is -1, the
35160 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 n the SQL functi
35170 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 on or.** aggrega
35180 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 te may take any
35190 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 number of argume
351a0 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e nts between 0 an
351b0 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 d the limit.** s
351c0 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c et by [sqlite3_l
351d0 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 imit]([SQLITE_LI
351e0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 MIT_FUNCTION_ARG
351f0 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 ]). If the thir
35200 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 d.** parameter i
35210 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f s less than -1 o
35220 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 r greater than 1
35230 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 27 then the beha
35240 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 vior is.** undef
35250 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ined..**.** ^The
35260 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
35270 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 r, eTextRep, spe
35280 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b cifies what.** [
35290 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 SQLITE_UTF8 | te
352a0 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 xt encoding] thi
352b0 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 s SQL function p
352c0 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 refers for.** it
352d0 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 54 s parameters. T
352e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 he application s
352f0 68 6f 75 6c 64 20 73 65 74 20 74 68 69 73 20 70 hould set this p
35300 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b arameter to.** [
35310 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 SQLITE_UTF16LE]
35320 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 if the function
35330 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 implementation i
35340 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 nvokes .** [sqli
35350 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
35360 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 le()] on an inpu
35370 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 t, or [SQLITE_UT
35380 46 31 36 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a F16BE] if the.**
35390 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
353a0 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 invokes [sqlite3
353b0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 _value_text16be(
353c0 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 )] on an input,
353d0 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 or.** [SQLITE_UT
353e0 46 31 36 5d 20 69 66 20 5b 73 71 6c 69 74 65 33 F16] if [sqlite3
353f0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d _value_text16()]
35400 20 69 73 20 75 73 65 64 2c 20 6f 72 20 5b 53 51 is used, or [SQ
35410 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 LITE_UTF8].** ot
35420 68 65 72 77 69 73 65 2e 20 20 5e 54 68 65 20 73 herwise. ^The s
35430 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ame SQL function
35440 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 may be register
35450 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 ed multiple time
35460 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65 s using.** diffe
35470 72 65 6e 74 20 70 72 65 66 65 72 72 65 64 20 74 rent preferred t
35480 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77 ext encodings, w
35490 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 69 6d ith different im
354a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f plementations fo
354b0 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64 69 r.** each encodi
354c0 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c ng..** ^When mul
354d0 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 tiple implementa
354e0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d tions of the sam
354f0 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 e function are a
35500 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 vailable, SQLite
35510 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 .** will pick th
35520 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c e one that invol
35530 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d ves the least am
35540 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e ount of data con
35550 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e version..**.** ^
35560 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d The fourth param
35570 65 74 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61 eter may optiona
35580 6c 6c 79 20 62 65 20 4f 52 65 64 20 77 69 74 68 lly be ORed with
35590 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 [SQLITE_DETERMI
355a0 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 NISTIC].** to si
355b0 67 6e 61 6c 20 74 68 61 74 20 74 68 65 20 66 75 gnal that the fu
355c0 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 nction will alwa
355d0 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 ys return the sa
355e0 6d 65 20 72 65 73 75 6c 74 20 67 69 76 65 6e 0a me result given.
355f0 2a 2a 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 ** the same inpu
35600 74 73 20 77 69 74 68 69 6e 20 61 20 73 69 6e 67 ts within a sing
35610 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 le SQL statement
35620 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63 . Most SQL func
35630 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74 tions are.** det
35640 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 erministic. The
35650 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f built-in [rando
35660 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f m()] SQL functio
35670 6e 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 n is an example
35680 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e of a.** function
35690 20 74 68 61 74 20 69 73 20 6e 6f 74 20 64 65 74 that is not det
356a0 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 erministic. The
356b0 20 53 51 4c 69 74 65 20 71 75 65 72 79 20 70 6c SQLite query pl
356c0 61 6e 6e 65 72 20 69 73 20 61 62 6c 65 20 74 6f anner is able to
356d0 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64 64 69 .** perform addi
356e0 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74 tional optimizat
356f0 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e ions on determin
35700 69 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c istic functions,
35710 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68 so use.** of th
35720 65 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d e [SQLITE_DETERM
35730 49 4e 49 53 54 49 43 5d 20 66 6c 61 67 20 69 73 INISTIC] flag is
35740 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65 recommended whe
35750 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a re possible..**.
35760 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 ** ^(The fifth p
35770 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 arameter is an a
35780 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 rbitrary pointer
35790 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 . The implement
357a0 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 ation of the.**
357b0 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 function can gai
357c0 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 n access to this
357d0 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b pointer using [
357e0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 sqlite3_user_dat
357f0 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 a()].)^.**.** ^T
35800 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 he sixth, sevent
35810 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 h and eighth par
35820 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 ameters, xFunc,
35830 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c xStep and xFinal
35840 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 , are.** pointer
35850 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 s to C-language
35860 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 functions that i
35870 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c mplement the SQL
35880 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 function or.**
35890 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 aggregate. ^A sc
358a0 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f alar SQL functio
358b0 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d n requires an im
358c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
358d0 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c the xFunc.** cal
358e0 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c lback only; NULL
358f0 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 pointers must b
35900 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 e passed as the
35910 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c xStep and xFinal
35920 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 .** parameters.
35930 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 ^An aggregate SQ
35940 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 L function requi
35950 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 res an implement
35960 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a ation of xStep.*
35970 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 * and xFinal and
35980 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 NULL pointer mu
35990 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 st be passed for
359a0 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 xFunc. ^To dele
359b0 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a te an existing.*
359c0 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f * SQL function o
359d0 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 r aggregate, pas
359e0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 s NULL pointers
359f0 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 for all three fu
35a00 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 nction.** callba
35a10 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 cks..**.** ^(If
35a20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 the ninth parame
35a30 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 ter to sqlite3_c
35a40 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 reate_function_v
35a50 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 2() is not NULL,
35a60 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 .** then it is d
35a70 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 estructor for th
35a80 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 e application da
35a90 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 ta pointer. .**
35aa0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 The destructor i
35ab0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 s invoked when t
35ac0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 he function is d
35ad0 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 eleted, either b
35ae0 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c y being.** overl
35af0 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 oaded or when th
35b00 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
35b10 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a ction closes.)^.
35b20 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 ** ^The destruct
35b30 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b or is also invok
35b40 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 ed if the call t
35b50 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 o.** sqlite3_cre
35b60 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 ate_function_v2(
35b70 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 ) fails..** ^Whe
35b80 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 n the destructor
35b90 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 callback of the
35ba0 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 tenth parameter
35bb0 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a is invoked, it.
35bc0 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73 ** is passed a s
35bd0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 ingle argument w
35be0 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f hich is a copy o
35bf0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
35c00 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 n data .** point
35c10 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65 er which was the
35c20 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 fifth parameter
35c30 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 to sqlite3_crea
35c40 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 te_function_v2()
35c50 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 ..**.** ^It is p
35c60 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 ermitted to regi
35c70 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d ster multiple im
35c80 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 plementations of
35c90 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e the same.** fun
35ca0 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 ctions with the
35cb0 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 same name but wi
35cc0 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 th either differ
35cd0 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a ing numbers of.*
35ce0 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 * arguments or d
35cf0 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 iffering preferr
35d00 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 ed text encoding
35d10 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c s. ^SQLite will
35d20 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c use.** the impl
35d30 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 ementation that
35d40 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 most closely mat
35d50 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 ches the way in
35d60 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c which the.** SQL
35d70 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 function is use
35d80 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 d. ^A function
35d90 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 implementation w
35da0 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 ith a non-negati
35db0 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d ve.** nArg param
35dc0 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72 eter is a better
35dd0 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 match than a fu
35de0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 nction implement
35df0 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 ation with.** a
35e00 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 negative nArg.
35e10 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 ^A function wher
35e20 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 e the preferred
35e30 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a text encoding.**
35e40 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74 matches the dat
35e50 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 abase encoding i
35e60 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 s a better.** ma
35e70 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 tch than a funct
35e80 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e ion where the en
35e90 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 coding is differ
35ea0 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e ent. .** ^A fun
35eb0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 ction where the
35ec0 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 encoding differe
35ed0 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 nce is between U
35ee0 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 TF16le and UTF16
35ef0 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 be.** is a close
35f00 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 r match than a f
35f10 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 unction where th
35f20 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 e encoding diffe
35f30 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 rence is.** betw
35f40 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 een UTF8 and UTF
35f50 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 16..**.** ^Built
35f60 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 -in functions ma
35f70 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 y be overloaded
35f80 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 by new applicati
35f90 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
35fa0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 ions..**.** ^An
35fb0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
35fc0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 ned function is
35fd0 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c permitted to cal
35fe0 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 l other.** SQLit
35ff0 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 e interfaces. H
36000 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c owever, such cal
36010 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 ls must not.** c
36020 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 lose the databas
36030 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 e connection nor
36040 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 finalize or res
36050 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a et the prepared.
36060 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 ** statement in
36070 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 which the functi
36080 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a on is running..*
36090 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 /.int sqlite3_cr
360a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 eate_function(.
360b0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 sqlite3 *db,.
360c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e const char *zFun
360d0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 ctionName,. int
360e0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 nArg,. int eTe
360f0 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 xtRep,. void *p
36100 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 App,. void (*xF
36110 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e unc)(sqlite3_con
36120 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 text*,int,sqlite
36130 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 3_value**),. vo
36140 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 id (*xStep)(sqli
36150 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
36160 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
36170 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e ),. void (*xFin
36180 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 al)(sqlite3_cont
36190 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c ext*).);.int sql
361a0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
361b0 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 tion16(. sqlite
361c0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 3 *db,. const v
361d0 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 oid *zFunctionNa
361e0 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a me,. int nArg,.
361f0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a int eTextRep,.
36200 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 void *pApp,.
36210 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 void (*xFunc)(sq
36220 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
36230 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
36240 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 **),. void (*xS
36250 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e tep)(sqlite3_con
36260 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 text*,int,sqlite
36270 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 3_value**),. vo
36280 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c id (*xFinal)(sql
36290 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 ite3_context*).)
362a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 ;.int sqlite3_cr
362b0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 eate_function_v2
362c0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
362d0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
362e0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 FunctionName,.
362f0 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 int nArg,. int
36300 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 eTextRep,. void
36310 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 *pApp,. void (
36320 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f *xFunc)(sqlite3_
36330 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c context*,int,sql
36340 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 ite3_value**),.
36350 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 void (*xStep)(s
36360 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
36370 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 int,sqlite3_valu
36380 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 e**),. void (*x
36390 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 Final)(sqlite3_c
363a0 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 ontext*),. void
363b0 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 (*xDestroy)(void
363c0 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 *).);../*.** CAP
363d0 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f I3REF: Text Enco
363e0 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 dings.**.** Thes
363f0 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e e constant defin
36400 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 e integer codes
36410 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 that represent t
36420 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 he various.** te
36430 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 xt encodings sup
36440 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 ported by SQLite
36450 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
36460 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 ITE_UTF8
36470 20 20 20 31 20 20 20 20 2f 2a 20 49 4d 50 3a 20 1 /* IMP:
36480 52 2d 33 37 35 31 34 2d 33 35 35 36 36 20 2a 2f R-37514-35566 */
36490 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
364a0 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 UTF16LE 2
364b0 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 30 33 /* IMP: R-03
364c0 33 37 31 2d 33 37 36 33 37 20 2a 2f 0a 23 64 65 371-37637 */.#de
364d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 fine SQLITE_UTF1
364e0 36 42 45 20 20 20 20 20 20 20 20 33 20 20 20 20 6BE 3
364f0 2f 2a 20 49 4d 50 3a 20 52 2d 35 31 39 37 31 2d /* IMP: R-51971-
36500 33 34 31 35 34 20 2a 2f 0a 23 64 65 66 69 6e 65 34154 */.#define
36510 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 SQLITE_UTF16
36520 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 4 /* U
36530 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f se native byte o
36540 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rder */.#define
36550 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 SQLITE_ANY
36560 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 44 65 5 /* De
36570 70 72 65 63 61 74 65 64 20 2a 2f 0a 23 64 65 66 precated */.#def
36580 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 ine SQLITE_UTF16
36590 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f _ALIGNED 8 /
365a0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 * sqlite3_create
365b0 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 _collation only
365c0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
365d0 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61 EF: Function Fla
365e0 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 gs.**.** These c
365f0 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20 onstants may be
36600 4f 52 65 64 20 74 6f 67 65 74 68 65 72 20 77 69 ORed together wi
36610 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 th the .** [SQLI
36620 54 45 5f 55 54 46 38 20 7c 20 70 72 65 66 65 72 TE_UTF8 | prefer
36630 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e red text encodin
36640 67 5d 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 g] as the fourth
36650 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 argument.** to
36660 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
36670 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 function()], [sq
36680 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
36690 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a ction16()], or.*
366a0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 * [sqlite3_creat
366b0 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d e_function_v2()]
366c0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
366d0 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 ITE_DETERMINISTI
366e0 43 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a C 0x800../*.*
366f0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 * CAPI3REF: Depr
36700 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 ecated Functions
36710 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a .** DEPRECATED.*
36720 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 *.** These funct
36730 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 ions are [deprec
36740 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 ated]. In order
36750 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 to maintain.**
36760 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 backwards compat
36770 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 ibility with old
36780 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 er code, these f
36790 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 unctions continu
367a0 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 e .** to be supp
367b0 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c orted. However,
367c0 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e new application
367d0 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a s should avoid.*
367e0 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 * the use of the
367f0 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 se functions. T
36800 6f 20 65 6e 63 6f 75 72 61 67 65 20 70 72 6f 67 o encourage prog
36810 72 61 6d 6d 65 72 73 20 74 6f 20 61 76 6f 69 64 rammers to avoid
36820 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69 .** these functi
36830 6f 6e 73 2c 20 77 65 20 77 69 6c 6c 20 6e 6f 74 ons, we will not
36840 20 65 78 70 6c 61 69 6e 20 77 68 61 74 20 74 68 explain what th
36850 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 ey do..*/.#ifnde
36860 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 f SQLITE_OMIT_DE
36870 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f PRECATED.SQLITE_
36880 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 DEPRECATED int s
36890 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
368a0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 _count(sqlite3_c
368b0 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 ontext*);.SQLITE
368c0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 _DEPRECATED int
368d0 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 sqlite3_expired(
368e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a sqlite3_stmt*);.
368f0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 SQLITE_DEPRECATE
36900 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 D int sqlite3_tr
36910 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 ansfer_bindings(
36920 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 sqlite3_stmt*, s
36930 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 qlite3_stmt*);.S
36940 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 QLITE_DEPRECATED
36950 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f int sqlite3_glo
36960 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 bal_recover(void
36970 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 );.SQLITE_DEPREC
36980 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 ATED void sqlite
36990 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 3_thread_cleanup
369a0 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 (void);.SQLITE_D
369b0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 EPRECATED int sq
369c0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 lite3_memory_ala
369d0 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a rm(void(*)(void*
369e0 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 ,sqlite3_int64,i
369f0 6e 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 nt),.
36a00 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 2a void*
36a10 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b ,sqlite3_int64);
36a20 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 .#endif../*.** C
36a30 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 API3REF: Obtaini
36a40 6e 67 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a ng SQL Values.**
36a50 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
36a60 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 _value.**.** The
36a70 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c C-language impl
36a80 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 ementation of SQ
36a90 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 L functions and
36aa0 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a aggregates uses.
36ab0 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 ** this set of i
36ac0 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 nterface routine
36ad0 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 s to access the
36ae0 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 parameter values
36af0 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 on.** the funct
36b00 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 ion or aggregate
36b10 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 . .**.** The xF
36b20 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 unc (for scalar
36b30 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 functions) or xS
36b40 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 tep (for aggrega
36b50 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a tes) parameters.
36b60 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ** to [sqlite3_c
36b70 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
36b80 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 ] and [sqlite3_c
36b90 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
36ba0 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 ()].** define ca
36bb0 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 llbacks that imp
36bc0 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 lement the SQL f
36bd0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 unctions and agg
36be0 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 regates..** The
36bf0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 3rd parameter to
36c00 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 these callbacks
36c10 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 is an array of
36c20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b pointers to.** [
36c30 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
36c40 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 3_value] objects
36c50 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 . There is one
36c60 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 [sqlite3_value]
36c70 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 object for.** ea
36c80 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 ch parameter to
36c90 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
36ca0 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 . These routine
36cb0 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a s are used to.**
36cc0 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 extract values
36cd0 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 from the [sqlite
36ce0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 3_value] objects
36cf0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f ..**.** These ro
36d00 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 utines work only
36d10 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 with [protected
36d20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
36d30 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 objects..** Any
36d40 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 attempt to use t
36d50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e hese routines on
36d60 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 an [unprotected
36d70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a sqlite3_value].
36d80 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 ** object result
36d90 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 s in undefined b
36da0 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e ehavior..**.** ^
36db0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 These routines w
36dc0 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 ork just like th
36dd0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 e corresponding
36de0 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 [column access f
36df0 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 unctions].** exc
36e00 65 70 74 20 74 68 61 74 20 74 68 65 73 65 20 72 ept that these r
36e10 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 outines take a s
36e20 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 ingle [protected
36e30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
36e40 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 object.** pointe
36e50 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b r instead of a [
36e60 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 sqlite3_stmt*] p
36e70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e ointer and an in
36e80 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d teger column num
36e90 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ber..**.** ^The
36ea0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
36eb0 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 xt16() interface
36ec0 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d extracts a UTF-
36ed0 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 16 string.** in
36ee0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d the native byte-
36ef0 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 order of the hos
36f00 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 t machine. ^The
36f10 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 .** sqlite3_valu
36f20 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 e_text16be() and
36f30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
36f40 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 ext16le() interf
36f50 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 aces.** extract
36f60 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 UTF-16 strings a
36f70 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 s big-endian and
36f80 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 little-endian r
36f90 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a espectively..**.
36fa0 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 ** ^(The sqlite3
36fb0 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 _value_numeric_t
36fc0 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 ype() interface
36fd0 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c attempts to appl
36fe0 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 y.** numeric aff
36ff0 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c inity to the val
37000 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 ue. This means
37010 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 that an attempt
37020 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f is.** made to co
37030 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 nvert the value
37040 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 to an integer or
37050 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e floating point.
37060 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 If.** such a c
37070 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 onversion is pos
37080 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f sible without lo
37090 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f ss of informatio
370a0 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 n (in other.** w
370b0 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c ords, if the val
370c0 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 ue is a string t
370d0 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 hat looks like a
370e0 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e number).** then
370f0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 the conversion
37100 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f is performed. O
37110 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 therwise no conv
37120 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a ersion occurs..*
37130 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e * The [SQLITE_IN
37140 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 TEGER | datatype
37150 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 ] after conversi
37160 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 on is returned.)
37170 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 ^.**.** Please p
37180 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 ay particular at
37190 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 tention to the f
371a0 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 act that the poi
371b0 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a nter returned.**
371c0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 from [sqlite3_v
371d0 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 alue_blob()], [s
371e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
371f0 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c t()], or.** [sql
37200 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
37210 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6()] can be inva
37220 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 lidated by a sub
37230 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a sequent call to.
37240 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ** [sqlite3_valu
37250 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c e_bytes()], [sql
37260 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 ite3_value_bytes
37270 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 16()], [sqlite3_
37280 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a value_text()],.*
37290 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 * or [sqlite3_va
372a0 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a lue_text16()]..*
372b0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
372c0 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c nes must be call
372d0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 ed from the same
372e0 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 thread as.** th
372f0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 e SQL function t
37300 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 hat supplied the
37310 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a [sqlite3_value*
37320 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f ] parameters..*/
37330 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
37340 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 ite3_value_blob(
37350 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
37360 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c .int sqlite3_val
37370 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 ue_bytes(sqlite3
37380 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 _value*);.int sq
37390 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 lite3_value_byte
373a0 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 s16(sqlite3_valu
373b0 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 e*);.double sqli
373c0 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 te3_value_double
373d0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
373e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 ;.int sqlite3_va
373f0 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f lue_int(sqlite3_
37400 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 value*);.sqlite3
37410 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 _int64 sqlite3_v
37420 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 alue_int64(sqlit
37430 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 e3_value*);.cons
37440 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 t unsigned char
37450 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 *sqlite3_value_t
37460 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 ext(sqlite3_valu
37470 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 e*);.const void
37480 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 *sqlite3_value_t
37490 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 ext16(sqlite3_va
374a0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 lue*);.const voi
374b0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 d *sqlite3_value
374c0 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 _text16le(sqlite
374d0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 3_value*);.const
374e0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 void *sqlite3_v
374f0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 alue_text16be(sq
37500 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 lite3_value*);.i
37510 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt sqlite3_value
37520 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 _type(sqlite3_va
37530 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 lue*);.int sqlit
37540 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 e3_value_numeric
37550 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 _type(sqlite3_va
37560 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 lue*);../*.** CA
37570 50 49 33 52 45 46 3a 20 46 69 6e 64 69 6e 67 20 PI3REF: Finding
37580 54 68 65 20 53 75 62 74 79 70 65 20 4f 66 20 53 The Subtype Of S
37590 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 QL Values.** MET
375a0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c HOD: sqlite3_val
375b0 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c ue.**.** The sql
375c0 69 74 65 33 5f 76 61 6c 75 65 5f 73 75 62 74 79 ite3_value_subty
375d0 70 65 28 56 29 20 66 75 6e 63 74 69 6f 6e 20 72 pe(V) function r
375e0 65 74 75 72 6e 73 20 74 68 65 20 73 75 62 74 79 eturns the subty
375f0 70 65 20 66 6f 72 0a 2a 2a 20 61 6e 20 5b 61 70 pe for.** an [ap
37600 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
37610 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 d SQL function]
37620 61 72 67 75 6d 65 6e 74 20 56 2e 20 20 54 68 65 argument V. The
37630 20 73 75 62 74 79 70 65 0a 2a 2a 20 69 6e 66 6f subtype.** info
37640 72 6d 61 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 rmation can be u
37650 73 65 64 20 74 6f 20 70 61 73 73 20 61 20 6c 69 sed to pass a li
37660 6d 69 74 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 mited amount of
37670 63 6f 6e 74 65 78 74 20 66 72 6f 6d 0a 2a 2a 20 context from.**
37680 6f 6e 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e one SQL function
37690 20 74 6f 20 61 6e 6f 74 68 65 72 2e 20 20 55 73 to another. Us
376a0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 e the [sqlite3_r
376b0 65 73 75 6c 74 5f 73 75 62 74 79 70 65 28 29 5d esult_subtype()]
376c0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 73 .** routine to s
376d0 65 74 20 74 68 65 20 73 75 62 74 79 70 65 20 66 et the subtype f
376e0 6f 72 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 or the return va
376f0 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c 20 66 75 lue of an SQL fu
37700 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 nction..**.** SQ
37710 4c 69 74 65 20 6d 61 6b 65 73 20 6e 6f 20 75 73 Lite makes no us
37720 65 20 6f 66 20 73 75 62 74 79 70 65 20 69 74 73 e of subtype its
37730 65 6c 66 2e 20 20 49 74 20 6d 65 72 65 6c 79 20 elf. It merely
37740 70 61 73 73 65 73 20 74 68 65 20 73 75 62 74 79 passes the subty
37750 70 65 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 72 pe.** from the r
37760 65 73 75 6c 74 20 6f 66 20 6f 6e 65 20 5b 61 70 esult of one [ap
37770 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
37780 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 d SQL function]
37790 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6e 70 75 into the.** inpu
377a0 74 20 6f 66 20 61 6e 6f 74 68 65 72 2e 0a 2a 2f t of another..*/
377b0 0a 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 71 .unsigned int sq
377c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73 75 62 74 lite3_value_subt
377d0 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 ype(sqlite3_valu
377e0 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 e*);../*.** CAPI
377f0 33 52 45 46 3a 20 43 6f 70 79 20 41 6e 64 20 46 3REF: Copy And F
37800 72 65 65 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a ree SQL Values.*
37810 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
37820 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 5e 54 3_value.**.** ^T
37830 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 he sqlite3_value
37840 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66 61 63 _dup(V) interfac
37850 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f e makes a copy o
37860 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 f the [sqlite3_v
37870 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 alue].** object
37880 44 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 D and returns a
37890 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 pointer to that
378a0 63 6f 70 79 2e 20 20 5e 54 68 65 20 5b 73 71 6c copy. ^The [sql
378b0 69 74 65 33 5f 76 61 6c 75 65 5d 20 72 65 74 75 ite3_value] retu
378c0 72 6e 65 64 0a 2a 2a 20 69 73 20 61 20 5b 70 72 rned.** is a [pr
378d0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
378e0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 65 76 value] object ev
378f0 65 6e 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 en if the input
37900 69 73 20 6e 6f 74 2e 0a 2a 2a 20 5e 54 68 65 20 is not..** ^The
37910 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 sqlite3_value_du
37920 70 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 72 p(V) interface r
37930 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 56 eturns NULL if V
37940 20 69 73 20 4e 55 4c 4c 20 6f 72 20 69 66 20 61 is NULL or if a
37950 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 .** memory alloc
37960 61 74 69 6f 6e 20 66 61 69 6c 73 2e 0a 2a 2a 0a ation fails..**.
37970 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
37980 76 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69 6e value_free(V) in
37990 74 65 72 66 61 63 65 20 66 72 65 65 73 20 61 6e terface frees an
379a0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d [sqlite3_value]
379b0 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 72 65 76 69 object.** previ
379c0 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 ously obtained f
379d0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c rom [sqlite3_val
379e0 75 65 5f 64 75 70 28 29 5d 2e 20 20 5e 49 66 20 ue_dup()]. ^If
379f0 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e V is a NULL poin
37a00 74 65 72 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 ter.** then sqli
37a10 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 te3_value_free(V
37a20 29 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 ) is a harmless
37a30 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 73 71 6c 69 74 65 no-op..*/.sqlite
37a40 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 3_value *sqlite3
37a50 5f 76 61 6c 75 65 5f 64 75 70 28 63 6f 6e 73 74 _value_dup(const
37a60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 sqlite3_value*)
37a70 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 76 ;.void sqlite3_v
37a80 61 6c 75 65 5f 66 72 65 65 28 73 71 6c 69 74 65 alue_free(sqlite
37a90 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 3_value*);../*.*
37aa0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 * CAPI3REF: Obta
37ab0 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e in Aggregate Fun
37ac0 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a ction Context.**
37ad0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
37ae0 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 _context.**.** I
37af0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f mplementations o
37b00 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 f aggregate SQL
37b10 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 functions use th
37b20 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f is.** routine to
37b30 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 allocate memory
37b40 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 for storing the
37b50 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 ir state..**.**
37b60 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 ^The first time
37b70 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 the sqlite3_aggr
37b80 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c egate_context(C,
37b90 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 N) routine is ca
37ba0 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 lled .** for a p
37bb0 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 articular aggreg
37bc0 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 ate function, SQ
37bd0 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 Lite.** allocate
37be0 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a s N of memory, z
37bf0 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d eroes out that m
37c00 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 emory, and retur
37c10 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 ns a pointer.**
37c20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 to the new memor
37c30 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e y. ^On second an
37c40 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c d subsequent cal
37c50 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 ls to.** sqlite3
37c60 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
37c70 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d xt() for the sam
37c80 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 e aggregate func
37c90 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a tion instance,.*
37ca0 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 * the same buffe
37cb0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 r is returned.
37cc0 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 Sqlite3_aggregat
37cd0 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e e_context() is n
37ce0 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 ormally.** calle
37cf0 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 d once for each
37d00 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 invocation of th
37d10 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b e xStep callback
37d20 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a and then one.**
37d30 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 last time when
37d40 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 the xFinal callb
37d50 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 ack is invoked.
37d60 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 ^(When no rows
37d70 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 match.** an aggr
37d80 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 egate query, the
37d90 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 xStep() callbac
37da0 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 k of the aggrega
37db0 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 te function.** i
37dc0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 mplementation is
37dd0 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e never called an
37de0 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 d xFinal() is ca
37df0 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 lled exactly onc
37e00 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 e..** In those c
37e10 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 ases, sqlite3_ag
37e20 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
37e30 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 ) might be calle
37e40 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 d for the.** fir
37e50 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 st time from wit
37e60 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a hin xFinal().)^.
37e70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
37e80 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
37e90 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e text(C,N) routin
37ea0 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c e returns a NULL
37eb0 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65 pointer .** whe
37ec0 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69 n first called i
37ed0 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e f N is less than
37ee0 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 or equal to zer
37ef0 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 o or if a memory
37f00 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 .** allocate err
37f10 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a or occurs..**.**
37f20 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 ^(The amount of
37f30 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 space allocated
37f40 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 by sqlite3_aggr
37f50 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c egate_context(C,
37f60 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 N) is.** determi
37f70 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 ned by the N par
37f80 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 ameter on first
37f90 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e successful call.
37fa0 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a Changing the.*
37fb0 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 * value of N in
37fc0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 subsequent call
37fd0 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 to sqlite3_aggre
37fe0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 gate_context() w
37ff0 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d ithin.** the sam
38000 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 e aggregate func
38010 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 tion instance wi
38020 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 ll not resize th
38030 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f e memory.** allo
38040 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69 cation.)^ Withi
38050 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c n the xFinal cal
38060 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73 lback, it is cus
38070 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a tomary to set.**
38080 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f N=0 in calls to
38090 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 sqlite3_aggrega
380a0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 te_context(C,N)
380b0 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 so that no .** p
380c0 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20 ointless memory
380d0 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75 allocations occu
380e0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 r..**.** ^SQLite
380f0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 automatically f
38100 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 rees the memory
38110 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a allocated by .**
38120 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 sqlite3_aggrega
38130 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 te_context() whe
38140 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 n the aggregate
38150 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e query concludes.
38160 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
38170 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 parameter must
38180 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 be a copy of the
38190 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
381a0 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 text | SQL funct
381b0 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 ion context] tha
381c0 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 t is the first p
381d0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 arameter.** to t
381e0 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e he xStep or xFin
381f0 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 al callback rout
38200 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 ine that impleme
38210 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 nts the aggregat
38220 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a e.** function..*
38230 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
38240 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 e must be called
38250 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 from the same t
38260 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a hread in which.*
38270 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 * the aggregate
38280 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 SQL function is
38290 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 running..*/.void
382a0 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 *sqlite3_aggreg
382b0 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 ate_context(sqli
382c0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
382d0 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a t nBytes);../*.*
382e0 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 * CAPI3REF: User
382f0 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 Data For Functi
38300 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ons.** METHOD: s
38310 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a qlite3_context.*
38320 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
38330 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 3_user_data() in
38340 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
38350 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 a copy of.** the
38360 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 pointer that wa
38370 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 s the pUserData
38380 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 parameter (the 5
38390 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a th parameter).**
383a0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
383b0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
383c0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 ()].** and [sqli
383d0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
383e0 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 ion16()] routine
383f0 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c s that originall
38400 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 y.** registered
38410 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
38420 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
38430 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 ..**.** This rou
38440 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c tine must be cal
38450 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d led from the sam
38460 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 e thread in whic
38470 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 h.** the applica
38480 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
38490 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 ction is running
384a0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 ..*/.void *sqlit
384b0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c e3_user_data(sql
384c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a ite3_context*);.
384d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
384e0 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 Database Connec
384f0 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f tion For Functio
38500 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 ns.** METHOD: sq
38510 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a lite3_context.**
38520 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
38530 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 _context_db_hand
38540 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 le() interface r
38550 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 eturns a copy of
38560 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 .** the pointer
38570 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 to the [database
38580 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 connection] (th
38590 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 e 1st parameter)
385a0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 .** of the [sqli
385b0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
385c0 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 ion()].** and [s
385d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
385e0 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 nction16()] rout
385f0 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e ines that origin
38600 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 ally.** register
38610 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ed the applicati
38620 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on defined funct
38630 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 ion..*/.sqlite3
38640 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 *sqlite3_context
38650 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 _db_handle(sqlit
38660 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f e3_context*);../
38670 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
38680 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 unction Auxiliar
38690 79 20 44 61 74 61 0a 2a 2a 20 4d 45 54 48 4f 44 y Data.** METHOD
386a0 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 : sqlite3_contex
386b0 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 t.**.** These fu
386c0 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 nctions may be u
386d0 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 sed by (non-aggr
386e0 65 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63 74 egate) SQL funct
386f0 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 ions to.** assoc
38700 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 iate metadata wi
38710 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 th argument valu
38720 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 es. If the same
38730 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 value is passed
38740 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 to.** multiple i
38750 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 nvocations of th
38760 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 e same SQL funct
38770 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 ion during query
38780 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 execution, unde
38790 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d r.** some circum
387a0 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f stances the asso
387b0 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 ciated metadata
387c0 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 may be preserved
387d0 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a . An example.**
387e0 20 6f 66 20 77 68 65 72 65 20 74 68 69 73 20 6d of where this m
387f0 69 67 68 74 20 62 65 20 75 73 65 66 75 6c 20 69 ight be useful i
38800 73 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 s in a regular-e
38810