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 20 -in (UTC) and a
1090: 53 48 41 31 0a 2a 2a 20 6f 72 20 53 48 41 33 2d SHA1.** or SHA3-
10a0: 32 35 36 20 68 61 73 68 20 6f 66 20 74 68 65 20 256 hash of the
10b0: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72 entire source tr
10c0: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c ee..**.** See al
10d0: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 so: [sqlite3_lib
10e0: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b version()],.** [
10f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
1100: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 on_number()], [s
1110: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 qlite3_sourceid(
1120: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 )],.** [sqlite_v
1130: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 ersion()] and [s
1140: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 qlite_source_id(
1150: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 )]..*/.#define S
1160: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 QLITE_VERSION
1170: 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a "--VERS--".
1180: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 #define SQLITE_V
1190: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d ERSION_NUMBER --
11a0: 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d VERSION-NUMBER--
11b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
11c0: 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 SOURCE_ID "
11d0: 2d 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a --SOURCE-ID--"..
11e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
11f0: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 Run-Time Library
1200: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 Version Numbers
1210: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 .** KEYWORDS: sq
1220: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71 lite3_version sq
1230: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a lite3_sourceid.*
1240: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 *.** These inter
1250: 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 faces provide th
1260: 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 e same informati
1270: 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 on as the [SQLIT
1280: 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b E_VERSION],.** [
1290: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e SQLITE_VERSION_N
12a0: 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c UMBER], and [SQL
12b0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 ITE_SOURCE_ID] C
12c0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 preprocessor ma
12d0: 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 cros.** but are
12e0: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
12f0: 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 the library inst
1300: 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 ead of the heade
1310: 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 r file. ^(Cauti
1320: 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 ous.** programme
1330: 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 rs might include
1340: 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d assert() statem
1350: 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 ents in their ap
1360: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 plication to.**
1370: 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 verify that valu
1380: 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 es returned by t
1390: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 hese interfaces
13a0: 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 match the macros
13b0: 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 in.** the heade
13c0: 72 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 r, and thus ensu
13d0: 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c re that the appl
13e0: 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f ication is.** co
13f0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 mpiled with matc
1400: 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 hing library and
1410: 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a header files..*
1420: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
1430: 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 ><pre>.** assert
1440: 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 ( sqlite3_libver
1450: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 sion_number()==S
1460: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 QLITE_VERSION_NU
1470: 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 MBER );.** asser
1480: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 t( strcmp(sqlite
1490: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c 3_sourceid(),SQL
14a0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d ITE_SOURCE_ID)==
14b0: 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 0 );.** assert(
14c0: 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c strcmp(sqlite3_l
14d0: 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49 ibversion(),SQLI
14e0: 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29 TE_VERSION)==0 )
14f0: 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f ;.** </pre></blo
1500: 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a ckquote>)^.**.**
1510: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65 ^The sqlite3_ve
1520: 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 rsion[] string c
1530: 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 onstant contains
1540: 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53 51 the text of [SQ
1550: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a LITE_VERSION].**
1560: 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 71 macro. ^The sq
1570: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e lite3_libversion
1580: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 () function retu
1590: 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
15a0: 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73 the.** to the s
15b0: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d qlite3_version[]
15c0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 string constant
15d0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c . The sqlite3_l
15e0: 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 ibversion().** f
15f0: 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 unction is provi
1600: 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 44 ded for use in D
1610: 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 LLs since DLL us
1620: 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e ers usually do n
1630: 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 63 ot have.** direc
1640: 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72 69 t access to stri
1650: 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 ng constants wit
1660: 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54 hin the DLL. ^T
1670: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 he.** sqlite3_li
1680: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 bversion_number(
1690: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 ) function retur
16a0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71 ns an integer eq
16b0: 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 ual to.** [SQLIT
16c0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 E_VERSION_NUMBER
16d0: 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 ]. ^The sqlite3
16e0: 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63 _sourceid() func
16f0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a tion returns .**
1700: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
1710: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 string constant
1720: 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74 whose value is t
1730: 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a he same as the .
1740: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 ** [SQLITE_SOURC
1750: 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 E_ID] C preproce
1760: 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a ssor macro..**.*
1770: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
1780: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 ite_version()] a
1790: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 nd [sqlite_sourc
17a0: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 e_id()]..*/.SQLI
17b0: 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 TE_EXTERN const
17c0: 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 char sqlite3_ver
17d0: 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 sion[];.const ch
17e0: 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 ar *sqlite3_libv
17f0: 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 63 6f ersion(void);.co
1800: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
1810: 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3_sourceid(void)
1820: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 ;.int sqlite3_li
1830: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 bversion_number(
1840: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 void);../*.** CA
1850: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 PI3REF: Run-Time
1860: 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c 61 Library Compila
1870: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61 tion Options Dia
1880: 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e gnostics.**.** ^
1890: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 The sqlite3_comp
18a0: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 ileoption_used()
18b0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e function return
18c0: 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 s 0 or 1 .** ind
18d0: 69 63 61 74 69 6e 67 20 77 68 65 74 68 65 72 20 icating whether
18e0: 74 68 65 20 73 70 65 63 69 66 69 65 64 20 6f 70 the specified op
18f0: 74 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65 64 tion was defined
1900: 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 at .** compile
1910: 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c 49 time. ^The SQLI
1920: 54 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20 62 TE_ prefix may b
1930: 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 e omitted from t
1940: 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 he .** option na
1950: 6d 65 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c me passed to sql
1960: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 ite3_compileopti
1970: 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a on_used(). .**.
1980: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 compileoption_ge
19a0: 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c t() function all
19b0: 6f 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a ows iterating.**
19c0: 20 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20 6f over the list o
19d0: 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 77 f options that w
19e0: 65 72 65 20 64 65 66 69 6e 65 64 20 61 74 20 63 ere defined at c
19f0: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a ompile time by.*
1a00: 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65 20 * returning the
1a10: 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d N-th compile tim
1a20: 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e e option string.
1a30: 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20 6f ^If N is out o
1a40: 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 f range,.** sqli
1a50: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f te3_compileoptio
1a60: 6e 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73 20 n_get() returns
1a70: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 a NULL pointer.
1a80: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a ^The SQLITE_ .*
1a90: 2a 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69 74 * prefix is omit
1aa0: 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74 72 ted from any str
1ab0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 ings returned by
1ac0: 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d .** sqlite3_com
1ad0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 pileoption_get()
1ae0: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 ..**.** ^Support
1af0: 20 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f 73 for the diagnos
1b00: 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73 71 tic functions sq
1b10: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 lite3_compileopt
1b20: 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e ion_used().** an
1b30: 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c d sqlite3_compil
1b40: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61 eoption_get() ma
1b50: 79 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79 20 y be omitted by
1b60: 73 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 0a specifying the .
1b70: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f ** [SQLITE_OMIT_
1b80: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 COMPILEOPTION_DI
1b90: 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63 AGS] option at c
1ba0: 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a ompile time..**.
1bb0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c ** See also: SQL
1bc0: 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69 functions [sqli
1bd0: 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e te_compileoption
1be0: 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 _used()] and.**
1bf0: 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f [sqlite_compileo
1c00: 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64 ption_get()] and
1c10: 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 the [compile_op
1c20: 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a tions pragma]..*
1c30: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 /.#ifndef SQLITE
1c40: 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 _OMIT_COMPILEOPT
1c50: 49 4f 4e 5f 44 49 41 47 53 0a 69 6e 74 20 73 71 ION_DIAGS.int sq
1c60: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 lite3_compileopt
1c70: 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63 ion_used(const c
1c80: 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a har *zOptName);.
1c90: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 const char *sqli
1ca0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f te3_compileoptio
1cb0: 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 n_get(int N);.#e
1cc0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ndif../*.** CAPI
1cd0: 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 3REF: Test To Se
1ce0: 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 e If The Library
1cf0: 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a Is Threadsafe.*
1d00: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
1d10: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66 3_threadsafe() f
1d20: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
1d30: 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 zero if and only
1d40: 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 if.** SQLite wa
1d50: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 s compiled with
1d60: 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d mutexing code om
1d70: 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65 itted due to the
1d80: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 .** [SQLITE_THRE
1d90: 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d ADSAFE] compile-
1da0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e time option bein
1db0: 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a g set to 0..**.*
1dc0: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 * SQLite can be
1dd0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 compiled with or
1de0: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 without mutexes
1df0: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b . When.** the [
1e00: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
1e10: 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f E] C preprocesso
1e20: 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20 r macro is 1 or
1e30: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 2, mutexes.** ar
1e40: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 e enabled and SQ
1e50: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61 Lite is threadsa
1e60: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a fe. When the.**
1e70: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
1e80: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c AFE] macro is 0,
1e90: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 .** the mutexes
1ea0: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 are omitted. W
1eb0: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 ithout the mutex
1ec0: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 es, it is not sa
1ed0: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c fe.** to use SQL
1ee0: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 ite concurrently
1ef0: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 from more than
1f00: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a one thread..**.*
1f10: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 * Enabling mutex
1f20: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 es incurs a meas
1f30: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e urable performan
1f40: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 ce penalty..** S
1f50: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 o if speed is of
1f60: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e utmost importan
1f70: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e ce, it makes sen
1f80: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a se to disable.**
1f90: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 the mutexes. B
1fa0: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 ut for maximum s
1fb0: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 afety, mutexes s
1fc0: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 hould be enabled
1fd0: 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c ..** ^The defaul
1fe0: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f t behavior is fo
1ff0: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 r mutexes to be
2000: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 enabled..**.** T
2010: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 his interface ca
2020: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20 n be used by an
2030: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d application to m
2040: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68 ake sure that th
2050: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 e.** version of
2060: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69 SQLite that it i
2070: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 s linking agains
2080: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 t was compiled w
2090: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 ith.** the desir
20a0: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68 ed setting of th
20b0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
20c0: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a SAFE] macro..**.
20d0: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 ** This interfac
20e0: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f e only reports o
20f0: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 n the compile-ti
2100: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67 me mutex setting
2110: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 .** of the [SQLI
2120: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66 TE_THREADSAFE] f
2130: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20 lag. If SQLite
2140: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
2150: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41 .** SQLITE_THREA
2160: 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 DSAFE=1 or =2 th
2170: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 en mutexes are e
2180: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c nabled by defaul
2190: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 t but.** can be
21a0: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c fully or partial
21b0: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e ly disabled usin
21c0: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c g a call to [sql
21d0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a ite3_config()].*
21e0: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73 * with the verbs
21f0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
2200: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b SINGLETHREAD], [
2210: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
2220: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f LTITHREAD],.** o
2230: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 r [SQLITE_CONFIG
2240: 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20 5e _SERIALIZED]. ^
2250: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 (The return valu
2260: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 e of the.** sqli
2270: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 te3_threadsafe()
2280: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 function shows
2290: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 only the compile
22a0: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 -time setting of
22b0: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74 .** thread safet
22c0: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 y, not any run-t
22d0: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74 ime changes to t
22e0: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65 hat setting made
22f0: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 by.** sqlite3_c
2300: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 onfig(). In othe
2310: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74 r words, the ret
2320: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 urn value from s
2330: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 qlite3_threadsaf
2340: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e e().** is unchan
2350: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 ged by calls to
2360: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
2370: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 .)^.**.** See th
2380: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 e [threading mod
2390: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e e] documentation
23a0: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 for additional
23b0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a information..*/.
23c0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 int sqlite3_thre
23d0: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f adsafe(void);../
23e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
23f0: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 atabase Connecti
2400: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 on Handle.** KEY
2410: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 WORDS: {database
2420: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 connection} {da
2430: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2440: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f ns}.**.** Each o
2450: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 pen SQLite datab
2460: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 ase is represent
2470: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 ed by a pointer
2480: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f to an instance o
2490: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 f.** the opaque
24a0: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 structure named
24b0: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 "sqlite3". It i
24c0: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e s useful to thin
24d0: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a k of an sqlite3.
24e0: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e ** pointer as an
24f0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 object. The [s
2500: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 qlite3_open()],
2510: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 [sqlite3_open16(
2520: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 )], and.** [sqli
2530: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 te3_open_v2()] i
2540: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74 nterfaces are it
2550: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 s constructors,
2560: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f and [sqlite3_clo
2570: 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 se()].** and [sq
2580: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 lite3_close_v2()
2590: 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72 75 ] are its destru
25a0: 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72 ctors. There ar
25b0: 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 e many other.**
25c0: 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68 interfaces (such
25d0: 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f as.** [sqlite3_
25e0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b prepare_v2()], [
25f0: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
2600: 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a unction()], and.
2610: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 ** [sqlite3_busy
2620: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e _timeout()] to n
2630: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74 ame but three) t
2640: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20 hat are methods
2650: 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 on an.** sqlite3
2660: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 object..*/.type
2670: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
2680: 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a e3 sqlite3;../*.
2690: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d ** CAPI3REF: 64-
26a0: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 Bit Integer Type
26b0: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 s.** KEYWORDS: s
26c0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 qlite_int64 sqli
26d0: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 te_uint64.**.**
26e0: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73 Because there is
26f0: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f no cross-platfo
2700: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 rm way to specif
2710: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 y 64-bit integer
2720: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 types.** SQLite
2730: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 includes typede
2740: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 fs for 64-bit si
2750: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 gned and unsigne
2760: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a d integers..**.*
2770: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e * The sqlite3_in
2780: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f t64 and sqlite3_
2790: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 uint64 are the p
27a0: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65 referred type de
27b0: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 finitions..** Th
27c0: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 e sqlite_int64 a
27d0: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 nd sqlite_uint64
27e0: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f types are suppo
27f0: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 rted for backwar
2800: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c ds.** compatibil
2810: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ity only..**.**
2820: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 ^The sqlite3_int
2830: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e 64 and sqlite_in
2840: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 t64 types can st
2850: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 ore integer valu
2860: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39 es.** between -9
2870: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38 2233720368547758
2880: 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30 08 and +92233720
2890: 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c 36854775807 incl
28a0: 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 usive. ^The.**
28b0: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 sqlite3_uint64 a
28c0: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 nd sqlite_uint64
28d0: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 types can store
28e0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 integer values
28f0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e .** between 0 an
2900: 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 30 d +1844674407370
2910: 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76 9551615 inclusiv
2920: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c e..*/.#ifdef SQL
2930: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 ITE_INT64_TYPE.
2940: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f typedef SQLITE_
2950: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 INT64_TYPE sqlit
2960: 65 5f 69 6e 74 36 34 3b 0a 23 20 69 66 64 65 66 e_int64;.# ifdef
2970: 20 53 51 4c 49 54 45 5f 55 49 4e 54 36 34 5f 54 SQLITE_UINT64_T
2980: 59 50 45 0a 20 20 20 20 74 79 70 65 64 65 66 20 YPE. typedef
2990: 53 51 4c 49 54 45 5f 55 49 4e 54 36 34 5f 54 59 SQLITE_UINT64_TY
29a0: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 PE sqlite_uint64
29b0: 3b 0a 23 20 65 6c 73 65 20 20 0a 20 20 20 20 74 ;.# else . t
29c0: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 ypedef unsigned
29d0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 SQLITE_INT64_TYP
29e0: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b E sqlite_uint64;
29f0: 0a 23 20 65 6e 64 69 66 0a 23 65 6c 69 66 20 64 .# endif.#elif d
2a00: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 efined(_MSC_VER)
2a10: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f || defined(__BO
2a20: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 RLANDC__). type
2a30: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 def __int64 sqli
2a40: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 te_int64;. type
2a50: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 def unsigned __i
2a60: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 nt64 sqlite_uint
2a70: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64;.#else. type
2a80: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e def long long in
2a90: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a t sqlite_int64;.
2aa0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e typedef unsign
2ab0: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 ed long long int
2ac0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a sqlite_uint64;.
2ad0: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73 #endif.typedef s
2ae0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 qlite_int64 sqli
2af0: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 te3_int64;.typed
2b00: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 ef sqlite_uint64
2b10: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b sqlite3_uint64;
2b20: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 ../*.** If compi
2b30: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65 ling for a proce
2b40: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20 ssor that lacks
2b50: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 floating point s
2b60: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 upport,.** subst
2b70: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f itute integer fo
2b80: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 r floating-point
2b90: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 ..*/.#ifdef SQLI
2ba0: 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 TE_OMIT_FLOATING
2bb0: 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 _POINT.# define
2bc0: 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 double sqlite3_i
2bd0: 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a nt64.#endif../*.
2be0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f ** CAPI3REF: Clo
2bf0: 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20 sing A Database
2c00: 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44 45 Connection.** DE
2c10: 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 STRUCTOR: sqlite
2c20: 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 3.**.** ^The sql
2c30: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 ite3_close() and
2c40: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 sqlite3_close_v
2c50: 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 2() routines are
2c60: 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20 destructors.**
2c70: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 for the [sqlite3
2c80: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 ] object..** ^Ca
2c90: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 lls to sqlite3_c
2ca0: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 lose() and sqlit
2cb0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65 e3_close_v2() re
2cc0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d turn [SQLITE_OK]
2cd0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 if.** the [sqli
2ce0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 te3] object is s
2cf0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 uccessfully dest
2d00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 royed and all as
2d10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f sociated.** reso
2d20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f urces are deallo
2d30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 cated..**.** ^If
2d40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
2d50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f nnection is asso
2d60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 ciated with unfi
2d70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 nalized prepared
2d80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f .** statements o
2d90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c r unfinished sql
2da0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 ite3_backup obje
2db0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 cts then sqlite3
2dc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c _close().** will
2dd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62 leave the datab
2de0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f ase connection o
2df0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b pen and return [
2e00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a SQLITE_BUSY]..**
2e10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f ^If sqlite3_clo
2e20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 se_v2() is calle
2e30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a d with unfinaliz
2e40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74 ed prepared stat
2e50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72 ements.** and/or
2e60: 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 unfinished sqli
2e70: 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 te3_backups, the
2e80: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
2e90: 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 onnection become
2ea0: 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 s.** an unusable
2eb0: 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20 "zombie" which
2ec0: 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c will automatical
2ed0: 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 ly be deallocate
2ee0: 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 d when the.** la
2ef0: 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 st prepared stat
2f00: 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a ement is finaliz
2f10: 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73 ed or the last s
2f20: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73 qlite3_backup is
2f30: 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54 .** finished. T
2f40: 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 he sqlite3_close
2f50: 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 _v2() interface
2f60: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 is intended for
2f70: 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 use with.** host
2f80: 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61 74 20 languages that
2f90: 61 72 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c are garbage coll
2fa0: 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65 ected, and where
2fb0: 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68 the order in wh
2fc0: 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f ich.** destructo
2fd0: 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73 rs are called is
2fe0: 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a arbitrary..**.*
2ff0: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 * Applications s
3000: 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 hould [sqlite3_f
3010: 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 inalize | finali
3020: 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 ze] all [prepare
3030: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a d statements],.*
3040: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f * [sqlite3_blob_
3050: 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 close | close] a
3060: 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 ll [BLOB handles
3070: 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 ], and .** [sqli
3080: 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 te3_backup_finis
3090: 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 h | finish] all
30a0: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d [sqlite3_backup]
30b0: 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61 objects associa
30c0: 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 ted.** with the
30d0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 [sqlite3] object
30e0: 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 prior to attemp
30f0: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 ting to close th
3100: 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a e object. ^If.*
3110: 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f * sqlite3_close_
3120: 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f v2() is called o
3130: 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f n a [database co
3140: 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 nnection] that s
3150: 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 till has.** outs
3160: 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65 tanding [prepare
3170: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b d statements], [
3180: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 BLOB handles], a
3190: 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 nd/or.** [sqlite
31a0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 3_backup] object
31b0: 73 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e s then it return
31c0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e s [SQLITE_OK] an
31d0: 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 69 d the deallocati
31e0: 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63 on.** of resourc
31f0: 65 73 20 69 73 20 64 65 66 65 72 72 65 64 20 75 es is deferred u
3200: 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72 ntil all [prepar
3210: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 ed statements],
3220: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a [BLOB handles],.
3230: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ** and [sqlite3_
3240: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 backup] objects
3250: 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72 6f 79 are also destroy
3260: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e ed..**.** ^If an
3270: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 [sqlite3] objec
3280: 74 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 77 t is destroyed w
3290: 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69 hile a transacti
32a0: 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 on is open,.** t
32b0: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 he transaction i
32c0: 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 s automatically
32d0: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a rolled back..**.
32e0: 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 74 ** The C paramet
32f0: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 er to [sqlite3_c
3300: 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 71 lose(C)] and [sq
3310: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43 lite3_close_v2(C
3320: 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 )].** must be ei
3330: 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 ther a NULL.** p
3340: 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 ointer or an [sq
3350: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f lite3] object po
3360: 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a inter obtained.*
3370: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f * from [sqlite3_
3380: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 open()], [sqlite
3390: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 3_open16()], or.
33a0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ** [sqlite3_open
33b0: 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 _v2()], and not
33c0: 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 previously close
33d0: 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 d..** ^Calling s
33e0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f qlite3_close() o
33f0: 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f r sqlite3_close_
3400: 76 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c v2() with a NULL
3410: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75 pointer.** argu
3420: 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d 6c 65 ment is a harmle
3430: 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 ss no-op..*/.int
3440: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 sqlite3_close(s
3450: 71 6c 69 74 65 33 2a 29 3b 0a 69 6e 74 20 73 71 qlite3*);.int sq
3460: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 lite3_close_v2(s
3470: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
3480: 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 The type for a
3490: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
34a0: 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 n..** This is le
34b0: 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 gacy and depreca
34c0: 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c ted. It is incl
34d0: 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 uded for histori
34e0: 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 cal.** compatibi
34f0: 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 lity and is not
3500: 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 documented..*/.t
3510: 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c ypedef int (*sql
3520: 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 ite3_callback)(v
3530: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c oid*,int,char**,
3540: 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a char**);../*.**
3550: 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 CAPI3REF: One-S
3560: 74 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74 tep Query Execut
3570: 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a ion Interface.**
3580: 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
3590: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
35a0: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 e3_exec() interf
35b0: 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 ace is a conveni
35c0: 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f ence wrapper aro
35d0: 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f und.** [sqlite3_
35e0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b prepare_v2()], [
35f0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c sqlite3_step()],
3600: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 and [sqlite3_fi
3610: 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 nalize()],.** th
3620: 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70 at allows an app
3630: 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20 lication to run
3640: 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65 multiple stateme
3650: 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 nts of SQL.** wi
3660: 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 thout having to
3670: 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 use a lot of C c
3680: 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ode. .**.** ^The
3690: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
36a0: 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a interface runs z
36b0: 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d ero or more UTF-
36c0: 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 8 encoded,.** se
36d0: 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 micolon-separate
36e0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
36f0: 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20 passed into its
3700: 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 2nd argument,.**
3710: 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 in the context
3720: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 of the [database
3730: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73 connection] pas
3740: 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73 sed in as its 1s
3750: 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 t.** argument.
3760: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b ^If the callback
3770: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 function of the
3780: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 3rd argument to
3790: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 .** sqlite3_exec
37a0: 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 () is not NULL,
37b0: 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b then it is invok
37c0: 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75 ed for each resu
37d0: 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 lt row.** coming
37e0: 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c out of the eval
37f0: 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d uated SQL statem
3800: 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20 ents. ^The 4th
3810: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 argument to.** s
3820: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 qlite3_exec() is
3830: 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68 relayed through
3840: 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75 to the 1st argu
3850: 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 ment of each.**
3860: 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 callback invocat
3870: 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61 ion. ^If the ca
3880: 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 llback pointer t
3890: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 o sqlite3_exec()
38a0: 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 .** is NULL, the
38b0: 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 n no callback is
38c0: 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e ever invoked an
38d0: 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72 d result rows ar
38e0: 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a e.** ignored..**
38f0: 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 .** ^If an error
3900: 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76 occurs while ev
3910: 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c aluating the SQL
3920: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 statements pass
3930: 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 ed into.** sqlit
3940: 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20 e3_exec(), then
3950: 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 execution of the
3960: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65 current stateme
3970: 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 nt stops and.**
3980: 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65 subsequent state
3990: 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65 ments are skippe
39a0: 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20 d. ^If the 5th
39b0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
39c0: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 ite3_exec().** i
39d0: 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 s not NULL then
39e0: 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 any error messag
39f0: 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 e is written int
3a00: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 o memory obtaine
3a10: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 d.** from [sqlit
3a20: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 e3_malloc()] and
3a30: 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 passed back thr
3a40: 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 ough the 5th par
3a50: 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 ameter..** To av
3a60: 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 oid memory leaks
3a70: 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f , the applicatio
3a80: 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 n should invoke
3a90: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
3aa0: 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 .** on error mes
3ab0: 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74 sage strings ret
3ac0: 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 urned through th
3ad0: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 5th parameter
3ae0: 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 of.** sqlite3_ex
3af0: 65 63 28 29 20 61 66 74 65 72 20 74 68 65 20 65 ec() after the e
3b00: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 rror message str
3b10: 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 ing is no longer
3b20: 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 needed..** ^If
3b30: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 the 5th paramete
3b40: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 r to sqlite3_exe
3b50: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 c() is not NULL
3b60: 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a and no errors.**
3b70: 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c occur, then sql
3b80: 69 74 65 33 5f 65 78 65 63 28 29 20 73 65 74 73 ite3_exec() sets
3b90: 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 the pointer in
3ba0: 69 74 73 20 35 74 68 20 70 61 72 61 6d 65 74 65 its 5th paramete
3bb0: 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 r to.** NULL bef
3bc0: 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a ore returning..*
3bd0: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 *.** ^If an sqli
3be0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 te3_exec() callb
3bf0: 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d ack returns non-
3c00: 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 zero, the sqlite
3c10: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 3_exec().** rout
3c20: 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 ine returns SQLI
3c30: 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74 TE_ABORT without
3c40: 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 invoking the ca
3c50: 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 llback again and
3c60: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e .** without runn
3c70: 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75 65 ing any subseque
3c80: 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 nt SQL statement
3c90: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e s..**.** ^The 2n
3ca0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 d argument to th
3cb0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 e sqlite3_exec()
3cc0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
3cd0: 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d on is the.** num
3ce0: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 ber of columns i
3cf0: 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e n the result. ^
3d00: 54 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 The 3rd argument
3d10: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
3d20: 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 exec().** callba
3d30: 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f ck is an array o
3d40: 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 f pointers to st
3d50: 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61 rings obtained a
3d60: 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 s if from.** [sq
3d70: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
3d80: 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 t()], one for ea
3d90: 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 ch column. ^If
3da0: 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a an element of a.
3db0: 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73 ** result row is
3dc0: 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 NULL then the c
3dd0: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 orresponding str
3de0: 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 ing pointer for
3df0: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 the.** sqlite3_e
3e00: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 xec() callback i
3e10: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
3e20: 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 . ^The 4th argu
3e30: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 ment to the.** s
3e40: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 qlite3_exec() ca
3e50: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 llback is an arr
3e60: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 ay of pointers t
3e70: 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 o strings where
3e80: 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 each.** entry re
3e90: 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d presents the nam
3ea0: 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 e of correspondi
3eb0: 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e ng result column
3ec0: 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 as obtained.**
3ed0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f from [sqlite3_co
3ee0: 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a lumn_name()]..**
3ef0: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20 .** ^If the 2nd
3f00: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
3f10: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 61 ite3_exec() is a
3f20: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 NULL pointer, a
3f30: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 pointer.** to a
3f40: 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 n empty string,
3f50: 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61 or a pointer tha
3f60: 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 t contains only
3f70: 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f whitespace and/o
3f80: 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e r .** SQL commen
3f90: 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 ts, then no SQL
3fa0: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 statements are e
3fb0: 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65 valuated and the
3fc0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 database.** is
3fd0: 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a not changed..**.
3fe0: 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a ** Restrictions:
3ff0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
4000: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 li> The applicat
4010: 69 6f 6e 20 6d 75 73 74 20 65 6e 73 75 72 65 20 ion must ensure
4020: 74 68 61 74 20 74 68 65 20 31 73 74 20 70 61 72 that the 1st par
4030: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
4040: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 3_exec().**
4050: 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20 is a valid and
4060: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 open [database c
4070: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c onnection]..** <
4080: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 li> The applicat
4090: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f ion must not clo
40a0: 73 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 se the [database
40b0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 connection] spe
40c0: 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 cified by.**
40d0: 20 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 the 1st parame
40e0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 ter to sqlite3_e
40f0: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 xec() while sqli
4100: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 te3_exec() is ru
4110: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 nning..** <li> T
4120: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d he application m
4130: 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 ust not modify t
4140: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
4150: 20 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74 text passed int
4160: 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e o.** the 2n
4170: 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 d parameter of s
4180: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 qlite3_exec() wh
4190: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 ile sqlite3_exec
41a0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a () is running..*
41b0: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 * </ul>.*/.int s
41c0: 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 qlite3_exec(. s
41d0: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 qlite3*,
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
41f0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 /* An
4200: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f open database */
4210: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 . const char *s
4220: 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 ql,
4230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
4240: 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 SQL to be evalu
4250: 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a ated */. int (*
4260: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c callback)(void*,
4270: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a int,char**,char*
4280: 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b *), /* Callback
4290: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 function */. v
42a0: 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 oid *,
42b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
42c0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 /* 1st
42d0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c argument to cal
42e0: 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 lback */. char
42f0: 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 **errmsg
4300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4310: 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d /* Error m
4320: 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 sg written here
4330: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.);../*.** CAP
4340: 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f I3REF: Result Co
4350: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a des.** KEYWORDS:
4360: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 {result code de
4370: 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a finitions}.**.**
4380: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e Many SQLite fun
4390: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e ctions return an
43a0: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 integer result
43b0: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 code from the se
43c0: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 t shown.** here
43d0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 in order to indi
43e0: 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20 cate success or
43f0: 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e failure..**.** N
4400: 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d ew error codes m
4410: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 ay be added in f
4420: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
4430: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 f SQLite..**.**
4440: 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74 65 6e See also: [exten
4450: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 ded result code
4460: 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f 0a definitions].*/.
4470: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
4480: 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 K 0
4490: 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 /* Successful re
44a0: 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e sult */./* begin
44b0: 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f ning-of-error-co
44c0: 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 des */.#define S
44d0: 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 QLITE_ERROR
44e0: 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 1 /* SQL er
44f0: 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 ror or missing d
4500: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 atabase */.#defi
4510: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e ne SQLITE_INTERN
4520: 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e AL 2 /* In
4530: 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 ternal logic err
4540: 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a or in SQLite */.
4550: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 #define SQLITE_P
4560: 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 ERM 3
4570: 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 /* Access permis
4580: 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 sion denied */.#
4590: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 define SQLITE_AB
45a0: 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f ORT 4 /
45b0: 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 * Callback routi
45c0: 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 ne requested an
45d0: 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 abort */.#define
45e0: 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 SQLITE_BUSY
45f0: 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 5 /* The
4600: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 database file is
4610: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 locked */.#defi
4620: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 ne SQLITE_LOCKED
4630: 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 6 /* A
4640: 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 table in the dat
4650: 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 abase is locked
4660: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4670: 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 E_NOMEM 7
4680: 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 /* A malloc()
4690: 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 failed */.#defi
46a0: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e ne SQLITE_READON
46b0: 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 LY 8 /* At
46c0: 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 tempt to write a
46d0: 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 readonly databa
46e0: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 se */.#define SQ
46f0: 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 LITE_INTERRUPT
4700: 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 9 /* Operati
4710: 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 on terminated by
4720: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
4730: 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 pt()*/.#define S
4740: 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 QLITE_IOERR
4750: 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 10 /* Some k
4760: 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 ind of disk I/O
4770: 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a error occurred *
4780: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4790: 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 _CORRUPT 11
47a0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 /* The databas
47b0: 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 e disk image is
47c0: 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 malformed */.#de
47d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 fine SQLITE_NOTF
47e0: 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 OUND 12 /*
47f0: 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69 Unknown opcode i
4800: 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 n sqlite3_file_c
4810: 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 ontrol() */.#def
4820: 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 ine SQLITE_FULL
4830: 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 13 /* I
4840: 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 nsertion failed
4850: 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65 because database
4860: 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 is full */.#def
4870: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f ine SQLITE_CANTO
4880: 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 PEN 14 /* U
4890: 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 nable to open th
48a0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
48b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
48c0: 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 E_PROTOCOL 15
48d0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6c /* Database l
48e0: 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 ock protocol err
48f0: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 or */.#define SQ
4900: 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 LITE_EMPTY
4910: 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 16 /* Databas
4920: 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 e is empty */.#d
4930: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 efine SQLITE_SCH
4940: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a EMA 17 /*
4950: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63 The database sc
4960: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a hema changed */.
4970: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
4980: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20 OOBIG 18
4990: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f /* String or BLO
49a0: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c B exceeds size l
49b0: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 imit */.#define
49c0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
49d0: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 T 19 /* Abort
49e0: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 due to constrai
49f0: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a nt violation */.
4a00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d #define SQLITE_M
4a10: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 ISMATCH 20
4a20: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 /* Data type mis
4a30: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 match */.#define
4a40: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 SQLITE_MISUSE
4a50: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 21 /* Libr
4a60: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 ary used incorre
4a70: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ctly */.#define
4a80: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 SQLITE_NOLFS
4a90: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 22 /* Uses
4aa0: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 OS features not
4ab0: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 supported on hos
4ac0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
4ad0: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 ITE_AUTH
4ae0: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 23 /* Authoriz
4af0: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a ation denied */.
4b00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
4b10: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 ORMAT 24
4b20: 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 /* Auxiliary dat
4b30: 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 abase format err
4b40: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 or */.#define SQ
4b50: 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 LITE_RANGE
4b60: 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 25 /* 2nd par
4b70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
4b80: 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 3_bind out of ra
4b90: 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nge */.#define S
4ba0: 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 QLITE_NOTADB
4bb0: 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 26 /* File o
4bc0: 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f pened that is no
4bd0: 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c t a database fil
4be0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
4bf0: 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20 20 20 ITE_NOTICE
4c00: 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69 63 61 27 /* Notifica
4c10: 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c 69 74 tions from sqlit
4c20: 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 e3_log() */.#def
4c30: 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 ine SQLITE_WARNI
4c40: 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a 20 57 NG 28 /* W
4c50: 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73 71 6c arnings from sql
4c60: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 ite3_log() */.#d
4c70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 efine SQLITE_ROW
4c80: 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 100 /*
4c90: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
4ca0: 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 has another row
4cb0: 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 ready */.#define
4cc0: 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 SQLITE_DONE
4cd0: 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 101 /* sqli
4ce0: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 te3_step() has f
4cf0: 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e inished executin
4d00: 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 g */./* end-of-e
4d10: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f rror-codes */../
4d20: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 *.** CAPI3REF: E
4d30: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 xtended Result C
4d40: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 odes.** KEYWORDS
4d50: 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 : {extended resu
4d60: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 lt code definiti
4d70: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 ons}.**.** In it
4d80: 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 s default config
4d90: 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 uration, SQLite
4da0: 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 API routines ret
4db0: 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20 69 6e urn one of 30 in
4dc0: 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75 6c 74 teger.** [result
4dd0: 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 codes]. Howeve
4de0: 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 r, experience ha
4df0: 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e s shown that man
4e00: 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 y of.** these re
4e10: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 sult codes are t
4e20: 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 oo coarse-graine
4e30: 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 d. They do not
4e40: 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 provide as.** mu
4e50: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 ch information a
4e60: 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 bout problems as
4e70: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 programmers mig
4e80: 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 ht like. In an
4e90: 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 effort to.** add
4ea0: 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 ress this, newer
4eb0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
4ec0: 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 ite (version 3.3
4ed0: 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33 2e 38 .8 [dateof:3.3.8
4ee0: 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72 29 20 ].** and later)
4ef0: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f include.** suppo
4f00: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 rt for additiona
4f10: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 l result codes t
4f20: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 hat provide more
4f30: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d detailed inform
4f40: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 ation.** about e
4f50: 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78 rrors. These [ex
4f60: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
4f70: 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 des] are enabled
4f80: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 or disabled.**
4f90: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73 on a per databas
4fa0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 e connection bas
4fb0: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 is using the.**
4fc0: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 [sqlite3_extende
4fd0: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 d_result_codes()
4fe0: 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20 ] API. Or, the
4ff0: 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f extended code fo
5000: 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 r.** the most re
5010: 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62 cent error can b
5020: 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67 e obtained using
5030: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 .** [sqlite3_ext
5040: 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d ended_errcode()]
5050: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
5060: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 ITE_IOERR_READ
5070: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
5080: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c ITE_IOERR | (1<<
5090: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
50a0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 TE_IOERR_SHORT_R
50b0: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 EAD (SQLI
50c0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 TE_IOERR | (2<<8
50d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
50e0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 E_IOERR_WRITE
50f0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
5100: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 E_IOERR | (3<<8)
5110: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5120: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 _IOERR_FSYNC
5130: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5140: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 _IOERR | (4<<8))
5150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5160: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 IOERR_DIR_FSYNC
5170: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5180: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a IOERR | (5<<8)).
5190: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
51a0: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 OERR_TRUNCATE
51b0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
51c0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 OERR | (6<<8)).#
51d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
51e0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 ERR_FSTAT
51f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
5200: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 ERR | (7<<8)).#d
5210: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5220: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 RR_UNLOCK
5230: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
5240: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 RR | (8<<8)).#de
5250: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
5260: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 R_RDLOCK
5270: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
5280: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 R | (9<<8)).#def
5290: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
52a0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 _DELETE
52b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
52c0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 | (10<<8)).#def
52d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
52e0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 _BLOCKED
52f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5300: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 | (11<<8)).#def
5310: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5320: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 _NOMEM
5330: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5340: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 | (12<<8)).#def
5350: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5360: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 _ACCESS
5370: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5380: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 | (13<<8)).#def
5390: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
53a0: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f _CHECKRESERVEDLO
53b0: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 CK (SQLITE_IOERR
53c0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 | (14<<8)).#def
53d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
53e0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 _LOCK
53f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5400: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 | (15<<8)).#def
5410: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5420: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 _CLOSE
5430: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5440: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 | (16<<8)).#def
5450: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5460: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 _DIR_CLOSE
5470: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5480: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 | (17<<8)).#def
5490: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
54a0: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 _SHMOPEN
54b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
54c0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 | (18<<8)).#def
54d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
54e0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 _SHMSIZE
54f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5500: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 | (19<<8)).#def
5510: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5520: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 _SHMLOCK
5530: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5540: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 | (20<<8)).#def
5550: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5560: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 _SHMMAP
5570: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5580: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 | (21<<8)).#def
5590: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
55a0: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 _SEEK
55b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
55c0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 | (22<<8)).#def
55d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
55e0: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 _DELETE_NOENT
55f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5600: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 | (23<<8)).#def
5610: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5620: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 _MMAP
5630: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5640: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 | (24<<8)).#def
5650: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5660: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 _GETTEMPPATH
5670: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5680: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 | (25<<8)).#def
5690: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
56a0: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 _CONVPATH
56b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
56c0: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 | (26<<8)).#def
56d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
56e0: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20 _VNODE
56f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5700: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66 | (27<<8)).#def
5710: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5720: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20 _AUTH
5730: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5740: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66 | (28<<8)).#def
5750: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 ine SQLITE_LOCKE
5760: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 D_SHAREDCACHE
5770: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 (SQLITE_LOCKE
5780: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 D | (1<<8)).#de
5790: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 fine SQLITE_BUSY
57a0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 _RECOVERY
57b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 (SQLITE_BUSY
57c0: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 | (1<<8)).#d
57d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 efine SQLITE_BUS
57e0: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20 Y_SNAPSHOT
57f0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 (SQLITE_BUS
5800: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 Y | (2<<8)).#
5810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 define SQLITE_CA
5820: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 NTOPEN_NOTEMPDIR
5830: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 (SQLITE_CA
5840: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 NTOPEN | (1<<8))
5850: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5860: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 CANTOPEN_ISDIR
5870: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5880: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 CANTOPEN | (2<<8
5890: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
58a0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 E_CANTOPEN_FULLP
58b0: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 ATH (SQLIT
58c0: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c E_CANTOPEN | (3<
58d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
58e0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e ITE_CANTOPEN_CON
58f0: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c VPATH (SQL
5900: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 ITE_CANTOPEN | (
5910: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 4<<8)).#define S
5920: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 QLITE_CORRUPT_VT
5930: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53 AB (S
5940: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 QLITE_CORRUPT |
5950: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (1<<8)).#define
5960: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f SQLITE_READONLY_
5970: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 RECOVERY (
5980: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 SQLITE_READONLY
5990: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (1<<8)).#defin
59a0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c e SQLITE_READONL
59b0: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 Y_CANTLOCK
59c0: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c (SQLITE_READONL
59d0: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 Y | (2<<8)).#def
59e0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f ine SQLITE_READO
59f0: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 NLY_ROLLBACK
5a00: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f (SQLITE_READO
5a10: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 NLY | (3<<8)).#d
5a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 efine SQLITE_REA
5a30: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 DONLY_DBMOVED
5a40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 (SQLITE_REA
5a50: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a DONLY | (4<<8)).
5a60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
5a70: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 BORT_ROLLBACK
5a80: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 (SQLITE_A
5a90: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 BORT | (2<<8)).#
5aa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
5ab0: 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 NSTRAINT_CHECK
5ac0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f (SQLITE_CO
5ad0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 NSTRAINT | (1<<8
5ae0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5af0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d E_CONSTRAINT_COM
5b00: 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 MITHOOK (SQLIT
5b10: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 E_CONSTRAINT | (
5b20: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 2<<8)).#define S
5b30: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
5b40: 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53 _FOREIGNKEY (S
5b50: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
5b60: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 | (3<<8)).#defi
5b70: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 ne SQLITE_CONSTR
5b80: 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 AINT_FUNCTION
5b90: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 (SQLITE_CONSTR
5ba0: 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 AINT | (4<<8)).#
5bb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
5bc0: 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c NSTRAINT_NOTNULL
5bd0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f (SQLITE_CO
5be0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 NSTRAINT | (5<<8
5bf0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5c00: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 E_CONSTRAINT_PRI
5c10: 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54 MARYKEY (SQLIT
5c20: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 E_CONSTRAINT | (
5c30: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 6<<8)).#define S
5c40: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
5c50: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53 _TRIGGER (S
5c60: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
5c70: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 | (7<<8)).#defi
5c80: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 ne SQLITE_CONSTR
5c90: 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20 AINT_UNIQUE
5ca0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 (SQLITE_CONSTR
5cb0: 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 AINT | (8<<8)).#
5cc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
5cd0: 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20 NSTRAINT_VTAB
5ce0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f (SQLITE_CO
5cf0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 NSTRAINT | (9<<8
5d00: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5d10: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 E_CONSTRAINT_ROW
5d20: 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 ID (SQLIT
5d30: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 E_CONSTRAINT |(1
5d40: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 0<<8)).#define S
5d50: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 QLITE_NOTICE_REC
5d60: 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53 OVER_WAL (S
5d70: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 QLITE_NOTICE | (
5d80: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 1<<8)).#define S
5d90: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 QLITE_NOTICE_REC
5da0: 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 OVER_ROLLBACK (S
5db0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 QLITE_NOTICE | (
5dc0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 2<<8)).#define S
5dd0: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 QLITE_WARNING_AU
5de0: 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53 TOINDEX (S
5df0: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 QLITE_WARNING |
5e00: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (1<<8)).#define
5e10: 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52 SQLITE_AUTH_USER
5e20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 (
5e30: 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31 SQLITE_AUTH | (1
5e40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5e50: 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44 5f 50 45 52 LITE_OK_LOAD_PER
5e60: 4d 41 4e 45 4e 54 4c 59 20 20 20 20 20 28 53 51 MANENTLY (SQ
5e70: 4c 49 54 45 5f 4f 4b 20 7c 20 28 31 3c 3c 38 29 LITE_OK | (1<<8)
5e80: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 )../*.** CAPI3RE
5e90: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c F: Flags For Fil
5ea0: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e e Open Operation
5eb0: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 s.**.** These bi
5ec0: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 t values are int
5ed0: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e ended for use in
5ee0: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 the.** 3rd para
5ef0: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 meter to the [sq
5f00: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d lite3_open_v2()]
5f10: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a interface and.*
5f20: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 * in the 4th par
5f30: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 ameter to the [s
5f40: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e qlite3_vfs.xOpen
5f50: 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 ] method..*/.#de
5f60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
5f70: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 _READONLY
5f80: 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 0x00000001 /*
5f90: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
5fa0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
5fb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
5fc0: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20 _READWRITE
5fd0: 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 0x00000002 /*
5fe0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
5ff0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
6000: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
6010: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20 _CREATE
6020: 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 0x00000004 /*
6030: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
6040: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
6050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
6060: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 _DELETEONCLOSE
6070: 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 0x00000008 /*
6080: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
6090: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
60a0: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 _EXCLUSIVE
60b0: 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 0x00000010 /*
60c0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
60d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
60e0: 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 _AUTOPROXY
60f0: 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 0x00000020 /*
6100: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
6110: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
6120: 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20 _URI
6130: 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a 0x00000040 /*
6140: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
6150: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
6160: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
6170: 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20 _MEMORY
6180: 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a 0x00000080 /*
6190: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
61a0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
61b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
61c0: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 _MAIN_DB
61d0: 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 0x00000100 /*
61e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
61f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
6200: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 _TEMP_DB
6210: 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 0x00000200 /*
6220: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
6230: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
6240: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 _TRANSIENT_DB
6250: 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 0x00000400 /*
6260: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
6270: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
6280: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 _MAIN_JOURNAL
6290: 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 0x00000800 /*
62a0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
62b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
62c0: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 _TEMP_JOURNAL
62d0: 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 0x00001000 /*
62e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
62f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
6300: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 _SUBJOURNAL
6310: 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 0x00002000 /*
6320: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
6330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
6340: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 _MASTER_JOURNAL
6350: 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 0x00004000 /*
6360: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 VFS only */.#de
6370: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
6380: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 _NOMUTEX
6390: 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 0x00008000 /*
63a0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
63b0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
63c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
63d0: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 _FULLMUTEX
63e0: 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 0x00010000 /*
63f0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
6400: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
6410: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
6420: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20 _SHAREDCACHE
6430: 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 0x00020000 /*
6440: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
6450: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
6460: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
6470: 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20 _PRIVATECACHE
6480: 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 0x00040000 /*
6490: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f Ok for sqlite3_
64a0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 open_v2() */.#de
64b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e fine SQLITE_OPEN
64c0: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 _WAL
64d0: 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a 0x00080000 /*
64e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a VFS only */../*
64f0: 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20 Reserved:
6500: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6510: 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0x00F00000 */
6520: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
6530: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74 : Device Charact
6540: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 eristics.**.** T
6550: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 he xDeviceCharac
6560: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 teristics method
6570: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
6580: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 _io_methods].**
6590: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 object returns a
65a0: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 n integer which
65b0: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 is a vector of t
65c0: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 hese.** bit valu
65d0: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f es expressing I/
65e0: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63 O characteristic
65f0: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 s of the mass st
6600: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 orage.** device
6610: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 that holds the f
6620: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 ile that the [sq
6630: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
6640: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a ].** refers to..
6650: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 **.** The SQLITE
6660: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 _IOCAP_ATOMIC pr
6670: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 operty means tha
6680: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a t all writes of.
6690: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 ** any size are
66a0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c atomic. The SQL
66b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
66c0: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 nnn values.** me
66d0: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f an that writes o
66e0: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 f blocks that ar
66f0: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 e nnn bytes in s
6700: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 ize and.** are a
6710: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 ligned to an add
6720: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e ress which is an
6730: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c integer multipl
6740: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 e of.** nnn are
6750: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c atomic. The SQL
6760: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 ITE_IOCAP_SAFE_A
6770: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e PPEND value mean
6780: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 s.** that when d
6790: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 ata is appended
67a0: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 to a file, the d
67b0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a ata is appended.
67c0: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 ** first then th
67d0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 e size of the fi
67e0: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 le is extended,
67f0: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a never the other.
6800: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 ** way around.
6810: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
6820: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 _SEQUENTIAL prop
6830: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a erty means that.
6840: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 ** information i
6850: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 s written to dis
6860: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 k in the same or
6870: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 der as calls.**
6880: 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 68 to xWrite(). Th
6890: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 e SQLITE_IOCAP_P
68a0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 OWERSAFE_OVERWRI
68b0: 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e TE property mean
68c0: 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 s that.** after
68d0: 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 reboot following
68e0: 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65 a crash or powe
68f0: 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 r loss, the only
6900: 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 bytes in a.** f
6910: 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 72 ile that were wr
6920: 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 70 itten at the app
6930: 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d lication level m
6940: 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 65 ight have change
6950: 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64 d.** and that ad
6960: 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76 jacent bytes, ev
6970: 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e 20 en bytes within
6980: 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20 the same sector
6990: 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 are.** guarantee
69a0: 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 d to be unchange
69b0: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 d. The SQLITE_I
69c0: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 OCAP_UNDELETABLE
69d0: 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c _WHEN_OPEN.** fl
69e0: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 ag indicates tha
69f0: 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 t a file cannot
6a00: 62 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 be deleted when
6a10: 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51 open. The.** SQ
6a20: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 LITE_IOCAP_IMMUT
6a30: 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69 63 61 ABLE flag indica
6a40: 74 65 73 20 74 68 61 74 20 74 68 65 20 66 69 6c tes that the fil
6a50: 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d e is on.** read-
6a60: 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64 20 63 only media and c
6a70: 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 annot be changed
6a80: 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65 73 73 even by process
6a90: 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61 es with.** eleva
6aa0: 74 65 64 20 70 72 69 76 69 6c 65 67 65 73 2e 0a ted privileges..
6ab0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
6ac0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 E_IOCAP_ATOMIC
6ad0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
6ae0: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e x00000001.#defin
6af0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
6b00: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20 TOMIC512
6b10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0x00000002
6b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6b30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 IOCAP_ATOMIC1K
6b40: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
6b50: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 0000004.#define
6b60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
6b70: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20 MIC2K
6b80: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 0x00000008.#
6b90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
6ba0: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 CAP_ATOMIC4K
6bb0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
6bc0: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 00010.#define SQ
6bd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
6be0: 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 C8K
6bf0: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 0x00000020.#de
6c00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
6c10: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 P_ATOMIC16K
6c20: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
6c30: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 040.#define SQLI
6c40: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 TE_IOCAP_ATOMIC3
6c50: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2K
6c60: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 0x00000080.#defi
6c70: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
6c80: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 ATOMIC64K
6c90: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 0x0000010
6ca0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
6cb0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 _IOCAP_SAFE_APPE
6cc0: 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78 ND 0x
6cd0: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 00000200.#define
6ce0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 SQLITE_IOCAP_SE
6cf0: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20 QUENTIAL
6d00: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 0x00000400.
6d10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
6d20: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 OCAP_UNDELETABLE
6d30: 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 _WHEN_OPEN 0x00
6d40: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 000800.#define S
6d50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 QLITE_IOCAP_POWE
6d60: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 RSAFE_OVERWRITE
6d70: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64 0x00001000.#d
6d80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
6d90: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 AP_IMMUTABLE
6da0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
6db0: 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 2000../*.** CAPI
6dc0: 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 3REF: File Locki
6dd0: 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 ng Levels.**.**
6de0: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 SQLite uses one
6df0: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 of these integer
6e00: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 values as the s
6e10: 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e econd.** argumen
6e20: 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 t to calls it ma
6e30: 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b kes to the xLock
6e40: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 () and xUnlock()
6e50: 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 methods.** of a
6e60: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 n [sqlite3_io_me
6e70: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a thods] object..*
6e80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6e90: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 _LOCK_NONE
6ea0: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 0.#define SQ
6eb0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 LITE_LOCK_SHARED
6ec0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 1.#defin
6ed0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 e SQLITE_LOCK_RE
6ee0: 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 SERVED 2.#d
6ef0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 efine SQLITE_LOC
6f00: 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 K_PENDING
6f10: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 3.#define SQLITE
6f20: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 _LOCK_EXCLUSIVE
6f30: 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 4../*.** CAP
6f40: 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 I3REF: Synchroni
6f50: 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 zation Type Flag
6f60: 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c s.**.** When SQL
6f70: 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 ite invokes the
6f80: 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f xSync() method o
6f90: 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 f an.** [sqlite3
6fa0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a _io_methods] obj
6fb0: 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f ect it uses a co
6fc0: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 mbination of.**
6fd0: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 these integer va
6fe0: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f lues as the seco
6ff0: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a nd argument..**.
7000: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 ** When the SQLI
7010: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 TE_SYNC_DATAONLY
7020: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 flag is used, i
7030: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 t means that the
7040: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 .** sync operati
7050: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f on only needs to
7060: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d flush data to m
7070: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e ass storage. In
7080: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 ode.** informati
7090: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 on need not be f
70a0: 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c lushed. If the l
70b0: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f ower four bits o
70c0: 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 f the flag.** eq
70d0: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f ual SQLITE_SYNC_
70e0: 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 NORMAL, that mea
70f0: 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c ns to use normal
7100: 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 fsync() semanti
7110: 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f cs..** If the lo
7120: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 wer four bits eq
7130: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f ual SQLITE_SYNC_
7140: 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 FULL, that means
7150: 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f .** to use Mac O
7160: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 S X style fullsy
7170: 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 nc instead of fs
7180: 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 ync()..**.** Do
7190: 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 not confuse the
71a0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d SQLITE_SYNC_NORM
71b0: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 AL and SQLITE_SY
71c0: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a NC_FULL flags.**
71d0: 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d with the [PRAGM
71e0: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e A synchronous]=N
71f0: 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d ORMAL and [PRAGM
7200: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 A synchronous]=F
7210: 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e ULL.** settings.
7220: 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f The [synchrono
7230: 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 us pragma] deter
7240: 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 mines when calls
7250: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 to the.** xSync
7260: 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 VFS method occu
7270: 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e r and applies un
7280: 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 iformly across a
7290: 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a ll platforms..**
72a0: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 The SQLITE_SYNC
72b0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 _NORMAL and SQLI
72c0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 TE_SYNC_FULL fla
72d0: 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 gs determine how
72e0: 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 .** energetic or
72f0: 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 rigorous or for
7300: 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f ceful the sync o
7310: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e perations are an
7320: 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 d.** only make a
7330: 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d difference on M
7340: 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 ac OSX for the d
7350: 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f efault SQLite co
7360: 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 de..** (Third-pa
7370: 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e rty VFS implemen
7380: 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c tations might al
7390: 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 so make the dist
73a0: 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 inction.** betwe
73b0: 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e en SQLITE_SYNC_N
73c0: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 ORMAL and SQLITE
73d0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 _SYNC_FULL, but
73e0: 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 among the.** ope
73f0: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e rating systems n
7400: 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 atively supporte
7410: 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c d by SQLite, onl
7420: 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 y Mac OSX.** car
7430: 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 es about the dif
7440: 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 ference.).*/.#de
7450: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 fine SQLITE_SYNC
7460: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 _NORMAL 0
7470: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 x00002.#define S
7480: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 QLITE_SYNC_FULL
7490: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0x00003
74a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
74b0: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 SYNC_DATAONLY
74c0: 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 0x00010../*.*
74d0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 * CAPI3REF: OS I
74e0: 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 nterface Open Fi
74f0: 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 le Handle.**.**
7500: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 An [sqlite3_file
7510: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 ] object represe
7520: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 nts an open file
7530: 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c in the .** [sql
7540: 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e ite3_vfs | OS in
7550: 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 terface layer].
7560: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 Individual OS i
7570: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c nterface.** impl
7580: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c ementations will
7590: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 .** want to subc
75a0: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 lass this object
75b0: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 by appending ad
75c0: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a ditional fields.
75d0: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e ** for their own
75e0: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 use. The pMeth
75f0: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 ods entry is a p
7600: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 ointer to an.**
7610: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
7620: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 ods] object that
7630: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 defines methods
7640: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a for performing.
7650: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e ** I/O operation
7660: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 s on the open fi
7670: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 le..*/.typedef s
7680: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 truct sqlite3_fi
7690: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b le sqlite3_file;
76a0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
76b0: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 file {. const s
76c0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f truct sqlite3_io
76d0: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f _methods *pMetho
76e0: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 ds; /* Methods
76f0: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 for an open file
7700: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.};../*.** CA
7710: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 PI3REF: OS Inter
7720: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 face File Virtua
7730: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 l Methods Object
7740: 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c .**.** Every fil
7750: 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 e opened by the
7760: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 [sqlite3_vfs.xOp
7770: 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c en] method popul
7780: 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 ates an.** [sqli
7790: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 te3_file] object
77a0: 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f (or, more commo
77b0: 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 nly, a subclass
77c0: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 of the.** [sqlit
77d0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 e3_file] object)
77e0: 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 with a pointer
77f0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f to an instance o
7800: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a f this object..*
7810: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 * This object de
7820: 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 fines the method
7830: 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 s used to perfor
7840: 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 m various operat
7850: 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 ions.** against
7860: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 the open file re
7870: 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 presented by the
7880: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
7890: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 object..**.** If
78a0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 the [sqlite3_vf
78b0: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 s.xOpen] method
78c0: 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 sets the sqlite3
78d0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 _file.pMethods e
78e0: 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 lement .** to a
78f0: 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 non-NULL pointer
7900: 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 , then the sqlit
7910: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 e3_io_methods.xC
7920: 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d lose method.** m
7930: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 ay be invoked ev
7940: 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 en if the [sqlit
7950: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 e3_vfs.xOpen] re
7960: 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66 ported that it f
7970: 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f ailed. The.** o
7980: 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 nly way to preve
7990: 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c nt a call to xCl
79a0: 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 ose following a
79b0: 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f failed [sqlite3_
79c0: 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 vfs.xOpen].** is
79d0: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 for the [sqlite
79e0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 3_vfs.xOpen] to
79f0: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f set the sqlite3_
7a00: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c file.pMethods el
7a10: 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c ement.** to NULL
7a20: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 ..**.** The flag
7a30: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 s argument to xS
7a40: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f ync may be one o
7a50: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e f [SQLITE_SYNC_N
7a60: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 ORMAL] or.** [SQ
7a70: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e LITE_SYNC_FULL].
7a80: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 The first choi
7a90: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c ce is the normal
7aa0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 fsync()..** The
7ab0: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 second choice i
7ac0: 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 s a Mac OS X sty
7ad0: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 le fullsync. Th
7ae0: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 e [SQLITE_SYNC_D
7af0: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 ATAONLY].** flag
7b00: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 may be ORed in
7b10: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 to indicate that
7b20: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f only the data o
7b30: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e f the file.** an
7b40: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 d not its inode
7b50: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 needs to be sync
7b60: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e ed..**.** The in
7b70: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 teger values to
7b80: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c xLock() and xUnl
7b90: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 ock() are one of
7ba0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
7bb0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f [SQLITE_LOCK_NO
7bc0: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 NE],.** <li> [SQ
7bd0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 LITE_LOCK_SHARED
7be0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 ],.** <li> [SQLI
7bf0: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 TE_LOCK_RESERVED
7c00: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 ],.** <li> [SQLI
7c10: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d TE_LOCK_PENDING]
7c20: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 , or.** <li> [SQ
7c30: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 LITE_LOCK_EXCLUS
7c40: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a IVE]..** </ul>.*
7c50: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 * xLock() increa
7c60: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 ses the lock. xU
7c70: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 nlock() decrease
7c80: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 s the lock..** T
7c90: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 he xCheckReserve
7ca0: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 dLock() method c
7cb0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e hecks whether an
7cc0: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 y database conne
7cd0: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 ction,.** either
7ce0: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 in this process
7cf0: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 or in some othe
7d00: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f r process, is ho
7d10: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 lding a RESERVED
7d20: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 ,.** PENDING, or
7d30: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 EXCLUSIVE lock
7d40: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 on the file. It
7d50: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a returns true.**
7d60: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 if such a lock
7d70: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 exists and false
7d80: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a otherwise..**.*
7d90: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 * The xFileContr
7da0: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 ol() method is a
7db0: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 generic interfa
7dc0: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 ce that allows c
7dd0: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 ustom.** VFS imp
7de0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 lementations to
7df0: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c directly control
7e00: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 an open file us
7e10: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 ing the.** [sqli
7e20: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
7e30: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 ()] interface.
7e40: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 The second "op"
7e50: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a argument is an.*
7e60: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 * integer opcode
7e70: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 . The third arg
7e80: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 ument is a gener
7e90: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e ic pointer inten
7ea0: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 ded to.** point
7eb0: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 to a structure t
7ec0: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 hat may contain
7ed0: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 arguments or spa
7ee0: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a ce in which to.*
7ef0: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 * write return v
7f00: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 alues. Potentia
7f10: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 l uses for xFile
7f20: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 Control() might
7f30: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 be.** functions
7f40: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 to enable blocki
7f50: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 ng locks with ti
7f60: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 meouts, to chang
7f70: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 e the.** locking
7f80: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 strategy (for e
7f90: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f xample to use do
7fa0: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 t-file locks), t
7fb0: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f o inquire.** abo
7fc0: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 ut the status of
7fd0: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 a lock, or to b
7fe0: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 reak stale locks
7ff0: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a . The SQLite.**
8000: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 core reserves a
8010: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 ll opcodes less
8020: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 than 100 for its
8030: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b own use..** A [
8040: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 file control opc
8050: 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f odes | list of o
8060: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 pcodes] less tha
8070: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 n 100 is availab
8080: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 le..** Applicati
8090: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 ons that define
80a0: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f a custom xFileCo
80b0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f ntrol method sho
80c0: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a uld use opcodes.
80d0: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 ** greater than
80e0: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 100 to avoid con
80f0: 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 flicts. VFS imp
8100: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f lementations sho
8110: 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 uld.** return [S
8120: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 QLITE_NOTFOUND]
8130: 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c for file control
8140: 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 opcodes that th
8150: 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 ey do not.** rec
8160: 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 ognize..**.** Th
8170: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 e xSectorSize()
8180: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 method returns t
8190: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f he sector size o
81a0: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 f the.** device
81b0: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 that underlies t
81c0: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 he file. The se
81d0: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 ctor size is the
81e0: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 .** minimum writ
81f0: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 e that can be pe
8200: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 rformed without
8210: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 disturbing.** ot
8220: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 her bytes in the
8230: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 file. The xDev
8240: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 iceCharacteristi
8250: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 cs().** method r
8260: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 eturns a bit vec
8270: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 tor describing b
8280: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a ehaviors of the.
8290: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 ** underlying de
82a0: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e vice:.**.** <ul>
82b0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
82c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a _IOCAP_ATOMIC].*
82d0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
82e0: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a OCAP_ATOMIC512].
82f0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
8300: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a IOCAP_ATOMIC1K].
8310: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
8320: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a IOCAP_ATOMIC2K].
8330: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
8340: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a IOCAP_ATOMIC4K].
8350: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
8360: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a IOCAP_ATOMIC8K].
8370: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
8380: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d IOCAP_ATOMIC16K]
8390: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
83a0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b _IOCAP_ATOMIC32K
83b0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
83c0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 E_IOCAP_ATOMIC64
83d0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
83e0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 TE_IOCAP_SAFE_AP
83f0: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 PEND].** <li> [S
8400: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 QLITE_IOCAP_SEQU
8410: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 ENTIAL].** <li>
8420: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e [SQLITE_IOCAP_UN
8430: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f DELETABLE_WHEN_O
8440: 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 PEN].** <li> [SQ
8450: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 LITE_IOCAP_POWER
8460: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 0a SAFE_OVERWRITE].
8470: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
8480: 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d IOCAP_IMMUTABLE]
8490: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
84a0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
84b0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 _ATOMIC property
84c0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 means that all
84d0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 writes of.** any
84e0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 size are atomic
84f0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
8500: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 CAP_ATOMICnnn va
8510: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 lues.** mean tha
8520: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 t writes of bloc
8530: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 ks that are nnn
8540: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e bytes in size an
8550: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 d.** are aligned
8560: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 to an address w
8570: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 hich is an integ
8580: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a er multiple of.*
8590: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 * nnn are atomic
85a0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
85b0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 CAP_SAFE_APPEND
85c0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 value means.** t
85d0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 hat when data is
85e0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 appended to a f
85f0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 ile, the data is
8600: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 appended.** fir
8610: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 st then the size
8620: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 of the file is
8630: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 extended, never
8640: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 the other.** way
8650: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 around. The SQ
8660: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 LITE_IOCAP_SEQUE
8670: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d NTIAL property m
8680: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 eans that.** inf
8690: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 ormation is writ
86a0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 ten to disk in t
86b0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 he same order as
86c0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 calls.** to xWr
86d0: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 ite()..**.** If
86e0: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 xRead() returns
86f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f SQLITE_IOERR_SHO
8700: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 RT_READ it must
8710: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 also fill.** in
8720: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 the unread porti
8730: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 ons of the buffe
8740: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 r with zeros. A
8750: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 VFS that.** fai
8760: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 ls to zero-fill
8770: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 short reads migh
8780: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 t seem to work.
8790: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 However,.** fai
87a0: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c lure to zero-fil
87b0: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 l short reads wi
87c0: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 ll eventually le
87d0: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 ad to.** databas
87e0: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f e corruption..*/
87f0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
8800: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
8810: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 ds sqlite3_io_me
8820: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 thods;.struct sq
8830: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
8840: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f {. int iVersio
8850: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 n;. int (*xClos
8860: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a e)(sqlite3_file*
8870: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 );. int (*xRead
8880: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
8890: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 void*, int iAmt
88a0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
88b0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a iOfst);. int (*
88c0: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f xWrite)(sqlite3_
88d0: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 file*, const voi
88e0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 d*, int iAmt, sq
88f0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 lite3_int64 iOfs
8900: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 t);. int (*xTru
8910: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 ncate)(sqlite3_f
8920: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e ile*, sqlite3_in
8930: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 t64 size);. int
8940: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 (*xSync)(sqlite
8950: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 3_file*, int fla
8960: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 gs);. int (*xFi
8970: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f leSize)(sqlite3_
8980: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 file*, sqlite3_i
8990: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 nt64 *pSize);.
89a0: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c int (*xLock)(sql
89b0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 ite3_file*, int)
89c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 ;. int (*xUnloc
89d0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a k)(sqlite3_file*
89e0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a , int);. int (*
89f0: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f xCheckReservedLo
8a00: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ck)(sqlite3_file
8a10: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 *, int *pResOut)
8a20: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 ;. int (*xFileC
8a30: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f ontrol)(sqlite3_
8a40: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 file*, int op, v
8a50: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e oid *pArg);. in
8a60: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 t (*xSectorSize)
8a70: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b (sqlite3_file*);
8a80: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 . int (*xDevice
8a90: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29 Characteristics)
8aa0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b (sqlite3_file*);
8ab0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 . /* Methods ab
8ac0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f ove are valid fo
8ad0: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 r version 1 */.
8ae0: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 int (*xShmMap)(
8af0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
8b00: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a nt iPg, int pgsz
8b10: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 , int, void vola
8b20: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 tile**);. int (
8b30: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 *xShmLock)(sqlit
8b40: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 e3_file*, int of
8b50: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 fset, int n, int
8b60: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 flags);. void
8b70: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 (*xShmBarrier)(s
8b80: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 qlite3_file*);.
8b90: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 int (*xShmUnmap
8ba0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
8bb0: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 int deleteFlag)
8bc0: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 ;. /* Methods a
8bd0: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 bove are valid f
8be0: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a or version 2 */.
8bf0: 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28 int (*xFetch)(
8c00: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 sqlite3_file*, s
8c10: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 qlite3_int64 iOf
8c20: 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f st, int iAmt, vo
8c30: 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 id **pp);. int
8c40: 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69 (*xUnfetch)(sqli
8c50: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 te3_file*, sqlit
8c60: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 e3_int64 iOfst,
8c70: 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d void *p);. /* M
8c80: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 ethods above are
8c90: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 valid for versi
8ca0: 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 on 3 */. /* Add
8cb0: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 itional methods
8cc0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 may be added in
8cd0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
8ce0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.};../*.** CAP
8cf0: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 I3REF: Standard
8d00: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 File Control Opc
8d10: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 odes.** KEYWORDS
8d20: 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 : {file control
8d30: 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63 opcodes} {file c
8d40: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a ontrol opcode}.*
8d50: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 *.** These integ
8d60: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 er constants are
8d70: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 opcodes for the
8d80: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 xFileControl me
8d90: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b thod.** of the [
8da0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
8db0: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 ds] object and f
8dc0: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f or the [sqlite3_
8dd0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a file_control()].
8de0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a ** interface..**
8df0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
8e00: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c [[SQLITE_FCNTL_L
8e10: 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68 OCKSTATE]].** Th
8e20: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
8e30: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 LOCKSTATE] opcod
8e40: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 e is used for de
8e50: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a bugging. This.*
8e60: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 * opcode causes
8e70: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c the xFileControl
8e80: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 method to write
8e90: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 the current sta
8ea0: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 te of.** the loc
8eb0: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 k (one of [SQLIT
8ec0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 E_LOCK_NONE], [S
8ed0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 QLITE_LOCK_SHARE
8ee0: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c D],.** [SQLITE_L
8ef0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b OCK_RESERVED], [
8f00: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 SQLITE_LOCK_PEND
8f10: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 ING], or [SQLITE
8f20: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d _LOCK_EXCLUSIVE]
8f30: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 ).** into an int
8f40: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 eger that the pA
8f50: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e rg argument poin
8f60: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 ts to. This capa
8f70: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 bility.** is use
8f80: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 d during testing
8f90: 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61 and is only ava
8fa0: 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20 ilable when the
8fb0: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63 SQLITE_TEST.** c
8fc0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
8fd0: 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a on is used..**.*
8fe0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
8ff0: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d CNTL_SIZE_HINT]]
9000: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
9010: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d FCNTL_SIZE_HINT]
9020: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 opcode is used
9030: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 by SQLite to giv
9040: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 e the VFS.** lay
9050: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 er a hint of how
9060: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62 large the datab
9070: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 ase file will gr
9080: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 ow to be during
9090: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 the.** current t
90a0: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 ransaction. Thi
90b0: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 s hint is not gu
90c0: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 aranteed to be a
90d0: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a ccurate but it.*
90e0: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 * is often close
90f0: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e . The underlyin
9100: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f g VFS might choo
9110: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 se to preallocat
9120: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 e database.** fi
9130: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f le space based o
9140: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f n this hint in o
9150: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 rder to help wri
9160: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 tes to the datab
9170: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 ase.** file run
9180: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c faster..**.** <l
9190: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
91a0: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a _CHUNK_SIZE]].**
91b0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
91c0: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f TL_CHUNK_SIZE] o
91d0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f pcode is used to
91e0: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68 request that th
91f0: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 e VFS.** extends
9200: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 and truncates t
9210: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
9220: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 in chunks of a
9230: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a size specified.*
9240: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 * by the user. T
9250: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 he fourth argume
9260: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 nt to [sqlite3_f
9270: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 ile_control()] s
9280: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 hould .** point
9290: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 to an integer (t
92a0: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e ype int) contain
92b0: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e ing the new chun
92c0: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a k-size to use.**
92d0: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 for the nominat
92e0: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c ed database. All
92f0: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 ocating database
9300: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c file space in l
9310: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 arge.** chunks (
9320: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d say 1MB at a tim
9330: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 e), may reduce f
9340: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d ile-system fragm
9350: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 entation and.**
9360: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 improve performa
9370: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 nce on some syst
9380: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b ems..**.** <li>[
9390: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 [SQLITE_FCNTL_FI
93a0: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 LE_POINTER]].**
93b0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
93c0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 L_FILE_POINTER]
93d0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 opcode is used t
93e0: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 o obtain a point
93f0: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 er.** to the [sq
9400: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 lite3_file] obje
9410: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ct associated wi
9420: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 th a particular
9430: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
9440: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 ection. See als
9450: 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f o [SQLITE_FCNTL_
9460: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d JOURNAL_POINTER]
9470: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
9480: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e LITE_FCNTL_JOURN
9490: 41 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 AL_POINTER]].**
94a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
94b0: 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 L_JOURNAL_POINTE
94c0: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 R] opcode is use
94d0: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f d to obtain a po
94e0: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 inter.** to the
94f0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f [sqlite3_file] o
9500: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 bject associated
9510: 20 77 69 74 68 20 74 68 65 20 6a 6f 75 72 6e 61 with the journa
9520: 6c 20 66 69 6c 65 20 28 65 69 74 68 65 72 0a 2a l file (either.*
9530: 2a 20 74 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20 * the [rollback
9540: 6a 6f 75 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20 journal] or the
9550: 5b 77 72 69 74 65 2d 61 68 65 61 64 20 6c 6f 67 [write-ahead log
9560: 5d 29 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 ]) for a particu
9570: 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 lar database.**
9580: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 connection. See
9590: 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 also [SQLITE_FC
95a0: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 NTL_FILE_POINTER
95b0: 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 ]..**.** <li>[[S
95c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 QLITE_FCNTL_SYNC
95d0: 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f _OMITTED]].** No
95e0: 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a longer in use..
95f0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
9600: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a TE_FCNTL_SYNC]].
9610: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
9620: 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 CNTL_SYNC] opcod
9630: 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 e is generated i
9640: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c nternally by SQL
9650: 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 ite and.** sent
9660: 74 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64 to the VFS immed
9670: 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68 iately before th
9680: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 e xSync method i
9690: 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a s invoked on a.*
96a0: 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 * database file
96b0: 64 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 descriptor. Or,
96c0: 69 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 if the xSync met
96d0: 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b hod is not invok
96e0: 65 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 ed .** because t
96f0: 68 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66 he user has conf
9700: 69 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69 igured SQLite wi
9710: 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 th .** [PRAGMA s
9720: 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 ynchronous | PRA
9730: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d GMA synchronous=
9740: 4f 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b OFF] it is invok
9750: 65 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 ed in place .**
9760: 6f 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 of the xSync met
9770: 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 hod. In most cas
9780: 65 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20 es, the pointer
9790: 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 argument passed
97a0: 77 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c with.** this fil
97b0: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c e-control is NUL
97c0: 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74 L. However, if t
97d0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
97e0: 20 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64 is being synced
97f0: 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61 .** as part of a
9800: 20 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20 multi-database
9810: 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75 commit, the argu
9820: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 ment points to a
9830: 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a nul-terminated.
9840: 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 ** string contai
9850: 6e 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63 ning the transac
9860: 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 tions master-jou
9870: 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 rnal file name.
9880: 56 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 VFSes that .** d
9890: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 o not need this
98a0: 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 signal should si
98b0: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 lently ignore th
98c0: 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 is opcode. Appli
98d0: 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 cations .** shou
98e0: 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c ld not call [sql
98f0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
9900: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f l()] with this o
9910: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 pcode as doing s
9920: 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 o may .** disrup
9930: 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 t the operation
9940: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a of the specializ
9950: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f ed VFSes that do
9960: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a require it. .*
9970: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
9980: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 E_FCNTL_COMMIT_P
9990: 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 HASETWO]].** The
99a0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 [SQLITE_FCNTL_C
99b0: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 OMMIT_PHASETWO]
99c0: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 opcode is genera
99d0: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 ted internally b
99e0: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 y SQLite.** and
99f0: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 sent to the VFS
9a00: 61 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74 after a transact
9a10: 69 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d ion has been com
9a20: 6d 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65 mitted immediate
9a30: 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 ly.** but before
9a40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 the database is
9a50: 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 unlocked. VFSes
9a60: 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 that do not nee
9a70: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a d this signal.**
9a80: 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 should silently
9a90: 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 ignore this opc
9aa0: 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e ode. Application
9ab0: 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c s should not cal
9ac0: 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 l.** [sqlite3_fi
9ad0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 le_control()] wi
9ae0: 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 th this opcode a
9af0: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 s doing so may d
9b00: 69 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f isrupt the .** o
9b10: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 peration of the
9b20: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 specialized VFSe
9b30: 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 s that do requir
9b40: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c e it. .**.** <l
9b50: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
9b60: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d _WIN32_AV_RETRY]
9b70: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 ].** ^The [SQLIT
9b80: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 E_FCNTL_WIN32_AV
9b90: 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 _RETRY] opcode i
9ba0: 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 s used to config
9bb0: 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a ure automatic.**
9bc0: 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e retry counts an
9bd0: 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 d intervals for
9be0: 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f certain disk I/O
9bf0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 operations for
9c00: 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b the.** windows [
9c10: 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f VFS] in order to
9c20: 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e provide robustn
9c30: 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 ess in the prese
9c40: 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 nce of.** anti-v
9c50: 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 irus programs.
9c60: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 By default, the
9c70: 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c windows VFS will
9c80: 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 retry file read
9c90: 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c ,.** file write,
9ca0: 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 and file delete
9cb0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 operations up t
9cc0: 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 o 10 times, with
9cd0: 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 a delay.** of 2
9ce0: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 5 milliseconds b
9cf0: 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 efore the first
9d00: 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 retry and with t
9d10: 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 he delay increas
9d20: 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 ing.** by an add
9d30: 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 itional 25 milli
9d40: 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 seconds with eac
9d50: 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 h subsequent ret
9d60: 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 ry. This.** opc
9d70: 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 ode allows these
9d80: 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 two values (10
9d90: 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d retries and 25 m
9da0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 illiseconds of d
9db0: 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 elay).** to be a
9dc0: 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 djusted. The va
9dd0: 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 lues are changed
9de0: 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 for all databas
9df0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a e connections.**
9e00: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 within the same
9e10: 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 process. The a
9e20: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 rgument is a poi
9e30: 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 nter to an array
9e40: 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 of two.** integ
9e50: 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69 ers where the fi
9e60: 72 73 74 20 69 6e 74 65 67 65 72 20 69 73 20 74 rst integer is t
9e70: 68 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 he new retry cou
9e80: 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e nt and the secon
9e90: 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 d.** integer is
9ea0: 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 the delay. If e
9eb0: 69 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 ither integer is
9ec0: 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 negative, then
9ed0: 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 the setting.** i
9ee0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 s not changed bu
9ef0: 74 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 t instead the pr
9f00: 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 ior value of tha
9f10: 74 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 t setting is wri
9f20: 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 tten.** into the
9f30: 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c array entry, al
9f40: 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 lowing the curre
9f50: 6e 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 nt retry setting
9f60: 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 s to be.** inter
9f70: 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 rogated. The zD
9f80: 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 bName parameter
9f90: 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a is ignored..**.*
9fa0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
9fb0: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c CNTL_PERSIST_WAL
9fc0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 ]].** ^The [SQLI
9fd0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 TE_FCNTL_PERSIST
9fe0: 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 _WAL] opcode is
9ff0: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 used to set or q
a000: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 uery the.** pers
a010: 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 istent [WAL | Wr
a020: 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 ite Ahead Log] s
a030: 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 etting. By defa
a040: 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 ult, the auxilia
a050: 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 ry.** write ahea
a060: 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 d log and shared
a070: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 memory files us
a080: 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 ed for transacti
a090: 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 on control.** ar
a0a0: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 e automatically
a0b0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 deleted when the
a0c0: 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 latest connecti
a0d0: 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 on to the databa
a0e0: 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 se.** closes. S
a0f0: 65 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e etting persisten
a100: 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 t WAL mode cause
a110: 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f s those files to
a120: 20 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a persist after.*
a130: 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 * close. Persis
a140: 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 ting the files i
a150: 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 s useful when ot
a160: 68 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 her processes th
a170: 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 at do not.** hav
a180: 65 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 e write permissi
a190: 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 on on the direct
a1a0: 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 ory containing t
a1b0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
a1c0: 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 want.** to read
a1d0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
a1e0: 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 le, as the WAL a
a1f0: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 nd shared memory
a200: 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 files must exis
a210: 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f t.** in order fo
a220: 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 r the database t
a230: 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 o be readable.
a240: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d The fourth param
a250: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 eter to.** [sqli
a260: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
a270: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 ()] for this opc
a280: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 ode should be a
a290: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
a2a0: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 teger..** That i
a2b0: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 nteger is 0 to d
a2c0: 69 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e isable persisten
a2d0: 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 t WAL mode or 1
a2e0: 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 to enable persis
a2f0: 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 tent.** WAL mode
a300: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 . If the intege
a310: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 r is -1, then it
a320: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 is overwritten
a330: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 with the current
a340: 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 .** WAL persiste
a350: 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a nce setting..**.
a360: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
a370: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f FCNTL_POWERSAFE_
a380: 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e OVERWRITE]].** ^
a390: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
a3a0: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 L_POWERSAFE_OVER
a3b0: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 WRITE] opcode is
a3c0: 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 used to set or
a3d0: 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 query the.** per
a3e0: 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 sistent "powersa
a3f0: 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 fe-overwrite" or
a400: 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e "PSOW" setting.
a410: 20 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 The PSOW setti
a420: 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 ng.** determines
a430: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 the [SQLITE_IOC
a440: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 AP_POWERSAFE_OVE
a450: 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 RWRITE] bit of t
a460: 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 he.** xDeviceCha
a470: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 racteristics met
a480: 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 hods. The fourth
a490: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
a4a0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 [sqlite3_file_c
a4b0: 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 ontrol()] for th
a4c0: 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 is opcode should
a4d0: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f be a pointer to
a4e0: 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 an integer..**
a4f0: 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 That integer is
a500: 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 0 to disable zer
a510: 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 o-damage mode or
a520: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 1 to enable zer
a530: 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 o-damage.** mode
a540: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 . If the intege
a550: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 r is -1, then it
a560: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 is overwritten
a570: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 with the current
a580: 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 .** zero-damage
a590: 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a mode setting..**
a5a0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
a5b0: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 _FCNTL_OVERWRITE
a5c0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 ]].** ^The [SQLI
a5d0: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 TE_FCNTL_OVERWRI
a5e0: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e TE] opcode is in
a5f0: 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 voked by SQLite
a600: 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a after opening.**
a610: 20 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 a write transac
a620: 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 tion to indicate
a630: 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 that, unless it
a640: 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 is rolled back
a650: 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 for some.** reas
a660: 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 on, the entire d
a670: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c atabase file wil
a680: 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e l be overwritten
a690: 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 by the current
a6a0: 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e .** transaction.
a6b0: 20 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79 This is used by
a6c0: 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f VACUUM operatio
a6d0: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b ns..**.** <li>[[
a6e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 SQLITE_FCNTL_VFS
a6f0: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b NAME]].** ^The [
a700: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 SQLITE_FCNTL_VFS
a710: 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e NAME] opcode can
a720: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 be used to obta
a730: 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a in the names of.
a740: 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 ** all [VFSes] i
a750: 6e 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e n the VFS stack.
a760: 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 The names are
a770: 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 of all VFS shims
a780: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 and the.** fina
a790: 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 l bottom-level V
a7a0: 46 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 FS are written i
a7b0: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 nto memory obtai
a7c0: 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 ned from .** [sq
a7d0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
a7e0: 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 and the result i
a7f0: 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 s stored in the
a800: 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a char* variable.*
a810: 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 * that the fourt
a820: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b h parameter of [
a830: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e sqlite3_file_con
a840: 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 trol()] points t
a850: 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 o..** The caller
a860: 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 is responsible
a870: 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 for freeing the
a880: 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 memory when done
a890: 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c . As with.** al
a8a0: 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 l file-control a
a8b0: 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 ctions, there is
a8c0: 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 no guarantee th
a8d0: 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 at this will act
a8e0: 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 ually.** do anyt
a8f0: 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 hing. Callers s
a900: 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 hould initialize
a910: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 the char* varia
a920: 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a ble to a NULL.**
a930: 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 pointer in case
a940: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 this file-contr
a950: 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d ol is not implem
a960: 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c ented. This fil
a970: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 e-control.** is
a980: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 intended for dia
a990: 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 gnostic use only
a9a0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
a9b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 LITE_FCNTL_VFS_P
a9c0: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 OINTER]].** ^The
a9d0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 [SQLITE_FCNTL_V
a9e0: 46 53 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f FS_POINTER] opco
a9f0: 64 65 20 66 69 6e 64 73 20 61 20 70 6f 69 6e 74 de finds a point
aa00: 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 er to the top-le
aa10: 76 65 6c 0a 2a 2a 20 5b 56 46 53 65 73 5d 20 63 vel.** [VFSes] c
aa20: 75 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e urrently in use.
aa30: 20 20 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74 ^(The argument
aa40: 20 58 20 69 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 X in.** sqlite3
aa50: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 _file_control(db
aa60: 2c 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 ,SQLITE_FCNTL_VF
aa70: 53 5f 50 4f 49 4e 54 45 52 2c 58 29 20 6d 75 73 S_POINTER,X) mus
aa80: 74 20 62 65 0a 2a 2a 20 6f 66 20 74 79 70 65 20 t be.** of type
aa90: 22 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 2a "[sqlite3_vfs] *
aaa0: 2a 22 2e 20 20 54 68 69 73 20 6f 70 63 6f 64 65 *". This opcode
aab0: 73 20 77 69 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a s will set *X.**
aac0: 20 74 6f 20 61 20 70 6f 69 6e 74 65 72 20 74 6f to a pointer to
aad0: 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 20 56 the top-level V
aae0: 46 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 FS.)^.** ^When t
aaf0: 68 65 72 65 20 61 72 65 20 6d 75 6c 74 69 70 6c here are multipl
ab00: 65 20 56 46 53 20 73 68 69 6d 73 20 69 6e 20 74 e VFS shims in t
ab10: 68 65 20 73 74 61 63 6b 2c 20 74 68 69 73 20 6f he stack, this o
ab20: 70 63 6f 64 65 20 66 69 6e 64 73 20 74 68 65 0a pcode finds the.
ab30: 2a 2a 20 75 70 70 65 72 2d 6d 6f 73 74 20 73 68 ** upper-most sh
ab40: 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c im only..**.** <
ab50: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
ab60: 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 L_PRAGMA]].** ^W
ab70: 68 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d henever a [PRAGM
ab80: 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 A] statement is
ab90: 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 parsed, an [SQLI
aba0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d TE_FCNTL_PRAGMA]
abb0: 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f .** file contro
abc0: 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 l is sent to the
abd0: 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 open [sqlite3_f
abe0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 ile] object corr
abf0: 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 esponding.** to
ac00: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
ac10: 65 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 e to which the p
ac20: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 ragma statement
ac30: 72 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 refers. ^The arg
ac40: 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 ument.** to the
ac50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 [SQLITE_FCNTL_PR
ac60: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 AGMA] file contr
ac70: 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f ol is an array o
ac80: 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f f.** pointers to
ac90: 20 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a strings (char**
aca0: 29 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 ) in which the s
acb0: 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 econd element of
acc0: 20 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 the array.** is
acd0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
ace0: 20 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 pragma and the
acf0: 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 third element is
ad00: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f the argument to
ad10: 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f the.** pragma o
ad20: 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 r NULL if the pr
ad30: 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 agma has no argu
ad40: 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 ment. ^The hand
ad50: 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 ler for an.** [S
ad60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 QLITE_FCNTL_PRAG
ad70: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c MA] file control
ad80: 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 can optionally
ad90: 6d 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 make the first e
ada0: 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 lement.** of the
adb0: 20 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 char** argument
adc0: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 point to a stri
add0: 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ng obtained from
ade0: 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 [sqlite3_mprint
adf0: 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 f()].** or the e
ae00: 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 quivalent and th
ae10: 61 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 at string will b
ae20: 65 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 ecome the result
ae30: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f of the pragma o
ae40: 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d r.** the error m
ae50: 65 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72 essage if the pr
ae60: 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 agma fails. ^If
ae70: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 the.** [SQLITE_F
ae80: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c CNTL_PRAGMA] fil
ae90: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e e control return
aea0: 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 s [SQLITE_NOTFOU
aeb0: 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c ND], then normal
aec0: 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 .** [PRAGMA] pr
aed0: 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 ocessing continu
aee0: 65 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 es. ^If the [SQ
aef0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d LITE_FCNTL_PRAGM
af00: 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 A].** file contr
af10: 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ol returns [SQLI
af20: 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 TE_OK], then the
af30: 20 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 parser assumes
af40: 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 that the.** VFS
af50: 68 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 has handled the
af60: 50 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e PRAGMA itself an
af70: 64 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e d the parser gen
af80: 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a erates a no-op.*
af90: 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 * prepared state
afa0: 6d 65 6e 74 20 69 66 20 72 65 73 75 6c 74 20 73 ment if result s
afb0: 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f tring is NULL, o
afc0: 72 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 61 r that returns a
afd0: 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 copy.** of the
afe0: 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 66 result string if
aff0: 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 20 6e the string is n
b000: 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 on-NULL..** ^If
b010: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 the [SQLITE_FCNT
b020: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 L_PRAGMA] file c
b030: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a ontrol returns.*
b040: 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 * any result cod
b050: 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 e other than [SQ
b060: 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c LITE_OK] or [SQL
b070: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 ITE_NOTFOUND], t
b080: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 hat means.** tha
b090: 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e t the VFS encoun
b0a0: 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 tered an error w
b0b0: 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 hile handling th
b0c0: 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 e [PRAGMA] and t
b0d0: 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f he.** compilatio
b0e0: 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 n of the PRAGMA
b0f0: 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 fails with an er
b100: 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 ror. ^The [SQLI
b110: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d TE_FCNTL_PRAGMA]
b120: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c .** file control
b130: 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62 occurs at the b
b140: 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 eginning of prag
b150: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 ma statement ana
b160: 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 lysis and so.**
b170: 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 it is able to ov
b180: 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 erride built-in
b190: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 [PRAGMA] stateme
b1a0: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b nts..**.** <li>[
b1b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 [SQLITE_FCNTL_BU
b1c0: 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e SYHANDLER]].** ^
b1d0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
b1e0: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a L_BUSYHANDLER].*
b1f0: 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d * file-control m
b200: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 ay be invoked by
b210: 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 SQLite on the d
b220: 61 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e atabase file han
b230: 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 dle.** shortly a
b240: 66 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65 fter it is opene
b250: 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 d in order to pr
b260: 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56 ovide a custom V
b270: 46 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a FS with access.*
b280: 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 * to the connect
b290: 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 ions busy-handle
b2a0: 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 r callback. The
b2b0: 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 argument is of t
b2c0: 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a ype (void **).**
b2d0: 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 - an array of t
b2e0: 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 wo (void *) valu
b2f0: 65 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76 es. The first (v
b300: 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 oid *) actually
b310: 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 points.** to a f
b320: 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 unction of type
b330: 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 (int (*)(void *)
b340: 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 ). In order to i
b350: 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 nvoke the connec
b360: 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 tions.** busy-ha
b370: 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63 ndler, this func
b380: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 tion should be i
b390: 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20 nvoked with the
b3a0: 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 second (void *)
b3b0: 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20 in.** the array
b3c0: 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 as the only argu
b3d0: 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75 ment. If it retu
b3e0: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 rns non-zero, th
b3f0: 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e en the operation
b400: 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 .** should be re
b410: 74 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74 tried. If it ret
b420: 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 urns zero, the c
b430: 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 ustom VFS should
b440: 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 abandon the.**
b450: 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f current operatio
b460: 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 n..**.** <li>[[S
b470: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 QLITE_FCNTL_TEMP
b480: 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 FILENAME]].** ^A
b490: 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 pplication can i
b4a0: 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 nvoke the [SQLIT
b4b0: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 E_FCNTL_TEMPFILE
b4c0: 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 NAME] file-contr
b4d0: 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 ol.** to have SQ
b4e0: 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a Lite generate a.
b4f0: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c ** temporary fil
b500: 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20 ename using the
b510: 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 same algorithm t
b520: 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 hat is followed
b530: 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 to generate.** t
b540: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d emporary filenam
b550: 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c es for TEMP tabl
b560: 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 es and other int
b570: 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65 ernal uses. The
b580: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f .** argument sho
b590: 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20 uld be a char**
b5a0: 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69 which will be fi
b5b0: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69 lled with the fi
b5c0: 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 lename.** writte
b5d0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 n into memory ob
b5e0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c tained from [sql
b5f0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 ite3_malloc()].
b600: 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 The caller shou
b610: 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 ld.** invoke [sq
b620: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e lite3_free()] on
b630: 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61 the result to a
b640: 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 void a memory le
b650: 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b ak..**.** <li>[[
b660: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 SQLITE_FCNTL_MMA
b670: 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 P_SIZE]].** The
b680: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d [SQLITE_FCNTL_MM
b690: 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f AP_SIZE] file co
b6a0: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f ntrol is used to
b6b0: 20 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68 query or set th
b6c0: 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d e.** maximum num
b6d0: 62 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61 ber of bytes tha
b6e0: 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66 t will be used f
b6f0: 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 or memory-mapped
b700: 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 I/O..** The arg
b710: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 ument is a point
b720: 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 er to a value of
b730: 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e type sqlite3_in
b740: 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 t64 that.** is a
b750: 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d n advisory maxim
b760: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 um number of byt
b770: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74 es in the file t
b780: 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 o memory map. T
b790: 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 he.** pointer is
b7a0: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 overwritten wit
b7b0: 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e h the old value.
b7c0: 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e The limit is n
b7d0: 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a ot changed if.**
b7e0: 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69 the value origi
b7f0: 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f nally pointed to
b800: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e is negative, an
b810: 64 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74 d so the current
b820: 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 limit .** can b
b830: 65 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73 e queried by pas
b840: 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 sing in a pointe
b850: 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20 r to a negative
b860: 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a number. This.**
b870: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 file-control is
b880: 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 used internally
b890: 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 to implement [P
b8a0: 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d RAGMA mmap_size]
b8b0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
b8c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 LITE_FCNTL_TRACE
b8d0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 ]].** The [SQLIT
b8e0: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 E_FCNTL_TRACE] f
b8f0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 ile control prov
b900: 69 64 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e ides advisory in
b910: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 formation.** to
b920: 74 68 65 20 56 46 53 20 61 62 6f 75 74 20 77 68 the VFS about wh
b930: 61 74 20 74 68 65 20 68 69 67 68 65 72 20 6c 61 at the higher la
b940: 79 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69 yers of the SQLi
b950: 74 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69 te stack are doi
b960: 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 ng..** This file
b970: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 control is used
b980: 20 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74 by some VFS act
b990: 69 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73 ivity tracing [s
b9a0: 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 hims]..** The ar
b9b0: 67 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f gument is a zero
b9c0: 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 -terminated stri
b9d0: 6e 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65 ng. Higher laye
b9e0: 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c rs in the.** SQL
b9f0: 69 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65 ite stack may ge
ba00: 6e 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73 nerate instances
ba10: 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f of this file co
ba20: 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 ntrol if.** the
ba30: 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 [SQLITE_USE_FCNT
ba40: 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 L_TRACE] compile
ba50: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 -time option is
ba60: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c enabled..**.** <
ba70: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
ba80: 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a L_HAS_MOVED]].**
ba90: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
baa0: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 TL_HAS_MOVED] fi
bab0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 le control inter
bac0: 70 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 prets its argume
bad0: 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 nt as a.** point
bae0: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 er to an integer
baf0: 20 61 6e 64 20 69 74 20 77 72 69 74 65 73 20 61 and it writes a
bb00: 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 boolean into th
bb10: 61 74 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e at integer depen
bb20: 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 ding.** on wheth
bb30: 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 er or not the fi
bb40: 6c 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61 le has been rena
bb50: 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 med, moved, or d
bb60: 65 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a eleted since it.
bb70: 2a 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70 65 ** was first ope
bb80: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b ned..**.** <li>[
bb90: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 [SQLITE_FCNTL_WI
bba0: 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 5d N32_GET_HANDLE]]
bbb0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
bbc0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f FCNTL_WIN32_GET_
bbd0: 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 63 HANDLE] opcode c
bbe0: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 an be used to ob
bbf0: 74 61 69 6e 20 74 68 65 0a 2a 2a 20 75 6e 64 65 tain the.** unde
bc00: 72 6c 79 69 6e 67 20 6e 61 74 69 76 65 20 66 69 rlying native fi
bc10: 6c 65 20 68 61 6e 64 6c 65 20 61 73 73 6f 63 69 le handle associ
bc20: 61 74 65 64 20 77 69 74 68 20 61 20 66 69 6c 65 ated with a file
bc30: 20 68 61 6e 64 6c 65 2e 20 20 54 68 69 73 20 66 handle. This f
bc40: 69 6c 65 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69 ile.** control i
bc50: 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 nterprets its ar
bc60: 67 75 6d 65 6e 74 20 61 73 20 61 20 70 6f 69 6e gument as a poin
bc70: 74 65 72 20 74 6f 20 61 20 6e 61 74 69 76 65 20 ter to a native
bc80: 66 69 6c 65 20 68 61 6e 64 6c 65 20 61 6e 64 0a file handle and.
bc90: 2a 2a 20 77 72 69 74 65 73 20 74 68 65 20 72 65 ** writes the re
bca0: 73 75 6c 74 69 6e 67 20 76 61 6c 75 65 20 74 68 sulting value th
bcb0: 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b ere..**.** <li>[
bcc0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 [SQLITE_FCNTL_WI
bcd0: 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d N32_SET_HANDLE]]
bce0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
bcf0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f FCNTL_WIN32_SET_
bd00: 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 HANDLE] opcode i
bd10: 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 s used for debug
bd20: 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f ging. This.** o
bd30: 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 pcode causes the
bd40: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 xFileControl me
bd50: 74 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65 thod to swap the
bd60: 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 file handle wit
bd70: 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 h the one.** poi
bd80: 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 70 nted to by the p
bd90: 41 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 Arg argument. T
bda0: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 20 69 his capability i
bdb0: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 s used during te
bdc0: 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c sting.** and onl
bdd0: 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 y needs to be su
bde0: 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c pported when SQL
bdf0: 49 54 45 5f 54 45 53 54 20 69 73 20 64 65 66 69 ITE_TEST is defi
be00: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b ned..**.** <li>[
be10: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 [SQLITE_FCNTL_WA
be20: 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 L_BLOCK]].** The
be30: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 [SQLITE_FCNTL_W
be40: 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73 AL_BLOCK] is a s
be50: 69 67 6e 61 6c 20 74 6f 20 74 68 65 20 56 46 53 ignal to the VFS
be60: 20 6c 61 79 65 72 20 74 68 61 74 20 69 74 20 6d layer that it m
be70: 69 67 68 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e ight.** be advan
be80: 74 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b tageous to block
be90: 20 6f 6e 20 74 68 65 20 6e 65 78 74 20 57 41 4c on the next WAL
bea0: 20 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f 63 lock if the loc
beb0: 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61 k is not immedia
bec0: 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c tely.** availabl
bed0: 65 2e 20 20 54 68 65 20 57 41 4c 20 73 75 62 73 e. The WAL subs
bee0: 79 73 74 65 6d 20 69 73 73 75 65 73 20 74 68 69 ystem issues thi
bef0: 73 20 73 69 67 6e 61 6c 20 64 75 72 69 6e 67 20 s signal during
bf00: 72 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74 rare.** circumst
bf10: 61 6e 63 65 73 20 69 6e 20 6f 72 64 65 72 20 74 ances in order t
bf20: 6f 20 66 69 78 20 61 20 70 72 6f 62 6c 65 6d 20 o fix a problem
bf30: 77 69 74 68 20 70 72 69 6f 72 69 74 79 20 69 6e with priority in
bf40: 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c version..** Appl
bf50: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 ications should
bf60: 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 <em>not</em> use
bf70: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 this file-contr
bf80: 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b ol..**.** <li>[[
bf90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 SQLITE_FCNTL_ZIP
bfa0: 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 VFS]].** The [SQ
bfb0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 LITE_FCNTL_ZIPVF
bfc0: 53 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 S] opcode is imp
bfd0: 6c 65 6d 65 6e 74 65 64 20 62 79 20 7a 69 70 76 lemented by zipv
bfe0: 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 fs only. All oth
bff0: 65 72 0a 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64 er.** VFS should
c000: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e return SQLITE_N
c010: 4f 54 46 4f 55 4e 44 20 66 6f 72 20 74 68 69 73 OTFOUND for this
c020: 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c opcode..**.** <
c030: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
c040: 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b L_RBU]].** The [
c050: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 SQLITE_FCNTL_RBU
c060: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c ] opcode is impl
c070: 65 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20 73 emented by the s
c080: 70 65 63 69 61 6c 20 56 46 53 20 75 73 65 64 20 pecial VFS used
c090: 62 79 0a 2a 2a 20 74 68 65 20 52 42 55 20 65 78 by.** the RBU ex
c0a0: 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 tension only. A
c0b0: 6c 6c 20 6f 74 68 65 72 20 56 46 53 20 73 68 6f ll other VFS sho
c0c0: 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 uld return SQLIT
c0d0: 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a E_NOTFOUND for.*
c0e0: 2a 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 20 * this opcode.
c0f0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 .** </ul>.*/.#de
c100: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
c110: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 L_LOCKSTATE
c120: 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 1.#def
c130: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
c140: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 _GET_LOCKPROXYFI
c150: 4c 45 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 LE 2.#defi
c160: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
c170: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c SET_LOCKPROXYFIL
c180: 45 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e E 3.#defin
c190: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c e SQLITE_FCNTL_L
c1a0: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 AST_ERRNO
c1b0: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 4.#define
c1c0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 SQLITE_FCNTL_SI
c1d0: 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 ZE_HINT
c1e0: 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 5.#define
c1f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 SQLITE_FCNTL_CHU
c200: 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 NK_SIZE
c210: 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 6.#define S
c220: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 QLITE_FCNTL_FILE
c230: 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 _POINTER
c240: 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 7.#define SQ
c250: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f LITE_FCNTL_SYNC_
c260: 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20 OMITTED
c270: 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 8.#define SQL
c280: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f ITE_FCNTL_WIN32_
c290: 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 AV_RETRY
c2a0: 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 9.#define SQLI
c2b0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 TE_FCNTL_PERSIST
c2c0: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 _WAL
c2d0: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 10.#define SQLIT
c2e0: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 E_FCNTL_OVERWRIT
c2f0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 E 1
c300: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
c310: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 _FCNTL_VFSNAME
c320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32 12
c330: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
c340: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f FCNTL_POWERSAFE_
c350: 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a OVERWRITE 13.
c360: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
c370: 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 CNTL_PRAGMA
c380: 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 14.#
c390: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
c3a0: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 NTL_BUSYHANDLER
c3b0: 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 15.#d
c3c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
c3d0: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 TL_TEMPFILENAME
c3e0: 20 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 16.#de
c3f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
c400: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 L_MMAP_SIZE
c410: 20 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 18.#def
c420: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
c430: 5f 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20 _TRACE
c440: 20 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 19.#defi
c450: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
c460: 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 HAS_MOVED
c470: 20 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 20.#defin
c480: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 e SQLITE_FCNTL_S
c490: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 YNC
c4a0: 20 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 21.#define
c4b0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f SQLITE_FCNTL_CO
c4c0: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 MMIT_PHASETWO
c4d0: 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20 22.#define
c4e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e SQLITE_FCNTL_WIN
c4f0: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 32_SET_HANDLE
c500: 20 20 20 20 32 33 0a 23 64 65 66 69 6e 65 20 53 23.#define S
c510: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f QLITE_FCNTL_WAL_
c520: 42 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 BLOCK
c530: 20 20 20 32 34 0a 23 64 65 66 69 6e 65 20 53 51 24.#define SQ
c540: 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 LITE_FCNTL_ZIPVF
c550: 53 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 S
c560: 20 20 32 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 25.#define SQL
c570: 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 ITE_FCNTL_RBU
c580: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
c590: 20 32 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 26.#define SQLI
c5a0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 TE_FCNTL_VFS_POI
c5b0: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20 NTER
c5c0: 32 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 27.#define SQLIT
c5d0: 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f E_FCNTL_JOURNAL_
c5e0: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 32 POINTER 2
c5f0: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 8.#define SQLITE
c600: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 _FCNTL_WIN32_GET
c610: 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 39 _HANDLE 29
c620: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
c630: 46 43 4e 54 4c 5f 50 44 42 20 20 20 20 20 20 20 FCNTL_PDB
c640: 20 20 20 20 20 20 20 20 20 20 20 20 20 33 30 0a 30.
c650: 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e ./* deprecated n
c660: 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ames */.#define
c670: 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 SQLITE_GET_LOCKP
c680: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 ROXYFILE SQ
c690: 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c LITE_FCNTL_GET_L
c6a0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 OCKPROXYFILE.#de
c6b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f fine SQLITE_SET_
c6c0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 LOCKPROXYFILE
c6d0: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f SQLITE_FCNTL_
c6e0: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c SET_LOCKPROXYFIL
c6f0: 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 E.#define SQLITE
c700: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 _LAST_ERRNO
c710: 20 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 SQLITE_F
c720: 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a CNTL_LAST_ERRNO.
c730: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
c740: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a : Mutex Handle.*
c750: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d *.** The mutex m
c760: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c odule within SQL
c770: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c ite defines [sql
c780: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 ite3_mutex] to b
c790: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 e an.** abstract
c7a0: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 type for a mute
c7b0: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 x object. The S
c7c0: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 QLite core never
c7d0: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 looks.** at the
c7e0: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 internal repres
c7f0: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b entation of an [
c800: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 sqlite3_mutex].
c810: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c It only.** deal
c820: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 s with pointers
c830: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
c840: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a mutex] object..*
c850: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 *.** Mutexes are
c860: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b created using [
c870: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c sqlite3_mutex_al
c880: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 loc()]..*/.typed
c890: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
c8a0: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 3_mutex sqlite3_
c8b0: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 mutex;../*.** CA
c8c0: 50 49 33 52 45 46 3a 20 4c 6f 61 64 61 62 6c 65 PI3REF: Loadable
c8d0: 20 45 78 74 65 6e 73 69 6f 6e 20 54 68 75 6e 6b Extension Thunk
c8e0: 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 .**.** A pointer
c8f0: 20 74 6f 20 74 68 65 20 6f 70 61 71 75 65 20 73 to the opaque s
c900: 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 qlite3_api_routi
c910: 6e 65 73 20 73 74 72 75 63 74 75 72 65 20 69 73 nes structure is
c920: 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 passed as.** th
c930: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
c940: 72 20 74 6f 20 65 6e 74 72 79 20 70 6f 69 6e 74 r to entry point
c950: 73 20 6f 66 20 5b 6c 6f 61 64 61 62 6c 65 20 65 s of [loadable e
c960: 78 74 65 6e 73 69 6f 6e 73 5d 2e 20 20 54 68 69 xtensions]. Thi
c970: 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 6d s.** structure m
c980: 75 73 74 20 62 65 20 74 79 70 65 64 65 66 65 64 ust be typedefed
c990: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 77 6f 72 in order to wor
c9a0: 6b 20 61 72 6f 75 6e 64 20 63 6f 6d 70 69 6c 65 k around compile
c9b0: 72 20 77 61 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e r warnings.** on
c9c0: 20 73 6f 6d 65 20 70 6c 61 74 66 6f 72 6d 73 2e some platforms.
c9d0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
c9e0: 63 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 ct sqlite3_api_r
c9f0: 6f 75 74 69 6e 65 73 20 73 71 6c 69 74 65 33 5f outines sqlite3_
ca00: 61 70 69 5f 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f api_routines;../
ca10: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
ca20: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 S Interface Obje
ca30: 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 ct.**.** An inst
ca40: 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 ance of the sqli
ca50: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 te3_vfs object d
ca60: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 efines the inter
ca70: 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 face between.**
ca80: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 the SQLite core
ca90: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 and the underlyi
caa0: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 ng operating sys
cab0: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a tem. The "vfs".
cac0: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f ** in the name o
cad0: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 f the object sta
cae0: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c nds for "virtual
caf0: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 file system".
cb00: 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 See.** the [VFS
cb10: 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 | VFS documentat
cb20: 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 ion] for further
cb30: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a information..**
cb40: 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 .** The value of
cb50: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 the iVersion fi
cb60: 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 eld is initially
cb70: 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 1 but may be la
cb80: 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 rger in.** futur
cb90: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
cba0: 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 Lite. Additiona
cbb0: 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 l fields may be
cbc0: 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 appended to this
cbd0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 .** object when
cbe0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c the iVersion val
cbf0: 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e ue is increased.
cc00: 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 Note that the
cc10: 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 structure.** of
cc20: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 the sqlite3_vfs
cc30: 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 object changes i
cc40: 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f n the transactio
cc50: 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c n between.** SQL
cc60: 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e ite version 3.5.
cc70: 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 9 and 3.6.0 and
cc80: 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e yet the iVersion
cc90: 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a field was not.*
cca0: 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a * modified..**.*
ccb0: 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 * The szOsFile f
ccc0: 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 ield is the size
ccd0: 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 of the subclass
cce0: 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 ed [sqlite3_file
ccf0: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 ].** structure u
cd00: 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e sed by this VFS.
cd10: 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 mxPathname is
cd20: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 the maximum leng
cd30: 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e th of.** a pathn
cd40: 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e ame in this VFS.
cd50: 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 .**.** Registere
cd60: 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 d sqlite3_vfs ob
cd70: 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f jects are kept o
cd80: 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 n a linked list
cd90: 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 formed by.** the
cda0: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 pNext pointer.
cdb0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 The [sqlite3_vf
cdc0: 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a s_register()].**
cdd0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 and [sqlite3_vf
cde0: 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 s_unregister()]
cdf0: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 interfaces manag
ce00: 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 e this list.** i
ce10: 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 n a thread-safe
ce20: 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 way. The [sqlit
ce30: 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 e3_vfs_find()] i
ce40: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 nterface.** sear
ce50: 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 ches the list.
ce60: 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c Neither the appl
ce70: 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 ication code nor
ce80: 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c the VFS.** impl
ce90: 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c ementation shoul
cea0: 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 d use the pNext
ceb0: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 pointer..**.** T
cec0: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 he pNext field i
ced0: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 s the only field
cee0: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f in the sqlite3_
cef0: 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 vfs.** structure
cf00: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c that SQLite wil
cf10: 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 l ever modify.
cf20: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 SQLite will only
cf30: 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f access.** or mo
cf40: 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 dify this field
cf50: 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 while holding a
cf60: 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 particular stati
cf70: 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 c mutex..** The
cf80: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 application shou
cf90: 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 ld never modify
cfa0: 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 anything within
cfb0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a the sqlite3_vfs.
cfc0: 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 ** object once t
cfd0: 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 he object has be
cfe0: 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a en registered..*
cff0: 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 *.** The zName f
d000: 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e ield holds the n
d010: 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d ame of the VFS m
d020: 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 odule. The name
d030: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 must.** be uniq
d040: 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 ue across all VF
d050: 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a S modules..**.**
d060: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 [[sqlite3_vfs.x
d070: 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 Open]].** ^SQLit
d080: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 e guarantees tha
d090: 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 t the zFilename
d0a0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 parameter to xOp
d0b0: 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 en.** is either
d0c0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f a NULL pointer o
d0d0: 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 r string obtaine
d0e0: 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 d.** from xFullP
d0f0: 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 athname() with a
d100: 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 n optional suffi
d110: 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 x added..** ^If
d120: 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 a suffix is adde
d130: 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 d to the zFilena
d140: 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 me parameter, it
d150: 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 will.** consist
d160: 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 of a single "-"
d170: 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f character follo
d180: 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 wed by no more t
d190: 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e han.** 11 alphan
d1a0: 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d umeric and/or "-
d1b0: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a " characters..**
d1c0: 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 ^SQLite further
d1d0: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 guarantees that
d1e0: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 .** the string w
d1f0: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 ill be valid and
d200: 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c unchanged until
d210: 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 xClose() is.**
d220: 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 called. Because
d230: 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 of the previous
d240: 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 sentence,.** the
d250: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
d260: 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 can safely store
d270: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
d280: 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 e.** filename if
d290: 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d it needs to rem
d2a0: 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 ember the filena
d2b0: 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 me for some reas
d2c0: 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 on..** If the zF
d2d0: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 ilename paramete
d2e0: 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 r to xOpen is a
d2f0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 NULL pointer the
d300: 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 n xOpen.** must
d310: 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 invent its own t
d320: 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f emporary name fo
d330: 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 r the file. ^Wh
d340: 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 enever the .** x
d350: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 Filename paramet
d360: 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 er is NULL it wi
d370: 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 ll also be the c
d380: 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 ase that the.**
d390: 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 flags parameter
d3a0: 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 will include [SQ
d3b0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
d3c0: 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 ONCLOSE]..**.**
d3d0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 The flags argume
d3e0: 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e nt to xOpen() in
d3f0: 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 cludes all bits
d400: 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c set in.** the fl
d410: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ags argument to
d420: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
d430: 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c ()]. Or if [sql
d440: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 ite3_open()].**
d450: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e or [sqlite3_open
d460: 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 16()] is used, t
d470: 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 hen flags includ
d480: 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b es at least.** [
d490: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
d4a0: 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 WRITE] | [SQLITE
d4b0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a _OPEN_CREATE]. .
d4c0: 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 ** If xOpen() op
d4d0: 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d ens a file read-
d4e0: 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 only then it set
d4f0: 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a s *pOutFlags to.
d500: 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 ** include [SQLI
d510: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 TE_OPEN_READONLY
d520: 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 ]. Other bits i
d530: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 n *pOutFlags may
d540: 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e be set..**.** ^
d550: 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 (SQLite will als
d560: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 o add one of the
d570: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 following flags
d580: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a to the xOpen().
d590: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 ** call, dependi
d5a0: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 ng on the object
d5b0: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a being opened:.*
d5c0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
d5d0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
d5e0: 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e MAIN_DB].** <li>
d5f0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d [SQLITE_OPEN_M
d600: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 AIN_JOURNAL].**
d610: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
d620: 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c EN_TEMP_DB].** <
d630: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
d640: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a N_TEMP_JOURNAL].
d650: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
d660: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f _OPEN_TRANSIENT_
d670: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 DB].** <li> [SQ
d680: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 LITE_OPEN_SUBJOU
d690: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b RNAL].** <li> [
d6a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 SQLITE_OPEN_MAST
d6b0: 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c ER_JOURNAL].** <
d6c0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
d6d0: 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 N_WAL].** </ul>)
d6e0: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 ^.**.** The file
d6f0: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 I/O implementat
d700: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 ion can use the
d710: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 object type flag
d720: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 s to.** change t
d730: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 he way it deals
d740: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 with files. For
d750: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 example, an app
d760: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 lication.** that
d770: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 does not care a
d780: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 bout crash recov
d790: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 ery or rollback
d7a0: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 might make.** th
d7b0: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 e open of a jour
d7c0: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 nal file a no-op
d7d0: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 . Writes to thi
d7e0: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a s journal would.
d7f0: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 ** also be no-op
d800: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d s, and any attem
d810: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a pt to read the j
d820: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 ournal would ret
d830: 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f urn.** SQLITE_IO
d840: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 ERR. Or the imp
d850: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 lementation migh
d860: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 t recognize that
d870: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 a database.** f
d880: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e ile will be doin
d890: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 g page-aligned s
d8a0: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 ector reads and
d8b0: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 writes in a rand
d8c0: 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 om.** order and
d8d0: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 set up its I/O s
d8e0: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 ubsystem accordi
d8f0: 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 ngly..**.** SQLi
d900: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 te might also ad
d910: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c d one of the fol
d920: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 lowing flags to
d930: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 the xOpen method
d940: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
d950: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 <li> [SQLITE_OPE
d960: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d N_DELETEONCLOSE]
d970: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
d980: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d _OPEN_EXCLUSIVE]
d990: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
d9a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e The [SQLITE_OPEN
d9b0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 _DELETEONCLOSE]
d9c0: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 flag means the f
d9d0: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a ile should be.**
d9e0: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 deleted when it
d9f0: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 is closed. ^Th
da00: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 e [SQLITE_OPEN_D
da10: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a ELETEONCLOSE].**
da20: 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 will be set for
da30: 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 TEMP databases
da40: 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 and their journa
da50: 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a ls, transient.**
da60: 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 databases, and
da70: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a subjournals..**.
da80: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f ** ^The [SQLITE_
da90: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 OPEN_EXCLUSIVE]
daa0: 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 flag is always u
dab0: 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 sed in conjuncti
dac0: 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b on.** with the [
dad0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 SQLITE_OPEN_CREA
dae0: 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 TE] flag, which
daf0: 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c are both directl
db00: 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 y.** analogous t
db10: 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 o the O_EXCL and
db20: 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f O_CREAT flags o
db30: 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e f the POSIX open
db40: 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 ().** API. The
db50: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c SQLITE_OPEN_EXCL
db60: 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e USIVE flag, when
db70: 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 paired with the
db80: 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e .** SQLITE_OPEN
db90: 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 _CREATE, is used
dba0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 to indicate tha
dbb0: 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c t file should al
dbc0: 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 ways.** be creat
dbd0: 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 ed, and that it
dbe0: 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 is an error if i
dbf0: 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 t already exists
dc00: 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f ..** It is <i>no
dc10: 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e t</i> used to in
dc20: 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 dicate the file
dc30: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 should be opened
dc40: 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 .** for exclusi
dc50: 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a ve access..**.**
dc60: 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 ^At least szOsF
dc70: 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d ile bytes of mem
dc80: 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 ory are allocate
dc90: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 d by SQLite.** t
dca0: 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c o hold the [sql
dcb0: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 ite3_file] struc
dcc0: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 ture passed as t
dcd0: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 he third.** argu
dce0: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 ment to xOpen.
dcf0: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 The xOpen method
dd00: 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 does not have t
dd10: 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 o.** allocate th
dd20: 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 e structure; it
dd30: 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c should just fill
dd40: 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 it in. Note th
dd50: 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 at.** the xOpen
dd60: 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 method must set
dd70: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 the sqlite3_file
dd80: 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 .pMethods to eit
dd90: 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b her.** a valid [
dda0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
ddb0: 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f ds] object or to
ddc0: 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 NULL. xOpen mu
ddd0: 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 st do.** this ev
dde0: 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 en if the open f
ddf0: 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 ails. SQLite ex
de00: 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 pects that the s
de10: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 qlite3_file.pMet
de20: 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 hods.** element
de30: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 will be valid af
de40: 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e ter xOpen return
de50: 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 s regardless of
de60: 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f the success.** o
de70: 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 r failure of the
de80: 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a xOpen call..**.
de90: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 ** [[sqlite3_vfs
dea0: 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 .xAccess]].** ^T
deb0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e he flags argumen
dec0: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d t to xAccess() m
ded0: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 ay be [SQLITE_AC
dee0: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 CESS_EXISTS].**
def0: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 to test for the
df00: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 existence of a f
df10: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f ile, or [SQLITE_
df20: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 ACCESS_READWRITE
df30: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 ] to.** test whe
df40: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 ther a file is r
df50: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 eadable and writ
df60: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 able, or [SQLITE
df70: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a _ACCESS_READ].**
df80: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 to test whether
df90: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 a file is at le
dfa0: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 ast readable.
dfb0: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 The file can be
dfc0: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a a.** directory..
dfd0: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 **.** ^SQLite wi
dfe0: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 ll always alloca
dff0: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 te at least mxPa
e000: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 thname+1 bytes f
e010: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 or the.** output
e020: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 buffer xFullPat
e030: 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 hname. The exac
e040: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 t size of the ou
e050: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 tput buffer.** i
e060: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 s also passed as
e070: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 a parameter to
e080: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 both methods. I
e090: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 f the output buf
e0a0: 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 fer.** is not la
e0b0: 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c rge enough, [SQL
e0c0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 ITE_CANTOPEN] sh
e0d0: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 ould be returned
e0e0: 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a . Since this is.
e0f0: 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 ** handled as a
e100: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 fatal error by S
e110: 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 QLite, vfs imple
e120: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c mentations shoul
e130: 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f d endeavor.** to
e140: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 prevent this by
e150: 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e setting mxPathn
e160: 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 ame to a suffici
e170: 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 ently large valu
e180: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 e..**.** The xRa
e190: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 ndomness(), xSle
e1a0: 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 ep(), xCurrentTi
e1b0: 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 me(), and xCurre
e1c0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a ntTimeInt64().**
e1d0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
e1e0: 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 not strictly a p
e1f0: 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 art of the files
e200: 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 ystem, but they
e210: 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 are.** included
e220: 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 in the VFS struc
e230: 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 ture for complet
e240: 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 eness..** The xR
e250: 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 andomness() func
e260: 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f tion attempts to
e270: 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 return nBytes b
e280: 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d ytes.** of good-
e290: 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 quality randomne
e2a0: 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 ss into zOut. T
e2b0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
e2c0: 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c is.** the actual
e2d0: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
e2e0: 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f of randomness o
e2f0: 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 btained..** The
e300: 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 xSleep() method
e310: 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 causes the calli
e320: 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 ng thread to sle
e330: 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 ep for at.** lea
e340: 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 st the number of
e350: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 microseconds gi
e360: 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 ven. ^The xCurr
e370: 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 entTime().** met
e380: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 hod returns a Ju
e390: 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 lian Day Number
e3a0: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 for the current
e3b0: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 date and time as
e3c0: 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 .** a floating p
e3d0: 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e oint value..** ^
e3e0: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 The xCurrentTime
e3f0: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 Int64() method r
e400: 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e eturns, as an in
e410: 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 teger, the Julia
e420: 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 n.** Day Number
e430: 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 multiplied by 86
e440: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 400000 (the numb
e450: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e er of millisecon
e460: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 ds in .** a 24-h
e470: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e our day). .** ^
e480: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 SQLite will use
e490: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 the xCurrentTime
e4a0: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 Int64() method t
e4b0: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e o get the curren
e4c0: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 t.** date and ti
e4d0: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f me if that metho
e4e0: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 d is available (
e4f0: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 if iVersion is 2
e500: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 or .** greater
e510: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e and the function
e520: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 pointer is not
e530: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 NULL) and will f
e540: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 all back.** to x
e550: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 CurrentTime() if
e560: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 xCurrentTimeInt
e570: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 64() is unavaila
e580: 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ble..**.** ^The
e590: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 xSetSystemCall()
e5a0: 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c , xGetSystemCall
e5b0: 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 (), and xNestSys
e5c0: 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 temCall() interf
e5d0: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 aces.** are not
e5e0: 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 used by the SQLi
e5f0: 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 te core. These
e600: 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 optional interfa
e610: 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 ces are provided
e620: 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 .** by some VFSe
e630: 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 s to facilitate
e640: 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 testing of the V
e650: 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 FS code. By over
e660: 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 riding .** syste
e670: 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e m calls with fun
e680: 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 ctions under its
e690: 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 control, a test
e6a0: 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 program can.**
e6b0: 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 simulate faults
e6c0: 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 and error condit
e6d0: 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 ions that would
e6e0: 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 otherwise be dif
e6f0: 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 ficult.** or imp
e700: 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 ossible to induc
e710: 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 e. The set of s
e720: 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 ystem calls that
e730: 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 can be overridd
e740: 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f en.** varies fro
e750: 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f m one VFS to ano
e760: 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f ther, and from o
e770: 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 ne version of th
e780: 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 e same VFS to th
e790: 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c e.** next. Appl
e7a0: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 ications that us
e7b0: 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 e these interfac
e7c0: 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 es must be prepa
e7d0: 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f red for any.** o
e7e0: 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 r all of these i
e7f0: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 nterfaces to be
e800: 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 NULL or for thei
e810: 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 r behavior to ch
e820: 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 ange.** from one
e830: 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 release to the
e840: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 next. Applicati
e850: 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 ons must not att
e860: 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a empt to access.*
e870: 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d * any of these m
e880: 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 ethods if the iV
e890: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 ersion of the VF
e8a0: 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 S is less than 3
e8b0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
e8c0: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 uct sqlite3_vfs
e8d0: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 sqlite3_vfs;.typ
e8e0: 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 edef void (*sqli
e8f0: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 te3_syscall_ptr)
e900: 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 (void);.struct s
e910: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 qlite3_vfs {. i
e920: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 nt iVersion;
e930: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 /* Struc
e940: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d ture version num
e950: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 ber (currently 3
e960: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 ) */. int szOsF
e970: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 ile;
e980: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c /* Size of subcl
e990: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 assed sqlite3_fi
e9a0: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 le */. int mxPa
e9b0: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 thname;
e9c0: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 /* Maximum file
e9d0: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 pathname length
e9e0: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 */. sqlite3_vf
e9f0: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f s *pNext; /
ea00: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 * Next registere
ea10: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 d VFS */. const
ea20: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 char *zName;
ea30: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 /* Name of t
ea40: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 his virtual file
ea50: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 system */. voi
ea60: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 d *pAppData;
ea70: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 /* Pointer
ea80: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d to application-
ea90: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f specific data */
eaa0: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 . int (*xOpen)(
eab0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
eac0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
ead0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a sqlite3_file*,.
eae0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 i
eaf0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 nt flags, int *p
eb00: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 OutFlags);. int
eb10: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 (*xDelete)(sqli
eb20: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
eb30: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 char *zName, int
eb40: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 syncDir);. int
eb50: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 (*xAccess)(sqli
eb60: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
eb70: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 char *zName, int
eb80: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 flags, int *pRe
eb90: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 sOut);. int (*x
eba0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 FullPathname)(sq
ebb0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 lite3_vfs*, cons
ebc0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 t char *zName, i
ebd0: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a nt nOut, char *z
ebe0: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a Out);. void *(*
ebf0: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 xDlOpen)(sqlite3
ec00: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
ec10: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 r *zFilename);.
ec20: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 void (*xDlError
ec30: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
ec40: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 int nByte, char
ec50: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 *zErrMsg);. voi
ec60: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 d (*(*xDlSym)(sq
ec70: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a lite3_vfs*,void*
ec80: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 , const char *zS
ec90: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 ymbol))(void);.
eca0: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 void (*xDlClose
ecb0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
ecc0: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a void*);. int (*
ecd0: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c xRandomness)(sql
ece0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e ite3_vfs*, int n
ecf0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 Byte, char *zOut
ed00: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 );. int (*xSlee
ed10: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c p)(sqlite3_vfs*,
ed20: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 int microsecond
ed30: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 s);. int (*xCur
ed40: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 rentTime)(sqlite
ed50: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3_vfs*, double*)
ed60: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 ;. int (*xGetLa
ed70: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 stError)(sqlite3
ed80: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 _vfs*, int, char
ed90: 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 *);. /*. ** T
eda0: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 he methods above
edb0: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 are in version
edc0: 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 1 of the sqlite_
edd0: 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 vfs object. **
ede0: 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f definition. Tho
edf0: 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 se that follow a
ee00: 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 re added in vers
ee10: 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 ion 2 or later.
ee20: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 */. int (*xCur
ee30: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 rentTimeInt64)(s
ee40: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c qlite3_vfs*, sql
ee50: 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 ite3_int64*);.
ee60: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 /*. ** The meth
ee70: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e ods above are in
ee80: 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 versions 1 and
ee90: 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 2 of the sqlite_
eea0: 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a vfs object.. **
eeb0: 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 Those below are
eec0: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 for version 3 a
eed0: 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f nd greater.. */
eee0: 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 . int (*xSetSys
eef0: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 temCall)(sqlite3
ef00: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
ef10: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 r *zName, sqlite
ef20: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 3_syscall_ptr);.
ef30: 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c sqlite3_syscal
ef40: 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 l_ptr (*xGetSyst
ef50: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f emCall)(sqlite3_
ef60: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
ef70: 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 *zName);. cons
ef80: 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 t char *(*xNextS
ef90: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 ystemCall)(sqlit
efa0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
efb0: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f har *zName);. /
efc0: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f *. ** The metho
efd0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 ds above are in
efe0: 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 versions 1 throu
eff0: 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 gh 3 of the sqli
f000: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 te_vfs object..
f010: 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d ** New fields m
f020: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 ay be appended i
f030: 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e n future version
f040: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e s. The iVersion
f050: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c . ** value will
f060: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 increment whene
f070: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 ver this happens
f080: 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a . . */.};../*.*
f090: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 * CAPI3REF: Flag
f0a0: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 s for the xAcces
f0b0: 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a s VFS method.**.
f0c0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 ** These integer
f0d0: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 constants can b
f0e0: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 e used as the th
f0f0: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ird parameter to
f100: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 .** the xAccess
f110: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 method of an [sq
f120: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
f130: 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 t. They determi
f140: 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 ne.** what kind
f150: 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 of permissions t
f160: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f he xAccess metho
f170: 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 d is looking for
f180: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 ..** With SQLITE
f190: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 _ACCESS_EXISTS,
f1a0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 the xAccess meth
f1b0: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 od.** simply che
f1c0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 cks whether the
f1d0: 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 file exists..**
f1e0: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 With SQLITE_ACCE
f1f0: 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 SS_READWRITE, th
f200: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 e xAccess method
f210: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 .** checks wheth
f220: 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 er the named dir
f230: 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 ectory is both r
f240: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 eadable and writ
f250: 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 able.** (in othe
f260: 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 r words, if file
f270: 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 s can be added,
f280: 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e removed, and ren
f290: 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 amed within.** t
f2a0: 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a he directory)..*
f2b0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 * The SQLITE_ACC
f2c0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f ESS_READWRITE co
f2d0: 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e nstant is curren
f2e0: 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 tly used only by
f2f0: 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 the.** [temp_st
f300: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 ore_directory pr
f310: 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 agma], though th
f320: 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 is could change
f330: 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 in a future.** r
f340: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 elease of SQLite
f350: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 ..** With SQLITE
f360: 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 _ACCESS_READ, th
f370: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 e xAccess method
f380: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 .** checks wheth
f390: 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 er the file is r
f3a0: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 eadable. The SQ
f3b0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
f3c0: 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 constant is.**
f3d0: 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 currently unused
f3e0: 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 , though it migh
f3f0: 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 t be used in a f
f400: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 uture release of
f410: 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 .** SQLite..*/.#
f420: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 define SQLITE_AC
f430: 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 CESS_EXISTS 0
f440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
f450: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 ACCESS_READWRITE
f460: 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 1 /* Used by
f470: 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 PRAGMA temp_stor
f480: 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 e_directory */.#
f490: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 define SQLITE_AC
f4a0: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 CESS_READ 2
f4b0: 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a /* Unused */.
f4c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
f4d0: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 Flags for the x
f4e0: 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 ShmLock VFS meth
f4f0: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 od.**.** These i
f500: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 nteger constants
f510: 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 define the vari
f520: 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 ous locking oper
f530: 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 ations.** allowe
f540: 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 d by the xShmLoc
f550: 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c k method of [sql
f560: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
f570: 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 . The.** follow
f580: 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 ing are the only
f590: 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 legal combinati
f5a0: 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 ons of flags to
f5b0: 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 the.** xShmLock
f5c0: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 method:.**.** <u
f5d0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 l>.** <li> SQLI
f5e0: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 TE_SHM_LOCK | SQ
f5f0: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a LITE_SHM_SHARED.
f600: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f ** <li> SQLITE_
f610: 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 SHM_LOCK | SQLIT
f620: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a E_SHM_EXCLUSIVE.
f630: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f ** <li> SQLITE_
f640: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c SHM_UNLOCK | SQL
f650: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a ITE_SHM_SHARED.*
f660: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 * <li> SQLITE_S
f670: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 HM_UNLOCK | SQLI
f680: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 TE_SHM_EXCLUSIVE
f690: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
f6a0: 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 When unlocking,
f6b0: 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 the same SHARED
f6c0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 or EXCLUSIVE fla
f6d0: 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 g must be suppli
f6e0: 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 ed as.** was giv
f6f0: 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 en on the corres
f700: 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a ponding lock. .
f710: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f **.** The xShmLo
f720: 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 ck method can tr
f730: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e ansition between
f740: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 unlocked and SH
f750: 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 ARED or.** betwe
f760: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 en unlocked and
f770: 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 EXCLUSIVE. It c
f780: 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e annot transition
f790: 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a between SHARED.
f7a0: 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 ** and EXCLUSIVE
f7b0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
f7c0: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 ITE_SHM_UNLOCK
f7d0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 1.#define S
f7e0: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 QLITE_SHM_LOCK
f7f0: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 2.#define
f800: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 SQLITE_SHM_SHAR
f810: 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 ED 4.#defi
f820: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 ne SQLITE_SHM_EX
f830: 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a CLUSIVE 8../*
f840: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 .** CAPI3REF: Ma
f850: 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 ximum xShmLock i
f860: 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ndex.**.** The x
f870: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f ShmLock method o
f880: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 n [sqlite3_io_me
f890: 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 thods] may use v
f8a0: 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e alues.** between
f8b0: 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 0 and this uppe
f8c0: 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 r bound as its "
f8d0: 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 offset" argument
f8e0: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 ..** The SQLite
f8f0: 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 core will never
f900: 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 attempt to acqui
f910: 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a re or release a.
f920: 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 ** lock outside
f930: 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f of this range.*/
f940: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
f950: 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 SHM_NLOCK
f960: 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 8.../*.** CAPI3
f970: 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 REF: Initialize
f980: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 The SQLite Libra
f990: 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 ry.**.** ^The sq
f9a0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
f9b0: 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 () routine initi
f9c0: 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 alizes the.** SQ
f9d0: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e Lite library. ^
f9e0: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 The sqlite3_shut
f9f0: 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a down() routine.*
fa00: 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e * deallocates an
fa10: 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 y resources that
fa20: 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 were allocated
fa30: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 by sqlite3_initi
fa40: 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 alize()..** Thes
fa50: 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 e routines are d
fa60: 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 esigned to aid i
fa70: 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 n process initia
fa80: 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 lization and.**
fa90: 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 shutdown on embe
faa0: 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 dded systems. W
fab0: 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 orkstation appli
fac0: 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a cations using.**
fad0: 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 SQLite normally
fae0: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 do not need to
faf0: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 invoke either of
fb00: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e these routines.
fb10: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f .**.** A call to
fb20: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
fb30: 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 ize() is an "eff
fb40: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 ective" call if
fb50: 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 it is.** the fir
fb60: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f st time sqlite3_
fb70: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 initialize() is
fb80: 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 invoked during t
fb90: 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a he lifetime of.*
fba0: 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f * the process, o
fbb0: 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 r if it is the f
fbc0: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 irst time sqlite
fbd0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 3_initialize() i
fbe0: 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c s invoked.** fol
fbf0: 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f lowing a call to
fc00: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
fc10: 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 n(). ^(Only an
fc20: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a effective call.*
fc30: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 * of sqlite3_ini
fc40: 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 tialize() does a
fc50: 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f ny initializatio
fc60: 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 n. All other ca
fc70: 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c lls.** are harml
fc80: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a ess no-ops.)^.**
fc90: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 .** A call to sq
fca0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
fcb0: 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 is an "effectiv
fcc0: 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 e" call if it is
fcd0: 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 the first.** ca
fce0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 ll to sqlite3_sh
fcf0: 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 utdown() since t
fd00: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f he last sqlite3_
fd10: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e initialize(). ^
fd20: 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 (Only.** an effe
fd30: 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 ctive call to sq
fd40: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
fd50: 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 does any deinit
fd60: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 ialization..** A
fd70: 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 ll other valid c
fd80: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
fd90: 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 shutdown() are h
fda0: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 armless no-ops.)
fdb0: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ^.**.** The sqli
fdc0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
fdd0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 interface is th
fde0: 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 readsafe, but sq
fdf0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
fe00: 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 .** is not. The
fe10: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
fe20: 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 n() interface mu
fe30: 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 st only be calle
fe40: 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 d from a.** sing
fe50: 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 le thread. All
fe60: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 open [database c
fe70: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 onnections] must
fe80: 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 be closed and a
fe90: 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 ll.** other SQLi
fea0: 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 te resources mus
feb0: 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 t be deallocated
fec0: 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 prior to invoki
fed0: 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 ng.** sqlite3_sh
fee0: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 utdown()..**.**
fef0: 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e Among other thin
ff00: 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 gs, ^sqlite3_ini
ff10: 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 tialize() will i
ff20: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 nvoke.** sqlite3
ff30: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d _os_init(). Sim
ff40: 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 ilarly, ^sqlite3
ff50: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 _shutdown().** w
ff60: 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 ill invoke sqlit
ff70: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a e3_os_end()..**.
ff80: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
ff90: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 initialize() rou
ffa0: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 tine returns [SQ
ffb0: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 LITE_OK] on succ
ffc0: 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 ess..** ^If for
ffd0: 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c some reason, sql
ffe0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
fff0: 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 ) is unable to i
10000 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 nitialize.** the
10010 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 library (perhap
10020 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 s it is unable t
10030 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 o allocate a nee
10040 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 ded resource suc
10050 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 h.** as a mutex)
10060 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b it returns an [
10070 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 error code] othe
10080 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f r than [SQLITE_O
10090 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 K]..**.** ^The s
100a0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
100b0 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 e() routine is c
100c0 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 alled internally
100d0 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a by many other.*
100e0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 * SQLite interfa
100f0 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 ces so that an a
10100 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c pplication usual
10110 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 ly does not need
10120 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 to.** invoke sq
10130 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
10140 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f () directly. Fo
10150 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 r example, [sqli
10160 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 te3_open()].** c
10170 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 alls sqlite3_ini
10180 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 tialize() so the
10190 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 SQLite library
101a0 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 will be automati
101b0 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c cally.** initial
101c0 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 ized when [sqlit
101d0 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 e3_open()] is ca
101e0 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e lled if it has n
101f0 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 ot be initialize
10200 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e d.** already. ^
10210 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 However, if SQLi
10220 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
10230 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ith the [SQLITE_
10240 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a OMIT_AUTOINIT].*
10250 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f * compile-time o
10260 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 ption, then the
10270 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 automatic calls
10280 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 to sqlite3_initi
10290 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f alize().** are o
102a0 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 mitted and the a
102b0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
102c0 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 call sqlite3_ini
102d0 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 tialize() direct
102e0 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 ly.** prior to u
102f0 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 sing any other S
10300 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e QLite interface.
10310 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f For maximum po
10320 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 rtability,.** it
10330 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
10340 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e that application
10350 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 s always invoke
10360 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
10370 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 ze().** directly
10380 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 prior to using
10390 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 any other SQLite
103a0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 interface. Fut
103b0 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 ure releases.**
103c0 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 of SQLite may re
103d0 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 quire this. In
103e0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 other words, the
103f0 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 behavior exhibi
10400 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 ted.** when SQLi
10410 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
10420 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 ith [SQLITE_OMIT
10430 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 _AUTOINIT] might
10440 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 become the.** d
10450 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 efault behavior
10460 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 in some future r
10470 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 elease of SQLite
10480 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
10490 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f te3_os_init() ro
104a0 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 utine does opera
104b0 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 ting-system spec
104c0 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 ific.** initiali
104d0 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 zation of the SQ
104e0 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 Lite library. T
104f0 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e he sqlite3_os_en
10500 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 d().** routine u
10510 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 ndoes the effect
10520 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 of sqlite3_os_i
10530 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 nit(). Typical
10540 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d tasks.** perform
10550 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 ed by these rout
10560 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c ines include all
10570 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c ocation or deall
10580 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 ocation.** of st
10590 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 atic resources,
105a0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f initialization o
105b0 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c f global variabl
105c0 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 es,.** setting u
105d0 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c p a default [sql
105e0 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 ite3_vfs] module
105f0 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a , or setting up.
10600 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e ** a default con
10610 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 figuration using
10620 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
10630 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 ()]..**.** The a
10640 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
10650 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 d never invoke e
10660 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 ither sqlite3_os
10670 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 _init().** or sq
10680 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 lite3_os_end() d
10690 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 irectly. The ap
106a0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 plication should
106b0 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 only invoke.**
106c0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
106d0 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 ze() and sqlite3
106e0 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 _shutdown(). Th
106f0 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 e sqlite3_os_ini
10700 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 t().** interface
10710 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d is called autom
10720 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 atically by sqli
10730 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
10740 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f and.** sqlite3_
10750 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c os_end() is call
10760 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 ed by sqlite3_sh
10770 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f utdown(). Appro
10780 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d priate.** implem
10790 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 entations for sq
107a0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 lite3_os_init()
107b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 and sqlite3_os_e
107c0 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c nd().** are buil
107d0 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 t into SQLite wh
107e0 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 en it is compile
107f0 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 d for Unix, Wind
10800 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a ows, or OS/2..**
10810 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 When [custom bu
10820 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 ilds | built for
10830 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 other platforms
10840 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 ].** (using the
10850 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 [SQLITE_OS_OTHER
10860 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 =1] compile-time
10870 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 .** option) the
10880 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
10890 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 supply a suitab
108a0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
108b0 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 n for.** sqlite3
108c0 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 _os_init() and s
108d0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e qlite3_os_end().
108e0 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e An application
108f0 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 -supplied.** imp
10900 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 lementation of s
10910 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
10920 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 or sqlite3_os_e
10930 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 nd().** must ret
10940 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 urn [SQLITE_OK]
10950 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 on success and s
10960 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 ome other [error
10970 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 code] upon.** f
10980 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 ailure..*/.int s
10990 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
109a0 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c e(void);.int sql
109b0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f ite3_shutdown(vo
109c0 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 id);.int sqlite3
109d0 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a _os_init(void);.
109e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 int sqlite3_os_e
109f0 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a nd(void);../*.**
10a00 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 CAPI3REF: Confi
10a10 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 guring The SQLit
10a20 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 e Library.**.**
10a30 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 The sqlite3_conf
10a40 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 ig() interface i
10a50 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 s used to make g
10a60 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 lobal configurat
10a70 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 ion.** changes t
10a80 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 o SQLite in orde
10a90 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 r to tune SQLite
10aa0 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 to the specific
10ab0 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 needs of.** the
10ac0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 application. T
10ad0 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 he default confi
10ae0 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f guration is reco
10af0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 mmended for most
10b00 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 .** applications
10b10 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 and so this rou
10b20 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 tine is usually
10b30 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 not necessary.
10b40 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 It is.** provide
10b50 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 d to support rar
10b60 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 e applications w
10b70 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 ith unusual need
10b80 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 s..**.** <b>The
10b90 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
10ba0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f interface is no
10bb0 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 54 68 t threadsafe. Th
10bc0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a e application.**
10bd0 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 must ensure tha
10be0 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 t no other SQLit
10bf0 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 e interfaces are
10c00 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 invoked by othe
10c10 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 r.** threads whi
10c20 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 le sqlite3_confi
10c30 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c g() is running.<
10c40 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 /b>.**.** The sq
10c50 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 lite3_config() i
10c60 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20 nterface.** may
10c70 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 only be invoked
10c80 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 prior to library
10c90 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
10ca0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 using.** [sqlite
10cb0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 3_initialize()]
10cc0 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 or after shutdow
10cd0 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 n by [sqlite3_sh
10ce0 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 utdown()]..** ^I
10cf0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 f sqlite3_config
10d00 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 () is called aft
10d10 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 er [sqlite3_init
10d20 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 ialize()] and be
10d30 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 fore.** [sqlite3
10d40 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 _shutdown()] the
10d50 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e n it will return
10d60 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a SQLITE_MISUSE..
10d70 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 ** Note, however
10d80 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f , that ^sqlite3_
10d90 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 config() can be
10da0 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f called as part o
10db0 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 f the.** impleme
10dc0 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 ntation of an ap
10dd0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
10de0 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e d [sqlite3_os_in
10df0 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 it()]..**.** The
10e00 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
10e10 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 to sqlite3_confi
10e20 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 g() is an intege
10e30 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 r.** [configurat
10e40 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 ion option] that
10e50 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 determines.** w
10e60 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 hat property of
10e70 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 SQLite is to be
10e80 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 configured. Sub
10e90 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 sequent argument
10ea0 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 s.** vary depend
10eb0 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 ing on the [conf
10ec0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
10ed0 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 ].** in the firs
10ee0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a t argument..**.*
10ef0 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 * ^When a config
10f00 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 uration option i
10f10 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 s set, sqlite3_c
10f20 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 onfig() returns
10f30 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 [SQLITE_OK]..**
10f40 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 ^If the option i
10f50 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c s unknown or SQL
10f60 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f ite is unable to
10f70 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a set the option.
10f80 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 ** then this rou
10f90 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e tine returns a n
10fa0 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 on-zero [error c
10fb0 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c ode]..*/.int sql
10fc0 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c ite3_config(int,
10fd0 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ...);../*.** CA
10fe0 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 PI3REF: Configur
10ff0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
11000 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 ctions.** METHOD
11010 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
11020 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 The sqlite3_db_c
11030 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 onfig() interfac
11040 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b e is used to mak
11050 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a e configuration.
11060 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 ** changes to a
11070 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
11080 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 tion]. The inte
11090 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 rface is similar
110a0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
110b0 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 config()] except
110c0 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 that the change
110d0 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e s apply to a sin
110e0 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 gle.** [database
110f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 connection] (sp
11100 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 ecified in the f
11110 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a irst argument)..
11120 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 **.** The second
11130 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
11140 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 ite3_db_config(D
11150 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a ,V,...) is the.
11160 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e ** [SQLITE_DBCON
11170 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 FIG_LOOKASIDE |
11180 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 configuration ve
11190 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 rb] - an integer
111a0 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 code .** that i
111b0 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73 ndicates what as
111c0 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 pect of the [dat
111d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
111e0 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 ] is being confi
111f0 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 gured..** Subseq
11200 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 uent arguments v
11210 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e ary depending on
11220 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 the configurati
11230 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e on verb..**.** ^
11240 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 Calls to sqlite3
11250 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 _db_config() ret
11260 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 urn SQLITE_OK if
11270 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 and only if.**
11280 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 the call is cons
11290 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75 idered successfu
112a0 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 l..*/.int sqlite
112b0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 3_db_config(sqli
112c0 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e te3*, int op, ..
112d0 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
112e0 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f REF: Memory Allo
112f0 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a cation Routines.
11300 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 **.** An instanc
11310 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 e of this object
11320 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 defines the int
11330 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 erface between S
11340 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 QLite.** and low
11350 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c -level memory al
11360 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 location routine
11370 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 s..**.** This ob
11380 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 ject is used in
11390 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 only one place i
113a0 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 n the SQLite int
113b0 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 erface..** A poi
113c0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 nter to an insta
113d0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 nce of this obje
113e0 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 ct is the argume
113f0 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 nt to.** [sqlite
11400 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 3_config()] when
11410 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 the configurati
11420 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 on option is.**
11430 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
11440 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 ALLOC] or [SQLIT
11450 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c E_CONFIG_GETMALL
11460 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 OC]. .** By cre
11470 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 ating an instanc
11480 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 e of this object
11490 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 .** and passing
114a0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 it to [sqlite3_c
114b0 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 onfig]([SQLITE_C
114c0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a ONFIG_MALLOC]).*
114d0 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 * during configu
114e0 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 ration, an appli
114f0 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 cation can speci
11500 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 fy an alternativ
11510 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f e.** memory allo
11520 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d cation subsystem
11530 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 for SQLite to u
11540 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 se for all of it
11550 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d s.** dynamic mem
11560 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a ory needs..**.**
11570 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 Note that SQLit
11580 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 e comes with sev
11590 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d eral [built-in m
115a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 emory allocators
115b0 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 ].** that are pe
115c0 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 rfectly adequate
115d0 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 for the overwhe
115e0 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f lming majority o
115f0 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a f applications.*
11600 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 * and that this
11610 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 object is only u
11620 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 seful to a tiny
11630 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c minority of appl
11640 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 ications.** with
11650 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d specialized mem
11660 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
11670 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 equirements. Th
11680 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 is object is.**
11690 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 also used during
116a0 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 testing of SQLi
116b0 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 te in order to s
116c0 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e pecify an altern
116d0 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 ative.** memory
116e0 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 allocator that s
116f0 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 imulates memory
11700 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f out-of-memory co
11710 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f nditions in.** o
11720 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 rder to verify t
11730 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 hat SQLite recov
11740 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 ers gracefully f
11750 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 rom such.** cond
11760 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 itions..**.** Th
11770 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c e xMalloc, xReal
11780 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d loc, and xFree m
11790 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b ethods must work
117a0 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c like the.** mal
117b0 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 loc(), realloc()
117c0 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 and free() func
117d0 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 tions from the s
117e0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 tandard C librar
117f0 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 y..** ^SQLite gu
11800 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 arantees that th
11810 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
11820 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 t to.** xRealloc
11830 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c is always a val
11840 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 ue returned by a
11850 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 prior call to x
11860 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 Roundup..**.** x
11870 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 Size should retu
11880 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 rn the allocated
11890 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 size of a memor
118a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 y allocation.**
118b0 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 previously obtai
118c0 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 ned from xMalloc
118d0 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 or xRealloc. T
118e0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a he allocated siz
118f0 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 e.** is always a
11900 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 t least as big a
11910 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 s the requested
11920 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 size but may be
11930 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 larger..**.** Th
11940 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f e xRoundup metho
11950 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 d returns what w
11960 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f ould be the allo
11970 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a cated size of.**
11980 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
11990 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 tion given a par
119a0 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 ticular requeste
119b0 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 d size. Most me
119c0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f mory.** allocato
119d0 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f rs round up memo
119e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 ry allocations a
119f0 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e t least to the n
11a00 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 ext multiple.**
11a10 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f of 8. Some allo
11a20 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 cators round up
11a30 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 to a larger mult
11a40 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 iple or to a pow
11a50 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 er of 2..** Ever
11a60 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 y memory allocat
11a70 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 ion request comi
11a80 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 ng in through [s
11a90 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
11aa0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f .** or [sqlite3_
11ab0 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 realloc()] first
11ac0 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e calls xRoundup.
11ad0 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 If xRoundup re
11ae0 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 turns 0, .** tha
11af0 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 t causes the cor
11b00 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 responding memor
11b10 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 y allocation to
11b20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 fail..**.** The
11b30 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 xInit method ini
11b40 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d tializes the mem
11b50 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 ory allocator.
11b60 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 For example,.**
11b70 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 it might allocat
11b80 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 e any require mu
11b90 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c texes or initial
11ba0 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 ize internal dat
11bb0 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e a.** structures.
11bc0 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 The xShutdown
11bd0 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 method is invoke
11be0 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 d (indirectly) b
11bf0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 y.** [sqlite3_sh
11c00 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 utdown()] and sh
11c10 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 ould deallocate
11c20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 any resources ac
11c30 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e quired.** by xIn
11c40 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 it. The pAppDat
11c50 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 a pointer is use
11c60 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 d as the only pa
11c70 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 rameter to.** xI
11c80 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 nit and xShutdow
11c90 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 n..**.** SQLite
11ca0 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 holds the [SQLIT
11cb0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d E_MUTEX_STATIC_M
11cc0 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 ASTER] mutex whe
11cd0 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 n it invokes.**
11ce0 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 the xInit method
11cf0 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d , so the xInit m
11d00 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 ethod need not b
11d10 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 e threadsafe. T
11d20 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 he.** xShutdown
11d30 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 method is only c
11d40 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 alled from [sqli
11d50 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 te3_shutdown()]
11d60 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f so it does.** no
11d70 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 t need to be thr
11d80 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 eadsafe either.
11d90 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d For all other m
11da0 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a ethods, SQLite.*
11db0 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c * holds the [SQL
11dc0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 ITE_MUTEX_STATIC
11dd0 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c _MEM] mutex as l
11de0 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 ong as the.** [S
11df0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d QLITE_CONFIG_MEM
11e00 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 STATUS] configur
11e10 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 ation option is
11e20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 turned on (which
11e30 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 .** it is by def
11e40 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 ault) and so the
11e50 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 methods are aut
11e60 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 omatically seria
11e70 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 lized..** Howeve
11e80 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f r, if [SQLITE_CO
11e90 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 NFIG_MEMSTATUS]
11ea0 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 is disabled, the
11eb0 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d n the other.** m
11ec0 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 ethods must be t
11ed0 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 hreadsafe or els
11ee0 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e e make their own
11ef0 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f arrangements fo
11f00 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 r.** serializati
11f10 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 on..**.** SQLite
11f20 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f will never invo
11f30 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 ke xInit() more
11f40 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 than once withou
11f50 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 t an intervening
11f60 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 .** call to xShu
11f70 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 tdown()..*/.type
11f80 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
11f90 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 e3_mem_methods s
11fa0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
11fb0 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 ds;.struct sqlit
11fc0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b e3_mem_methods {
11fd0 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c . void *(*xMall
11fe0 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 oc)(int);
11ff0 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f /* Memory allo
12000 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 cation function
12010 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 */. void (*xFre
12020 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 e)(void*);
12030 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 /* Free a pr
12040 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a ior allocation *
12050 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 /. void *(*xRea
12060 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 lloc)(void*,int)
12070 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 ; /* Resize an
12080 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 allocation */.
12090 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 int (*xSize)(voi
120a0 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f d*); /
120b0 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a * Return the siz
120c0 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 e of an allocati
120d0 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 on */. int (*xR
120e0 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 oundup)(int);
120f0 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 /* Round
12100 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 up request size
12110 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 to allocation si
12120 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 ze */. int (*xI
12130 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 nit)(void*);
12140 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 /* Initia
12150 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 lize the memory
12160 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 allocator */. v
12170 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 oid (*xShutdown)
12180 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a (void*); /*
12190 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 Deinitialize th
121a0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
121b0 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 or */. void *pA
121c0 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 ppData;
121d0 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 /* Argume
121e0 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e nt to xInit() an
121f0 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f d xShutdown() */
12200 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
12210 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 REF: Configurati
12220 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 on Options.** KE
12230 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 YWORDS: {configu
12240 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a ration option}.*
12250 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 *.** These const
12260 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 ants are the ava
12270 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 ilable integer c
12280 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
12290 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e ions that.** can
122a0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 be passed as th
122b0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
122c0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
122d0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 _config()] inter
122e0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 face..**.** New
122f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
12300 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 tions may be add
12310 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c ed in future rel
12320 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e eases of SQLite.
12330 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e .** Existing con
12340 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
12350 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 ns might be disc
12360 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 ontinued. Appli
12370 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c cations.** shoul
12380 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 d check the retu
12390 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 rn code from [sq
123a0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
123b0 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 to make sure tha
123c0 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f t.** the call wo
123d0 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 rked. The [sqli
123e0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e te3_config()] in
123f0 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 terface will ret
12400 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 urn a.** non-zer
12410 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 o [error code] i
12420 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 f a discontinued
12430 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 or unsupported
12440 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
12450 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b tion.** is invok
12460 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a ed..**.** <dl>.*
12470 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
12480 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d G_SINGLETHREAD]]
12490 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
124a0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c IG_SINGLETHREAD<
124b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 /dt>.** <dd>Ther
124c0 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e e are no argumen
124d0 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f ts to this optio
124e0 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e n. ^This option
124f0 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 sets the.** [th
12500 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f reading mode] to
12510 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 Single-thread.
12520 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c In other words,
12530 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 it disables.**
12540 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 all mutexing and
12550 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 puts SQLite int
12560 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 o a mode where i
12570 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 t can only be us
12580 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c ed.** by a singl
12590 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 e thread. ^If
125a0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
125b0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b ed with.** the [
125c0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
125d0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 E | SQLITE_THREA
125e0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 DSAFE=0] compile
125f0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 -time option the
12600 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 n.** it is not p
12610 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 ossible to chang
12620 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 e the [threading
12630 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 mode] from its
12640 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 default.** value
12650 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 of Single-threa
12660 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 d and so [sqlite
12670 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 3_config()] will
12680 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c return .** [SQL
12690 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 ITE_ERROR] if ca
126a0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 lled with the SQ
126b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
126c0 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 LETHREAD.** conf
126d0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
126e0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 .</dd>.**.** [[S
126f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c QLITE_CONFIG_MUL
12700 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 TITHREAD]] <dt>S
12710 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c QLITE_CONFIG_MUL
12720 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a TITHREAD</dt>.**
12730 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e <dd>There are n
12740 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 o arguments to t
12750 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 his option. ^Th
12760 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 is option sets t
12770 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 he.** [threading
12780 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d mode] to Multi-
12790 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 thread. In othe
127a0 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 r words, it disa
127b0 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 bles.** mutexing
127c0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f on [database co
127d0 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 nnection] and [p
127e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
127f0 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 t] objects..** T
12800 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 he application i
12810 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f s responsible fo
12820 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 r serializing ac
12830 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 cess to.** [data
12840 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
12850 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 ] and [prepared
12860 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 statements]. Bu
12870 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a t other mutexes.
12880 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 ** are enabled s
12890 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 o that SQLite wi
128a0 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 ll be safe to us
128b0 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 e in a multi-thr
128c0 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e eaded.** environ
128d0 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 ment as long as
128e0 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 no two threads a
128f0 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 ttempt to use th
12900 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 e same.** [datab
12910 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
12920 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 at the same time
12930 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 . ^If SQLite is
12940 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a compiled with.*
12950 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 * the [SQLITE_TH
12960 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 READSAFE | SQLIT
12970 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 E_THREADSAFE=0]
12980 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
12990 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 ion then.** it i
129a0 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 s not possible t
129b0 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d o set the Multi-
129c0 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e thread [threadin
129d0 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b g mode] and.** [
129e0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
129f0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 ] will return [S
12a00 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 QLITE_ERROR] if
12a10 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a called with the.
12a20 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ** SQLITE_CONFIG
12a30 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e _MULTITHREAD con
12a40 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
12a50 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b n.</dd>.**.** [[
12a60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 SQLITE_CONFIG_SE
12a70 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 RIALIZED]] <dt>S
12a80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 QLITE_CONFIG_SER
12a90 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 IALIZED</dt>.**
12aa0 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f <dd>There are no
12ab0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 arguments to th
12ac0 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 is option. ^Thi
12ad0 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 s option sets th
12ae0 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 e.** [threading
12af0 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 mode] to Seriali
12b00 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f zed. In other wo
12b10 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e rds, this option
12b20 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 enables.** all
12b30 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e mutexes includin
12b40 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a g the recursive.
12b50 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 ** mutexes on [d
12b60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
12b70 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 on] and [prepare
12b80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a d statement] obj
12b90 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 ects..** In this
12ba0 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 mode (which is
12bb0 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e the default when
12bc0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
12bd0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c led with.** [SQL
12be0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 ITE_THREADSAFE=1
12bf0 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 ]) the SQLite li
12c00 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c brary will itsel
12c10 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 f serialize acce
12c20 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 ss.** to [databa
12c30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 se connections]
12c40 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 and [prepared st
12c50 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 atements] so tha
12c60 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 t the.** applica
12c70 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 tion is free to
12c80 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 use the same [da
12c90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
12ca0 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d n] or the.** sam
12cb0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
12cc0 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 ement] in differ
12cd0 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 ent threads at t
12ce0 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a he same time..**
12cf0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 ^If SQLite is c
12d00 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 ompiled with.**
12d10 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 the [SQLITE_THRE
12d20 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f ADSAFE | SQLITE_
12d30 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f THREADSAFE=0] co
12d40 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
12d50 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 n then.** it is
12d60 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 not possible to
12d70 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a set the Serializ
12d80 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ed [threading mo
12d90 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 de] and.** [sqli
12da0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 te3_config()] wi
12db0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ll return [SQLIT
12dc0 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c E_ERROR] if call
12dd0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 ed with the.** S
12de0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 QLITE_CONFIG_SER
12df0 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 IALIZED configur
12e00 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 ation option.</d
12e10 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
12e20 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d E_CONFIG_MALLOC]
12e30 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
12e40 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a FIG_MALLOC</dt>.
12e50 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 ** <dd> ^(The SQ
12e60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c LITE_CONFIG_MALL
12e70 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 OC option takes
12e80 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
12e90 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 t which is .** a
12ea0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
12eb0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b nstance of the [
12ec0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
12ed0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a ods] structure..
12ee0 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 ** The argument
12ef0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 specifies.** alt
12f00 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 ernative low-lev
12f10 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 el memory alloca
12f20 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f tion routines to
12f30 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 be used in plac
12f40 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f e of.** the memo
12f50 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f ry allocation ro
12f60 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 utines built int
12f70 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c o SQLite.)^ ^SQL
12f80 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 ite makes.** its
12f90 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 own private cop
12fa0 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 y of the content
12fb0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
12fc0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 _mem_methods] st
12fd0 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 ructure.** befor
12fe0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 e the [sqlite3_c
12ff0 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 onfig()] call re
13000 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a turns.</dd>.**.*
13010 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
13020 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 G_GETMALLOC]] <d
13030 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
13040 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a GETMALLOC</dt>.*
13050 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c * <dd> ^(The SQL
13060 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 ITE_CONFIG_GETMA
13070 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 LLOC option take
13080 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
13090 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 ent which.** is
130a0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
130b0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
130c0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 [sqlite3_mem_met
130d0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e hods] structure.
130e0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 .** The [sqlite3
130f0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a _mem_methods].**
13100 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 structure is fi
13110 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 lled with the cu
13120 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 rrently defined
13130 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
13140 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a n routines.)^.**
13150 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e This option can
13160 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 be used to over
13170 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 load the default
13180 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
13190 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 on.** routines w
131a0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 ith a wrapper th
131b0 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d at simulations m
131c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
131d0 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 failure or.** t
131e0 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 racks memory usa
131f0 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e ge, for example.
13200 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 </dd>.**.** [[S
13210 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d QLITE_CONFIG_MEM
13220 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c STATUS]] <dt>SQL
13230 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 ITE_CONFIG_MEMST
13240 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 ATUS</dt>.** <dd
13250 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f > ^The SQLITE_CO
13260 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f NFIG_MEMSTATUS o
13270 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 ption takes sing
13280 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 le argument of t
13290 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 ype int,.** inte
132a0 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f rpreted as a boo
132b0 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 lean, which enab
132c0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 les or disables
132d0 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f the collection o
132e0 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f f.** memory allo
132f0 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 cation statistic
13300 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 s. ^(When memory
13310 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 allocation stat
13320 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 istics are.** di
13330 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c sabled, the foll
13340 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 owing SQLite int
13350 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e erfaces become n
13360 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a on-operational:.
13370 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c ** <ul>.** <
13380 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d li> [sqlite3_mem
13390 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 ory_used()].**
133a0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d <li> [sqlite3_m
133b0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 emory_highwater(
133c0 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 )].** <li> [sq
133d0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f lite3_soft_heap_
133e0 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 limit64()].**
133f0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 <li> [sqlite3_st
13400 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c atus64()].** <
13410 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 /ul>)^.** ^Memor
13420 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 y allocation sta
13430 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 tistics are enab
13440 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 led by default u
13450 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a nless SQLite is.
13460 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 ** compiled with
13470 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 [SQLITE_DEFAULT
13480 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e _MEMSTATUS]=0 in
13490 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f which case memo
134a0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e ry.** allocation
134b0 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 statistics are
134c0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 disabled by defa
134d0 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a ult..** </dd>.**
134e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
134f0 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 FIG_SCRATCH]] <d
13500 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
13510 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 SCRATCH</dt>.**
13520 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 <dd> ^The SQLITE
13530 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 _CONFIG_SCRATCH
13540 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 option specifies
13550 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 a static memory
13560 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 buffer.** that
13570 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 SQLite can use f
13580 6f 72 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 or scratch memor
13590 79 2e 20 20 5e 28 54 68 65 72 65 20 61 72 65 20 y. ^(There are
135a0 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 0a three arguments.
135b0 2a 2a 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e ** to SQLITE_CON
135c0 46 49 47 5f 53 43 52 41 54 43 48 3a 20 20 41 20 FIG_SCRATCH: A
135d0 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 pointer an 8-byt
135e0 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d e.** aligned mem
135f0 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 ory buffer from
13600 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63 which the scratc
13610 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 h allocations wi
13620 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 ll be.** drawn,
13630 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 the size of each
13640 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 scratch allocat
13650 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 ion (sz),.** and
13660 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d the maximum num
13670 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 ber of scratch a
13680 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29 llocations (N).)
13690 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 ^.** The first a
136a0 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 rgument must be
136b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
136c0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 8-byte aligned b
136d0 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c uffer.** of at l
136e0 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 east sz*N bytes
136f0 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 of memory..** ^S
13700 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75 QLite will not u
13710 73 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 se more than one
13720 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73 scratch buffers
13730 20 70 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20 per thread..**
13740 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 ^SQLite will nev
13750 65 72 20 72 65 71 75 65 73 74 20 61 20 73 63 72 er request a scr
13760 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74 atch buffer that
13770 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a is more than 6.
13780 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 ** times the dat
13790 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e abase page size.
137a0 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 6e .** ^If SQLite n
137b0 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 eeds needs addit
137c0 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 ional.** scratch
137d0 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 memory beyond w
137e0 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 hat is provided
137f0 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 by this configur
13800 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 ation option, th
13810 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f en .** [sqlite3_
13820 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 malloc()] will b
13830 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e e used to obtain
13840 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 the memory need
13850 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 ed.<p>.** ^When
13860 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
13870 70 72 6f 76 69 64 65 73 20 61 6e 79 20 61 6d 6f provides any amo
13880 75 6e 74 20 6f 66 20 73 63 72 61 74 63 68 20 6d unt of scratch m
13890 65 6d 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53 emory using.** S
138a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 QLITE_CONFIG_SCR
138b0 41 54 43 48 2c 20 53 51 4c 69 74 65 20 61 76 6f ATCH, SQLite avo
138c0 69 64 73 20 75 6e 6e 65 63 65 73 73 61 72 79 20 ids unnecessary
138d0 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 large.** [sqlite
138e0 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 3_malloc|heap al
138f0 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 locations]..** T
13900 68 69 73 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f his can help [Ro
13910 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65 bson proof|preve
13920 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 nt memory alloca
13930 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20 64 tion failures] d
13940 75 65 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72 ue to heap.** fr
13950 61 67 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c agmentation in l
13960 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64 ow-memory embedd
13970 65 64 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c ed systems..** <
13980 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
13990 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 ITE_CONFIG_PAGEC
139a0 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 ACHE]] <dt>SQLIT
139b0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
139c0 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 HE</dt>.** <dd>
139d0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 ^The SQLITE_CONF
139e0 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74 IG_PAGECACHE opt
139f0 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 ion specifies a
13a00 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 memory pool.** t
13a10 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 hat SQLite can u
13a20 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 se for the datab
13a30 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 ase page cache w
13a40 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 ith the default
13a50 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d page.** cache im
13a60 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a plementation. .
13a70 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 ** This configur
13a80 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 ation option is
13a90 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70 a no-op if an ap
13aa0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
13ab0 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 page.** cache i
13ac0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 mplementation is
13ad0 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 loaded using th
13ae0 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 e [SQLITE_CONFIG
13af0 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 _PCACHE2]..** ^T
13b00 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 here are three a
13b10 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 rguments to SQLI
13b20 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
13b30 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 CHE: A pointer t
13b40 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 o.** 8-byte alig
13b50 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d ned memory (pMem
13b60 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 ), the size of e
13b70 61 63 68 20 70 61 67 65 20 63 61 63 68 65 20 6c ach page cache l
13b80 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 ine (sz),.** and
13b90 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 the number of c
13ba0 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a ache lines (N)..
13bb0 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 ** The sz argume
13bc0 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 nt should be the
13bd0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 size of the lar
13be0 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 gest database pa
13bf0 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f ge.** (a power o
13c00 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 f two between 51
13c10 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 2 and 65536) plu
13c20 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 s some extra byt
13c30 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 es for each.** p
13c40 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 age header. ^Th
13c50 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 e number of extr
13c60 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 a bytes needed b
13c70 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64 65 y the page heade
13c80 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 r.** can be dete
13c90 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51 rmined using [SQ
13ca0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
13cb0 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 HE_HDRSZ]..** ^I
13cc0 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 t is harmless, a
13cd0 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 part from the wa
13ce0 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 sted memory,.**
13cf0 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d for the sz param
13d00 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65 eter to be large
13d10 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79 r than necessary
13d20 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 . The pMem.** a
13d30 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 rgument must be
13d40 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f either a NULL po
13d50 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74 inter or a point
13d60 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a er to an 8-byte.
13d70 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b ** aligned block
13d80 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 of memory of at
13d90 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 least sz*N byte
13da0 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 s, otherwise.**
13db0 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 subsequent behav
13dc0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ior is undefined
13dd0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20 ..** ^When pMem
13de0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c is not NULL, SQL
13df0 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20 ite will strive
13e00 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 to use the memor
13e10 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f y provided.** to
13e20 20 73 61 74 69 73 66 79 20 70 61 67 65 20 63 61 satisfy page ca
13e30 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69 che needs, falli
13e40 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69 ng back to [sqli
13e50 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 te3_malloc()] if
13e60 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68 65 .** a page cache
13e70 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20 line is larger
13e80 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72 than sz bytes or
13e90 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70 if all of the p
13ea0 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 Mem buffer.** is
13eb0 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e exhausted..** ^
13ec0 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 If pMem is NULL
13ed0 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 and N is non-zer
13ee0 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61 74 o, then each dat
13ef0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
13f00 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74 .** does an init
13f10 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 ial bulk allocat
13f20 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63 ion for page cac
13f30 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f he memory.** fro
13f40 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f m [sqlite3_mallo
13f50 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20 c()] sufficient
13f60 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65 for N cache line
13f70 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 s if N is positi
13f80 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 ve or.** of -102
13f90 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69 4*N bytes if N i
13fa0 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49 s negative, . ^I
13fb0 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 f additional.**
13fc0 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 page cache memor
13fd0 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f y is needed beyo
13fe0 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 nd what is provi
13ff0 64 65 64 20 62 79 20 74 68 65 20 69 6e 69 74 69 ded by the initi
14000 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e al.** allocation
14010 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f , then SQLite go
14020 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d es to [sqlite3_m
14030 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74 alloc()] separat
14040 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 ely for each.**
14050 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65 additional cache
14060 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a line. </dd>.**.
14070 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
14080 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 IG_HEAP]] <dt>SQ
14090 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 LITE_CONFIG_HEAP
140a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 </dt>.** <dd> ^T
140b0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
140c0 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 _HEAP option spe
140d0 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 cifies a static
140e0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a memory buffer .*
140f0 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 * that SQLite wi
14100 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f ll use for all o
14110 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 f its dynamic me
14120 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
14130 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 needs.** beyond
14140 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 those provided f
14150 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f or by [SQLITE_CO
14160 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e NFIG_SCRATCH] an
14170 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e d.** [SQLITE_CON
14180 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a FIG_PAGECACHE]..
14190 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 ** ^The SQLITE_C
141a0 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f ONFIG_HEAP optio
141b0 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 n is only availa
141c0 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 ble if SQLite is
141d0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 compiled.** wit
141e0 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 h either [SQLITE
141f0 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d _ENABLE_MEMSYS3]
14200 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 or [SQLITE_ENAB
14210 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 LE_MEMSYS5] and
14220 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 returns.** [SQLI
14230 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 TE_ERROR] if inv
14240 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a oked otherwise..
14250 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 ** ^There are th
14260 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f ree arguments to
14270 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 SQLITE_CONFIG_H
14280 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 EAP:.** An 8-byt
14290 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 e aligned pointe
142a0 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c r to the memory,
142b0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f .** the number o
142c0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d f bytes in the m
142d0 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e emory buffer, an
142e0 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c d the minimum al
142f0 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a location size..*
14300 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 * ^If the first
14310 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d pointer (the mem
14320 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 ory pointer) is
14330 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 NULL, then SQLit
14340 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 e reverts.** to
14350 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c using its defaul
14360 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 t memory allocat
14370 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d or (the system m
14380 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e alloc() implemen
14390 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f tation),.** undo
143a0 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e ing any prior in
143b0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c vocation of [SQL
143c0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f ITE_CONFIG_MALLO
143d0 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 C]. ^If the.**
143e0 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 memory pointer i
143f0 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 s not NULL then
14400 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 the alternative
14410 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 memory.** alloca
14420 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 tor is engaged t
14430 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 o handle all of
14440 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 SQLites memory a
14450 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e llocation needs.
14460 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f .** The first po
14470 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 inter (the memor
14480 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 y pointer) must
14490 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e be aligned to an
144a0 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 8-byte.** bound
144b0 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e ary or subsequen
144c0 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 t behavior of SQ
144d0 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 Lite will be und
144e0 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d efined..** The m
144f0 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f inimum allocatio
14500 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 n size is capped
14510 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f at 2**12. Reaso
14520 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 nable values.**
14530 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 for the minimum
14540 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 allocation size
14550 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 are 2**5 through
14560 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2**8.</dd>.**.*
14570 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
14580 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 G_MUTEX]] <dt>SQ
14590 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 LITE_CONFIG_MUTE
145a0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e X</dt>.** <dd> ^
145b0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 (The SQLITE_CONF
145c0 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 IG_MUTEX option
145d0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
145e0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
145f0 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f a.** pointer to
14600 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 an instance of
14610 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 the [sqlite3_mut
14620 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 ex_methods] stru
14630 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 cture..** The ar
14640 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 gument specifies
14650 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 alternative low
14660 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 -level mutex rou
14670 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 tines to be used
14680 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 .** in place the
14690 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 mutex routines
146a0 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 built into SQLit
146b0 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 e.)^ ^SQLite ma
146c0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a kes a copy of.**
146d0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
146e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 the [sqlite3_mut
146f0 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 ex_methods] stru
14700 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 cture before the
14710 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c call to.** [sql
14720 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 ite3_config()] r
14730 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 eturns. ^If SQLi
14740 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
14750 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 ith.** the [SQLI
14760 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 TE_THREADSAFE |
14770 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
14780 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d E=0] compile-tim
14790 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a e option then.**
147a0 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 the entire mute
147b0 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 xing subsystem i
147c0 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 s omitted from t
147d0 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e he build and hen
147e0 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b ce calls to.** [
147f0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
14800 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 ] with the SQLIT
14810 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 E_CONFIG_MUTEX c
14820 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
14830 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 ion will.** retu
14840 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 rn [SQLITE_ERROR
14850 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b ].</dd>.**.** [[
14860 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
14870 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c TMUTEX]] <dt>SQL
14880 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 ITE_CONFIG_GETMU
14890 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TEX</dt>.** <dd>
148a0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f ^(The SQLITE_CO
148b0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 NFIG_GETMUTEX op
148c0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e tion takes a sin
148d0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 gle argument whi
148e0 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 ch.** is a point
148f0 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 er to an instanc
14900 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 e of the [sqlite
14910 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 3_mutex_methods]
14920 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 structure. The
14930 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 .** [sqlite3_mut
14940 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 ex_methods].** s
14950 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c tructure is fill
14960 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 ed with the curr
14970 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 ently defined mu
14980 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a tex routines.)^.
14990 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 ** This option c
149a0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 an be used to ov
149b0 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 erload the defau
149c0 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 lt mutex allocat
149d0 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 ion.** routines
149e0 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 with a wrapper u
149f0 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 sed to track mut
14a00 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 ex usage for per
14a10 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 formance.** prof
14a20 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 iling or testing
14a30 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 , for example.
14a40 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 ^If SQLite is c
14a50 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 ompiled with.**
14a60 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 the [SQLITE_THRE
14a70 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f ADSAFE | SQLITE_
14a80 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f THREADSAFE=0] co
14a90 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
14aa0 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e n then.** the en
14ab0 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 tire mutexing su
14ac0 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 bsystem is omitt
14ad0 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c ed from the buil
14ae0 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c d and hence call
14af0 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 s to.** [sqlite3
14b00 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 _config()] with
14b10 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 the SQLITE_CONFI
14b20 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 G_GETMUTEX confi
14b30 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 guration option
14b40 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b will.** return [
14b50 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f SQLITE_ERROR].</
14b60 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
14b70 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 TE_CONFIG_LOOKAS
14b80 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 IDE]] <dt>SQLITE
14b90 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 _CONFIG_LOOKASID
14ba0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e E</dt>.** <dd> ^
14bb0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 (The SQLITE_CONF
14bc0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 IG_LOOKASIDE opt
14bd0 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 ion takes two ar
14be0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 guments that det
14bf0 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 ermine.** the de
14c00 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f fault size of lo
14c10 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f okaside memory o
14c20 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 n each [database
14c30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a connection]..**
14c40 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
14c50 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 ent is the.** si
14c60 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 ze of each looka
14c70 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 side buffer slot
14c80 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 and the second
14c90 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 is the number of
14ca0 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 .** slots alloca
14cb0 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 ted to each data
14cc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e base connection.
14cd0 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e )^ ^(SQLITE_CON
14ce0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a FIG_LOOKASIDE.**
14cf0 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 sets the <i>def
14d00 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 ault</i> lookasi
14d10 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 de size. The [SQ
14d20 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f LITE_DBCONFIG_LO
14d30 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 OKASIDE].** opti
14d40 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 on to [sqlite3_d
14d50 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 b_config()] can
14d60 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 be used to chang
14d70 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a e the lookaside.
14d80 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ** configuration
14d90 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 on individual c
14da0 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f onnections.)^ </
14db0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
14dc0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
14dd0 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 2]] <dt>SQLITE_C
14de0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 ONFIG_PCACHE2</d
14df0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 t>.** <dd> ^(The
14e00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
14e10 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 CACHE2 option ta
14e20 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
14e30 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a ument which is .
14e40 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ** a pointer to
14e50 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 an [sqlite3_pcac
14e60 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a he_methods2] obj
14e70 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 ect. This objec
14e80 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 t specifies.** t
14e90 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 he interface to
14ea0 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 a custom page ca
14eb0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 che implementati
14ec0 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 on.)^.** ^SQLite
14ed0 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 makes a copy of
14ee0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 the [sqlite3_pc
14ef0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f ache_methods2] o
14f00 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a bject.</dd>.**.*
14f10 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
14f20 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c G_GETPCACHE2]] <
14f30 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
14f40 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e _GETPCACHE2</dt>
14f50 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 .** <dd> ^(The S
14f60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
14f70 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 PCACHE2 option t
14f80 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
14f90 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 gument which.**
14fa0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
14fb0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 an [sqlite3_pcac
14fc0 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a he_methods2] obj
14fd0 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 ect. SQLite cop
14fe0 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 ies of.** the cu
14ff0 72 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 rrent page cache
15000 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
15010 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 into that object
15020 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 .)^ </dd>.**.**
15030 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
15040 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 LOG]] <dt>SQLITE
15050 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e _CONFIG_LOG</dt>
15060 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c .** <dd> The SQL
15070 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f ITE_CONFIG_LOG o
15080 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f ption is used to
15090 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 configure the S
150a0 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 QLite.** global
150b0 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 [error log]..**
150c0 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e (^The SQLITE_CON
150d0 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 FIG_LOG option t
150e0 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e akes two argumen
150f0 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f ts: a pointer to
15100 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 a.** function w
15110 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 ith a call signa
15120 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 ture of void(*)(
15130 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 void*,int,const
15140 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 char*), .** and
15150 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 a pointer to voi
15160 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 d. ^If the funct
15170 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e ion pointer is n
15180 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a ot NULL, it is.*
15190 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 * invoked by [sq
151a0 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 lite3_log()] to
151b0 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 process each log
151c0 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 ging event. ^If
151d0 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e the.** function
151e0 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c pointer is NULL
151f0 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c , the [sqlite3_l
15200 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 og()] interface
15210 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e becomes a no-op.
15220 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f .** ^The void po
15230 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 inter that is th
15240 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
15250 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 t to SQLITE_CONF
15260 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 IG_LOG is.** pas
15270 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 sed through as t
15280 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
15290 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 er to the applic
152a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f ation-defined lo
152b0 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e gger.** function
152c0 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 whenever that f
152d0 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b unction is invok
152e0 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 ed. ^The second
152f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
15300 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 the logger func
15310 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f tion is a copy o
15320 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 f the first para
15330 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 meter to the cor
15340 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 responding.** [s
15350 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 qlite3_log()] ca
15360 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 ll and is intend
15370 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 ed to be a [resu
15380 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a lt code] or an.*
15390 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 * [extended resu
153a0 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 lt code]. ^The
153b0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
153c0 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f passed to the lo
153d0 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d gger is.** log m
153e0 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 essage after for
153f0 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c matting via [sql
15400 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d ite3_snprintf()]
15410 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 ..** The SQLite
15420 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 logging interfac
15430 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 e is not reentra
15440 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 nt; the logger f
15450 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c unction.** suppl
15460 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 ied by the appli
15470 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 cation must not
15480 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 invoke any SQLit
15490 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 e interface..**
154a0 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 In a multi-threa
154b0 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c ded application,
154c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
154d0 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a -defined logger.
154e0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 ** function must
154f0 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 be threadsafe.
15500 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
15510 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d LITE_CONFIG_URI]
15520 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
15530 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e FIG_URI.** <dd>^
15540 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 (The SQLITE_CONF
15550 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 IG_URI option ta
15560 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
15570 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e ument of type in
15580 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 t..** If non-zer
15590 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 o, then URI hand
155a0 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 ling is globally
155b0 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 enabled. If the
155c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 parameter is ze
155d0 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 ro,.** then URI
155e0 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 handling is glob
155f0 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e ally disabled.)^
15600 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e ^If URI handlin
15610 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a g is globally.**
15620 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 enabled, all fi
15630 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 lenames passed t
15640 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 o [sqlite3_open(
15650 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
15660 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c n_v2()],.** [sql
15670 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f ite3_open16()] o
15680 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 r.** specified a
15690 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 s part of [ATTAC
156a0 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 H] commands are
156b0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 interpreted as U
156c0 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a RIs, regardless.
156d0 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 ** of whether or
156e0 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 not the [SQLITE
156f0 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 _OPEN_URI] flag
15700 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 is set when the
15710 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
15720 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 ection is opened
15730 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 . ^If it is glob
15740 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 ally disabled, f
15750 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 ilenames are.**
15760 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 only interpreted
15770 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20 as URIs if the
15780 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 SQLITE_OPEN_URI
15790 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e flag is set when
157a0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 the.** database
157b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f connection is o
157c0 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 pened. ^(By defa
157d0 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e ult, URI handlin
157e0 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a g is globally.**
157f0 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 disabled. The d
15800 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 efault value may
15810 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 be changed by c
15820 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 ompiling with th
15830 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 e.** [SQLITE_USE
15840 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 _URI] symbol def
15850 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b ined.)^.**.** [[
15860 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f SQLITE_CONFIG_CO
15870 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 VERING_INDEX_SCA
15880 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 N]] <dt>SQLITE_C
15890 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 ONFIG_COVERING_I
158a0 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 NDEX_SCAN.** <dd
158b0 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e >^The SQLITE_CON
158c0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 FIG_COVERING_IND
158d0 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 EX_SCAN option t
158e0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e akes a single in
158f0 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e teger.** argumen
15900 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 t which is inter
15910 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c preted as a bool
15920 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 ean in order to
15930 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c enable or disabl
15940 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 e.** the use of
15950 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 covering indices
15960 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 for full table
15970 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 scans in the que
15980 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a ry optimizer..**
15990 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 ^The default se
159a0 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 tting is determi
159b0 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 ned.** by the [S
159c0 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 QLITE_ALLOW_COVE
159d0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d RING_INDEX_SCAN]
159e0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
159f0 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 tion, or is "on"
15a00 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 .** if that comp
15a10 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
15a20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 is omitted..** T
15a30 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 he ability to di
15a40 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 sable the use of
15a50 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 covering indice
15a60 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 s for full table
15a70 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 scans.** is bec
15a80 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 ause some incorr
15a90 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 ectly coded lega
15aa0 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 cy applications
15ab0 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f might malfunctio
15ac0 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 n.** when the op
15ad0 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e timization is en
15ae0 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e abled. Providin
15af0 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f g the ability to
15b00 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 .** disable the
15b10 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c optimization all
15b20 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 ows the older, b
15b30 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e uggy application
15b40 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a code to work.**
15b50 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 without change
15b60 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 even with newer
15b70 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
15b80 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 te..**.** [[SQLI
15b90 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
15ba0 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ]] [[SQLITE_CONF
15bb0 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a IG_GETPCACHE]].*
15bc0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
15bd0 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 FIG_PCACHE and S
15be0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
15bf0 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 PCACHE.** <dd> T
15c00 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 hese options are
15c10 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 obsolete and sh
15c20 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 ould not be used
15c30 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a by new code..**
15c40 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e They are retain
15c50 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 ed for backwards
15c60 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 compatibility b
15c70 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 ut are now no-op
15c80 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a s..** </dd>.**.*
15c90 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
15ca0 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 G_SQLLOG]].** <d
15cb0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
15cc0 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 SQLLOG.** <dd>Th
15cd0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c is option is onl
15ce0 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 y available if s
15cf0 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 qlite is compile
15d00 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 d with the.** [S
15d10 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c QLITE_ENABLE_SQL
15d20 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 LOG] pre-process
15d30 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 or macro defined
15d40 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 . The first argu
15d50 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 ment should.** b
15d60 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 e a pointer to a
15d70 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 function of typ
15d80 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c e void(*)(void*,
15d90 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 sqlite3*,const c
15da0 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 har*, int)..** T
15db0 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 he second should
15dc0 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 be of type (voi
15dd0 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 d*). The callbac
15de0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 k is invoked by
15df0 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 the library.** i
15e00 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65 n three separate
15e10 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 circumstances,
15e20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 identified by th
15e30 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 e value passed a
15e40 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 s the.** fourth
15e50 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 parameter. If th
15e60 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
15e70 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 er is 0, then th
15e80 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
15e90 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 ction.** passed
15ea0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 as the second ar
15eb0 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 gument has just
15ec0 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 been opened. The
15ed0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a third argument.
15ee0 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 ** points to a b
15ef0 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 uffer containing
15f00 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
15f10 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 main database f
15f20 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 ile. If the.** f
15f30 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
15f40 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 is 1, then the S
15f50 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 QL statement tha
15f60 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 t the third para
15f70 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 meter.** points
15f80 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e to has just been
15f90 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 executed. Or, i
15fa0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 f the fourth par
15fb0 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 ameter is 2, the
15fc0 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 n.** the connect
15fd0 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 ion being passed
15fe0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 as the second p
15ff0 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e arameter is bein
16000 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a g closed. The.**
16010 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
16020 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 is passed NULL
16030 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 In this case. A
16040 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 n example of usi
16050 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 ng this.** confi
16060 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 guration option
16070 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 can be seen in t
16080 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e he "test_sqllog.
16090 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 c" source file i
160a0 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 n.** the canonic
160b0 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 al SQLite source
160c0 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a tree.</dd>.**.*
160d0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
160e0 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a G_MMAP_SIZE]].**
160f0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
16100 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 IG_MMAP_SIZE.**
16110 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dd>^SQLITE_CONF
16120 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b IG_MMAP_SIZE tak
16130 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e es two 64-bit in
16140 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 teger (sqlite3_i
16150 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 nt64) values.**
16160 74 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66 that are the def
16170 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c ault mmap size l
16180 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c imit (the defaul
16190 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a t setting for.**
161a0 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 [PRAGMA mmap_si
161b0 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 ze]) and the max
161c0 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 imum allowed mma
161d0 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a p size limit..**
161e0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 ^The default se
161f0 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 tting can be ove
16200 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 rridden by each
16210 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
16220 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 ion using.** eit
16230 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 her the [PRAGMA
16240 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 mmap_size] comma
16250 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 nd, or by using
16260 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 the.** [SQLITE_F
16270 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 CNTL_MMAP_SIZE]
16280 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e file control. ^
16290 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c (The maximum all
162a0 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a owed mmap size.*
162b0 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 * will be silent
162c0 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 ly truncated if
162d0 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 necessary so tha
162e0 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 t it does not ex
162f0 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 ceed the.** comp
16300 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d ile-time maximum
16310 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 mmap size set b
16320 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 y the.** [SQLITE
16330 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 _MAX_MMAP_SIZE]
16340 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
16350 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 ion.)^.** ^If ei
16360 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f ther argument to
16370 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 this option is
16380 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 negative, then t
16390 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a hat argument is.
163a0 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 ** changed to it
163b0 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 s compile-time d
163c0 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b efault..**.** [[
163d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 SQLITE_CONFIG_WI
163e0 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a N32_HEAPSIZE]].*
163f0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
16400 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 FIG_WIN32_HEAPSI
16410 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 ZE.** <dd>^The S
16420 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e QLITE_CONFIG_WIN
16430 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 32_HEAPSIZE opti
16440 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c on is only avail
16450 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 able if SQLite i
16460 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f s.** compiled fo
16470 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 r Windows with t
16480 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 he [SQLITE_WIN32
16490 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f _MALLOC] pre-pro
164a0 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 cessor macro.**
164b0 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 defined. ^SQLITE
164c0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 _CONFIG_WIN32_HE
164d0 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 APSIZE takes a 3
164e0 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 2-bit unsigned i
164f0 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 nteger value.**
16500 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74 that specifies t
16510 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 he maximum size
16520 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68 of the created h
16530 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c eap..**.** [[SQL
16540 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 ITE_CONFIG_PCACH
16550 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 E_HDRSZ]].** <dt
16560 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 >SQLITE_CONFIG_P
16570 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c CACHE_HDRSZ.** <
16580 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 dd>^The SQLITE_C
16590 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 ONFIG_PCACHE_HDR
165a0 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 SZ option takes
165b0 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 a single paramet
165c0 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 er which.** is a
165d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
165e0 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 nteger and write
165f0 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 s into that inte
16600 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f ger the number o
16610 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 f extra.** bytes
16620 20 70 65 72 20 70 61 67 65 20 72 65 71 75 69 72 per page requir
16630 65 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 ed for each page
16640 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 in [SQLITE_CONF
16650 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a IG_PAGECACHE]..*
16660 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 * The amount of
16670 65 78 74 72 61 20 73 70 61 63 65 20 72 65 71 75 extra space requ
16680 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 ired can change
16690 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 depending on the
166a0 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 compiler,.** ta
166b0 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 rget platform, a
166c0 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f nd SQLite versio
166d0 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 n..**.** [[SQLIT
166e0 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d E_CONFIG_PMASZ]]
166f0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
16700 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c ONFIG_PMASZ.** <
16710 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 dd>^The SQLITE_C
16720 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 ONFIG_PMASZ opti
16730 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
16740 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 e parameter whic
16750 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 h.** is an unsig
16760 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 ned integer and
16770 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 sets the "Minimu
16780 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 m PMA Size" for
16790 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 the multithreade
167a0 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 d.** sorter to t
167b0 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 hat integer. Th
167c0 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 e default minimu
167d0 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 m PMA Size is se
167e0 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c t by the.** [SQL
167f0 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a ITE_SORTER_PMASZ
16800 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
16810 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 ption. New thre
16820 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 ads are launched
16830 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 .** to help with
16840 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 sort operations
16850 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 when multithrea
16860 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 ded sorting.** i
16870 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 s enabled (using
16880 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 the [PRAGMA thr
16890 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 eads] command) a
168a0 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 nd the amount of
168b0 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 content.** to b
168c0 65 20 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 e sorted exceeds
168d0 20 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 the page size t
168e0 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d imes the minimum
168f0 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 of the.** [PRAG
16900 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 MA cache_size] s
16910 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 etting and this
16920 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 value..**.** [[S
16930 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d QLITE_CONFIG_STM
16940 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a TJRNL_SPILL]].**
16950 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
16960 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c IG_STMTJRNL_SPIL
16970 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 L.** <dd>^The SQ
16980 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 LITE_CONFIG_STMT
16990 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f JRNL_SPILL optio
169a0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
169b0 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 parameter which
169c0 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 20 .** becomes the
169d0 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e [statement journ
169e0 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73 al] spill-to-dis
169f0 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a k threshold. .*
16a00 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75 * [Statement jou
16a10 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 20 rnals] are held
16a20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20 in memory until
16a30 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e 20 62 their size (in b
16a40 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 73 ytes).** exceeds
16a50 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c 64 2c this threshold,
16a60 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e 74 20 at which point
16a70 74 68 65 79 20 61 72 65 20 77 72 69 74 74 65 6e they are written
16a80 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20 to disk..** Or
16a90 69 66 20 74 68 65 20 74 68 72 65 73 68 6f 6c 64 if the threshold
16aa0 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e is -1, statemen
16ab0 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 61 t journals are a
16ac0 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78 lways held.** ex
16ad0 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d clusively in mem
16ae0 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61 ory..** Since ma
16af0 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 ny statement jou
16b00 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 63 6f rnals never beco
16b10 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74 69 6e me large, settin
16b20 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74 g the spill.** t
16b30 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 61 hreshold to a va
16b40 6c 75 65 20 73 75 63 68 20 61 73 20 36 34 4b 69 lue such as 64Ki
16b50 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20 72 65 B can greatly re
16b60 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 20 duce the amount
16b70 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72 of.** I/O requir
16b80 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 73 74 ed to support st
16b90 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b atement rollback
16ba0 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 ..** The default
16bb0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20 value for this
16bc0 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 72 setting is contr
16bd0 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 olled by the.**
16be0 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c [SQLITE_STMTJRNL
16bf0 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d _SPILL] compile-
16c00 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 time option..**
16c10 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 </dl>.*/.#define
16c20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 SQLITE_CONFIG_S
16c30 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 INGLETHREAD 1
16c40 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e /* nil */.#defin
16c50 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
16c60 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 MULTITHREAD 2
16c70 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 /* nil */.#defi
16c80 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
16c90 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 _SERIALIZED 3
16ca0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 /* nil */.#def
16cb0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
16cc0 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 G_MALLOC
16cd0 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 4 /* sqlite3_me
16ce0 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 m_methods* */.#d
16cf0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
16d00 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 FIG_GETMALLOC
16d10 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 5 /* sqlite3_
16d20 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a mem_methods* */.
16d30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
16d40 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 ONFIG_SCRATCH
16d50 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 6 /* void*,
16d60 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a int sz, int N *
16d70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
16d80 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 _CONFIG_PAGECACH
16d90 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 E 7 /* void
16da0 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e *, int sz, int N
16db0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
16dc0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 TE_CONFIG_HEAP
16dd0 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 8 /* vo
16de0 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 id*, int nByte,
16df0 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 int min */.#defi
16e00 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
16e10 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 _MEMSTATUS 9
16e20 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a /* boolean */.
16e30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
16e40 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 ONFIG_MUTEX
16e50 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 10 /* sqlite
16e60 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 3_mutex_methods*
16e70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
16e80 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 TE_CONFIG_GETMUT
16e90 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 EX 11 /* sq
16ea0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 lite3_mutex_meth
16eb0 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 ods* */./* previ
16ec0 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e ously SQLITE_CON
16ed0 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 FIG_CHUNKALLOC 1
16ee0 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 2 which is now u
16ef0 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 nused. */ .#defi
16f00 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
16f10 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 _LOOKASIDE 13
16f20 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a /* int int */.
16f30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
16f40 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 ONFIG_PCACHE
16f50 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 14 /* no-op
16f60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
16f70 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 E_CONFIG_GETPCAC
16f80 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d HE 15 /* no-
16f90 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 op */.#define SQ
16fa0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 LITE_CONFIG_LOG
16fb0 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 16 /*
16fc0 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a xFunc, void* */.
16fd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
16fe0 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 ONFIG_URI
16ff0 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 17 /* int */
17000 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
17010 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 CONFIG_PCACHE2
17020 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 18 /* sqlit
17030 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 e3_pcache_method
17040 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 s2* */.#define S
17050 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
17060 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a PCACHE2 19 /*
17070 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f sqlite3_pcache_
17080 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 methods2* */.#de
17090 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
170a0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 IG_COVERING_INDE
170b0 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e X_SCAN 20 /* in
170c0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
170d0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f ITE_CONFIG_SQLLO
170e0 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 G 21 /* x
170f0 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f Sqllog, void* */
17100 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
17110 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 CONFIG_MMAP_SIZE
17120 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 22 /* sqlit
17130 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 e3_int64, sqlite
17140 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 3_int64 */.#defi
17150 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
17160 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 _WIN32_HEAPSIZE
17170 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 23 /* int
17180 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 nByte */.#define
17190 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
171a0 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20 CACHE_HDRSZ
171b0 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70 24 /* int *p
171c0 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 sz */.#define SQ
171d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 LITE_CONFIG_PMAS
171e0 5a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 Z
171f0 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20 25 /* unsigned
17200 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 23 64 65 int szPma */.#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 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c IG_STMTJRNL_SPIL
17230 4c 20 20 20 20 20 20 32 36 20 20 2f 2a 20 69 6e L 26 /* in
17240 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a t nByte */../*.*
17250 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 * CAPI3REF: Data
17260 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 base Connection
17270 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 Configuration Op
17280 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 tions.**.** Thes
17290 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 e constants are
172a0 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e the available in
172b0 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 teger configurat
172c0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 ion options that
172d0 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 .** can be passe
172e0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 d as the second
172f0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
17300 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 [sqlite3_db_conf
17310 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e ig()] interface.
17320 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 .**.** New confi
17330 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 guration options
17340 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e may be added in
17350 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
17360 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 of SQLite..** E
17370 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 xisting configur
17380 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 ation options mi
17390 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e ght be discontin
173a0 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f ued. Applicatio
173b0 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 ns.** should che
173c0 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f ck the return co
173d0 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 de from [sqlite3
173e0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f _db_config()] to
173f0 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a make sure that.
17400 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b ** the call work
17410 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 ed. ^The [sqlit
17420 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 e3_db_config()]
17430 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 interface will r
17440 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a eturn a.** non-z
17450 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d ero [error code]
17460 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 if a discontinu
17470 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 ed or unsupporte
17480 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 d configuration
17490 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 option.** is inv
174a0 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e oked..**.** <dl>
174b0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 .** <dt>SQLITE_D
174c0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
174d0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e E</dt>.** <dd> ^
174e0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
174f0 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e s three addition
17500 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 al arguments tha
17510 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 t determine the
17520 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d .** [lookaside m
17530 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d emory allocator]
17540 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 configuration f
17550 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 or the [database
17560 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a connection]..**
17570 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 ^The first argu
17580 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 ment (the third
17590 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
175a0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
175b0 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 )] is a.** point
175c0 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 er to a memory b
175d0 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 uffer to use for
175e0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 lookaside memor
175f0 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 y..** ^The first
17600 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 argument after
17610 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e the SQLITE_DBCON
17620 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 FIG_LOOKASIDE ve
17630 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c rb.** may be NUL
17640 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 L in which case
17650 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f SQLite will allo
17660 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b cate the.** look
17670 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73 aside buffer its
17680 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 elf using [sqlit
17690 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 e3_malloc()]. ^T
176a0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
176b0 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a nt is the.** siz
176c0 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 e of each lookas
176d0 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e ide buffer slot.
176e0 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 ^The third arg
176f0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d ument is the num
17700 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e ber of.** slots.
17710 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 The size of th
17720 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 e buffer in the
17730 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d first argument m
17740 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74 ust be greater t
17750 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 han.** or equal
17760 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f to the product o
17770 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 f the second and
17780 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 third arguments
17790 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a . The buffer.**
177a0 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 must be aligned
177b0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f to an 8-byte bo
177c0 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 undary. ^If the
177d0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
177e0 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 to.** SQLITE_DB
177f0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
17800 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 is not a multip
17810 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 le of 8, it is i
17820 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 nternally.** rou
17830 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 nded down to the
17840 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 next smaller mu
17850 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 ltiple of 8. ^(
17860 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 The lookaside me
17870 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 mory.** configur
17880 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 ation for a data
17890 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
178a0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e can only be chan
178b0 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a ged when that.**
178c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e connection is n
178d0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 ot currently usi
178e0 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d ng lookaside mem
178f0 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 ory, or in other
17900 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 words.** when t
17910 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 he "current valu
17920 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a e" returned by.*
17930 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 * [sqlite3_db_st
17940 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f atus](D,[SQLITE_
17950 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
17960 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a ],...) is zero..
17970 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 ** Any attempt t
17980 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f o change the loo
17990 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f kaside memory co
179a0 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e nfiguration when
179b0 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 lookaside.** me
179c0 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c mory is in use l
179d0 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 eaves the config
179e0 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 uration unchange
179f0 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a d and returns .*
17a00 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e * [SQLITE_BUSY].
17a10 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 )^</dd>.**.** <d
17a20 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 t>SQLITE_DBCONFI
17a30 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 G_ENABLE_FKEY</d
17a40 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 t>.** <dd> ^This
17a50 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 option is used
17a60 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 to enable or dis
17a70 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 able the enforce
17a80 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 ment of.** [fore
17a90 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 ign key constrai
17aa0 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f nts]. There sho
17ab0 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 uld be two addit
17ac0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e ional arguments.
17ad0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 .** The first ar
17ae0 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 gument is an int
17af0 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 eger which is 0
17b00 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e to disable FK en
17b10 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f forcement,.** po
17b20 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 sitive to enable
17b30 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 FK enforcement
17b40 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c or negative to l
17b50 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d eave FK enforcem
17b60 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 ent.** unchanged
17b70 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 . The second pa
17b80 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 rameter is a poi
17b90 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 nter to an integ
17ba0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a er into which.**
17bb0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 is written 0 or
17bc0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 1 to indicate w
17bd0 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 hether FK enforc
17be0 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 ement is off or
17bf0 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 on.** following
17c00 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 this call. The
17c10 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
17c20 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 may be a NULL p
17c30 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 ointer, in.** wh
17c40 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 ich case the FK
17c50 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 enforcement sett
17c60 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 ing is not repor
17c70 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a ted back. </dd>.
17c80 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
17c90 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 _DBCONFIG_ENABLE
17ca0 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a _TRIGGER</dt>.**
17cb0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 <dd> ^This opti
17cc0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e on is used to en
17cd0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 able or disable
17ce0 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 [CREATE TRIGGER
17cf0 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 | triggers]..**
17d00 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 There should be
17d10 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 two additional a
17d20 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 rguments..** The
17d30 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
17d40 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 is an integer wh
17d50 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 ich is 0 to disa
17d60 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a ble triggers,.**
17d70 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 positive to ena
17d80 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 ble triggers or
17d90 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 negative to leav
17da0 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e e the setting un
17db0 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 changed..** The
17dc0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
17dd0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
17de0 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f an integer into
17df0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 which.** is wri
17e00 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 tten 0 or 1 to i
17e10 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 ndicate whether
17e20 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73 triggers are dis
17e30 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 abled or enabled
17e40 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 .** following th
17e50 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 is call. The se
17e60 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d cond parameter m
17e70 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 ay be a NULL poi
17e80 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 nter, in.** whic
17e90 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67 h case the trigg
17ea0 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f er setting is no
17eb0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e t reported back.
17ec0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 </dd>.**.** <dt
17ed0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 >SQLITE_DBCONFIG
17ee0 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b _ENABLE_FTS3_TOK
17ef0 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c ENIZER</dt>.** <
17f00 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e dd> ^This option
17f10 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 is used to enab
17f20 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 le or disable th
17f30 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74 0a 2a e two-argument.*
17f40 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 * version of the
17f50 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 [fts3_tokenizer
17f60 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68 69 ()] function whi
17f70 63 68 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 ch is part of th
17f80 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c 6c e.** [FTS3] full
17f90 2d 74 65 78 74 20 73 65 61 72 63 68 20 65 6e 67 -text search eng
17fa0 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a 2a ine extension..*
17fb0 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 * There should b
17fc0 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c e two additional
17fd0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 arguments..** T
17fe0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
17ff0 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 t is an integer
18000 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 which is 0 to di
18010 73 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e sable fts3_token
18020 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f 73 izer() or.** pos
18030 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 itive to enable
18040 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 fts3_tokenizer()
18050 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 or negative to
18060 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e leave the settin
18070 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 0a g.** unchanged..
18080 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 ** The second pa
18090 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 rameter is a poi
180a0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 nter to an integ
180b0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a er into which.**
180c0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 is written 0 or
180d0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 1 to indicate w
180e0 68 65 74 68 65 72 20 66 74 73 33 5f 74 6f 6b 65 hether fts3_toke
180f0 6e 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 nizer is disable
18100 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 d or enabled.**
18110 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 following this c
18120 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 all. The second
18130 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 parameter may b
18140 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 e a NULL pointer
18150 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 , in.** which ca
18160 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 se the new setti
18170 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 ng is not report
18180 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a ed back. </dd>.*
18190 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
181a0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f DBCONFIG_ENABLE_
181b0 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 3c 2f LOAD_EXTENSION</
181c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 dt>.** <dd> ^Thi
181d0 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 s option is used
181e0 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 to enable or di
181f0 73 61 62 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 sable the [sqlit
18200 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f e3_load_extensio
18210 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 n()].** interfac
18220 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c 79 20 e independently
18230 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74 of the [load_ext
18240 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20 66 75 ension()] SQL fu
18250 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 5b nction..** The [
18260 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c sqlite3_enable_l
18270 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d oad_extension()]
18280 20 41 50 49 20 65 6e 61 62 6c 65 73 20 6f 72 20 API enables or
18290 64 69 73 61 62 6c 65 73 20 62 6f 74 68 20 74 68 disables both th
182a0 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71 6c 69 e.** C-API [sqli
182b0 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 te3_load_extensi
182c0 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65 20 53 51 on()] and the SQ
182d0 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f 61 64 L function [load
182e0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a _extension()]..*
182f0 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 * There should b
18300 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c e two additional
18310 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 57 arguments..** W
18320 68 65 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 hen the first ar
18330 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 69 gument to this i
18340 6e 74 65 72 66 61 63 65 20 69 73 20 31 2c 20 74 nterface is 1, t
18350 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43 2d 41 hen only the C-A
18360 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 PI is.** enabled
18370 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e and the SQL fun
18380 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 64 69 ction remains di
18390 73 61 62 6c 65 64 2e 20 20 49 66 20 74 68 65 20 sabled. If the
183a0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
183b0 6f 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72 66 o.** this interf
183c0 61 63 65 20 69 73 20 30 2c 20 74 68 65 6e 20 62 ace is 0, then b
183d0 6f 74 68 20 74 68 65 20 43 2d 41 50 49 20 61 6e oth the C-API an
183e0 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 d the SQL functi
183f0 6f 6e 20 61 72 65 20 64 69 73 61 62 6c 65 64 2e on are disabled.
18400 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 72 73 74 .** If the first
18410 20 61 72 67 75 6d 65 6e 74 20 69 73 20 2d 31 2c argument is -1,
18420 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 73 then no changes
18430 20 61 72 65 20 6d 61 64 65 20 74 6f 20 73 74 61 are made to sta
18440 74 65 20 6f 66 20 65 69 74 68 65 72 20 74 68 65 te of either the
18450 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74 68 65 .** C-API or the
18460 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a SQL function..*
18470 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 * The second par
18480 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e ameter is a poin
18490 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 ter to an intege
184a0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 r into which.**
184b0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 is written 0 or
184c0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 1 to indicate wh
184d0 65 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 6c ether [sqlite3_l
184e0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d oad_extension()]
184f0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 interface.** is
18500 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 disabled or ena
18510 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 bled following t
18520 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 his call. The s
18530 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
18540 6d 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55 4c 4c may.** be a NULL
18550 20 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77 68 69 pointer, in whi
18560 63 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20 ch case the new
18570 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 setting is not r
18580 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a 2a 2a eported back..**
18590 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 </dd>.**.** <dt
185a0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 >SQLITE_DBCONFIG
185b0 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f 64 74 3e _MAINDBNAME</dt>
185c0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f .** <dd> ^This o
185d0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f ption is used to
185e0 20 63 68 61 6e 67 65 20 74 68 65 20 6e 61 6d 65 change the name
185f0 20 6f 66 20 74 68 65 20 22 6d 61 69 6e 22 20 64 of the "main" d
18600 61 74 61 62 61 73 65 0a 2a 2a 20 73 63 68 65 6d atabase.** schem
18610 61 2e 20 20 5e 54 68 65 20 73 6f 6c 65 20 61 72 a. ^The sole ar
18620 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e gument is a poin
18630 74 65 72 20 74 6f 20 61 20 63 6f 6e 73 74 61 6e ter to a constan
18640 74 20 55 54 46 38 20 73 74 72 69 6e 67 0a 2a 2a t UTF8 string.**
18650 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 63 6f which will beco
18660 6d 65 20 74 68 65 20 6e 65 77 20 73 63 68 65 6d me the new schem
18670 61 20 6e 61 6d 65 20 69 6e 20 70 6c 61 63 65 20 a name in place
18680 6f 66 20 22 6d 61 69 6e 22 2e 20 20 5e 53 51 4c of "main". ^SQL
18690 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 ite.** does not
186a0 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 make a copy of t
186b0 68 65 20 6e 65 77 20 6d 61 69 6e 20 73 63 68 65 he new main sche
186c0 6d 61 20 6e 61 6d 65 20 73 74 72 69 6e 67 2c 20 ma name string,
186d0 73 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 so the applicati
186e0 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 on.** must ensur
186f0 65 20 74 68 61 74 20 74 68 65 20 61 72 67 75 6d e that the argum
18700 65 6e 74 20 70 61 73 73 65 64 20 69 6e 74 6f 20 ent passed into
18710 74 68 69 73 20 44 42 43 4f 4e 46 49 47 20 6f 70 this DBCONFIG op
18720 74 69 6f 6e 20 69 73 20 75 6e 63 68 61 6e 67 65 tion is unchange
18730 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 66 74 65 72 d.** until after
18740 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
18750 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e nnection closes.
18760 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 .** </dd>.**.**
18770 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e <dt>SQLITE_DBCON
18780 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 FIG_NO_CKPT_ON_C
18790 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 LOSE</dt>.** <dd
187a0 3e 20 55 73 75 61 6c 6c 79 2c 20 77 68 65 6e 20 > Usually, when
187b0 61 20 64 61 74 61 62 61 73 65 20 69 6e 20 77 61 a database in wa
187c0 6c 20 6d 6f 64 65 20 69 73 20 63 6c 6f 73 65 64 l mode is closed
187d0 20 6f 72 20 64 65 74 61 63 68 65 64 20 66 72 6f or detached fro
187e0 6d 20 61 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 m a .** database
187f0 20 68 61 6e 64 6c 65 2c 20 53 51 4c 69 74 65 20 handle, SQLite
18800 63 68 65 63 6b 73 20 69 66 20 74 68 69 73 20 77 checks if this w
18810 69 6c 6c 20 6d 65 61 6e 20 74 68 61 74 20 74 68 ill mean that th
18820 65 72 65 20 61 72 65 20 6e 6f 77 20 6e 6f 20 0a ere are now no .
18830 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 61 ** connections a
18840 74 20 61 6c 6c 20 74 6f 20 74 68 65 20 64 61 74 t all to the dat
18850 61 62 61 73 65 2e 20 49 66 20 73 6f 2c 20 69 74 abase. If so, it
18860 20 70 65 72 66 6f 72 6d 73 20 61 20 63 68 65 63 performs a chec
18870 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70 65 72 61 kpoint .** opera
18880 74 69 6f 6e 20 62 65 66 6f 72 65 20 63 6c 6f 73 tion before clos
18890 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 ing the connecti
188a0 6f 6e 2e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 on. This option
188b0 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 0a 2a may be used to.*
188c0 2a 20 6f 76 65 72 72 69 64 65 20 74 68 69 73 20 * override this
188d0 62 65 68 61 76 69 6f 75 72 2e 20 54 68 65 20 66 behaviour. The f
188e0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 70 irst parameter p
188f0 61 73 73 65 64 20 74 6f 20 74 68 69 73 20 6f 70 assed to this op
18900 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 61 6e eration.** is an
18910 20 69 6e 74 65 67 65 72 20 2d 20 6e 6f 6e 2d 7a integer - non-z
18920 65 72 6f 20 74 6f 20 64 69 73 61 62 6c 65 20 63 ero to disable c
18930 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c heckpoints-on-cl
18940 6f 73 65 2c 20 6f 72 20 7a 65 72 6f 20 28 74 68 ose, or zero (th
18950 65 0a 2a 2a 20 64 65 66 61 75 6c 74 29 20 74 6f e.** default) to
18960 20 65 6e 61 62 6c 65 20 74 68 65 6d 2e 20 54 68 enable them. Th
18970 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
18980 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 er is a pointer
18990 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a to an integer.**
189a0 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73 20 77 into which is w
189b0 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f ritten 0 or 1 to
189c0 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 indicate whethe
189d0 72 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e r checkpoints-on
189e0 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 76 65 20 62 -close.** have b
189f0 65 65 6e 20 64 69 73 61 62 6c 65 64 20 2d 20 30 een disabled - 0
18a00 20 69 66 20 74 68 65 79 20 61 72 65 20 6e 6f 74 if they are not
18a10 20 64 69 73 61 62 6c 65 64 2c 20 31 20 69 66 20 disabled, 1 if
18a20 74 68 65 79 20 61 72 65 2e 0a 2a 2a 20 3c 2f 64 they are..** </d
18a30 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a d>.**.** </dl>.*
18a40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
18a50 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 _DBCONFIG_MAINDB
18a60 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 NAME
18a70 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74 20 63 68 1000 /* const ch
18a80 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ar* */.#define S
18a90 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c QLITE_DBCONFIG_L
18aa0 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 20 OOKASIDE
18ab0 20 20 20 20 20 31 30 30 31 20 2f 2a 20 76 6f 69 1001 /* voi
18ac0 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 d* int int */.#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 45 4e 41 42 4c 45 5f 46 4b 45 ONFIG_ENABLE_FKE
18af0 59 20 20 20 20 20 20 20 20 20 20 20 31 30 30 32 Y 1002
18b00 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a /* int int* */.
18b10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
18b20 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 BCONFIG_ENABLE_T
18b30 52 49 47 47 45 52 20 20 20 20 20 20 20 20 31 30 RIGGER 10
18b40 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 03 /* int int* *
18b50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
18b60 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 _DBCONFIG_ENABLE
18b70 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 20 _FTS3_TOKENIZER
18b80 31 30 30 34 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 1004 /* int int*
18b90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
18ba0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 TE_DBCONFIG_ENAB
18bb0 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f LE_LOAD_EXTENSIO
18bc0 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74 20 69 6e N 1005 /* int in
18bd0 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 t* */.#define SQ
18be0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f LITE_DBCONFIG_NO
18bf0 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 20 20 _CKPT_ON_CLOSE
18c00 20 20 20 20 31 30 30 36 20 2f 2a 20 69 6e 74 20 1006 /* int
18c10 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 int* */.../*.**
18c20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 CAPI3REF: Enable
18c30 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 Or Disable Exte
18c40 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 nded Result Code
18c50 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c s.** METHOD: sql
18c60 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ite3.**.** ^The
18c70 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
18c80 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 _result_codes()
18c90 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 routine enables
18ca0 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a or disables the.
18cb0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 ** [extended res
18cc0 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 ult codes] featu
18cd0 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 re of SQLite. ^T
18ce0 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 he extended resu
18cf0 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 lt.** codes are
18d00 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 disabled by defa
18d10 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 ult for historic
18d20 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 al compatibility
18d30 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
18d40 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 _extended_result
18d50 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c _codes(sqlite3*,
18d60 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a int onoff);../*
18d70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 .** CAPI3REF: La
18d80 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a st Insert Rowid.
18d90 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
18da0 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 e3.**.** ^Each e
18db0 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c ntry in most SQL
18dc0 69 74 65 20 74 61 62 6c 65 73 20 28 65 78 63 65 ite tables (exce
18dd0 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 pt for [WITHOUT
18de0 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a ROWID] tables).*
18df0 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 * has a unique 6
18e00 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 4-bit signed.**
18e10 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c integer key call
18e20 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 ed the [ROWID |
18e30 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 "rowid"]. ^The r
18e40 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 owid is always a
18e50 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 vailable.** as a
18e60 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c n undeclared col
18e70 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c umn named ROWID,
18e80 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f OID, or _ROWID_
18e90 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 as long as thos
18ea0 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e e.** names are n
18eb0 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 ot also used by
18ec0 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 explicitly decla
18ed0 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 red columns. ^If
18ee0 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 .** the table ha
18ef0 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 s a column of ty
18f00 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d pe [INTEGER PRIM
18f10 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 ARY KEY] then th
18f20 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 at column.** is
18f30 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f another alias fo
18f40 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a r the rowid..**.
18f50 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
18f60 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 last_insert_rowi
18f70 64 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 75 d(D) interface u
18f80 73 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 sually returns t
18f90 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 0a 2a 2a he [rowid] of.**
18fa0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
18fb0 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 successful [INS
18fc0 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 ERT] into a rowi
18fd0 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 d table or [virt
18fe0 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e ual table].** on
18ff0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
19000 74 69 6f 6e 20 44 2e 20 5e 49 6e 73 65 72 74 73 tion D. ^Inserts
19010 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 into [WITHOUT R
19020 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65 OWID] tables are
19030 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 72 64 65 64 not.** recorded
19040 2e 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 . ^If no success
19050 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e ful [INSERT]s in
19060 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20 to rowid tables
19070 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 have ever occurr
19080 65 64 20 0a 2a 2a 20 6f 6e 20 74 68 65 20 64 61 ed .** on the da
19090 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
190a0 6e 20 44 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 n D, then sqlite
190b0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 3_last_insert_ro
190c0 77 69 64 28 44 29 20 72 65 74 75 72 6e 73 20 0a wid(D) returns .
190d0 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 41 ** zero..**.** A
190e0 73 20 77 65 6c 6c 20 61 73 20 62 65 69 6e 67 20 s well as being
190f0 73 65 74 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c set automaticall
19100 79 20 61 73 20 72 6f 77 73 20 61 72 65 20 69 6e y as rows are in
19110 73 65 72 74 65 64 20 69 6e 74 6f 20 64 61 74 61 serted into data
19120 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65 73 2c 20 base.** tables,
19130 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
19140 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 ed by this funct
19150 69 6f 6e 20 6d 61 79 20 62 65 20 73 65 74 20 65 ion may be set e
19160 78 70 6c 69 63 69 74 6c 79 20 62 79 0a 2a 2a 20 xplicitly by.**
19170 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 [sqlite3_set_las
19180 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 t_insert_rowid()
19190 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 76 69 72 ].**.** Some vir
191a0 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 tual table imple
191b0 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 49 mentations may I
191c0 4e 53 45 52 54 20 72 6f 77 73 20 69 6e 74 6f 20 NSERT rows into
191d0 72 6f 77 69 64 20 74 61 62 6c 65 73 20 61 73 0a rowid tables as.
191e0 2a 2a 20 70 61 72 74 20 6f 66 20 63 6f 6d 6d 69 ** part of commi
191f0 74 74 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 tting a transact
19200 69 6f 6e 20 28 65 2e 67 2e 20 74 6f 20 66 6c 75 ion (e.g. to flu
19210 73 68 20 64 61 74 61 20 61 63 63 75 6d 75 6c 61 sh data accumula
19220 74 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a ted in memory.**
19230 20 74 6f 20 64 69 73 6b 29 2e 20 49 6e 20 74 68 to disk). In th
19240 69 73 20 63 61 73 65 20 73 75 62 73 65 71 75 65 is case subseque
19250 6e 74 20 63 61 6c 6c 73 20 74 6f 20 74 68 69 73 nt calls to this
19260 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e function return
19270 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20 61 73 the rowid.** as
19280 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 sociated with th
19290 65 73 65 20 69 6e 74 65 72 6e 61 6c 20 49 4e 53 ese internal INS
192a0 45 52 54 20 6f 70 65 72 61 74 69 6f 6e 73 2c 20 ERT operations,
192b0 77 68 69 63 68 20 6c 65 61 64 73 20 74 6f 20 0a which leads to .
192c0 2a 2a 20 75 6e 69 6e 74 75 69 74 69 76 65 20 72 ** unintuitive r
192d0 65 73 75 6c 74 73 2e 20 56 69 72 74 75 61 6c 20 esults. Virtual
192e0 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 table implementa
192f0 74 69 6f 6e 73 20 74 68 61 74 20 64 6f 20 77 72 tions that do wr
19300 69 74 65 20 74 6f 20 72 6f 77 69 64 0a 2a 2a 20 ite to rowid.**
19310 74 61 62 6c 65 73 20 69 6e 20 74 68 69 73 20 77 tables in this w
19320 61 79 20 63 61 6e 20 61 76 6f 69 64 20 74 68 69 ay can avoid thi
19330 73 20 70 72 6f 62 6c 65 6d 20 62 79 20 72 65 73 s problem by res
19340 74 6f 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69 toring the origi
19350 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69 64 20 76 61 nal .** rowid va
19360 6c 75 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 lue using [sqlit
19370 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 e3_set_last_inse
19380 72 74 5f 72 6f 77 69 64 28 29 5d 20 62 65 66 6f rt_rowid()] befo
19390 72 65 20 72 65 74 75 72 6e 69 6e 67 20 0a 2a 2a re returning .**
193a0 20 63 6f 6e 74 72 6f 6c 20 74 6f 20 74 68 65 20 control to the
193b0 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 user..**.** ^(If
193c0 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 an [INSERT] occ
193d0 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 urs within a tri
193e0 67 67 65 72 20 74 68 65 6e 20 74 68 69 73 20 72 gger then this r
193f0 6f 75 74 69 6e 65 20 77 69 6c 6c 20 0a 2a 2a 20 outine will .**
19400 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 return the [rowi
19410 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 d] of the insert
19420 65 64 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 ed row as long a
19430 73 20 74 68 65 20 74 72 69 67 67 65 72 20 69 73 s the trigger is
19440 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 2e 20 4f 6e .** running. On
19450 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 70 ce the trigger p
19460 72 6f 67 72 61 6d 20 65 6e 64 73 2c 20 74 68 65 rogram ends, the
19470 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
19480 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 .** by this rout
19490 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 ine reverts to w
194a0 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 hat it was befor
194b0 65 20 74 68 65 20 74 72 69 67 67 65 72 20 77 61 e the trigger wa
194c0 73 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a s fired.)^.**.**
194d0 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 ^An [INSERT] th
194e0 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 at fails due to
194f0 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f a constraint vio
19500 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a lation is not a.
19510 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 ** successful [I
19520 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 NSERT] and does
19530 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 not change the v
19540 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 alue returned by
19550 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 this.** routine
19560 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 . ^Thus INSERT
19570 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 OR FAIL, INSERT
19580 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 OR IGNORE, INSER
19590 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a T OR ROLLBACK,.*
195a0 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 * and INSERT OR
195b0 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 ABORT make no ch
195c0 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 anges to the ret
195d0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 urn value of thi
195e0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 s.** routine whe
195f0 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f n their insertio
19600 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e n fails. ^(When
19610 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 INSERT OR REPLA
19620 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 CE.** encounters
19630 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 a constraint vi
19640 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 olation, it does
19650 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a not fail. The.
19660 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e ** INSERT contin
19670 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f ues to completio
19680 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 n after deleting
19690 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 rows that cause
196a0 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 d.** the constra
196b0 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 int problem so I
196c0 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 NSERT OR REPLACE
196d0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 will always cha
196e0 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 nge.** the retur
196f0 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 n value of this
19700 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a interface.)^.**.
19710 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 ** ^For the purp
19720 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 oses of this rou
19730 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 tine, an [INSERT
19740 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 ] is considered
19750 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 to.** be success
19760 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 ful even if it i
19770 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 s subsequently r
19780 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a olled back..**.*
19790 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 * This function
197a0 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f is accessible to
197b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
197c0 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 via the.** [last
197d0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 _insert_rowid()
197e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a SQL function]..*
197f0 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 *.** If a separa
19800 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 te thread perfor
19810 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 ms a new [INSERT
19820 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a ] on the same.**
19830 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
19840 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b tion while the [
19850 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 sqlite3_last_ins
19860 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 ert_rowid()].**
19870 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e function is runn
19880 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 ing and thus cha
19890 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e nges the last in
198a0 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a sert [rowid],.**
198b0 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 then the value
198c0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
198d0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 ite3_last_insert
198e0 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 _rowid()] is.**
198f0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e unpredictable an
19900 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 d might not equa
19910 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 l either the old
19920 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c or the new.** l
19930 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 ast insert [rowi
19940 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 d]..*/.sqlite3_i
19950 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 nt64 sqlite3_las
19960 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 t_insert_rowid(s
19970 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
19980 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 74 CAPI3REF: Set t
19990 68 65 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 he Last Insert R
199a0 6f 77 69 64 20 76 61 6c 75 65 2e 0a 2a 2a 20 4d owid value..** M
199b0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a ETHOD: sqlite3.*
199c0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
199d0 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 _set_last_insert
199e0 5f 72 6f 77 69 64 28 44 2c 20 52 29 20 6d 65 74 _rowid(D, R) met
199f0 68 6f 64 20 61 6c 6c 6f 77 73 20 74 68 65 20 61 hod allows the a
19a00 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a pplication to.**
19a10 20 73 65 74 20 74 68 65 20 76 61 6c 75 65 20 72 set the value r
19a20 65 74 75 72 6e 65 64 20 62 79 20 63 61 6c 6c 69 eturned by calli
19a30 6e 67 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f ng sqlite3_last_
19a40 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 insert_rowid(D)
19a50 74 6f 20 52 20 0a 2a 2a 20 77 69 74 68 6f 75 74 to R .** without
19a60 20 69 6e 73 65 72 74 69 6e 67 20 61 20 72 6f 77 inserting a row
19a70 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 into the databa
19a80 73 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 se..*/.void sqli
19a90 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 te3_set_last_ins
19aa0 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 ert_rowid(sqlite
19ab0 33 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3*,sqlite3_int64
19ac0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
19ad0 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 EF: Count The Nu
19ae0 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 mber Of Rows Mod
19af0 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a ified.** METHOD:
19b00 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e sqlite3.**.** ^
19b10 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 This function re
19b20 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
19b30 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 of rows modifie
19b40 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a d, inserted or.*
19b50 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 * deleted by the
19b60 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 most recently c
19b70 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c ompleted INSERT,
19b80 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 UPDATE or DELET
19b90 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f E.** statement o
19ba0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
19bb0 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66 onnection specif
19bc0 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 ied by the only
19bd0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 parameter..** ^E
19be0 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 xecuting any oth
19bf0 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 er type of SQL s
19c00 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f tatement does no
19c10 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c t modify the val
19c20 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 ue.** returned b
19c30 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e y this function.
19c40 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 .**.** ^Only cha
19c50 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63 74 nges made direct
19c60 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 ly by the INSERT
19c70 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 , UPDATE or DELE
19c80 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 TE statement are
19c90 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d .** considered -
19ca0 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 auxiliary chang
19cb0 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43 52 es caused by [CR
19cc0 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 EATE TRIGGER | t
19cd0 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 riggers], .** [f
19ce0 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f oreign key actio
19cf0 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d ns] or [REPLACE]
19d00 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f constraint reso
19d10 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 lution are not c
19d20 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 ounted..** .** C
19d30 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 hanges to a view
19d40 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 that are interc
19d50 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e epted by .** [IN
19d60 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 STEAD OF trigger
19d70 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 | INSTEAD OF tr
19d80 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 iggers] are not
19d90 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 counted. ^The va
19da0 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 lue .** returned
19db0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e by sqlite3_chan
19dc0 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c ges() immediatel
19dd0 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52 y after an INSER
19de0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a T, UPDATE or .**
19df0 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e DELETE statemen
19e00 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 t run on a view
19e10 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 is always zero.
19e20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 Only changes mad
19e30 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 e to real .** ta
19e40 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 bles are counted
19e50 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 ..**.** Things a
19e60 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 re more complica
19e70 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69 74 ted if the sqlit
19e80 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e e3_changes() fun
19e90 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 ction is.** exec
19ea0 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72 69 uted while a tri
19eb0 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20 gger program is
19ec0 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 running. This ma
19ed0 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a y happen if the.
19ee0 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 ** program uses
19ef0 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 the [changes() S
19f00 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 QL function], or
19f10 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 if some other c
19f20 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 allback.** funct
19f30 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 ion invokes sqli
19f40 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69 te3_changes() di
19f50 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 rectly. Essentia
19f60 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e lly:.** .** <ul>
19f70 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 .** <li> ^(Bef
19f80 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74 ore entering a t
19f90 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74 rigger program t
19fa0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
19fb0 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 d by.** s
19fc0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 qlite3_changes()
19fd0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 function is sav
19fe0 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74 72 ed. After the tr
19ff0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a igger program .*
1a000 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69 6e * has fin
1a010 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69 ished, the origi
1a020 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73 nal value is res
1a030 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 tored.)^.** .**
1a040 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 <li> ^(Within
1a050 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 a trigger progra
1a060 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55 m each INSERT, U
1a070 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45 PDATE and DELETE
1a080 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74 .** stat
1a090 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20 76 ement sets the v
1a0a0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 alue returned by
1a0b0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 sqlite3_changes
1a0c0 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 () .** up
1a0d0 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 on completion as
1a0e0 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 normal. Of cour
1a0f0 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77 se, this value w
1a100 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 ill not include
1a110 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63 .** any c
1a120 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64 hanges performed
1a130 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72 73 by sub-triggers
1a140 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65 33 , as the sqlite3
1a150 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 _changes() .**
1a160 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c value will
1a170 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72 65 be saved and re
1a180 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61 63 stored after eac
1a190 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68 61 h sub-trigger ha
1a1a0 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c s run.)^.** </ul
1a1b0 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d >.** .** ^This m
1a1c0 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68 65 eans that if the
1a1d0 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 changes() SQL f
1a1e0 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 unction (or simi
1a1f0 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 lar) is used.**
1a200 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e 53 by the first INS
1a210 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 ERT, UPDATE or D
1a220 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 ELETE statement
1a230 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 within a trigger
1a240 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 , it .** returns
1a250 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73 65 the value as se
1a260 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 t when the calli
1a270 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67 ng statement beg
1a280 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a an executing..**
1a290 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64 20 ^If it is used
1a2a0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 by the second or
1a2b0 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63 68 subsequent such
1a2c0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 statement withi
1a2d0 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 n a trigger .**
1a2e0 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c program, the val
1a2f0 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c ue returned refl
1a300 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20 ects the number
1a310 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 of rows modified
1a320 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 by the .** prev
1a330 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44 ious INSERT, UPD
1a340 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 ATE or DELETE st
1a350 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 atement within t
1a360 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e he same trigger.
1a370 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 .**.** See also
1a380 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 the [sqlite3_tot
1a390 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e al_changes()] in
1a3a0 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 terface, the.**
1a3b0 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 [count_changes p
1a3c0 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 ragma], and the
1a3d0 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 [changes() SQL f
1a3e0 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 unction]..**.**
1a3f0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 If a separate th
1a400 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 read makes chang
1a410 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 es on the same d
1a420 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1a430 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c on.** while [sql
1a440 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 ite3_changes()]
1a450 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 is running then
1a460 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
1a470 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 ed.** is unpredi
1a480 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d ctable and not m
1a490 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e eaningful..*/.in
1a4a0 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 t sqlite3_change
1a4b0 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a s(sqlite3*);../*
1a4c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f .** CAPI3REF: To
1a4d0 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f tal Number Of Ro
1a4e0 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d ws Modified.** M
1a4f0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a ETHOD: sqlite3.*
1a500 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 *.** ^This funct
1a510 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 ion returns the
1a520 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 total number of
1a530 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d rows inserted, m
1a540 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 odified or.** de
1a550 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e leted by all [IN
1a560 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 SERT], [UPDATE]
1a570 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 or [DELETE] stat
1a580 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 ements completed
1a590 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 .** since the da
1a5a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1a5b0 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e n was opened, in
1a5c0 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 cluding those ex
1a5d0 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 ecuted as.** par
1a5e0 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f t of trigger pro
1a5f0 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e grams. ^Executin
1a600 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 g any other type
1a610 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e of SQL statemen
1a620 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 t.** does not af
1a630 66 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 fect the value r
1a640 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
1a650 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
1a660 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e ()..** .** ^Chan
1a670 67 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 ges made as part
1a680 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 of [foreign key
1a690 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e actions] are in
1a6a0 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a cluded in the.**
1a6b0 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 count, but thos
1a6c0 65 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f e made as part o
1a6d0 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 f REPLACE constr
1a6e0 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 aint resolution
1a6f0 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 are.** not. ^Cha
1a700 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 nges to a view t
1a710 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 hat are intercep
1a720 74 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f ted by INSTEAD O
1a730 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 F triggers .** a
1a740 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a re not counted..
1a750 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 ** .** See also
1a760 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 the [sqlite3_cha
1a770 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 nges()] interfac
1a780 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 e, the.** [count
1a790 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d _changes pragma]
1a7a0 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c , and the [total
1a7b0 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 _changes() SQL f
1a7c0 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 unction]..**.**
1a7d0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 If a separate th
1a7e0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 read makes chang
1a7f0 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 es on the same d
1a800 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1a810 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c on.** while [sql
1a820 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
1a830 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 es()] is running
1a840 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a then the value.
1a850 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 ** returned is u
1a860 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 npredictable and
1a870 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e not meaningful.
1a880 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
1a890 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 total_changes(sq
1a8a0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
1a8b0 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 CAPI3REF: Interr
1a8c0 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 upt A Long-Runni
1a8d0 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48 ng Query.** METH
1a8e0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a OD: sqlite3.**.*
1a8f0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e * ^This function
1a900 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 causes any pend
1a910 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 ing database ope
1a920 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 ration to abort
1a930 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 and.** return at
1a940 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 its earliest op
1a950 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 portunity. This
1a960 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 routine is typic
1a970 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 ally.** called i
1a980 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 n response to a
1a990 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 user action such
1a9a0 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 as pressing "Ca
1a9b0 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c ncel".** or Ctrl
1a9c0 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 -C where the use
1a9d0 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 r wants a long q
1a9e0 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 uery operation t
1a9f0 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 o halt.** immedi
1aa00 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 ately..**.** ^It
1aa10 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c is safe to call
1aa20 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 this routine fr
1aa30 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 om a thread diff
1aa40 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a erent from the.*
1aa50 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 * thread that is
1aa60 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 currently runni
1aa70 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ng the database
1aa80 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 operation. But
1aa90 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 it.** is not saf
1aaa0 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 e to call this r
1aab0 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 outine with a [d
1aac0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1aad0 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 on] that.** is c
1aae0 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 losed or might c
1aaf0 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 lose before sqli
1ab00 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 te3_interrupt()
1ab10 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e returns..**.** ^
1ab20 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 If an SQL operat
1ab30 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 ion is very near
1ab40 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 ly finished at t
1ab50 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 he time when.**
1ab60 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
1ab70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 t() is called, t
1ab80 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 hen it might not
1ab90 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 have an opportu
1aba0 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e nity.** to be in
1abb0 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 terrupted and mi
1abc0 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 ght continue to
1abd0 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a completion..**.*
1abe0 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 * ^An SQL operat
1abf0 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 ion that is inte
1ac00 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 rrupted will ret
1ac10 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 urn [SQLITE_INTE
1ac20 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 RRUPT]..** ^If t
1ac30 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 he interrupted S
1ac40 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 QL operation is
1ac50 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 an INSERT, UPDAT
1ac60 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 E, or DELETE.**
1ac70 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 that is inside a
1ac80 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 n explicit trans
1ac90 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 action, then the
1aca0 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 entire transact
1acb0 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 ion.** will be r
1acc0 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d olled back autom
1acd0 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 atically..**.**
1ace0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 ^The sqlite3_int
1acf0 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 errupt(D) call i
1ad00 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 s in effect unti
1ad10 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 l all currently
1ad20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 running.** SQL s
1ad30 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 tatements on [da
1ad40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1ad50 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 n] D complete.
1ad60 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 ^Any new SQL sta
1ad70 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 tements.** that
1ad80 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 are started afte
1ad90 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e r the sqlite3_in
1ada0 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 terrupt() call a
1adb0 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a nd before the .*
1adc0 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d * running statem
1add0 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 ents reaches zer
1ade0 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 o are interrupte
1adf0 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64 d as if they had
1ae00 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 been.** running
1ae10 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 prior to the sq
1ae20 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
1ae30 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 ) call. ^New SQ
1ae40 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 L statements.**
1ae50 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 that are started
1ae60 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 after the runni
1ae70 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 ng statement cou
1ae80 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 nt reaches zero
1ae90 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 are.** not effec
1aea0 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 ted by the sqlit
1aeb0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a e3_interrupt()..
1aec0 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 ** ^A call to sq
1aed0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
1aee0 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 D) that occurs w
1aef0 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f hen there are no
1af00 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 running.** SQL
1af10 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 statements is a
1af20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f no-op and has no
1af30 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 effect on SQL s
1af40 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 tatements.** tha
1af50 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 t are started af
1af60 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f ter the sqlite3_
1af70 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c interrupt() call
1af80 20 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a 76 6f 69 returns..*/.voi
1af90 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 d sqlite3_interr
1afa0 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a upt(sqlite3*);..
1afb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1afc0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 Determine If An
1afd0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 SQL Statement Is
1afe0 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 Complete.**.**
1aff0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
1b000 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 re useful during
1b010 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e command-line in
1b020 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 put to determine
1b030 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 if the.** curre
1b040 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 ntly entered tex
1b050 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 t seems to form
1b060 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 a complete SQL s
1b070 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 tatement or.** i
1b080 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 f additional inp
1b090 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 ut is needed bef
1b0a0 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 ore sending the
1b0b0 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c text into.** SQL
1b0c0 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e ite for parsing.
1b0d0 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ^These routine
1b0e0 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 s return 1 if th
1b0f0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a e input string.*
1b100 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 * appears to be
1b110 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 a complete SQL s
1b120 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 tatement. ^A st
1b130 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 atement is judge
1b140 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c d to be.** compl
1b150 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 ete if it ends w
1b160 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 ith a semicolon
1b170 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 token and is not
1b180 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a a prefix of a.*
1b190 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 * well-formed CR
1b1a0 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 EATE TRIGGER sta
1b1b0 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f tement. ^Semico
1b1c0 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d lons that are em
1b1d0 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a bedded within.**
1b1e0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 string literals
1b1f0 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 or quoted ident
1b200 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 ifier names or c
1b210 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a omments are not.
1b220 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 ** independent t
1b230 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 okens (they are
1b240 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 part of the toke
1b250 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 n in which they
1b260 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 are.** embedded)
1b270 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 and thus do not
1b280 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 count as a stat
1b290 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 ement terminator
1b2a0 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a . ^Whitespace.*
1b2b0 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 * and comments t
1b2c0 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 hat follow the f
1b2d0 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 inal semicolon a
1b2e0 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a re ignored..**.*
1b2f0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 * ^These routine
1b300 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 s return 0 if th
1b310 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 e statement is i
1b320 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 ncomplete. ^If
1b330 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f a.** memory allo
1b340 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 cation fails, th
1b350 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 en SQLITE_NOMEM
1b360 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
1b370 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
1b380 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 es do not parse
1b390 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
1b3a0 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 ts thus.** will
1b3b0 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 not detect synta
1b3c0 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 ctically incorre
1b3d0 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ct SQL..**.** ^(
1b3e0 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f If SQLite has no
1b3f0 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a t been initializ
1b400 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ed using [sqlite
1b410 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 3_initialize()]
1b420 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 prior .** to inv
1b430 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f oking sqlite3_co
1b440 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 mplete16() then
1b450 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
1b460 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a ze() is invoked.
1b470 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ** automatically
1b480 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 by sqlite3_comp
1b490 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 lete16(). If th
1b4a0 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f at initializatio
1b4b0 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e n fails,.** then
1b4c0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
1b4d0 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 e from sqlite3_c
1b4e0 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c omplete16() will
1b4f0 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 be non-zero.**
1b500 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 regardless of wh
1b510 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 ether or not the
1b520 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f input SQL is co
1b530 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 mplete.)^.**.**
1b540 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 The input to [sq
1b550 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 lite3_complete()
1b560 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f ] must be a zero
1b570 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 -terminated.** U
1b580 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a TF-8 string..**.
1b590 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 ** The input to
1b5a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 [sqlite3_complet
1b5b0 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 e16()] must be a
1b5c0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
1b5d0 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e .** UTF-16 strin
1b5e0 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 g in native byte
1b5f0 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 order..*/.int s
1b600 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 qlite3_complete(
1b610 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 const char *sql)
1b620 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f ;.int sqlite3_co
1b630 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 mplete16(const v
1b640 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a oid *sql);../*.*
1b650 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 * CAPI3REF: Regi
1b660 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 ster A Callback
1b670 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 To Handle SQLITE
1b680 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 _BUSY Errors.**
1b690 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d KEYWORDS: {busy-
1b6a0 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b handler callback
1b6b0 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d } {busy handler}
1b6c0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
1b6d0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 te3.**.** ^The s
1b6e0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
1b6f0 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 ler(D,X,P) routi
1b700 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 ne sets a callba
1b710 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a ck function X.**
1b720 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 that might be i
1b730 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 nvoked with argu
1b740 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a ment P whenever.
1b750 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 ** an attempt is
1b760 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 made to access
1b770 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 a database table
1b780 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
1b790 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
1b7a0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e nnection] D when
1b7b0 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a another thread.
1b7c0 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 ** or process ha
1b7d0 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b s the table lock
1b7e0 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 ed..** The sqlit
1b7f0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 e3_busy_handler(
1b800 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 ) interface is u
1b810 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 sed to implement
1b820 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 .** [sqlite3_bus
1b830 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 y_timeout()] and
1b840 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 [PRAGMA busy_ti
1b850 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 meout]..**.** ^I
1b860 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 f the busy callb
1b870 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 ack is NULL, the
1b880 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a n [SQLITE_BUSY].
1b890 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 ** is returned i
1b8a0 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 mmediately upon
1b8b0 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 encountering the
1b8c0 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 lock. ^If the
1b8d0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a busy callback.**
1b8e0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 is not NULL, th
1b8f0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 en the callback
1b900 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 might be invoked
1b910 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 with two argume
1b920 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 nts..**.** ^The
1b930 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
1b940 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c o the busy handl
1b950 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 er is a copy of
1b960 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 the void* pointe
1b970 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 r which.** is th
1b980 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
1b990 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 to sqlite3_busy
1b9a0 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 _handler(). ^Th
1b9b0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
1b9c0 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 t to.** the busy
1b9d0 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 handler callbac
1b9e0 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 k is the number
1b9f0 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 of times that th
1ba00 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 e busy handler h
1ba10 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b as.** been invok
1ba20 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f ed previously fo
1ba30 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 r the same locki
1ba40 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 ng event. ^If t
1ba50 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 he.** busy callb
1ba60 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 ack returns 0, t
1ba70 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 hen no additiona
1ba80 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d l attempts are m
1ba90 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 ade to.** access
1baa0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e the database an
1bab0 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 d [SQLITE_BUSY]
1bac0 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 is returned.** t
1bad0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f o the applicatio
1bae0 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 n..** ^If the ca
1baf0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e llback returns n
1bb00 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e on-zero, then an
1bb10 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a other attempt.**
1bb20 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 is made to acce
1bb30 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ss the database
1bb40 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 and the cycle re
1bb50 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 peats..**.** The
1bb60 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 presence of a b
1bb70 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 usy handler does
1bb80 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 not guarantee t
1bb90 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 hat it will be i
1bba0 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 nvoked.** when t
1bbb0 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e here is lock con
1bbc0 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c tention. ^If SQL
1bbd0 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 ite determines t
1bbe0 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 hat invoking the
1bbf0 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 busy.** handler
1bc00 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e could result in
1bc10 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 a deadlock, it
1bc20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e will go ahead an
1bc30 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 d return [SQLITE
1bc40 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 _BUSY].** to the
1bc50 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 application ins
1bc60 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 tead of invoking
1bc70 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 the .** busy ha
1bc80 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 ndler..** Consid
1bc90 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 er a scenario wh
1bca0 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 ere one process
1bcb0 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 is holding a rea
1bcc0 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 d lock that.** i
1bcd0 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 t is trying to p
1bce0 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 romote to a rese
1bcf0 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a rved lock and.**
1bd00 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 a second proces
1bd10 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 s is holding a r
1bd20 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 eserved lock tha
1bd30 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a t it is trying.*
1bd40 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 * to promote to
1bd50 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 an exclusive loc
1bd60 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 k. The first pr
1bd70 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f ocess cannot pro
1bd80 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 ceed.** because
1bd90 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 it is blocked by
1bda0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 the second and
1bdb0 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 the second proce
1bdc0 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f ss cannot.** pro
1bdd0 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 ceed because it
1bde0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 is blocked by th
1bdf0 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 e first. If bot
1be00 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 h processes.** i
1be10 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 nvoke the busy h
1be20 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 andlers, neither
1be30 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 will make any p
1be40 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 rogress. Theref
1be50 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 ore,.** SQLite r
1be60 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 eturns [SQLITE_B
1be70 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 USY] for the fir
1be80 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 st process, hopi
1be90 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 ng that this.**
1bea0 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 will induce the
1beb0 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f first process to
1bec0 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 release its rea
1bed0 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 d lock and allow
1bee0 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 .** the second p
1bef0 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 rocess to procee
1bf00 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 d..**.** ^The de
1bf10 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 fault busy callb
1bf20 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a ack is NULL..**.
1bf30 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f ** ^(There can o
1bf40 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 nly be a single
1bf50 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 busy handler def
1bf60 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a ined for each.**
1bf70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
1bf80 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 ction]. Setting
1bf90 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 a new busy hand
1bfa0 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a ler clears any.*
1bfb0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 * previously set
1bfc0 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f handler.)^ ^No
1bfd0 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 te that calling
1bfe0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 [sqlite3_busy_ti
1bff0 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 meout()].** or e
1c000 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d valuating [PRAGM
1c010 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e A busy_timeout=N
1c020 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 ] will change th
1c030 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 e.** busy handle
1c040 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72 r and thus clear
1c050 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 any previously
1c060 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 set busy handler
1c070 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 ..**.** The busy
1c080 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 callback should
1c090 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 not take any ac
1c0a0 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 tions which modi
1c0b0 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 fy the.** databa
1c0c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 se connection th
1c0d0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 at invoked the b
1c0e0 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e usy handler. In
1c0f0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a other words,.**
1c100 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
1c110 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 r is not reentra
1c120 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 nt. Any such ac
1c130 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 tions.** result
1c140 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 in undefined beh
1c150 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 avior..** .** A
1c160 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 busy handler mus
1c170 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 t not close the
1c180 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1c190 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 ion.** or [prepa
1c1a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 red statement] t
1c1b0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 hat invoked the
1c1c0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f busy handler..*/
1c1d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 .int sqlite3_bus
1c1e0 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 y_handler(sqlite
1c1f0 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 3*,int(*)(void*,
1c200 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f 2a int),void*);../*
1c210 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 .** CAPI3REF: Se
1c220 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 t A Busy Timeout
1c230 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
1c240 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 te3.**.** ^This
1c250 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b routine sets a [
1c260 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e sqlite3_busy_han
1c270 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 dler | busy hand
1c280 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 ler] that sleeps
1c290 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 .** for a specif
1c2a0 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 ied amount of ti
1c2b0 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 me when a table
1c2c0 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 is locked. ^The
1c2d0 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c handler.** will
1c2e0 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 sleep multiple
1c2f0 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c times until at l
1c300 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 east "ms" millis
1c310 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 econds of sleepi
1c320 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d ng.** have accum
1c330 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 ulated. ^After
1c340 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 at least "ms" mi
1c350 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c lliseconds of sl
1c360 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 eeping,.** the h
1c370 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 andler returns 0
1c380 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 which causes [s
1c390 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 qlite3_step()] t
1c3a0 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c o return.** [SQL
1c3b0 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a ITE_BUSY]..**.**
1c3c0 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 ^Calling this r
1c3d0 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 outine with an a
1c3e0 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 rgument less tha
1c3f0 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 n or equal to ze
1c400 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 ro.** turns off
1c410 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 all busy handler
1c420 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 s..**.** ^(There
1c430 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 can only be a s
1c440 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c ingle busy handl
1c450 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 er for a particu
1c460 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 lar.** [database
1c470 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 connection] at
1c480 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 any given moment
1c490 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 . If another bu
1c4a0 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 sy handler.** wa
1c4b0 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e s defined (usin
1c4c0 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f g [sqlite3_busy_
1c4d0 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f handler()]) prio
1c4e0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 r to calling.**
1c4f0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 this routine, th
1c500 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 at other busy ha
1c510 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 ndler is cleared
1c520 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c .)^.**.** See al
1c530 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73 so: [PRAGMA bus
1c540 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e y_timeout].*/.in
1c550 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 t sqlite3_busy_t
1c560 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c imeout(sqlite3*,
1c570 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a int ms);../*.**
1c580 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 CAPI3REF: Conve
1c590 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 nience Routines
1c5a0 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 For Running Quer
1c5b0 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ies.** METHOD: s
1c5c0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 qlite3.**.** Thi
1c5d0 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e s is a legacy in
1c5e0 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20 terface that is
1c5f0 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 preserved for ba
1c600 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 ckwards compatib
1c610 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 ility..** Use of
1c620 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 this interface
1c630 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 is not recommend
1c640 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 ed..**.** Defini
1c650 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c tion: A <b>resul
1c660 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d t table</b> is m
1c670 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 emory data struc
1c680 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 ture created by
1c690 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
1c6a0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 get_table()] int
1c6b0 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c erface. A resul
1c6c0 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 t table records
1c6d0 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 the.** complete
1c6e0 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 query results fr
1c6f0 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 om one or more q
1c700 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 ueries..**.** Th
1c710 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 e table conceptu
1c720 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 ally has a numbe
1c730 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f r of rows and co
1c740 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 lumns. But.** t
1c750 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 hese numbers are
1c760 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 not part of the
1c770 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 result table it
1c780 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 self. These.**
1c790 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 numbers are obta
1c7a0 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e ined separately.
1c7b0 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e Let N be the n
1c7c0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a umber of rows.**
1c7d0 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 and M be the nu
1c7e0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e mber of columns.
1c7f0 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 .**.** A result
1c800 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 table is an arra
1c810 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f y of pointers to
1c820 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
1c830 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a UTF-8 strings..
1c840 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b ** There are (N+
1c850 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 1)*M elements in
1c860 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 the array. The
1c870 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 first M pointer
1c880 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 s point.** to ze
1c890 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 ro-terminated st
1c8a0 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 rings that cont
1c8b0 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 ain the names of
1c8c0 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a the columns..**
1c8d0 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 The remaining e
1c8e0 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 ntries all point
1c8f0 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 to query result
1c900 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 s. NULL values
1c910 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c result.** in NUL
1c920 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c L pointers. All
1c930 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 other values ar
1c940 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 e in their UTF-8
1c950 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
1c960 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 .** string repre
1c970 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 sentation as ret
1c980 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 urned by [sqlite
1c990 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 3_column_text()]
1c9a0 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 ..**.** A result
1c9b0 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e table might con
1c9c0 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d sist of one or m
1c9d0 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ore memory alloc
1c9e0 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 ations..** It is
1c9f0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 not safe to pas
1ca00 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 s a result table
1ca10 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 directly to [sq
1ca20 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a lite3_free()]..*
1ca30 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 * A result table
1ca40 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c should be deall
1ca50 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 ocated using [sq
1ca60 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 lite3_free_table
1ca70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 ()]..**.** ^(As
1ca80 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 an example of th
1ca90 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 e result table f
1caa0 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 ormat, suppose a
1cab0 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a query result.**
1cac0 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a is as follows:.
1cad0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
1cae0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 e><pre>.**
1caf0 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 Name |
1cb00 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d Age.** --
1cb10 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
1cb20 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 -----.**
1cb30 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 Alice | 43
1cb40 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 .** Bob
1cb50 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 | 28.**
1cb60 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 Cindy
1cb70 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e | 21.** </pre>
1cb80 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
1cb90 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 .** There are tw
1cba0 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 o column (M==2)
1cbb0 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 and three rows (
1cbc0 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 N==3). Thus the
1cbd0 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 .** result table
1cbe0 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 has 8 entries.
1cbf0 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 Suppose the res
1cc00 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f ult table is sto
1cc10 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 red.** in an arr
1cc20 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c ay names azResul
1cc30 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c t. Then azResul
1cc40 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e t holds this con
1cc50 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f tent:.**.** <blo
1cc60 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
1cc70 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
1cc80 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 [0] = "Name"
1cc90 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
1cca0 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 sult[1] = "A
1ccb0 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 ge";.** a
1ccc0 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d zResult[2] =
1ccd0 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 "Alice";.**
1cce0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
1ccf0 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 ;3] = "43";.**
1cd00 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
1cd10 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 91;4] = "Bob";.*
1cd20 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
1cd30 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b t[5] = "28";
1cd40 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
1cd50 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 ult[6] = "Ci
1cd60 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 ndy";.**
1cd70 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 azResult[7]
1cd80 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 = "21";.** </pre
1cd90 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e ></blockquote>)^
1cda0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
1cdb0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 te3_get_table()
1cdc0 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 function evaluat
1cdd0 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a es one or more.*
1cde0 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 * semicolon-sepa
1cdf0 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d rated SQL statem
1ce00 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f ents in the zero
1ce10 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d -terminated UTF-
1ce20 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 8.** string of i
1ce30 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 ts 2nd parameter
1ce40 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 and returns a r
1ce50 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 esult table to t
1ce60 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 he.** pointer gi
1ce70 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 ven in its 3rd p
1ce80 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 arameter..**.**
1ce90 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 After the applic
1cea0 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 ation has finish
1ceb0 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75 ed with the resu
1cec0 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f lt from sqlite3_
1ced0 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 get_table(),.**
1cee0 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 it must pass the
1cef0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f result table po
1cf00 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 inter to sqlite3
1cf10 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e _free_table() in
1cf20 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c order to.** rel
1cf30 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 ease the memory
1cf40 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 that was malloce
1cf50 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 d. Because of t
1cf60 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 he way the.** [s
1cf70 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
1cf80 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 happens within
1cf90 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
1cfa0 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 e(), the calling
1cfb0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 .** function mus
1cfc0 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c t not try to cal
1cfd0 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 l [sqlite3_free(
1cfe0 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e )] directly. On
1cff0 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 ly.** [sqlite3_f
1d000 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 ree_table()] is
1d010 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 able to release
1d020 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 the memory prope
1d030 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a rly and safely..
1d040 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
1d050 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 3_get_table() in
1d060 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 terface is imple
1d070 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 mented as a wrap
1d080 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 per around.** [s
1d090 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 qlite3_exec()].
1d0a0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 The sqlite3_get
1d0b0 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 _table() routine
1d0c0 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 does not have a
1d0d0 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 ccess.** to any
1d0e0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 internal data st
1d0f0 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 ructures of SQLi
1d100 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c te. It uses onl
1d110 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 y the public.**
1d120 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 interface define
1d130 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f d here. As a co
1d140 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 nsequence, error
1d150 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 s that occur in
1d160 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c the.** wrapper l
1d170 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 ayer outside of
1d180 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 the internal [sq
1d190 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 lite3_exec()] ca
1d1a0 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 ll are not.** re
1d1b0 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 flected in subse
1d1c0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b quent calls to [
1d1d0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
1d1e0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
1d1f0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 3_errmsg()]..*/.
1d200 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f int sqlite3_get_
1d210 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 table(. sqlite3
1d220 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f *db, /
1d230 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 * An open databa
1d240 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 se */. const ch
1d250 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a ar *zSql, /*
1d260 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 SQL to be evalu
1d270 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a ated */. char *
1d280 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 **pazResult,
1d290 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 /* Results of th
1d2a0 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 e query */. int
1d2b0 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 *pnRow,
1d2c0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 /* Number of
1d2d0 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 result rows writ
1d2e0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e ten here */. in
1d2f0 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 t *pnColumn,
1d300 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 /* Number of
1d310 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 result columns
1d320 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a written here */.
1d330 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 char **pzErrms
1d340 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 g /* Error
1d350 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 msg written her
1d360 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c e */.);.void sql
1d370 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 ite3_free_table(
1d380 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a char **result);.
1d390 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1d3a0 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e Formatted Strin
1d3b0 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 g Printing Funct
1d3c0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ions.**.** These
1d3d0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f routines are wo
1d3e0 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 rk-alikes of the
1d3f0 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 "printf()" fami
1d400 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a ly of functions.
1d410 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e ** from the stan
1d420 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a dard C library..
1d430 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
1d440 73 20 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 s understand mos
1d450 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 t of the common
1d460 4b 26 52 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f K&R formatting o
1d470 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20 ptions,.** plus
1d480 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 some additional
1d490 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f 72 non-standard for
1d4a0 6d 61 74 73 2c 20 64 65 74 61 69 6c 65 64 20 62 mats, detailed b
1d4b0 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 elow..** Note th
1d4c0 61 74 20 73 6f 6d 65 20 6f 66 20 74 68 65 20 6d at some of the m
1d4d0 6f 72 65 20 6f 62 73 63 75 72 65 20 66 6f 72 6d ore obscure form
1d4e0 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66 atting options f
1d4f0 72 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a 20 43 2d rom recent.** C-
1d500 6c 69 62 72 61 72 79 20 73 74 61 6e 64 61 72 64 library standard
1d510 73 20 61 72 65 20 6f 6d 69 74 74 65 64 20 66 72 s are omitted fr
1d520 6f 6d 20 74 68 69 73 20 69 6d 70 6c 65 6d 65 6e om this implemen
1d530 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 tation..**.** ^T
1d540 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e he sqlite3_mprin
1d550 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 tf() and sqlite3
1d560 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 _vmprintf() rout
1d570 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 ines write their
1d580 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f .** results into
1d590 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 memory obtained
1d5a0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
1d5b0 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 alloc()]..** The
1d5c0 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 strings returne
1d5d0 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 d by these two r
1d5e0 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 outines should b
1d5f0 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 e.** released by
1d600 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
1d610 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e ]. ^Both routin
1d620 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e es return a.** N
1d630 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b ULL pointer if [
1d640 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1d650 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 ] is unable to a
1d660 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a llocate enough.*
1d670 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 * memory to hold
1d680 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 the resulting s
1d690 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 tring..**.** ^(T
1d6a0 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 he sqlite3_snpri
1d6b0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 ntf() routine is
1d6c0 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 similar to "snp
1d6d0 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a rintf()" from.**
1d6e0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 the standard C
1d6f0 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 library. The re
1d700 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 sult is written
1d710 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 into the.** buff
1d720 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 er supplied as t
1d730 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
1d740 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 ter whose size i
1d750 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 s given by.** th
1d760 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
1d770 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 r. Note that the
1d780 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a order of the.**
1d790 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d first two param
1d7a0 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 eters is reverse
1d7b0 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 d from snprintf(
1d7c0 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e ).)^ This is an
1d7d0 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 .** historical a
1d7e0 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e ccident that can
1d7f0 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 not be fixed wit
1d800 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a hout breaking.**
1d810 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 backwards compa
1d820 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 tibility. ^(Not
1d830 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 e also that sqli
1d840 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a te3_snprintf().*
1d850 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e * returns a poin
1d860 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 ter to its buffe
1d870 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 r instead of the
1d880 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 number of.** ch
1d890 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c aracters actuall
1d8a0 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 y written into t
1d8b0 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 he buffer.)^ We
1d8c0 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 admit that.** t
1d8d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 he number of cha
1d8e0 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 racters written
1d8f0 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 would be a more
1d900 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a useful return.**
1d910 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 value but we ca
1d920 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 nnot change the
1d930 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
1d940 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e f sqlite3_snprin
1d950 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 tf().** now with
1d960 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d out breaking com
1d970 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a patibility..**.*
1d980 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 * ^As long as th
1d990 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 e buffer size is
1d9a0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 greater than ze
1d9b0 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 ro, sqlite3_snpr
1d9c0 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e intf().** guaran
1d9d0 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 tees that the bu
1d9e0 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a ffer is always z
1d9f0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 ero-terminated.
1da00 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 ^The first.** p
1da10 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 arameter "n" is
1da20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f the total size o
1da30 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e f the buffer, in
1da40 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f cluding space fo
1da50 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 r.** the zero te
1da60 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 rminator. So th
1da70 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 e longest string
1da80 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d that can be com
1da90 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 pletely.** writt
1daa0 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 en will be n-1 c
1dab0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a haracters..**.**
1dac0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 ^The sqlite3_vs
1dad0 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e nprintf() routin
1dae0 65 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76 e is a varargs v
1daf0 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 ersion of sqlite
1db00 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 3_snprintf()..**
1db10 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
1db20 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 es all implement
1db30 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c some additional
1db40 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f formatting.** o
1db50 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 ptions that are
1db60 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 useful for const
1db70 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 ructing SQL stat
1db80 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f ements..** All o
1db90 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e f the usual prin
1dba0 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 tf() formatting
1dbb0 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 options apply.
1dbc0 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 In addition, the
1dbd0 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 re.** is are "%q
1dbe0 22 2c 20 22 25 51 22 2c 20 22 25 77 22 20 61 6e ", "%Q", "%w" an
1dbf0 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a d "%z" options..
1dc00 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f **.** ^(The %q o
1dc10 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 ption works like
1dc20 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 %s in that it s
1dc30 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c ubstitutes a nul
1dc40 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 -terminated.** s
1dc50 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 tring from the a
1dc60 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 rgument list. B
1dc70 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c ut %q also doubl
1dc80 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 es every '\'' ch
1dc90 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 aracter..** %q i
1dca0 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 s designed for u
1dcb0 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 se inside a stri
1dcc0 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 ng literal.)^ B
1dcd0 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 y doubling each
1dce0 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 '\''.** characte
1dcf0 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 r it escapes tha
1dd00 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 t character and
1dd10 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 allows it to be
1dd20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a inserted into.**
1dd30 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a the string..**.
1dd40 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 ** For example,
1dd50 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e assume the strin
1dd60 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 g variable zText
1dd70 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 contains text a
1dd80 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a s follows:.**.**
1dd90 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
1dda0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 e>.** char *zTe
1ddb0 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 xt = "It's a hap
1ddc0 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 py day!";.** </p
1ddd0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
1dde0 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 .**.** One can u
1ddf0 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 se this text in
1de00 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 an SQL statement
1de10 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
1de20 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
1de30 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a pre>.** char *z
1de40 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 SQL = sqlite3_mp
1de50 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e rintf("INSERT IN
1de60 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 TO table VALUES(
1de70 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a '%q')", zText);.
1de80 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 ** sqlite3_exec
1de90 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c (db, zSQL, 0, 0,
1dea0 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 0);.** sqlite3
1deb0 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 _free(zSQL);.**
1dec0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
1ded0 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 te>.**.** Becaus
1dee0 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 e the %q format
1def0 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 string is used,
1df00 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 the '\'' charact
1df10 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 er in zText.** i
1df20 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 s escaped and th
1df30 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 e SQL generated
1df40 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a is as follows:.*
1df50 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
1df60 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 ><pre>.** INSER
1df70 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 T INTO table1 VA
1df80 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 LUES('It''s a ha
1df90 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f ppy day!').** </
1dfa0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
1dfb0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 >.**.** This is
1dfc0 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 correct. Had we
1dfd0 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 used %s instead
1dfe0 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 of %q, the gene
1dff0 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 rated SQL.** wou
1e000 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c ld have looked l
1e010 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 ike this:.**.**
1e020 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
1e030 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 >.** INSERT INT
1e040 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 O table1 VALUES(
1e050 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 'It's a happy da
1e060 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c y!');.** </pre><
1e070 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
1e080 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 ** This second e
1e090 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c xample is an SQL
1e0a0 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 syntax error.
1e0b0 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c As a general rul
1e0c0 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 e you should.**
1e0d0 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e always use %q in
1e0e0 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e stead of %s when
1e0f0 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 inserting text
1e100 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 into a string li
1e110 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 teral..**.** ^(T
1e120 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 he %Q option wor
1e130 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 ks like %q excep
1e140 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 t it also adds s
1e150 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f ingle quotes aro
1e160 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 und.** the outsi
1e170 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 de of the total
1e180 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f string. Additio
1e190 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 nally, if the pa
1e1a0 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a rameter in the.*
1e1b0 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 * argument list
1e1c0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
1e1d0 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65 r, %Q substitute
1e1e0 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c s the text "NULL
1e1f0 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 " (without.** si
1e200 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 ngle quotes).)^
1e210 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 So, for example
1e220 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a , one could say:
1e230 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
1e240 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 te><pre>.** cha
1e250 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 r *zSQL = sqlite
1e260 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 3_mprintf("INSER
1e270 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c T INTO table VAL
1e280 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 UES(%Q)", zText)
1e290 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 ;.** sqlite3_ex
1e2a0 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 ec(db, zSQL, 0,
1e2b0 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 0, 0);.** sqlit
1e2c0 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a e3_free(zSQL);.*
1e2d0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
1e2e0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 uote>.**.** The
1e2f0 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 code above will
1e300 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 render a correct
1e310 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 SQL statement i
1e320 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 n the zSQL.** va
1e330 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 riable even if t
1e340 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c he zText variabl
1e350 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e e is a NULL poin
1e360 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 ter..**.** ^(The
1e370 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 "%w" formatting
1e380 20 6f 70 74 69 6f 6e 20 69 73 20 6c 69 6b 65 20 option is like
1e390 22 25 71 22 20 65 78 63 65 70 74 20 74 68 61 74 "%q" except that
1e3a0 20 69 74 20 65 78 70 65 63 74 73 20 74 6f 0a 2a it expects to.*
1e3b0 2a 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 77 * be contained w
1e3c0 69 74 68 69 6e 20 64 6f 75 62 6c 65 2d 71 75 6f ithin double-quo
1e3d0 74 65 73 20 69 6e 73 74 65 61 64 20 6f 66 20 73 tes instead of s
1e3e0 69 6e 67 6c 65 20 71 75 6f 74 65 73 2c 20 61 6e ingle quotes, an
1e3f0 64 20 69 74 0a 2a 2a 20 65 73 63 61 70 65 73 20 d it.** escapes
1e400 74 68 65 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 the double-quote
1e410 20 63 68 61 72 61 63 74 65 72 20 69 6e 73 74 65 character inste
1e420 61 64 20 6f 66 20 74 68 65 20 73 69 6e 67 6c 65 ad of the single
1e430 2d 71 75 6f 74 65 0a 2a 2a 20 63 68 61 72 61 63 -quote.** charac
1e440 74 65 72 2e 29 5e 20 20 54 68 65 20 22 25 77 22 ter.)^ The "%w"
1e450 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 formatting opti
1e460 6f 6e 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 on is intended f
1e470 6f 72 20 73 61 66 65 6c 79 20 69 6e 73 65 72 74 or safely insert
1e480 69 6e 67 0a 2a 2a 20 74 61 62 6c 65 20 61 6e 64 ing.** table and
1e490 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 69 6e column names in
1e4a0 74 6f 20 61 20 63 6f 6e 73 74 72 75 63 74 65 64 to a constructed
1e4b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a SQL statement..
1e4c0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 **.** ^(The "%z"
1e4d0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 formatting opti
1e4e0 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 on works like "%
1e4f0 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a s" but with the.
1e500 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 ** addition that
1e510 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e after the strin
1e520 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 g has been read
1e530 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a and copied into.
1e540 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b ** the result, [
1e550 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 sqlite3_free()]
1e560 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 is called on the
1e570 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e input string.)^
1e580 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 .*/.char *sqlite
1e590 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 3_mprintf(const
1e5a0 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 char*,...);.char
1e5b0 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e *sqlite3_vmprin
1e5c0 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 tf(const char*,
1e5d0 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a va_list);.char *
1e5e0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
1e5f0 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 (int,char*,const
1e600 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 char*, ...);.ch
1e610 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 ar *sqlite3_vsnp
1e620 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c rintf(int,char*,
1e630 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f const char*, va_
1e640 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 list);../*.** CA
1e650 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 PI3REF: Memory A
1e660 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 llocation Subsys
1e670 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 tem.**.** The SQ
1e680 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 Lite core uses t
1e690 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 hese three routi
1e6a0 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 nes for all of i
1e6b0 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e ts own.** intern
1e6c0 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 al memory alloca
1e6d0 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 tion needs. "Cor
1e6e0 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f e" in the previo
1e6f0 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 us sentence.** d
1e700 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 oes not include
1e710 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d operating-system
1e720 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d specific VFS im
1e730 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 plementation. T
1e740 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 he.** Windows VF
1e750 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 S uses native ma
1e760 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 lloc() and free(
1e770 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 ) for some opera
1e780 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 tions..**.** ^Th
1e790 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 e sqlite3_malloc
1e7a0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 () routine retur
1e7b0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
1e7c0 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 a block.** of me
1e7d0 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 mory at least N
1e7e0 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c bytes in length,
1e7f0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 where N is the
1e800 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 parameter..** ^I
1e810 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 f sqlite3_malloc
1e820 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 () is unable to
1e830 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e obtain sufficien
1e840 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 t free.** memory
1e850 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e , it returns a N
1e860 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 ULL pointer. ^I
1e870 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 f the parameter
1e880 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f N to.** sqlite3_
1e890 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f malloc() is zero
1e8a0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 or negative the
1e8b0 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 n sqlite3_malloc
1e8c0 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 () returns.** a
1e8d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
1e8e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1e8f0 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75 _malloc64(N) rou
1e900 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20 tine works just
1e910 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f like.** sqlite3_
1e920 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74 malloc(N) except
1e930 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e that N is an un
1e940 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e signed 64-bit in
1e950 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a teger instead.**
1e960 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d of a signed 32-
1e970 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a bit integer..**.
1e980 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 ** ^Calling sqli
1e990 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 te3_free() with
1e9a0 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f a pointer previo
1e9b0 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a usly returned.**
1e9c0 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c by sqlite3_mall
1e9d0 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f oc() or sqlite3_
1e9e0 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 realloc() releas
1e9f0 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 es that memory s
1ea00 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 o.** that it mig
1ea10 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e ht be reused. ^
1ea20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 The sqlite3_free
1ea30 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a () routine is.**
1ea40 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 a no-op if is c
1ea50 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c alled with a NUL
1ea60 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 L pointer. Pass
1ea70 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 ing a NULL point
1ea80 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 er.** to sqlite3
1ea90 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c _free() is harml
1eaa0 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e ess. After bein
1eab0 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a g freed, memory.
1eac0 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 ** should neithe
1ead0 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 r be read nor wr
1eae0 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 itten. Even rea
1eaf0 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 ding previously
1eb00 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 freed.** memory
1eb10 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 might result in
1eb20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 a segmentation f
1eb30 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 ault or other se
1eb40 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d vere error..** M
1eb50 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e emory corruption
1eb60 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e , a segmentation
1eb70 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 fault, or other
1eb80 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a severe error.**
1eb90 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 might result if
1eba0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 sqlite3_free()
1ebb0 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 is called with a
1ebc0 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 non-NULL pointe
1ebd0 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f r that.** was no
1ebe0 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 t obtained from
1ebf0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1ec00 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c or sqlite3_real
1ec10 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 loc()..**.** ^Th
1ec20 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f e sqlite3_reallo
1ec30 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 c(X,N) interface
1ec40 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 attempts to res
1ec50 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d ize a.** prior m
1ec60 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
1ec70 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 X to be at leas
1ec80 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 t N bytes..** ^I
1ec90 66 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 f the X paramete
1eca0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 r to sqlite3_rea
1ecb0 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 lloc(X,N).** is
1ecc0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 a NULL pointer t
1ecd0 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 hen its behavior
1ece0 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f is identical to
1ecf0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 calling.** sqli
1ed00 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a te3_malloc(N)..*
1ed10 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61 * ^If the N para
1ed20 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
1ed30 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 _realloc(X,N) is
1ed40 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 zero or.** nega
1ed50 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 tive then the be
1ed60 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c havior is exactl
1ed70 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 y the same as ca
1ed80 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 lling.** sqlite3
1ed90 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 _free(X)..** ^sq
1eda0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c lite3_realloc(X,
1edb0 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 N) returns a poi
1edc0 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 nter to a memory
1edd0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f allocation.** o
1ede0 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 f at least N byt
1edf0 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 es in size or NU
1ee00 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 LL if insufficie
1ee10 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61 nt memory is ava
1ee20 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d ilable..** ^If M
1ee30 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 is the size of
1ee40 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 the prior alloca
1ee50 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e tion, then min(N
1ee60 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 ,M) bytes.** of
1ee70 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 the prior alloca
1ee80 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 tion are copied
1ee90 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 into the beginni
1eea0 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 ng of buffer ret
1eeb0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 urned.** by sqli
1eec0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 te3_realloc(X,N)
1eed0 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 and the prior a
1eee0 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 llocation is fre
1eef0 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 ed..** ^If sqlit
1ef00 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 e3_realloc(X,N)
1ef10 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 returns NULL and
1ef20 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 N is positive,
1ef30 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f then the.** prio
1ef40 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 r allocation is
1ef50 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a not freed..**.**
1ef60 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 ^The sqlite3_re
1ef70 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74 alloc64(X,N) int
1ef80 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68 erfaces works th
1ef90 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c e same as.** sql
1efa0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e ite3_realloc(X,N
1efb0 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 ) except that N
1efc0 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 is a 64-bit unsi
1efd0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73 gned integer ins
1efe0 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d tead.** of a 32-
1eff0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 bit signed integ
1f000 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 er..**.** ^If X
1f010 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f is a memory allo
1f020 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c cation previousl
1f030 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
1f040 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1f050 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c ,.** sqlite3_mal
1f060 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33 loc64(), sqlite3
1f070 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 _realloc(), or s
1f080 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 qlite3_realloc64
1f090 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 (), then.** sqli
1f0a0 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 te3_msize(X) ret
1f0b0 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 urns the size of
1f0c0 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c that memory all
1f0d0 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73 ocation in bytes
1f0e0 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 ..** ^The value
1f0f0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
1f100 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67 te3_msize(X) mig
1f110 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 ht be larger tha
1f120 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 n the number.**
1f130 6f 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74 of bytes request
1f140 65 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c ed when X was al
1f150 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20 located. ^If X
1f160 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
1f170 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 r then.** sqlite
1f180 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 3_msize(X) retur
1f190 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70 ns zero. If X p
1f1a0 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69 oints to somethi
1f1b0 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a ng that is not.*
1f1c0 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 * the beginning
1f1d0 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 of memory alloca
1f1e0 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70 tion, or if it p
1f1f0 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65 oints to a forme
1f200 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d rly.** valid mem
1f210 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 ory allocation t
1f220 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e hat has now been
1f230 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65 freed, then the
1f240 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 behavior.** of
1f250 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 sqlite3_msize(X)
1f260 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e is undefined an
1f270 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66 d possibly harmf
1f280 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d ul..**.** ^The m
1f290 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 emory returned b
1f2a0 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 y sqlite3_malloc
1f2b0 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c (), sqlite3_real
1f2c0 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 loc(),.** sqlite
1f2d0 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 3_malloc64(), an
1f2e0 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f d sqlite3_reallo
1f2f0 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 c64().** is alwa
1f300 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 ys aligned to at
1f310 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 least an 8 byte
1f320 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f boundary, or to
1f330 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 a.** 4 byte bou
1f340 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 ndary if the [SQ
1f350 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 LITE_4_BYTE_ALIG
1f360 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 NED_MALLOC] comp
1f370 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 ile-time.** opti
1f380 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a on is used..**.*
1f390 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 * In SQLite vers
1f3a0 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e ion 3.5.0 and 3.
1f3b0 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 5.1, it was poss
1f3c0 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a ible to define.*
1f3d0 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 * the SQLITE_OMI
1f3e0 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 T_MEMORY_ALLOCAT
1f3f0 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 ION which would
1f400 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d cause the built-
1f410 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 in.** implementa
1f420 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f tion of these ro
1f430 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 utines to be omi
1f440 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 tted. That capa
1f450 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 bility.** is no
1f460 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e longer provided.
1f470 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 Only built-in
1f480 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
1f490 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a s can be used..*
1f4a0 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 *.** Prior to SQ
1f4b0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 Lite version 3.7
1f4c0 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 .10, the Windows
1f4d0 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 OS interface la
1f4e0 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 yer called.** th
1f4f0 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 e system malloc(
1f500 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 ) and free() dir
1f510 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 ectly when conve
1f520 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d rting.** filenam
1f530 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 es between the U
1f540 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 TF-8 encoding us
1f550 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 ed by SQLite.**
1f560 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c and whatever fil
1f570 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 ename encoding i
1f580 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 s used by the pa
1f590 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 rticular Windows
1f5a0 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e .** installation
1f5b0 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 . Memory alloca
1f5c0 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 tion errors were
1f5d0 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a detected, but.*
1f5e0 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f * they were repo
1f5f0 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 rted back as [SQ
1f600 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f LITE_CANTOPEN] o
1f610 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 r.** [SQLITE_IOE
1f620 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 RR] rather than
1f630 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a [SQLITE_NOMEM]..
1f640 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 **.** The pointe
1f650 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b r arguments to [
1f660 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 sqlite3_free()]
1f670 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 and [sqlite3_rea
1f680 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 lloc()].** must
1f690 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f be either NULL o
1f6a0 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 r else pointers
1f6b0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 obtained from a
1f6c0 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 prior.** invocat
1f6d0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f ion of [sqlite3_
1f6e0 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 malloc()] or [sq
1f6f0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d lite3_realloc()]
1f700 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f that have.** no
1f710 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 t yet been relea
1f720 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 sed..**.** The a
1f730 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
1f740 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 not read or writ
1f750 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a e any part of.**
1f760 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f a block of memo
1f770 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 ry after it has
1f780 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 been released us
1f790 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
1f7a0 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 free()] or [sqli
1f7b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a te3_realloc()]..
1f7c0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 */.void *sqlite3
1f7d0 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f _malloc(int);.vo
1f7e0 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c id *sqlite3_mall
1f7f0 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e oc64(sqlite3_uin
1f800 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 t64);.void *sqli
1f810 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 te3_realloc(void
1f820 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 *, int);.void *s
1f830 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 qlite3_realloc64
1f840 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f (void*, sqlite3_
1f850 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 uint64);.void sq
1f860 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a lite3_free(void*
1f870 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 );.sqlite3_uint6
1f880 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 4 sqlite3_msize(
1f890 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 void*);../*.** C
1f8a0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 API3REF: Memory
1f8b0 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 Allocator Statis
1f8c0 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 tics.**.** SQLit
1f8d0 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 e provides these
1f8e0 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 two interfaces
1f8f0 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e for reporting on
1f900 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f the status.** o
1f910 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
1f920 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 alloc()], [sqlit
1f930 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 e3_free()], and
1f940 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
1f950 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c ()].** routines,
1f960 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 which form the
1f970 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 built-in memory
1f980 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 allocation subsy
1f990 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 stem..**.** ^The
1f9a0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
1f9b0 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 _used()] routine
1f9c0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
1f9d0 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 ber of bytes.**
1f9e0 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e of memory curren
1f9f0 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 tly outstanding
1fa00 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f (malloced but no
1fa10 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 t freed)..** ^Th
1fa20 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 e [sqlite3_memor
1fa30 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 y_highwater()] r
1fa40 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 outine returns t
1fa50 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 he maximum.** va
1fa60 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f lue of [sqlite3_
1fa70 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 memory_used()] s
1fa80 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 ince the high-wa
1fa90 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 ter mark.** was
1faa0 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 last reset. ^Th
1fab0 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 e values returne
1fac0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 d by [sqlite3_me
1fad0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 mory_used()] and
1fae0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d .** [sqlite3_mem
1faf0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d ory_highwater()]
1fb00 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 include any ove
1fb10 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 rhead.** added b
1fb20 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 y SQLite in its
1fb30 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
1fb40 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f f [sqlite3_mallo
1fb50 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 c()],.** but not
1fb60 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 overhead added
1fb70 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 by the any under
1fb80 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 lying system lib
1fb90 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 rary.** routines
1fba0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d that [sqlite3_m
1fbb0 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c alloc()] may cal
1fbc0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 l..**.** ^The me
1fbd0 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 mory high-water
1fbe0 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f mark is reset to
1fbf0 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c the current val
1fc00 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 ue of.** [sqlite
1fc10 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 3_memory_used()]
1fc20 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 if and only if
1fc30 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f the parameter to
1fc40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d .** [sqlite3_mem
1fc50 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d ory_highwater()]
1fc60 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 is true. ^The
1fc70 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a value returned.*
1fc80 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 * by [sqlite3_me
1fc90 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 mory_highwater(1
1fca0 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 )] is the high-w
1fcb0 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 ater mark.** pri
1fcc0 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e or to the reset.
1fcd0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 .*/.sqlite3_int6
1fce0 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 4 sqlite3_memory
1fcf0 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c _used(void);.sql
1fd00 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 ite3_int64 sqlit
1fd10 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
1fd20 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 ter(int resetFla
1fd30 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 g);../*.** CAPI3
1fd40 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 REF: Pseudo-Rand
1fd50 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 om Number Genera
1fd60 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 tor.**.** SQLite
1fd70 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 contains a high
1fd80 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d -quality pseudo-
1fd90 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 random number ge
1fda0 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 nerator (PRNG) u
1fdb0 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 sed to.** select
1fdc0 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c random [ROWID |
1fdd0 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e ROWIDs] when in
1fde0 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f serting new reco
1fdf0 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 rds into a table
1fe00 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 that.** already
1fe10 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 uses the larges
1fe20 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 t possible [ROWI
1fe30 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 D]. The PRNG is
1fe40 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a also used for.*
1fe50 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 * the build-in r
1fe60 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 andom() and rand
1fe70 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e omblob() SQL fun
1fe80 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e ctions. This in
1fe90 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a terface allows.*
1fea0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 * applications t
1feb0 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d o access the sam
1fec0 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 e PRNG for other
1fed0 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a purposes..**.**
1fee0 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 ^A call to this
1fef0 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 routine stores
1ff00 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f N bytes of rando
1ff10 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 mness into buffe
1ff20 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70 r P..** ^The P p
1ff30 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20 arameter can be
1ff40 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a a NULL pointer..
1ff50 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72 **.** ^If this r
1ff60 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62 outine has not b
1ff70 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63 een previously c
1ff80 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20 alled or if the
1ff90 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c previous.** call
1ffa0 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e had N less than
1ffb0 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70 one or a NULL p
1ffc0 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68 ointer for P, th
1ffd0 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a en the PRNG is.*
1ffe0 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 * seeded using r
1fff0 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e andomness obtain
20000 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e ed from the xRan
20010 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f domness method o
20020 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 f.** the default
20030 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f [sqlite3_vfs] o
20040 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 bject..** ^If th
20050 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 e previous call
20060 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 to this routine
20070 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 had an N of 1 or
20080 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e more and a.** n
20090 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74 on-NULL P then t
200a0 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d he pseudo-random
200b0 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 ness is generate
200c0 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 d.** internally
200d0 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f and without reco
200e0 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c urse to the [sql
200f0 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f ite3_vfs] xRando
20100 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e mness.** method.
20110 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 .*/.void sqlite3
20120 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 _randomness(int
20130 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a N, void *P);../*
20140 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
20150 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f mpile-Time Autho
20160 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 rization Callbac
20170 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 ks.** METHOD: sq
20180 6c 69 74 65 33 0a 2a 2a 20 4b 45 59 57 4f 52 44 lite3.** KEYWORD
20190 53 3a 20 7b 61 75 74 68 6f 72 69 7a 65 72 20 63 S: {authorizer c
201a0 61 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a 2a 2a 20 5e allback}.**.** ^
201b0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 This routine reg
201c0 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 isters an author
201d0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 izer callback wi
201e0 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a th a particular.
201f0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
20200 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 nection], suppli
20210 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 ed in the first
20220 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 argument..** ^Th
20230 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
20240 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
20250 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e as SQL statemen
20260 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d ts are being com
20270 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c piled.** by [sql
20280 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
20290 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 or its variants
202a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
202b0 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 _v2()],.** [sqli
202c0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d te3_prepare16()]
202d0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 and [sqlite3_pr
202e0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 epare16_v2()].
202f0 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 ^At various.** p
20300 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 oints during the
20310 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f compilation pro
20320 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 cess, as logic i
20330 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a s being created.
20340 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 ** to perform va
20350 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 rious actions, t
20360 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
20370 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
20380 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 d to.** see if t
20390 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 hose actions are
203a0 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 allowed. ^The
203b0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
203c0 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 ack should.** re
203d0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d turn [SQLITE_OK]
203e0 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 to allow the ac
203f0 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 tion, [SQLITE_IG
20400 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f NORE] to disallo
20410 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 w the.** specifi
20420 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c c action but all
20430 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 ow the SQL state
20440 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 ment to continue
20450 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c to be.** compil
20460 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 ed, or [SQLITE_D
20470 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 ENY] to cause th
20480 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 e entire SQL sta
20490 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 tement to be.**
204a0 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e rejected with an
204b0 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 error. ^If the
204c0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
204d0 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 back returns.**
204e0 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 any value other
204f0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e than [SQLITE_IGN
20500 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b ORE], [SQLITE_OK
20510 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 ], or [SQLITE_DE
20520 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 NY].** then the
20530 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
20540 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 _v2()] or equiva
20550 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 lent call that t
20560 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 riggered.** the
20570 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 authorizer will
20580 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 fail with an err
20590 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a or message..**.*
205a0 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 * When the callb
205b0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ack returns [SQL
205c0 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 ITE_OK], that me
205d0 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f ans the operatio
205e0 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 n.** requested i
205f0 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 s ok. ^When the
20600 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
20610 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c s [SQLITE_DENY],
20620 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
20630 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
20640 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c r equivalent cal
20650 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 l that triggered
20660 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a the.** authoriz
20670 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 er will fail wit
20680 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 h an error messa
20690 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 ge explaining th
206a0 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 at.** access is
206b0 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e denied. .**.** ^
206c0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 The first parame
206d0 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f ter to the autho
206e0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 rizer callback i
206f0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 s a copy of the
20700 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 third.** paramet
20710 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 er to the sqlite
20720 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
20730 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 () interface. ^T
20740 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
20750 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 ter.** to the ca
20760 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 llback is an int
20770 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 eger [SQLITE_COP
20780 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d Y | action code]
20790 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a that specifies.
207a0 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 ** the particula
207b0 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 r action to be a
207c0 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 uthorized. ^The
207d0 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 third through si
207e0 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a xth parameters.*
207f0 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 * to the callbac
20800 6b 20 61 72 65 20 65 69 74 68 65 72 20 4e 55 4c k are either NUL
20810 4c 20 70 6f 69 6e 74 65 72 73 20 6f 72 20 7a 65 L pointers or ze
20820 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 ro-terminated st
20830 72 69 6e 67 73 0a 2a 2a 20 74 68 61 74 20 63 6f rings.** that co
20840 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c ntain additional
20850 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 details about t
20860 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 he action to be
20870 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 20 41 authorized..** A
20880 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 pplications must
20890 20 61 6c 77 61 79 73 20 62 65 20 70 72 65 70 61 always be prepa
208a0 72 65 64 20 74 6f 20 65 6e 63 6f 75 6e 74 65 72 red to encounter
208b0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
208c0 69 6e 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 in any.** of the
208d0 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 74 third through t
208e0 68 65 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 he sixth paramet
208f0 65 72 73 20 6f 66 20 74 68 65 20 61 75 74 68 6f ers of the autho
20900 72 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 rization callbac
20910 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 k..**.** ^If the
20920 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 action code is
20930 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a [SQLITE_READ].**
20940 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 and the callbac
20950 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 k returns [SQLIT
20960 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 E_IGNORE] then t
20970 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 he.** [prepared
20980 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 statement] state
20990 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 ment is construc
209a0 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 ted to substitut
209b0 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 e.** a NULL valu
209c0 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 e in place of th
209d0 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 e table column t
209e0 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a hat would have.*
209f0 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b * been read if [
20a00 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 SQLITE_OK] had b
20a10 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 een returned. T
20a20 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 he [SQLITE_IGNOR
20a30 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e E].** return can
20a40 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 be used to deny
20a50 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 an untrusted us
20a60 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 er access to ind
20a70 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d ividual.** colum
20a80 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a ns of a table..*
20a90 2a 20 5e 57 68 65 6e 20 61 20 74 61 62 6c 65 20 * ^When a table
20aa0 69 73 20 72 65 66 65 72 65 6e 63 65 64 20 62 79 is referenced by
20ab0 20 61 20 5b 53 45 4c 45 43 54 5d 20 62 75 74 20 a [SELECT] but
20ac0 6e 6f 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 no column values
20ad0 20 61 72 65 0a 2a 2a 20 65 78 74 72 61 63 74 65 are.** extracte
20ae0 64 20 66 72 6f 6d 20 74 68 61 74 20 74 61 62 6c d from that tabl
20af0 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 69 e (for example i
20b00 6e 20 61 20 71 75 65 72 79 20 6c 69 6b 65 0a 2a n a query like.*
20b10 2a 20 22 53 45 4c 45 43 54 20 63 6f 75 6e 74 28 * "SELECT count(
20b20 2a 29 20 46 52 4f 4d 20 74 61 62 22 29 20 74 68 *) FROM tab") th
20b30 65 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 52 en the [SQLITE_R
20b40 45 41 44 5d 20 61 75 74 68 6f 72 69 7a 65 72 20 EAD] authorizer
20b50 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 69 callback.** is i
20b60 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 nvoked once for
20b70 74 68 61 74 20 74 61 62 6c 65 20 77 69 74 68 20 that table with
20b80 61 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 20 74 68 a column name th
20b90 61 74 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 at is an empty s
20ba0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 tring..** ^If th
20bb0 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 e action code is
20bc0 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d [SQLITE_DELETE]
20bd0 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 and the callbac
20be0 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 k returns.** [SQ
20bf0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 LITE_IGNORE] the
20c00 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f n the [DELETE] o
20c10 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 peration proceed
20c20 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 s but the.** [tr
20c30 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 uncate optimizat
20c40 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 ion] is disabled
20c50 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 and all rows ar
20c60 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 e deleted indivi
20c70 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e dually..**.** An
20c80 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 authorizer is u
20c90 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 sed when [sqlite
20ca0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 3_prepare | prep
20cb0 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 aring].** SQL st
20cc0 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e atements from an
20cd0 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 untrusted sourc
20ce0 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 e, to ensure tha
20cf0 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d t the SQL statem
20d00 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 ents.** do not t
20d10 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 ry to access dat
20d20 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 a they are not a
20d30 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f llowed to see, o
20d40 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e r that they do n
20d50 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 ot.** try to exe
20d60 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 cute malicious s
20d70 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 tatements that d
20d80 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 amage the databa
20d90 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d se. For.** exam
20da0 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 ple, an applicat
20db0 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 ion may allow a
20dc0 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 user to enter ar
20dd0 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 bitrary.** SQL q
20de0 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 ueries for evalu
20df0 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 ation by a datab
20e00 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 ase. But the ap
20e10 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a plication does.*
20e20 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 * not want the u
20e30 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 ser to be able t
20e40 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 o make arbitrary
20e50 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a changes to the.
20e60 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e ** database. An
20e70 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c authorizer coul
20e80 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e d then be put in
20e90 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 place while the
20ea0 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 .** user-entered
20eb0 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 SQL is being [s
20ec0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c qlite3_prepare |
20ed0 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a prepared] that.
20ee0 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 ** disallows eve
20ef0 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b rything except [
20f00 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
20f10 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 ts..**.** Applic
20f20 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 ations that need
20f30 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 to process SQL
20f40 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 from untrusted s
20f50 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 ources.** might
20f60 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f also consider lo
20f70 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 wering resource
20f80 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 limits using [sq
20f90 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a lite3_limit()].*
20fa0 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 * and limiting d
20fb0 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 atabase size usi
20fc0 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 ng the [max_page
20fd0 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d _count] [PRAGMA]
20fe0 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 .** in addition
20ff0 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 to using an auth
21000 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 orizer..**.** ^(
21010 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 Only a single au
21020 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 thorizer can be
21030 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 in place on a da
21040 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
21050 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 n.** at a time.
21060 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 Each call to sq
21070 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
21080 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 izer overrides t
21090 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 he.** previous c
210a0 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 all.)^ ^Disable
210b0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
210c0 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 by installing a
210d0 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a NULL callback..*
210e0 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 * The authorizer
210f0 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 is disabled by
21100 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 default..**.** T
21110 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
21120 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 llback must not
21130 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 do anything that
21140 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 will modify.**
21150 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
21160 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 nection that inv
21170 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 oked the authori
21180 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a zer callback..**
21190 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 Note that [sqli
211a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
211b0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 ] and [sqlite3_s
211c0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 tep()] both modi
211d0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 fy their.** data
211e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
211f0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 for the meaning
21200 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 of "modify" in
21210 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a this paragraph..
21220 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c **.** ^When [sql
21230 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
21240 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 )] is used to pr
21250 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e epare a statemen
21260 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d t, the.** statem
21270 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d ent might be re-
21280 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 prepared during
21290 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
212a0 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 due to a .** sc
212b0 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 hema change. He
212c0 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 nce, the applica
212d0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 tion should ensu
212e0 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 re that the.** c
212f0 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 orrect authorize
21300 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 r callback remai
21310 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 ns in place duri
21320 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f ng the [sqlite3_
21330 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e step()]..**.** ^
21340 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 Note that the au
21350 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
21360 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c k is invoked onl
21370 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c y during.** [sql
21380 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
21390 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e or its variants.
213a0 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 Authorization
213b0 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 is not.** perfor
213c0 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 med during state
213d0 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 ment evaluation
213e0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 in [sqlite3_step
213f0 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 ()], unless.** a
21400 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 s stated in the
21410 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 previous paragra
21420 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 ph, sqlite3_step
21430 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 () invokes.** sq
21440 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
21450 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 () to reprepare
21460 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 a statement afte
21470 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 r a schema chang
21480 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 e..*/.int sqlite
21490 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
214a0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 (. sqlite3*,.
214b0 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 int (*xAuth)(voi
214c0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 d*,int,const cha
214d0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 r*,const char*,c
214e0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 onst char*,const
214f0 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 char*),. void
21500 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f *pUserData.);../
21510 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 *.** CAPI3REF: A
21520 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e uthorizer Return
21530 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 Codes.**.** The
21540 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
21550 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f thorizer | autho
21560 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 rizer callback f
21570 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a unction] must.**
21580 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b return either [
21590 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e SQLITE_OK] or on
215a0 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 e of these two c
215b0 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 onstants in orde
215c0 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 r.** to signal S
215d0 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 QLite whether or
215e0 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 not the action
215f0 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 is permitted. S
21600 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ee the.** [sqlit
21610 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
21620 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 r | authorizer d
21630 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f ocumentation] fo
21640 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 r additional.**
21650 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a information..**.
21660 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c ** Note that SQL
21670 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c ITE_IGNORE is al
21680 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f so used as a [co
21690 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f nflict resolutio
216a0 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 n mode].** retur
216b0 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 ned from the [sq
216c0 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f lite3_vtab_on_co
216d0 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 nflict()] interf
216e0 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ace..*/.#define
216f0 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 SQLITE_DENY 1
21700 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 /* Abort the S
21710 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 QL statement wit
21720 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 h an error */.#d
21730 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e efine SQLITE_IGN
21740 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 ORE 2 /* Don't
21750 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 allow access, b
21760 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 ut don't generat
21770 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f e an error */../
21780 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 *.** CAPI3REF: A
21790 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e uthorizer Action
217a0 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 Codes.**.** The
217b0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
217c0 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 thorizer()] inte
217d0 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 rface registers
217e0 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 a callback funct
217f0 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 ion.** that is i
21800 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 nvoked to author
21810 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 ize certain SQL
21820 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e statement action
21830 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e s. The.** secon
21840 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 d parameter to t
21850 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 he callback is a
21860 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 n integer code t
21870 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a hat specifies.**
21880 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 what action is
21890 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 being authorized
218a0 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 . These are the
218b0 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 integer action
218c0 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 codes that.** th
218d0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
218e0 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 lback may be pas
218f0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 sed..**.** These
21900 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c action code val
21910 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 ues signify what
21920 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 kind of operati
21930 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 on is to be.** a
21940 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 uthorized. The
21950 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 3rd and 4th para
21960 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 meters to the au
21970 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 thorization.** c
21980 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
21990 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 will be paramet
219a0 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 ers or NULL depe
219b0 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f nding on which o
219c0 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 f these.** codes
219d0 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 is used as the
219e0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
219f0 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 . ^(The 5th par
21a00 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a ameter to the.**
21a10 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
21a20 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 back is the name
21a30 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
21a40 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 ("main", "temp"
21a50 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 ,.** etc.) if ap
21a60 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 plicable.)^ ^Th
21a70 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 6th parameter
21a80 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 to the authorize
21a90 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 r callback.** is
21aa0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
21ab0 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 inner-most trig
21ac0 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 ger or view that
21ad0 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 is responsible
21ae0 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 for.** the acces
21af0 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c s attempt or NUL
21b00 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 L if this access
21b10 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 attempt is dire
21b20 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 ctly from.** top
21b30 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e -level SQL code.
21b40 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a .*/./***********
21b50 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
21b60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
21b70 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 3rd ***********
21b80 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a * 4th **********
21b90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
21ba0 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 E_CREATE_INDEX
21bb0 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 1 /* I
21bc0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 ndex Name T
21bd0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
21be0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
21bf0 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 _CREATE_TABLE
21c00 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 2 /* Ta
21c10 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
21c20 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
21c30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
21c40 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 CREATE_TEMP_INDE
21c50 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 X 3 /* Ind
21c60 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 ex Name Tab
21c70 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
21c80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
21c90 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 REATE_TEMP_TABLE
21ca0 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 4 /* Tabl
21cb0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
21cc0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
21cd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
21ce0 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 EATE_TEMP_TRIGGE
21cf0 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 R 5 /* Trigg
21d00 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 er Name Table
21d10 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
21d20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
21d30 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 ATE_TEMP_VIEW
21d40 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 6 /* View N
21d50 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 ame NULL
21d60 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
21d70 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
21d80 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 TE_TRIGGER
21d90 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 7 /* Trigger
21da0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e Name Table N
21db0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
21dc0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
21dd0 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 E_VIEW
21de0 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 8 /* View Nam
21df0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 e NULL
21e00 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
21e10 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 ne SQLITE_DELETE
21e20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
21e30 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 9 /* Table Nam
21e40 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
21e50 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
21e60 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e e SQLITE_DROP_IN
21e70 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 DEX 10
21e80 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 /* Index Name
21e90 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 Table Name
21ea0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
21eb0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 SQLITE_DROP_TAB
21ec0 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 LE 11
21ed0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
21ee0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
21ef0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
21f00 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 SQLITE_DROP_TEMP
21f10 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 _INDEX 12
21f20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 /* Index Name
21f30 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
21f40 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
21f50 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f QLITE_DROP_TEMP_
21f60 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 TABLE 13
21f70 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
21f80 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
21f90 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
21fa0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 LITE_DROP_TEMP_T
21fb0 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f RIGGER 14 /
21fc0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 * Trigger Name
21fd0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
21fe0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
21ff0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 ITE_DROP_TEMP_VI
22000 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a EW 15 /*
22010 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 View Name
22020 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
22030 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
22040 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 TE_DROP_TRIGGER
22050 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 16 /*
22060 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 Trigger Name
22070 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
22080 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
22090 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 E_DROP_VIEW
220a0 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 17 /* V
220b0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e iew Name N
220c0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
220d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
220e0 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 _INSERT
220f0 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 18 /* Ta
22100 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
22110 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
22120 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
22130 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 PRAGMA
22140 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 19 /* Pra
22150 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 gma Name 1st
22160 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a arg or NULL */.
22170 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
22180 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 EAD
22190 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 20 /* Tabl
221a0 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 e Name Colu
221b0 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 mn Name */.#
221c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 define SQLITE_SE
221d0 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 LECT
221e0 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 21 /* NULL
221f0 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 NULL
22200 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
22210 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 efine SQLITE_TRA
22220 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 NSACTION
22230 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 22 /* Operat
22240 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 ion NULL
22250 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
22260 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 fine SQLITE_UPDA
22270 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TE
22280 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 23 /* Table N
22290 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 ame Column
222a0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 Name */.#def
222b0 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 ine SQLITE_ATTAC
222c0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 H
222d0 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 24 /* Filename
222e0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 NULL
222f0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
22300 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 ne SQLITE_DETACH
22310 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 2
22320 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 5 /* Database
22330 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 Name NULL
22340 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
22350 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 e SQLITE_ALTER_T
22360 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 ABLE 26
22370 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e /* Database N
22380 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 ame Table Name
22390 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
223a0 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 SQLITE_REINDEX
223b0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 27
223c0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 /* Index Name
223d0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
223e0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
223f0 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 SQLITE_ANALYZE
22400 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 28
22410 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
22420 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
22430 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
22440 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 QLITE_CREATE_VTA
22450 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 BLE 29
22460 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
22470 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 Module Name
22480 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
22490 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 LITE_DROP_VTABLE
224a0 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 30 /
224b0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
224c0 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 Module Name
224d0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
224e0 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 ITE_FUNCTION
224f0 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 31 /*
22500 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
22510 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 Function Name
22520 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
22530 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 TE_SAVEPOINT
22540 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 32 /*
22550 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 Operation
22560 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 Savepoint Name
22570 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
22580 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 E_COPY
22590 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 0 /* N
225a0 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f o longer used */
225b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
225c0 52 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20 RECURSIVE
225d0 20 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 33 /* NUL
225e0 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c L NUL
225f0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
22600 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
22610 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f Tracing And Pro
22620 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 filing Functions
22630 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
22640 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 te3.**.** These
22650 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 70 routines are dep
22660 72 65 63 61 74 65 64 2e 20 55 73 65 20 74 68 65 recated. Use the
22670 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f [sqlite3_trace_
22680 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a v2()] interface.
22690 2a 2a 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 ** instead of th
226a0 65 20 72 6f 75 74 69 6e 65 73 20 64 65 73 63 72 e routines descr
226b0 69 62 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a ibed here..**.**
226c0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
226d0 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 register callbac
226e0 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 k functions that
226f0 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 can be used for
22700 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 .** tracing and
22710 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 profiling the ex
22720 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 ecution of SQL s
22730 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a tatements..**.**
22740 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 ^The callback f
22750 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 unction register
22760 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 ed by sqlite3_tr
22770 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 ace() is invoked
22780 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 at.** various t
22790 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c imes when an SQL
227a0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 statement is be
227b0 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 ing run by [sqli
227c0 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 te3_step()]..**
227d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 ^The sqlite3_tra
227e0 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 ce() callback is
227f0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 invoked with a
22800 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 UTF-8 rendering
22810 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 of the.** SQL st
22820 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 atement text as
22830 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 the statement fi
22840 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 rst begins execu
22850 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 ting..** ^(Addit
22860 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 ional sqlite3_tr
22870 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 ace() callbacks
22880 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 might occur.** a
22890 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 s each triggered
228a0 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 subprogram is e
228b0 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c ntered. The cal
228c0 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 lbacks for trigg
228d0 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 ers.** contain a
228e0 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 UTF-8 SQL comme
228f0 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 nt that identifi
22900 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 es the trigger.)
22910 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c ^.**.** The [SQL
22920 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c ITE_TRACE_SIZE_L
22930 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 IMIT] compile-ti
22940 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 me option can be
22950 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a used to limit.*
22960 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 * the length of
22970 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 [bound parameter
22980 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 ] expansion in t
22990 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c he output of sql
229a0 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a ite3_trace()..**
229b0 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 .** ^The callbac
229c0 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 k function regis
229d0 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 tered by sqlite3
229e0 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e _profile() is in
229f0 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 voked.** as each
22a00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 SQL statement f
22a10 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 inishes. ^The p
22a20 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 rofile callback
22a30 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 contains.** the
22a40 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 original stateme
22a50 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 nt text and an e
22a60 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d stimate of wall-
22a70 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 clock time.** of
22a80 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 how long that s
22a90 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f tatement took to
22aa0 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 run. ^The prof
22ab0 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 ile callback.**
22ac0 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 time is in units
22ad0 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c of nanoseconds,
22ae0 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 however the cur
22af0 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 rent implementat
22b00 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 ion.** is only c
22b10 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 apable of millis
22b20 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e econd resolution
22b30 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 so the six leas
22b40 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a t significant.**
22b50 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 digits in the t
22b60 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c ime are meaningl
22b70 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 ess. Future ver
22b80 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a sions of SQLite.
22b90 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 ** might provide
22ba0 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 greater resolut
22bb0 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 ion on the profi
22bc0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 ler callback. T
22bd0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 he.** sqlite3_pr
22be0 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e ofile() function
22bf0 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 is considered e
22c00 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 xperimental and
22c10 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f is.** subject to
22c20 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 change in futur
22c30 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
22c40 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f Lite..*/.SQLITE_
22c50 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 DEPRECATED void
22c60 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 *sqlite3_trace(s
22c70 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 qlite3*,. void
22c80 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c (*xTrace)(void*,
22c90 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f const char*), vo
22ca0 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 id*);.SQLITE_DEP
22cb0 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71 RECATED void *sq
22cc0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 lite3_profile(sq
22cd0 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 lite3*,. void(
22ce0 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a *xProfile)(void*
22cf0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c ,const char*,sql
22d00 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f ite3_uint64), vo
22d10 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 id*);../*.** CAP
22d20 49 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 I3REF: SQL Trace
22d30 20 45 76 65 6e 74 20 43 6f 64 65 73 0a 2a 2a 20 Event Codes.**
22d40 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 KEYWORDS: SQLITE
22d50 5f 54 52 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65 _TRACE.**.** The
22d60 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 69 64 65 se constants ide
22d70 6e 74 69 66 79 20 63 6c 61 73 73 65 73 20 6f 66 ntify classes of
22d80 20 65 76 65 6e 74 73 20 74 68 61 74 20 63 61 6e events that can
22d90 20 62 65 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a be monitored.**
22da0 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 using the [sqli
22db0 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 te3_trace_v2()]
22dc0 74 72 61 63 69 6e 67 20 6c 6f 67 69 63 2e 20 20 tracing logic.
22dd0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 The third argume
22de0 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 nt.** to [sqlite
22df0 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 69 73 3_trace_v2()] is
22e00 20 61 6e 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e an OR-ed combin
22e10 61 74 69 6f 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 ation of one or
22e20 6d 6f 72 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 more of.** the f
22e30 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e ollowing constan
22e40 74 73 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 ts. ^The first
22e50 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
22e60 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a trace callback.*
22e70 2a 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 * is one of the
22e80 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 following consta
22e90 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 nts..**.** New t
22ea0 72 61 63 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 racing constants
22eb0 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e may be added in
22ec0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
22ed0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 ..**.** ^A trace
22ee0 20 63 61 6c 6c 62 61 63 6b 20 68 61 73 20 66 6f callback has fo
22ef0 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 78 43 ur arguments: xC
22f00 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 allback(T,C,P,X)
22f10 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75 ..** ^The T argu
22f20 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 ment is one of t
22f30 68 65 20 69 6e 74 65 67 65 72 20 74 79 70 65 20 he integer type
22f40 63 6f 64 65 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 codes above..**
22f50 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 ^The C argument
22f60 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 is a copy of the
22f70 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 context pointer
22f80 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 passed in as th
22f90 65 0a 2a 2a 20 66 6f 75 72 74 68 20 61 72 67 75 e.** fourth argu
22fa0 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 ment to [sqlite3
22fb0 5f 74 72 61 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a _trace_v2()]..**
22fc0 20 54 68 65 20 50 20 61 6e 64 20 58 20 61 72 67 The P and X arg
22fd0 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 uments are point
22fe0 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e ers whose meanin
22ff0 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a gs depend on T..
23000 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b **.** <dl>.** [[
23010 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d SQLITE_TRACE_STM
23020 54 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 T]] <dt>SQLITE_T
23030 52 41 43 45 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a RACE_STMT</dt>.*
23040 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 * <dd>^An SQLITE
23050 5f 54 52 41 43 45 5f 53 54 4d 54 20 63 61 6c 6c _TRACE_STMT call
23060 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
23070 77 68 65 6e 20 61 20 70 72 65 70 61 72 65 64 20 when a prepared
23080 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 statement.** fir
23090 73 74 20 62 65 67 69 6e 73 20 72 75 6e 6e 69 6e st begins runnin
230a0 67 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 61 g and possibly a
230b0 74 20 6f 74 68 65 72 20 74 69 6d 65 73 20 64 75 t other times du
230c0 72 69 6e 67 20 74 68 65 0a 2a 2a 20 65 78 65 63 ring the.** exec
230d0 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 70 72 65 ution of the pre
230e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c pared statement,
230f0 20 73 75 63 68 20 61 73 20 61 74 20 74 68 65 20 such as at the
23100 73 74 61 72 74 20 6f 66 20 65 61 63 68 0a 2a 2a start of each.**
23110 20 74 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 trigger subprog
23120 72 61 6d 2e 20 5e 54 68 65 20 50 20 61 72 67 75 ram. ^The P argu
23130 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 ment is a pointe
23140 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 70 72 65 r to the.** [pre
23150 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
23160 2e 20 5e 54 68 65 20 58 20 61 72 67 75 6d 65 6e . ^The X argumen
23170 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 t is a pointer t
23180 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 o a string which
23190 0a 2a 2a 20 69 73 20 74 68 65 20 75 6e 65 78 70 .** is the unexp
231a0 61 6e 64 65 64 20 53 51 4c 20 74 65 78 74 20 6f anded SQL text o
231b0 66 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 f the prepared s
231c0 74 61 74 65 6d 65 6e 74 20 6f 72 20 61 6e 20 53 tatement or an S
231d0 51 4c 20 63 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 QL comment .** t
231e0 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 hat indicates th
231f0 65 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 e invocation of
23200 61 20 74 72 69 67 67 65 72 2e 20 20 5e 54 68 65 a trigger. ^The
23210 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e 20 63 6f callback can co
23220 6d 70 75 74 65 0a 2a 2a 20 74 68 65 20 73 61 6d mpute.** the sam
23230 65 20 74 65 78 74 20 74 68 61 74 20 77 6f 75 6c e text that woul
23240 64 20 68 61 76 65 20 62 65 65 6e 20 72 65 74 75 d have been retu
23250 72 6e 65 64 20 62 79 20 74 68 65 20 6c 65 67 61 rned by the lega
23260 63 79 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 cy [sqlite3_trac
23270 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 e()].** interfac
23280 65 20 62 79 20 75 73 69 6e 67 20 74 68 65 20 58 e by using the X
23290 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 58 argument when X
232a0 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 2d 2d begins with "--
232b0 22 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a " and invoking.*
232c0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 70 61 6e * [sqlite3_expan
232d0 64 65 64 5f 73 71 6c 28 50 29 5d 20 6f 74 68 65 ded_sql(P)] othe
232e0 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 rwise..**.** [[S
232f0 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 QLITE_TRACE_PROF
23300 49 4c 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 ILE]] <dt>SQLITE
23310 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 3c 2f _TRACE_PROFILE</
23320 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 dt>.** <dd>^An S
23330 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 QLITE_TRACE_PROF
23340 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 70 72 6f ILE callback pro
23350 76 69 64 65 73 20 61 70 70 72 6f 78 69 6d 61 74 vides approximat
23360 65 6c 79 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 ely the same.**
23370 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 information as i
23380 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 s provided by th
23390 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 e [sqlite3_profi
233a0 6c 65 28 29 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a le()] callback..
233b0 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 ** ^The P argume
233c0 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 nt is a pointer
233d0 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 to the [prepared
233e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 statement] and
233f0 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e the.** X argumen
23400 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 36 34 t points to a 64
23410 2d 62 69 74 20 69 6e 74 65 67 65 72 20 77 68 69 -bit integer whi
23420 63 68 20 69 73 20 74 68 65 20 65 73 74 69 6d 61 ch is the estima
23430 74 65 64 20 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 ted of.** the nu
23440 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f mber of nanoseco
23450 6e 64 20 74 68 61 74 20 74 68 65 20 70 72 65 70 nd that the prep
23460 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74 ared statement t
23470 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e ook to run..** ^
23480 54 68 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 The SQLITE_TRACE
23490 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 _PROFILE callbac
234a0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 k is invoked whe
234b0 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 n the statement
234c0 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 finishes..**.**
234d0 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 [[SQLITE_TRACE_R
234e0 4f 57 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f OW]] <dt>SQLITE_
234f0 54 52 41 43 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a TRACE_ROW</dt>.*
23500 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 * <dd>^An SQLITE
23510 5f 54 52 41 43 45 5f 52 4f 57 20 63 61 6c 6c 62 _TRACE_ROW callb
23520 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 ack is invoked w
23530 68 65 6e 65 76 65 72 20 61 20 70 72 65 70 61 72 henever a prepar
23540 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 ed.** statement
23550 67 65 6e 65 72 61 74 65 73 20 61 20 73 69 6e 67 generates a sing
23560 6c 65 20 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 le row of result
23570 2e 20 20 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 . .** ^The P ar
23580 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e gument is a poin
23590 74 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70 ter to the [prep
235a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
235b0 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 and the.** X arg
235c0 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e ument is unused.
235d0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
235e0 54 52 41 43 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 TRACE_CLOSE]] <d
235f0 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 t>SQLITE_TRACE_C
23600 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 LOSE</dt>.** <dd
23610 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 >^An SQLITE_TRAC
23620 45 5f 43 4c 4f 53 45 20 63 61 6c 6c 62 61 63 6b E_CLOSE callback
23630 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e is invoked when
23640 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 a database.** c
23650 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 onnection closes
23660 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 ..** ^The P argu
23670 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 ment is a pointe
23680 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 r to the [databa
23690 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f se connection] o
236a0 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 74 68 65 bject.** and the
236b0 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75 X argument is u
236c0 6e 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a nused..** </dl>.
236d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
236e0 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 20 20 20 E_TRACE_STMT
236f0 20 20 20 30 78 30 31 0a 23 64 65 66 69 6e 65 20 0x01.#define
23700 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f SQLITE_TRACE_PRO
23710 46 49 4c 45 20 20 20 20 30 78 30 32 0a 23 64 65 FILE 0x02.#de
23720 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 fine SQLITE_TRAC
23730 45 5f 52 4f 57 20 20 20 20 20 20 20 20 30 78 30 E_ROW 0x0
23740 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
23750 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20 20 20 20 _TRACE_CLOSE
23760 20 20 30 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 0x08../*.** CA
23770 50 49 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63 PI3REF: SQL Trac
23780 65 20 48 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 e Hook.** METHOD
23790 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
237a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 ^The sqlite3_tra
237b0 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 20 69 ce_v2(D,M,X,P) i
237c0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 nterface registe
237d0 72 73 20 61 20 74 72 61 63 65 20 63 61 6c 6c 62 rs a trace callb
237e0 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ack.** function
237f0 58 20 61 67 61 69 6e 73 74 20 5b 64 61 74 61 62 X against [datab
23800 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
23810 44 2c 20 75 73 69 6e 67 20 70 72 6f 70 65 72 74 D, using propert
23820 79 20 6d 61 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 y mask M.** and
23830 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 context pointer
23840 50 2e 20 20 5e 49 66 20 74 68 65 20 58 20 63 61 P. ^If the X ca
23850 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c llback is.** NUL
23860 4c 20 6f 72 20 69 66 20 74 68 65 20 4d 20 6d 61 L or if the M ma
23870 73 6b 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e sk is zero, then
23880 20 74 72 61 63 69 6e 67 20 69 73 20 64 69 73 61 tracing is disa
23890 62 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 bled. The.** M
238a0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 argument should
238b0 62 65 20 74 68 65 20 62 69 74 77 69 73 65 20 4f be the bitwise O
238c0 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e R-ed combination
238d0 20 6f 66 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d of.** zero or m
238e0 6f 72 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 ore [SQLITE_TRAC
238f0 45 5d 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a E] constants..**
23900 0a 2a 2a 20 5e 45 61 63 68 20 63 61 6c 6c 20 74 .** ^Each call t
23910 6f 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 o either sqlite3
23920 5f 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 _trace() or sqli
23930 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20 6f te3_trace_v2() o
23940 76 65 72 72 69 64 65 73 20 0a 2a 2a 20 28 63 61 verrides .** (ca
23950 6e 63 65 6c 73 29 20 61 6e 79 20 70 72 69 6f 72 ncels) any prior
23960 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 calls to sqlite
23970 33 5f 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c 3_trace() or sql
23980 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 2e ite3_trace_v2().
23990 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 58 20 63 61 .**.** ^The X ca
239a0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
239b0 64 20 77 68 65 6e 65 76 65 72 20 61 6e 79 20 6f d whenever any o
239c0 66 20 74 68 65 20 65 76 65 6e 74 73 20 69 64 65 f the events ide
239d0 6e 74 69 66 69 65 64 20 62 79 20 0a 2a 2a 20 6d ntified by .** m
239e0 61 73 6b 20 4d 20 6f 63 63 75 72 2e 20 20 5e 54 ask M occur. ^T
239f0 68 65 20 69 6e 74 65 67 65 72 20 72 65 74 75 72 he integer retur
23a00 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 n value from the
23a10 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 75 72 callback is cur
23a20 72 65 6e 74 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 rently.** ignore
23a30 64 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 6d d, though this m
23a40 61 79 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 ay change in fut
23a50 75 72 65 20 72 65 6c 65 61 73 65 73 2e 20 20 43 ure releases. C
23a60 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 allback.** imple
23a70 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c mentations shoul
23a80 64 20 72 65 74 75 72 6e 20 7a 65 72 6f 20 74 6f d return zero to
23a90 20 65 6e 73 75 72 65 20 66 75 74 75 72 65 20 63 ensure future c
23aa0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a ompatibility..**
23ab0 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c .** ^A trace cal
23ac0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
23ad0 20 77 69 74 68 20 66 6f 75 72 20 61 72 67 75 6d with four argum
23ae0 65 6e 74 73 3a 20 63 61 6c 6c 62 61 63 6b 28 54 ents: callback(T
23af0 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 ,C,P,X)..** ^The
23b00 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f T argument is o
23b10 6e 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 ne of the [SQLIT
23b20 45 5f 54 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 E_TRACE].** cons
23b30 74 61 6e 74 73 20 74 6f 20 69 6e 64 69 63 61 74 tants to indicat
23b40 65 20 77 68 79 20 74 68 65 20 63 61 6c 6c 62 61 e why the callba
23b50 63 6b 20 77 61 73 20 69 6e 76 6f 6b 65 64 2e 0a ck was invoked..
23b60 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65 ** ^The C argume
23b70 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 nt is a copy of
23b80 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e the context poin
23b90 74 65 72 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e ter..** The P an
23ba0 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72 d X arguments ar
23bb0 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 e pointers whose
23bc0 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 meanings depend
23bd0 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 on T..**.** The
23be0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 sqlite3_trace_v
23bf0 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 2() interface is
23c00 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 72 65 70 intended to rep
23c10 6c 61 63 65 20 74 68 65 20 6c 65 67 61 63 79 0a lace the legacy.
23c20 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 ** interfaces [s
23c30 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 qlite3_trace()]
23c40 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f and [sqlite3_pro
23c50 66 69 6c 65 28 29 5d 2c 20 62 6f 74 68 20 6f 66 file()], both of
23c60 20 77 68 69 63 68 0a 2a 2a 20 61 72 65 20 64 65 which.** are de
23c70 70 72 65 63 61 74 65 64 2e 0a 2a 2f 0a 69 6e 74 precated..*/.int
23c80 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 sqlite3_trace_v
23c90 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 2(. sqlite3*,.
23ca0 20 75 6e 73 69 67 6e 65 64 20 75 4d 61 73 6b 2c unsigned uMask,
23cb0 0a 20 20 69 6e 74 28 2a 78 43 61 6c 6c 62 61 63 . int(*xCallbac
23cc0 6b 29 28 75 6e 73 69 67 6e 65 64 2c 76 6f 69 64 k)(unsigned,void
23cd0 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a *,void*,void*),.
23ce0 20 20 76 6f 69 64 20 2a 70 43 74 78 0a 29 3b 0a void *pCtx.);.
23cf0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
23d00 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 Query Progress
23d10 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 Callbacks.** MET
23d20 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
23d30 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
23d40 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 progress_handler
23d50 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 (D,N,X,P) interf
23d60 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63 ace causes the c
23d70 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 allback.** funct
23d80 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f ion X to be invo
23d90 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 ked periodically
23da0 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e during long run
23db0 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a ning calls to.**
23dc0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 [sqlite3_exec()
23dd0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ], [sqlite3_step
23de0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
23df0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f _get_table()] fo
23e00 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f r.** database co
23e10 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 nnection D. An
23e20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 example use for
23e30 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 this.** interfac
23e40 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 e is to keep a G
23e50 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e UI updated durin
23e60 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e g a large query.
23e70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 .**.** ^The para
23e80 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65 meter P is passe
23e90 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 d through as the
23ea0 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 only parameter
23eb0 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 to the .** callb
23ec0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 ack function X.
23ed0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 ^The parameter
23ee0 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 69 N is the approxi
23ef0 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a mate number of .
23f00 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 ** [virtual mach
23f10 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 ine instructions
23f20 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 ] that are evalu
23f30 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 ated between suc
23f40 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 cessive.** invoc
23f50 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 ations of the ca
23f60 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e llback X. ^If N
23f70 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e is less than on
23f80 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 e then the progr
23f90 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 ess.** handler i
23fa0 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a s disabled..**.*
23fb0 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 * ^Only a single
23fc0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 progress handle
23fd0 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 r may be defined
23fe0 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 at one time per
23ff0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
24000 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 nnection]; setti
24010 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 ng a new progres
24020 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c s handler cancel
24030 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 s the.** old one
24040 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 . ^Setting para
24050 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 meter X to NULL
24060 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f disables the pro
24070 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a gress handler..*
24080 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 * ^The progress
24090 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 handler is also
240a0 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 disabled by sett
240b0 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 ing N to a value
240c0 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e less.** than 1.
240d0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 .**.** ^If the p
240e0 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b rogress callback
240f0 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 returns non-zer
24100 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e o, the operation
24110 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 is.** interrupt
24120 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 ed. This featur
24130 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f e can be used to
24140 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 implement a.**
24150 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 "Cancel" button
24160 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 on a GUI progres
24170 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a s dialog box..**
24180 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 .** The progress
24190 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 handler callbac
241a0 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e k must not do an
241b0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c ything that will
241c0 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 modify.** the d
241d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
241e0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 on that invoked
241f0 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e the progress han
24200 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 dler..** Note th
24210 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 at [sqlite3_prep
24220 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 are_v2()] and [s
24230 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 qlite3_step()] b
24240 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 oth modify their
24250 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
24260 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 nections for the
24270 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 meaning of "mod
24280 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 ify" in this par
24290 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f agraph..**.*/.vo
242a0 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 id sqlite3_progr
242b0 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 ess_handler(sqli
242c0 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a te3*, int, int(*
242d0 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 )(void*), void*)
242e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
242f0 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 F: Opening A New
24300 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 Database Connec
24310 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 tion.** CONSTRUC
24320 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a TOR: sqlite3.**.
24330 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
24340 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 es open an SQLit
24350 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
24360 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20 as specified by
24370 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 the .** filename
24380 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 argument. ^The
24390 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e filename argumen
243a0 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 t is interpreted
243b0 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a as UTF-8 for.**
243c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
243d0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e and sqlite3_open
243e0 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 _v2() and as UTF
243f0 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 -16 in the nativ
24400 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 e byte.** order
24410 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e for sqlite3_open
24420 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 16(). ^(A [datab
24430 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
24440 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c handle is usuall
24450 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e y.** returned in
24460 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 *ppDb, even if
24470 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e an error occurs.
24480 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 The only excep
24490 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 tion is that.**
244a0 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 if SQLite is una
244b0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 ble to allocate
244c0 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 memory to hold t
244d0 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a he [sqlite3] obj
244e0 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 ect,.** a NULL w
244f0 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 ill be written i
24500 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 nto *ppDb instea
24510 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 d of a pointer t
24520 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a o the [sqlite3].
24530 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 ** object.)^ ^(I
24540 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 f the database i
24550 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 s opened (and/or
24560 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 created) succes
24570 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 sfully, then.**
24580 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 [SQLITE_OK] is r
24590 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 eturned. Otherw
245a0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f ise an [error co
245b0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e de] is returned.
245c0 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 )^ ^The.** [sqli
245d0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 te3_errmsg()] or
245e0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
245f0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 16()] routines c
24600 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 an be used to ob
24610 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 tain.** an Engli
24620 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 sh language desc
24630 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 ription of the e
24640 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 rror following a
24650 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a failure of any.
24660 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 ** of the sqlite
24670 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 3_open() routine
24680 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 s..**.** ^The de
24690 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 fault encoding w
246a0 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72 ill be UTF-8 for
246b0 20 64 61 74 61 62 61 73 65 73 20 63 72 65 61 74 databases creat
246c0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 ed using.** sqli
246d0 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 te3_open() or sq
246e0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e lite3_open_v2().
246f0 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 ^The default e
24700 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61 ncoding for data
24710 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 bases.** created
24720 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f using sqlite3_o
24730 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20 pen16() will be
24740 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 UTF-16 in the na
24750 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e tive byte order.
24760 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f .**.** Whether o
24770 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f r not an error o
24780 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 ccurs when it is
24790 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 opened, resourc
247a0 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 es.** associated
247b0 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 with the [datab
247c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
247d0 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 handle should be
247e0 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 released by.**
247f0 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 passing it to [s
24800 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 qlite3_close()]
24810 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f when it is no lo
24820 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a nger required..*
24830 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
24840 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 _open_v2() inter
24850 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 face works like
24860 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a sqlite3_open().*
24870 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 * except that it
24880 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 accepts two add
24890 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 itional paramete
248a0 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 rs for additiona
248b0 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 l control.** ove
248c0 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 r the new databa
248d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 se connection.
248e0 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 ^(The flags para
248f0 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 meter to.** sqli
24900 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 te3_open_v2() ca
24910 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a n take one of.**
24920 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 the following t
24930 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 hree values, opt
24940 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 ionally combined
24950 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 with the .** [S
24960 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 QLITE_OPEN_NOMUT
24970 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 EX], [SQLITE_OPE
24980 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 N_FULLMUTEX], [S
24990 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 QLITE_OPEN_SHARE
249a0 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c DCACHE],.** [SQL
249b0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 ITE_OPEN_PRIVATE
249c0 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b CACHE], and/or [
249d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d SQLITE_OPEN_URI]
249e0 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 flags:)^.**.**
249f0 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 <dl>.** ^(<dt>[S
24a00 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
24a10 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 NLY]</dt>.** <dd
24a20 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 >The database is
24a30 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d opened in read-
24a40 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 only mode. If t
24a50 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 he database does
24a60 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 not.** already
24a70 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 exist, an error
24a80 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 is returned.</dd
24a90 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e >)^.**.** ^(<dt>
24aa0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 [SQLITE_OPEN_REA
24ab0 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 DWRITE]</dt>.**
24ac0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 <dd>The database
24ad0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 is opened for r
24ae0 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 eading and writi
24af0 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 ng if possible,
24b00 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e or reading.** on
24b10 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 ly if the file i
24b20 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 s write protecte
24b30 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 d by the operati
24b40 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 ng system. In e
24b50 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 ither.** case th
24b60 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 e database must
24b70 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f already exist, o
24b80 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f therwise an erro
24b90 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f r is returned.</
24ba0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 dd>)^.**.** ^(<d
24bb0 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 t>[SQLITE_OPEN_R
24bc0 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c EADWRITE] | [SQL
24bd0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d ITE_OPEN_CREATE]
24be0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
24bf0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
24c00 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 ned for reading
24c10 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 and writing, and
24c20 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a is created if.*
24c30 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c * it does not al
24c40 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 ready exist. Thi
24c50 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f s is the behavio
24c60 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 r that is always
24c70 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c used for.** sql
24c80 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 ite3_open() and
24c90 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
24ca0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c .</dd>)^.** </dl
24cb0 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 >.**.** If the 3
24cc0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
24cd0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
24ce0 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 ) is not one of
24cf0 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 the.** combinati
24d00 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 ons shown above
24d10 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 optionally combi
24d20 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a ned with other.*
24d30 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 * [SQLITE_OPEN_R
24d40 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 EADONLY | SQLITE
24d50 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a _OPEN_* bits].**
24d60 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 then the behavi
24d70 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e or is undefined.
24d80 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b .**.** ^If the [
24d90 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 SQLITE_OPEN_NOMU
24da0 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 TEX] flag is set
24db0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 , then the datab
24dc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
24dd0 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d * opens in the m
24de0 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 ulti-thread [thr
24df0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 eading mode] as
24e00 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 long as the sing
24e10 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 le-thread.** mod
24e20 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 e has not been s
24e30 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 et at compile-ti
24e40 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 me or start-time
24e50 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 . ^If the.** [S
24e60 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d QLITE_OPEN_FULLM
24e70 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 UTEX] flag is se
24e80 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 t then the datab
24e90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f ase connection o
24ea0 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 pens.** in the s
24eb0 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 erialized [threa
24ec0 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 ding mode] unles
24ed0 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 s single-thread
24ee0 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c was.** previousl
24ef0 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f y selected at co
24f00 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 mpile-time or st
24f10 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 art-time..** ^Th
24f20 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 e [SQLITE_OPEN_S
24f30 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 HAREDCACHE] flag
24f40 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 causes the data
24f50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
24f60 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c to be.** eligibl
24f70 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 e to use [shared
24f80 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 cache mode], re
24f90 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 gardless of whet
24fa0 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 her or not share
24fb0 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e d.** cache is en
24fc0 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c abled using [sql
24fd0 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 ite3_enable_shar
24fe0 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 ed_cache()]. ^T
24ff0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 he.** [SQLITE_OP
25000 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d EN_PRIVATECACHE]
25010 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 flag causes the
25020 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
25030 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 tion to not.** p
25040 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 articipate in [s
25050 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 hared cache mode
25060 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 ] even if it is
25070 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e enabled..**.** ^
25080 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d The fourth param
25090 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
250a0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 open_v2() is the
250b0 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 name of the.**
250c0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
250d0 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 ject that define
250e0 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 s the operating
250f0 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 system interface
25100 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 that.** the new
25110 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
25120 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e tion should use.
25130 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 ^If the fourth
25140 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a parameter is.**
25150 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
25160 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 then the default
25170 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f [sqlite3_vfs] o
25180 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a bject is used..*
25190 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c *.** ^If the fil
251a0 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 ename is ":memor
251b0 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 y:", then a priv
251c0 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 ate, temporary i
251d0 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 n-memory databas
251e0 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 e.** is created
251f0 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 for the connecti
25200 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 on. ^This in-me
25210 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 mory database wi
25220 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a ll vanish when.*
25230 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 * the database c
25240 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f onnection is clo
25250 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 sed. Future ver
25260 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 sions of SQLite
25270 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 might.** make us
25280 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 e of additional
25290 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 special filename
252a0 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 s that begin wit
252b0 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 h the ":" charac
252c0 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 ter..** It is re
252d0 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 commended that w
252e0 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 hen a database f
252f0 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 ilename actually
25300 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 does begin with
25310 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 .** a ":" charac
25320 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 ter you should p
25330 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 refix the filena
25340 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 me with a pathna
25350 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e me such as.** ".
25360 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 /" to avoid ambi
25370 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 guity..**.** ^If
25380 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 the filename is
25390 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
253a0 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 , then a private
253b0 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f , temporary.** o
253c0 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 n-disk database
253d0 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e will be created.
253e0 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 ^This private
253f0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 database will be
25400 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c .** automaticall
25410 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f y deleted as soo
25420 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 n as the databas
25430 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
25440 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b closed..**.** [[
25450 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e URI filenames in
25460 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d sqlite3_open()]
25470 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 ] <h3>URI Filena
25480 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e mes</h3>.**.** ^
25490 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 If [URI filename
254a0 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e ] interpretation
254b0 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 is enabled, and
254c0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 the filename ar
254d0 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 gument.** begins
254e0 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 with "file:", t
254f0 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 hen the filename
25500 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 is interpreted
25510 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a as a URI. ^URI.*
25520 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 * filename inter
25530 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 pretation is ena
25540 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c bled if the [SQL
25550 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c ITE_OPEN_URI] fl
25560 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 ag is.** set in
25570 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d the fourth argum
25580 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f ent to sqlite3_o
25590 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 pen_v2(), or if
255a0 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 it has.** been e
255b0 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 nabled globally
255c0 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 using the [SQLIT
255d0 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 E_CONFIG_URI] op
255e0 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a tion with the.**
255f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
25600 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 ()] method or by
25610 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 the [SQLITE_USE
25620 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 _URI] compile-ti
25630 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 me option..** As
25640 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 of SQLite versi
25650 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 on 3.7.7, URI fi
25660 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 lename interpret
25670 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 ation is turned
25680 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c off.** by defaul
25690 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65 t, but future re
256a0 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
256b0 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 might enable UR
256c0 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e I filename.** in
256d0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 terpretation by
256e0 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b default. See "[
256f0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 URI filenames]"
25700 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a for additional.*
25710 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a * information..*
25720 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d *.** URI filenam
25730 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63 es are parsed ac
25740 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 cording to RFC 3
25750 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 986. ^If the URI
25760 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 contains an.**
25770 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 authority, then
25780 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 it must be eithe
25790 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e r an empty strin
257a0 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 g or the string
257b0 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e .** "localhost".
257c0 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 ^If the authori
257d0 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 ty is not an emp
257e0 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f ty string or "lo
257f0 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a calhost", an .**
25800 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e error is return
25810 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 ed to the caller
25820 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 . ^The fragment
25830 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 component of a U
25840 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 RI, if .** prese
25850 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a nt, is ignored..
25860 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 **.** ^SQLite us
25870 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 es the path comp
25880 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 onent of the URI
25890 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 as the name of
258a0 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a the disk file.**
258b0 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 which contains
258c0 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 the database. ^I
258d0 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e f the path begin
258e0 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 s with a '/' cha
258f0 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e racter, .** then
25900 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 it is interpret
25910 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 ed as an absolut
25920 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 e path. ^If the
25930 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 path does not be
25940 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 gin .** with a '
25950 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 /' (meaning that
25960 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 the authority s
25970 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 ection is omitte
25980 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a d from the URI).
25990 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 ** then the path
259a0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 is interpreted
259b0 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 as a relative pa
259c0 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e th. .** ^(On win
259d0 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 dows, the first
259e0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 component of an
259f0 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a absolute path .*
25a00 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65 * is a drive spe
25a10 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e cification (e.g.
25a20 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 "C:").)^.**.**
25a30 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 [[core URI query
25a40 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a parameters]].**
25a50 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f The query compo
25a60 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 nent of a URI ma
25a70 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 y contain parame
25a80 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e ters that are in
25a90 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 terpreted.** eit
25aa0 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 her by SQLite it
25ab0 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 self, or by a [V
25ac0 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 FS | custom VFS
25ad0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e implementation].
25ae0 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69 .** SQLite and i
25af0 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 ts built-in [VFS
25b00 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68 es] interpret th
25b10 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 e.** following q
25b20 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a uery parameters:
25b30 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 .**.** <ul>.**
25b40 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e <li> <b>vfs</b>
25b50 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 : ^The "vfs" par
25b60 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 ameter may be us
25b70 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 ed to specify th
25b80 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 e name of.**
25b90 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 a VFS object th
25ba0 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 at provides the
25bb0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d operating system
25bc0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 interface that
25bd0 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 should.** be
25be0 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 used to access
25bf0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
25c00 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 e on disk. ^If t
25c10 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 his option is se
25c20 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 t to.** an e
25c30 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 mpty string the
25c40 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 default VFS obje
25c50 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 ct is used. ^Spe
25c60 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f cifying an unkno
25c70 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 wn.** VFS is
25c80 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 an error. ^If s
25c90 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
25ca0 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 is used and the
25cb0 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a vfs option is.*
25cc0 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 * present, t
25cd0 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 hen the VFS spec
25ce0 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 ified by the opt
25cf0 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 ion takes preced
25d00 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 ence over.**
25d10 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 the value passe
25d20 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 d as the fourth
25d30 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
25d40 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a ite3_open_v2()..
25d50 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e **.** <li> <b>
25d60 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 mode</b>: ^(The
25d70 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d mode parameter m
25d80 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 ay be set to eit
25d90 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a her "ro", "rw",.
25da0 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 ** "rwc", or
25db0 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d "memory". Attem
25dc0 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 pting to set it
25dd0 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c to any other val
25de0 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 ue is.** an
25df0 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 error)^. .**
25e00 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 ^If "ro" is spe
25e10 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 cified, then the
25e20 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
25e30 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c ned for read-onl
25e40 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 y .** access
25e50 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 , just as if the
25e60 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 [SQLITE_OPEN_RE
25e70 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 ADONLY] flag had
25e80 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 been set in the
25e90 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 .** third a
25ea0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
25eb0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 e3_open_v2(). ^I
25ec0 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f f the mode optio
25ed0 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 n is set to .**
25ee0 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 "rw", then t
25ef0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
25f00 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 pened for read-w
25f10 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 rite (but not cr
25f20 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 eate) .** ac
25f30 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 cess, as if SQLI
25f40 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 TE_OPEN_READWRIT
25f50 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 E (but not SQLIT
25f60 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 E_OPEN_CREATE) h
25f70 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 ad .** been
25f80 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 set. ^Value "rwc
25f90 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 " is equivalent
25fa0 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 to setting both
25fb0 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f .** SQLITE_O
25fc0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e PEN_READWRITE an
25fd0 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 d SQLITE_OPEN_CR
25fe0 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d EATE. ^If the m
25ff0 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a ode option is.**
26000 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d set to "mem
26010 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 ory" then a pure
26020 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 [in-memory data
26030 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 base] that never
26040 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 reads.** or
26050 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 writes from dis
26060 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 k is used. ^It i
26070 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 s an error to sp
26080 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f ecify a value fo
26090 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 r.** the mod
260a0 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 e parameter that
260b0 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 is less restric
260c0 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 tive than that s
260d0 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 pecified by.**
260e0 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 the flags pas
260f0 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 sed in the third
26100 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
26110 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e lite3_open_v2().
26120 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 .**.** <li> <b
26130 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 >cache</b>: ^The
26140 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 cache parameter
26150 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 may be set to e
26160 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f ither "shared" o
26170 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 r.** "privat
26180 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 e". ^Setting it
26190 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65 to "shared" is e
261a0 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 quivalent to set
261b0 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 ting the.**
261c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 SQLITE_OPEN_SHAR
261d0 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 EDCACHE bit in t
261e0 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e he flags argumen
261f0 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 t passed to.**
26200 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f sqlite3_open_
26210 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 v2(). ^Setting t
26220 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 he cache paramet
26230 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 er to "private"
26240 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 is .** equiv
26250 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 alent to setting
26260 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e the SQLITE_OPEN
26270 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69 _PRIVATECACHE bi
26280 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 t..** ^If sq
26290 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
262a0 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 is used and the
262b0 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 "cache" paramete
262c0 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a r is present in.
262d0 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c ** a URI fil
262e0 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 ename, its value
262f0 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 overrides any b
26300 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 ehavior requeste
26310 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 d by setting.**
26320 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f SQLITE_OPEN_
26330 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 PRIVATECACHE or
26340 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 SQLITE_OPEN_SHAR
26350 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a EDCACHE flag..**
26360 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f .** <li> <b>pso
26370 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 w</b>: ^The psow
26380 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63 parameter indic
26390 61 74 65 73 20 77 68 65 74 68 65 72 20 6f 72 20 ates whether or
263a0 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b not the.** [
263b0 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 powersafe overwr
263c0 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f ite] property do
263d0 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 es or does not a
263e0 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 pply to the.**
263f0 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 storage media
26400 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 on which the da
26410 74 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 tabase file resi
26420 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e des..**.** <li>
26430 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 <b>nolock</b>:
26440 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 ^The nolock para
26450 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 meter is a boole
26460 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 an query paramet
26470 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20 er.** which
26480 69 66 20 73 65 74 20 64 69 73 61 62 6c 65 73 20 if set disables
26490 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 file locking in
264a0 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c rollback journal
264b0 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a modes. This.**
264c0 20 20 20 20 20 69 73 20 75 73 65 66 75 6c 20 66 is useful f
264d0 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61 20 64 or accessing a d
264e0 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c atabase on a fil
264f0 65 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 esystem that doe
26500 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 s not.** sup
26510 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 port locking. C
26520 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 aution: Databas
26530 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 e corruption mig
26540 68 74 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f ht result if two
26550 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 .** or more
26560 70 72 6f 63 65 73 73 65 73 20 77 72 69 74 65 20 processes write
26570 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 to the same data
26580 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 base and any one
26590 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 of those.**
265a0 20 70 72 6f 63 65 73 73 65 73 20 75 73 65 73 20 processes uses
265b0 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 nolock=1..**.**
265c0 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 <li> <b>immutab
265d0 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d le</b>: ^The imm
265e0 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 utable parameter
265f0 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 is a boolean qu
26600 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d ery.** param
26610 65 74 65 72 20 74 68 61 74 20 69 6e 64 69 63 61 eter that indica
26620 74 65 73 20 74 68 61 74 20 74 68 65 20 64 61 74 tes that the dat
26630 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 73 74 abase file is st
26640 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 ored on.** r
26650 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 ead-only media.
26660 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 ^When immutable
26670 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20 is set, SQLite
26680 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 assumes that the
26690 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 .** database
266a0 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 file cannot be
266b0 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 changed, even by
266c0 20 61 20 70 72 6f 63 65 73 73 20 77 69 74 68 20 a process with
266d0 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 higher.** pr
266e0 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 ivilege, and so
266f0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 the database is
26700 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 opened read-only
26710 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 and all locking
26720 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e .** and chan
26730 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 ge detection is
26740 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69 disabled. Cauti
26750 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20 on: Setting the
26760 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 immutable.**
26770 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 property on a d
26780 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 atabase file tha
26790 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63 t does in fact c
267a0 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74 hange can result
267b0 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 .** in incor
267c0 72 65 63 74 20 71 75 65 72 79 20 72 65 73 75 6c rect query resul
267d0 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 ts and/or [SQLIT
267e0 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 E_CORRUPT] error
267f0 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c s..** See al
26800 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 so: [SQLITE_IOCA
26810 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a P_IMMUTABLE]..**
26820 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e .** </ul>
26830 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 .**.** ^Specifyi
26840 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 ng an unknown pa
26850 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 rameter in the q
26860 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f uery component o
26870 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 f a URI is not a
26880 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 n.** error. Fut
26890 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 ure versions of
268a0 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 SQLite might und
268b0 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e erstand addition
268c0 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 al query.** para
268d0 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 meters. See "[q
268e0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 uery parameters
268f0 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 with special mea
26900 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 ning to SQLite]"
26910 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e for.** addition
26920 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a al information..
26930 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 **.** [[URI file
26940 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 name examples]]
26950 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 <h3>URI filename
26960 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a examples</h3>.*
26970 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 *.** <table bord
26980 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e er="1" align=cen
26990 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d ter cellpadding=
269a0 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 5>.** <tr><th> U
269b0 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 RI filenames <th
269c0 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 > Results.** <tr
269d0 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e ><td> file:data.
269e0 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 db <td> .**
269f0 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 Open the fi
26a00 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 le "data.db" in
26a10 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 the current dire
26a20 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 ctory..** <tr><t
26a30 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 d> file:/home/fr
26a40 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a ed/data.db<br>.*
26a50 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a * file:
26a60 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 ///home/fred/dat
26a70 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 a.db <br> .**
26a80 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f file://lo
26a90 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 calhost/home/fre
26aa0 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c d/data.db <br> <
26ab0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 td> .**
26ac0 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 Open the databa
26ad0 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 se file "/home/f
26ae0 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a red/data.db"..**
26af0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f <tr><td> file:/
26b00 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 /darkstar/home/f
26b10 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e red/data.db <td>
26b20 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e .** An
26b30 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 error. "darksta
26b40 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f r" is not a reco
26b50 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 gnized authority
26b60 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 ..** <tr><td sty
26b70 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a le="white-space:
26b80 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 nowrap"> .**
26b90 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a file:///C:
26ba0 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 /Documents%20and
26bb0 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 %20Settings/fred
26bc0 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 /Desktop/data.db
26bd0 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e .** <td> Win
26be0 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 dows only: Open
26bf0 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 the file "data.d
26c00 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 b" on fred's des
26c10 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a ktop on drive.**
26c20 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f C:. No
26c30 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20 te that the %20
26c40 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 escaping in this
26c50 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 example is not
26c60 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 strictly .**
26c70 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 necessary
26c80 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65 - space characte
26c90 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c rs can be used l
26ca0 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 iterally.**
26cb0 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 in URI file
26cc0 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 names..** <tr><t
26cd0 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f d> file:data.db?
26ce0 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 mode=ro&cache=pr
26cf0 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 ivate <td> .**
26d00 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c Open fil
26d10 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 e "data.db" in t
26d20 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 he current direc
26d30 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e tory for read-on
26d40 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 ly access..**
26d50 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 Regardles
26d60 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 s of whether or
26d70 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 not shared-cache
26d80 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 mode is enabled
26d90 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 by.**
26da0 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 default, use a p
26db0 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a rivate cache..**
26dc0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f <tr><td> file:/
26dd0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 home/fred/data.d
26de0 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 b?vfs=unix-dotfi
26df0 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 le <td>.**
26e00 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f Open file "/
26e10 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 home/fred/data.d
26e20 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 b". Use the spec
26e30 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f ial VFS "unix-do
26e40 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 tfile".**
26e50 20 20 20 74 68 61 74 20 75 73 65 73 20 64 6f 74 that uses dot
26e60 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 -files in place
26e70 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72 of posix advisor
26e80 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 y locking..** <t
26e90 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 r><td> file:data
26ea0 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c .db?mode=readonl
26eb0 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 y <td> .**
26ec0 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 An error. "r
26ed0 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 eadonly" is not
26ee0 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 a valid option f
26ef0 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 or the "mode" pa
26f00 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 rameter..** </ta
26f10 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 ble>.**.** ^URI
26f20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 hexadecimal esca
26f30 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 pe sequences (%H
26f40 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 H) are supported
26f50 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 within the path
26f60 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f and.** query co
26f70 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 mponents of a UR
26f80 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c I. A hexadecimal
26f90 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 escape sequence
26fa0 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a consists of a.*
26fb0 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d * percent sign -
26fc0 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 "%" - followed
26fd0 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 by exactly two h
26fe0 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 exadecimal digit
26ff0 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 s .** specifying
27000 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e an octet value.
27010 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 ^Before the pat
27020 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f h or query compo
27030 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 nents of a.** UR
27040 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 I filename are i
27050 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 nterpreted, they
27060 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 are encoded usi
27070 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c ng UTF-8 and all
27080 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c .** hexadecimal
27090 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 escape sequence
270a0 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 s replaced by a
270b0 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 single byte cont
270c0 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f aining the.** co
270d0 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 rresponding octe
270e0 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 t. If this proce
270f0 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 ss generates an
27100 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e invalid UTF-8 en
27110 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 coding,.** the r
27120 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 esults are undef
27130 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e ined..**.** <b>N
27140 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 ote to Windows u
27150 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 sers:</b> The e
27160 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 ncoding used for
27170 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 the filename ar
27180 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c gument.** of sql
27190 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 ite3_open() and
271a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
271b0 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c ) must be UTF-8,
271c0 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a not whatever.**
271d0 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 codepage is cur
271e0 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 rently defined.
271f0 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 Filenames conta
27200 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f ining internatio
27210 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 nal.** character
27220 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 s must be conver
27230 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 ted to UTF-8 pri
27240 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 or to passing th
27250 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 em into.** sqlit
27260 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c e3_open() or sql
27270 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a ite3_open_v2()..
27280 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f **.** <b>Note to
27290 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 Windows Runtime
272a0 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 users:</b> The
272b0 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 temporary direc
272c0 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 tory must be set
272d0 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c .** prior to cal
272e0 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 ling sqlite3_ope
272f0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f n() or sqlite3_o
27300 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 pen_v2(). Other
27310 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a wise, various.**
27320 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72 features that r
27330 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f equire the use o
27340 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 f temporary file
27350 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a s may fail..**.*
27360 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
27370 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 ite3_temp_direct
27380 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ory].*/.int sqli
27390 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 te3_open(. cons
273a0 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 t char *filename
273b0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 , /* Database
273c0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 filename (UTF-8)
273d0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a */. sqlite3 **
273e0 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a ppDb /*
273f0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 OUT: SQLite db
27400 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 handle */.);.int
27410 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 sqlite3_open16(
27420 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 . const void *f
27430 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 ilename, /* Da
27440 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 tabase filename
27450 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 (UTF-16) */. sq
27460 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 lite3 **ppDb
27470 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 /* OUT: SQ
27480 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a Lite db handle *
27490 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 /.);.int sqlite3
274a0 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 _open_v2(. cons
274b0 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 t char *filename
274c0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 , /* Database
274d0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 filename (UTF-8)
274e0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a */. sqlite3 **
274f0 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a ppDb, /*
27500 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 OUT: SQLite db
27510 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 handle */. int
27520 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 flags,
27530 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a /* Flags */.
27540 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 const char *zV
27550 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d fs /* Nam
27560 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 e of VFS module
27570 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a to use */.);../*
27580 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 .** CAPI3REF: Ob
27590 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 tain Values For
275a0 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a URI Parameters.*
275b0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 *.** These are u
275c0 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c tility routines,
275d0 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 useful to VFS i
275e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 mplementations,
275f0 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f that check.** to
27600 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61 see if a databa
27610 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 se file was a UR
27620 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 I that contained
27630 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72 a specific quer
27640 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c y .** parameter,
27650 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 and if so obtai
27660 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 ns the value of
27670 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d that query param
27680 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 eter..**.** If F
27690 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 is the database
276a0 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 filename pointe
276b0 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 r passed into th
276c0 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 e xOpen() method
276d0 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d of .** a VFS im
276e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 plementation whe
276f0 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 n the flags para
27700 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 meter to xOpen()
27710 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 has one or .**
27720 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c more of the [SQL
27730 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 ITE_OPEN_URI] or
27740 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 [SQLITE_OPEN_MA
27750 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 IN_DB] bits set
27760 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 and.** P is the
27770 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 name of the quer
27780 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 y parameter, the
27790 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 n.** sqlite3_uri
277a0 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 _parameter(F,P)
277b0 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 returns the valu
277c0 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 e of the P.** pa
277d0 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 rameter if it ex
277e0 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 ists or a NULL p
277f0 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 ointer if P does
27800 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 not appear as a
27810 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d .** query param
27820 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 eter on F. If P
27830 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61 is a query para
27840 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 meter of F.** ha
27850 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 s no explicit va
27860 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 lue, then sqlite
27870 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 3_uri_parameter(
27880 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 F,P) returns.**
27890 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
278a0 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a empty string..**
278b0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
278c0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c uri_boolean(F,P,
278d0 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d B) routine assum
278e0 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62 es that P is a b
278f0 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 oolean.** parame
27900 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 ter and returns
27910 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 true (1) or fals
27920 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 e (0) according
27930 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 to the value.**
27940 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 of P. The sqlit
27950 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 e3_uri_boolean(F
27960 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 ,P,B) routine re
27970 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 turns true (1) i
27980 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f f the.** value o
27990 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 f query paramete
279a0 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 r P is one of "y
279b0 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 es", "true", or
279c0 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 "on" in any.** c
279d0 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 ase or if the va
279e0 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 lue begins with
279f0 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 a non-zero numbe
27a00 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 r. The .** sqli
27a10 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 te3_uri_boolean(
27a20 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 F,P,B) routines
27a30 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 returns false (0
27a40 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f ) if the value o
27a50 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d f.** query param
27a60 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 eter P is one of
27a70 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 "no", "false",
27a80 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 or "off" in any
27a90 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 case or.** if th
27aa0 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 e value begins w
27ab0 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 ith a numeric ze
27ac0 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 ro. If P is not
27ad0 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 a query.** para
27ae0 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 meter on F or if
27af0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 the value of P
27b00 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 is does not matc
27b10 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 h any of the.**
27b20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 above, then sqli
27b30 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 te3_uri_boolean(
27b40 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 F,P,B) returns (
27b50 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 B!=0)..**.** The
27b60 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 sqlite3_uri_int
27b70 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 64(F,P,D) routin
27b80 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 e converts the v
27b90 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 alue of P into a
27ba0 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 .** 64-bit signe
27bb0 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 d integer and re
27bc0 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 turns that integ
27bd0 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f er, or D if P do
27be0 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e es not.** exist.
27bf0 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f If the value o
27c00 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 f P is something
27c10 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 other than an i
27c20 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 nteger, then.**
27c30 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 zero is returned
27c40 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 ..** .** If F is
27c50 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
27c60 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 then sqlite3_ur
27c70 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 i_parameter(F,P)
27c80 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e returns NULL an
27c90 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 d.** sqlite3_uri
27ca0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 _boolean(F,P,B)
27cb0 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 returns B. If F
27cc0 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 is not a NULL p
27cd0 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 ointer and.** is
27ce0 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 not a database
27cf0 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f file pathname po
27d00 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 inter that SQLit
27d10 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 e passed into th
27d20 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d e xOpen.** VFS m
27d30 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 ethod, then the
27d40 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 behavior of this
27d50 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 routine is unde
27d60 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 fined and probab
27d70 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c ly.** undesirabl
27d80 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 e..*/.const char
27d90 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 *sqlite3_uri_pa
27da0 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 rameter(const ch
27db0 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 ar *zFilename, c
27dc0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 onst char *zPara
27dd0 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f m);.int sqlite3_
27de0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 uri_boolean(cons
27df0 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 t char *zFile, c
27e00 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 onst char *zPara
27e10 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 m, int bDefault)
27e20 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 ;.sqlite3_int64
27e30 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 sqlite3_uri_int6
27e40 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 4(const char*, c
27e50 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 onst char*, sqli
27e60 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a te3_int64);.../*
27e70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 .** CAPI3REF: Er
27e80 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 ror Codes And Me
27e90 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 ssages.** METHOD
27ea0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
27eb0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 ^If the most rec
27ec0 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 ent sqlite3_* AP
27ed0 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 I call associate
27ee0 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 d with .** [data
27ef0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
27f00 20 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 D failed, then
27f10 74 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 the sqlite3_errc
27f20 6f 64 65 28 44 29 20 69 6e 74 65 72 66 61 63 65 ode(D) interface
27f30 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 .** returns the
27f40 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 numeric [result
27f50 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 code] or [extend
27f60 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 ed result code]
27f70 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 for that.** API
27f80 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20 call..** If the
27f90 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 most recent API
27fa0 63 61 6c 6c 20 77 61 73 20 73 75 63 63 65 73 73 call was success
27fb0 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ful,.** then the
27fc0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 return value fr
27fd0 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f om sqlite3_errco
27fe0 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 de() is undefine
27ff0 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 d..** ^The sqlit
28000 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 e3_extended_errc
28010 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 ode().** interfa
28020 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 ce is the same e
28030 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c xcept that it al
28040 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 ways returns the
28050 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 .** [extended r
28060 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e esult code] even
28070 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 when extended r
28080 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a esult codes are.
28090 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a ** disabled..**.
280a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
280b0 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c errmsg() and sql
280c0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 ite3_errmsg16()
280d0 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c return English-l
280e0 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 anguage.** text
280f0 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 that describes t
28100 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 he error, as eit
28110 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 her UTF-8 or UTF
28120 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 -16 respectively
28130 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f ..** ^(Memory to
28140 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 hold the error
28150 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 message string i
28160 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e s managed intern
28170 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 ally..** The app
28180 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f lication does no
28190 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 t need to worry
281a0 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 about freeing th
281b0 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 e result..** How
281c0 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 ever, the error
281d0 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 string might be
281e0 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 overwritten or d
281f0 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a eallocated by.**
28200 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
28210 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 s to other SQLit
28220 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 e interface func
28230 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e tions.)^.**.** ^
28240 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 The sqlite3_errs
28250 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 tr() interface r
28260 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 eturns the Engli
28270 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 sh-language text
28280 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 .** that describ
28290 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 es the [result c
282a0 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a ode], as UTF-8..
282b0 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 ** ^(Memory to h
282c0 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 old the error me
282d0 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 ssage string is
282e0 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c managed internal
282f0 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e ly.** and must n
28300 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74 ot be freed by t
28310 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e he application)^
28320 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 ..**.** When the
28330 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 serialized [thr
28340 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 eading mode] is
28350 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 in use, it might
28360 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 be the.** case
28370 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 that a second er
28380 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 ror occurs on a
28390 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 separate thread
283a0 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 in between.** th
283b0 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 e time of the fi
283c0 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 rst error and th
283d0 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 e call to these
283e0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 interfaces..** W
283f0 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 hen that happens
28400 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 , the second err
28410 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 or will be repor
28420 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a ted since these.
28430 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c ** interfaces al
28440 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 ways report the
28450 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 most recent resu
28460 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a lt. To avoid.**
28470 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 this, each thre
28480 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 ad can obtain ex
28490 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 clusive use of t
284a0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
284b0 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 nection] D.** by
284c0 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 invoking [sqlit
284d0 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 e3_mutex_enter](
284e0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 [sqlite3_db_mute
284f0 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 x](D)) before be
28500 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 ginning.** to us
28510 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 e D and invoking
28520 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
28530 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f leave]([sqlite3_
28540 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 db_mutex](D)) af
28550 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 ter.** all calls
28560 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 to the interfac
28570 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 es listed here a
28580 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a re completed..**
28590 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 .** If an interf
285a0 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 ace fails with S
285b0 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 QLITE_MISUSE, th
285c0 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 at means the int
285d0 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e erface.** was in
285e0 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c voked incorrectl
285f0 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 y by the applica
28600 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 tion. In that c
28610 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f ase, the.** erro
28620 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 r code and messa
28630 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f ge may or may no
28640 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 t be set..*/.int
28650 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 sqlite3_errcode
28660 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 (sqlite3 *db);.i
28670 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e nt sqlite3_exten
28680 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 ded_errcode(sqli
28690 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 te3 *db);.const
286a0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 char *sqlite3_er
286b0 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a rmsg(sqlite3*);.
286c0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
286d0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c te3_errmsg16(sql
286e0 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 ite3*);.const ch
286f0 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 ar *sqlite3_errs
28700 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 tr(int);../*.**
28710 43 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 CAPI3REF: Prepar
28720 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a ed Statement Obj
28730 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ect.** KEYWORDS:
28740 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 {prepared state
28750 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 ment} {prepared
28760 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a statements}.**.*
28770 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 * An instance of
28780 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 this object rep
28790 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 resents a single
287a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
287b0 68 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 hat.** has been
287c0 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62 69 compiled into bi
287d0 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 69 73 nary form and is
287e0 20 72 65 61 64 79 20 74 6f 20 62 65 20 65 76 61 ready to be eva
287f0 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 luated..**.** Th
28800 69 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 4c 20 ink of each SQL
28810 73 74 61 74 65 6d 65 6e 74 20 61 73 20 61 20 73 statement as a s
28820 65 70 61 72 61 74 65 20 63 6f 6d 70 75 74 65 72 eparate computer
28830 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a program. The.*
28840 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 * original SQL t
28850 65 78 74 20 69 73 20 73 6f 75 72 63 65 20 63 6f ext is source co
28860 64 65 2e 20 20 41 20 70 72 65 70 61 72 65 64 20 de. A prepared
28870 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 statement object
28880 20 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d 70 .** is the comp
28890 69 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f 64 65 iled object code
288a0 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20 . All SQL must
288b0 62 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 be converted int
288c0 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 o a.** prepared
288d0 73 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72 65 statement before
288e0 20 69 74 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a it can be run..
288f0 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63 **.** The life-c
28900 79 63 6c 65 20 6f 66 20 61 20 70 72 65 70 61 72 ycle of a prepar
28910 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a ed statement obj
28920 65 63 74 20 75 73 75 61 6c 6c 79 20 67 6f 65 73 ect usually goes
28930 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a like this:.**.*
28940 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 * <ol>.** <li> C
28950 72 65 61 74 65 20 74 68 65 20 70 72 65 70 61 72 reate the prepar
28960 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a ed statement obj
28970 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ect using [sqlit
28980 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
28990 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 ..** <li> Bind v
289a0 61 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 6d 65 alues to [parame
289b0 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 ters] using the
289c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 sqlite3_bind_*()
289d0 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 .** interfa
289e0 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e ces..** <li> Run
289f0 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c the SQL by call
28a00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 ing [sqlite3_ste
28a10 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 p()] one or more
28a20 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 times..** <li>
28a30 52 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 Reset the prepar
28a40 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 ed statement usi
28a50 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ng [sqlite3_rese
28a60 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 t()] then go bac
28a70 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 k.** to ste
28a80 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 p 2. Do this ze
28a90 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 ro or more times
28aa0 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f ..** <li> Destro
28ab0 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 y the object usi
28ac0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ng [sqlite3_fina
28ad0 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c lize()]..** </ol
28ae0 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 >.*/.typedef str
28af0 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 uct sqlite3_stmt
28b00 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a sqlite3_stmt;..
28b10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
28b20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a Run-time Limits.
28b30 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
28b40 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 e3.**.** ^(This
28b50 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 interface allows
28b60 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 the size of var
28b70 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 ious constructs
28b80 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a to be limited.**
28b90 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e on a connection
28ba0 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 by connection b
28bb0 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 asis. The first
28bc0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
28bd0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 e.** [database c
28be0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 onnection] whose
28bf0 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 limit is to be
28c00 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 set or queried.
28c10 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 The.** second p
28c20 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 arameter is one
28c30 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 of the [limit ca
28c40 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 tegories] that d
28c50 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 efine a.** class
28c60 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 of constructs t
28c70 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 o be size limite
28c80 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 d. The third pa
28c90 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a rameter is the.*
28ca0 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 * new limit for
28cb0 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 that construct.)
28cc0 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ^.**.** ^If the
28cd0 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e new limit is a n
28ce0 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 egative number,
28cf0 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 the limit is unc
28d00 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 hanged..** ^(For
28d10 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 each limit cate
28d20 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 gory SQLITE_LIMI
28d30 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 T_<i>NAME</i> th
28d40 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 ere is a .** [li
28d50 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 mits | hard uppe
28d60 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 r bound].** set
28d70 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 at compile-time
28d80 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 by a C preproces
28d90 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 sor macro called
28da0 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 .** [limits | SQ
28db0 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 LITE_MAX_<i>NAME
28dc0 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 </i>]..** (The "
28dd0 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 _LIMIT_" in the
28de0 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 name is changed
28df0 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a to "_MAX_".))^.*
28e00 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 * ^Attempts to i
28e10 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 ncrease a limit
28e20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 above its hard u
28e30 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a pper bound are.*
28e40 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 * silently trunc
28e50 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 ated to the hard
28e60 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a upper bound..**
28e70 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 .** ^Regardless
28e80 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f of whether or no
28e90 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 t the limit was
28ea0 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a changed, the .**
28eb0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 [sqlite3_limit(
28ec0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
28ed0 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 urns the prior v
28ee0 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 alue of the limi
28ef0 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f t..** ^Hence, to
28f00 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e find the curren
28f10 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d t value of a lim
28f20 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 it without chang
28f30 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c ing it,.** simpl
28f40 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e y invoke this in
28f50 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65 terface with the
28f60 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
28f70 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a set to -1..**.*
28f80 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 * Run-time limit
28f90 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 s are intended f
28fa0 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 or use in applic
28fb0 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 ations that mana
28fc0 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 ge.** both their
28fd0 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 own internal da
28fe0 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 tabase and also
28ff0 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 databases that a
29000 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a re controlled.**
29010 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 by untrusted ex
29020 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 ternal sources.
29030 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c An example appl
29040 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 ication might be
29050 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 a.** web browse
29060 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f r that has its o
29070 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 wn databases for
29080 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 storing history
29090 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 and.** separate
290a0 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 databases contr
290b0 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 olled by JavaScr
290c0 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 ipt applications
290d0 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f downloaded.** o
290e0 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e ff the Internet.
290f0 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 The internal d
29100 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 atabases can be
29110 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 given the.** lar
29120 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 ge, default limi
29130 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d ts. Databases m
29140 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e anaged by extern
29150 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a al sources can.*
29160 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 * be given much
29170 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 smaller limits d
29180 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 esigned to preve
29190 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 nt a denial of s
291a0 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b ervice.** attack
291b0 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 . Developers mi
291c0 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f ght also want to
291d0 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 use the [sqlite
291e0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
291f0 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 ()].** interface
29200 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 to further cont
29210 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 rol untrusted SQ
29220 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 L. The size of
29230 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 the database.**
29240 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e created by an un
29250 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 trusted script c
29260 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 an be contained
29270 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 using the.** [ma
29280 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 x_page_count] [P
29290 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 RAGMA]..**.** Ne
292a0 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 w run-time limit
292b0 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 categories may
292c0 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 be added in futu
292d0 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a re releases..*/.
292e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 int sqlite3_limi
292f0 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 t(sqlite3*, int
29300 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b id, int newVal);
29310 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
29320 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 : Run-Time Limit
29330 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b Categories.** K
29340 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 EYWORDS: {limit
29350 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 category} {*limi
29360 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a t categories}.**
29370 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
29380 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f nts define vario
29390 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c us performance l
293a0 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 imits.** that ca
293b0 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 n be lowered at
293c0 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b run-time using [
293d0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d sqlite3_limit()]
293e0 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 ..** The synopsi
293f0 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 s of the meaning
29400 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 s of the various
29410 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e limits is shown
29420 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 below..** Addit
29430 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f ional informatio
29440 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 n is available a
29450 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 t [limits | Limi
29460 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a ts in SQLite]..*
29470 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 *.** <dl>.** [[S
29480 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 QLITE_LIMIT_LENG
29490 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 TH]] ^(<dt>SQLIT
294a0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f E_LIMIT_LENGTH</
294b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
294c0 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 aximum size of a
294d0 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f ny string or BLO
294e0 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 B or table row,
294f0 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a in bytes.<dd>)^.
29500 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
29510 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d IMIT_SQL_LENGTH]
29520 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
29530 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c IMIT_SQL_LENGTH<
29540 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
29550 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f maximum length o
29560 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 f an SQL stateme
29570 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 nt, in bytes.</d
29580 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d>)^.**.** [[SQL
29590 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e ITE_LIMIT_COLUMN
295a0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ]] ^(<dt>SQLITE_
295b0 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 LIMIT_COLUMN</dt
295c0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
295d0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 imum number of c
295e0 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c olumns in a tabl
295f0 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 e definition or
29600 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 in the.** result
29610 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 set of a [SELEC
29620 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 T] or the maximu
29630 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 m number of colu
29640 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a mns in an index.
29650 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 ** or in an ORDE
29660 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 R BY or GROUP BY
29670 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a clause.</dd>)^.
29680 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
29690 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d IMIT_EXPR_DEPTH]
296a0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
296b0 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c IMIT_EXPR_DEPTH<
296c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
296d0 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 maximum depth of
296e0 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 the parse tree
296f0 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f on any expressio
29700 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 n.</dd>)^.**.**
29710 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 [[SQLITE_LIMIT_C
29720 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d OMPOUND_SELECT]]
29730 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
29740 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c MIT_COMPOUND_SEL
29750 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ECT</dt>.** <dd>
29760 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
29770 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 er of terms in a
29780 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 compound SELECT
29790 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e statement.</dd>
297a0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
297b0 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d E_LIMIT_VDBE_OP]
297c0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
297d0 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 IMIT_VDBE_OP</dt
297e0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
297f0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 imum number of i
29800 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 nstructions in a
29810 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 virtual machine
29820 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 program.** used
29830 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e to implement an
29840 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 SQL statement.
29850 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 If [sqlite3_pre
29860 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a pare_v2()] or.**
29870 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 the equivalent
29880 74 72 69 65 73 20 74 6f 20 61 6c 6c 6f 63 61 74 tries to allocat
29890 65 20 73 70 61 63 65 20 66 6f 72 20 6d 6f 72 65 e space for more
298a0 20 74 68 61 6e 20 74 68 69 73 20 6d 61 6e 79 20 than this many
298b0 6f 70 63 6f 64 65 73 0a 2a 2a 20 69 6e 20 61 20 opcodes.** in a
298c0 73 69 6e 67 6c 65 20 70 72 65 70 61 72 65 64 20 single prepared
298d0 73 74 61 74 65 6d 65 6e 74 2c 20 61 6e 20 53 51 statement, an SQ
298e0 4c 49 54 45 5f 4e 4f 4d 45 4d 20 65 72 72 6f 72 LITE_NOMEM error
298f0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 is returned.</d
29900 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d>)^.**.** [[SQL
29910 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 ITE_LIMIT_FUNCTI
29920 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 ON_ARG]] ^(<dt>S
29930 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 QLITE_LIMIT_FUNC
29940 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a TION_ARG</dt>.**
29950 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
29960 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d number of argum
29970 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 ents on a functi
29980 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a on.</dd>)^.**.**
29990 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
299a0 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 ATTACHED]] ^(<dt
299b0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 >SQLITE_LIMIT_AT
299c0 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c TACHED</dt>.** <
299d0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e dd>The maximum n
299e0 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 umber of [ATTACH
299f0 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 | attached data
29a00 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a bases].)^</dd>.*
29a10 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
29a20 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e MIT_LIKE_PATTERN
29a30 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c _LENGTH]].** ^(<
29a40 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
29a50 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e LIKE_PATTERN_LEN
29a60 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e GTH</dt>.** <dd>
29a70 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 The maximum leng
29a80 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 th of the patter
29a90 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 n argument to th
29aa0 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b e [LIKE] or.** [
29ab0 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e GLOB] operators.
29ac0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b </dd>)^.**.** [[
29ad0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 SQLITE_LIMIT_VAR
29ae0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a IABLE_NUMBER]].*
29af0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c * ^(<dt>SQLITE_L
29b00 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 IMIT_VARIABLE_NU
29b10 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 MBER</dt>.** <dd
29b20 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 >The maximum ind
29b30 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 ex number of any
29b40 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 [parameter] in
29b50 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 an SQL statement
29b60 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 .)^.**.** [[SQLI
29b70 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 TE_LIMIT_TRIGGER
29b80 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 _DEPTH]] ^(<dt>S
29b90 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 QLITE_LIMIT_TRIG
29ba0 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a GER_DEPTH</dt>.*
29bb0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
29bc0 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 m depth of recur
29bd0 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 sion for trigger
29be0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 s.</dd>)^.**.**
29bf0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 [[SQLITE_LIMIT_W
29c00 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 ORKER_THREADS]]
29c10 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
29c20 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 IT_WORKER_THREAD
29c30 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 S</dt>.** <dd>Th
29c40 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
29c50 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f of auxiliary wo
29c60 72 6b 65 72 20 74 68 72 65 61 64 73 20 74 68 61 rker threads tha
29c70 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 t a single.** [p
29c80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
29c90 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 t] may start.</d
29ca0 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f d>)^.** </dl>.*/
29cb0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
29cc0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 LIMIT_LENGTH
29cd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
29ce0 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
29cf0 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 _LIMIT_SQL_LENGT
29d00 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 H
29d10 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 1.#define SQLIT
29d20 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 E_LIMIT_COLUMN
29d30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
29d40 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 2.#define SQLI
29d50 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 TE_LIMIT_EXPR_DE
29d60 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 PTH
29d70 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 3.#define SQL
29d80 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 ITE_LIMIT_COMPOU
29d90 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 ND_SELECT
29da0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4.#define SQ
29db0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f LITE_LIMIT_VDBE_
29dc0 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 OP
29dd0 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 5.#define S
29de0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 QLITE_LIMIT_FUNC
29df0 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 TION_ARG
29e00 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 6.#define
29e10 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 SQLITE_LIMIT_ATT
29e20 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 ACHED
29e30 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 7.#define
29e40 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 SQLITE_LIMIT_LI
29e50 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 KE_PATTERN_LENGT
29e60 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e H 8.#defin
29e70 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 e SQLITE_LIMIT_V
29e80 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 ARIABLE_NUMBER
29e90 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 9.#defi
29ea0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
29eb0 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 TRIGGER_DEPTH
29ec0 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 10.#def
29ed0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
29ee0 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20 _WORKER_THREADS
29ef0 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a 0a 2f 11.../
29f00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
29f10 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 ompiling An SQL
29f20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 Statement.** KEY
29f30 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 WORDS: {SQL stat
29f40 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a ement compiler}.
29f50 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
29f60 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f e3.** CONSTRUCTO
29f70 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a R: sqlite3_stmt.
29f80 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 **.** To execute
29f90 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 an SQL query, i
29fa0 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 t must first be
29fb0 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 compiled into a
29fc0 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f byte-code.** pro
29fd0 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f gram using one o
29fe0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
29ff0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 ..**.** The firs
2a000 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 t argument, "db"
2a010 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 , is a [database
2a020 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 connection] obt
2a030 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 ained from a.**
2a040 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c prior successful
2a050 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
2a060 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 3_open()], [sqli
2a070 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f te3_open_v2()] o
2a080 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 r.** [sqlite3_op
2a090 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 en16()]. The da
2a0a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2a0b0 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 n must not have
2a0c0 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a been closed..**.
2a0d0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 ** The second ar
2a0e0 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 gument, "zSql",
2a0f0 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 is the statement
2a100 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c to be compiled,
2a110 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 encoded.** as e
2a120 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 ither UTF-8 or U
2a130 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 TF-16. The sqli
2a140 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e te3_prepare() an
2a150 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 d sqlite3_prepar
2a160 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 e_v2().** interf
2a170 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 aces use UTF-8,
2a180 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 and sqlite3_prep
2a190 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 are16() and sqli
2a1a0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
2a1b0 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 ().** use UTF-16
2a1c0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
2a1d0 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 nByte argument i
2a1e0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e s negative, then
2a1f0 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 zSql is read up
2a200 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 to the.** first
2a210 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 zero terminator
2a220 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 70 . ^If nByte is p
2a230 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69 74 ositive, then it
2a240 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 is the.** numbe
2a250 72 20 6f 66 20 62 79 74 65 73 20 72 65 61 64 20 r of bytes read
2a260 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20 from zSql. ^If
2a270 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 74 nByte is zero, t
2a280 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 0a hen no prepared.
2a290 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 ** statement is
2a2a0 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66 generated..** If
2a2b0 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 the caller know
2a2c0 73 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c s that the suppl
2a2d0 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 ied string is nu
2a2e0 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 l-terminated, th
2a2f0 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61 en.** there is a
2a300 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e small performan
2a310 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 ce advantage to
2a320 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 passing an nByte
2a330 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a parameter that.
2a340 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 ** is the number
2a350 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 of bytes in the
2a360 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 input string <i
2a370 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a >including</i>.*
2a380 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e * the nul-termin
2a390 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 ator..**.** ^If
2a3a0 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 pzTail is not NU
2a3b0 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 LL then *pzTail
2a3c0 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 is made to point
2a3d0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 to the first by
2a3e0 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 te.** past the e
2a3f0 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 nd of the first
2a400 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e SQL statement in
2a410 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f zSql. These ro
2a420 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 utines only.** c
2a430 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 ompile the first
2a440 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 statement in zS
2a450 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 ql, so *pzTail i
2a460 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 s left pointing
2a470 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 to.** what remai
2a480 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a ns uncompiled..*
2a490 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 *.** ^*ppStmt is
2a4a0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 left pointing t
2a4b0 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 o a compiled [pr
2a4c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2a4d0 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a ] that can be.**
2a4e0 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 executed using
2a4f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
2a500 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 . ^If there is
2a510 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d an error, *ppStm
2a520 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e t is set.** to N
2a530 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e ULL. ^If the in
2a540 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e put text contain
2a550 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 s no SQL (if the
2a560 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 input is an emp
2a570 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 ty.** string or
2a580 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 a comment) then
2a590 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 *ppStmt is set t
2a5a0 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 o NULL..** The c
2a5b0 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 alling procedure
2a5c0 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 is responsible
2a5d0 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 for deleting the
2a5e0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c compiled.** SQL
2a5f0 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 statement using
2a600 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
2a610 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 ze()] after it h
2a620 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 as finished with
2a630 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d it..** ppStmt m
2a640 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a ay not be NULL..
2a650 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 **.** ^On succes
2a660 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 s, the sqlite3_p
2a670 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 repare() family
2a680 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 of routines retu
2a690 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a rn [SQLITE_OK];.
2a6a0 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 ** otherwise an
2a6b0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 [error code] is
2a6c0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
2a6d0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 The sqlite3_prep
2a6e0 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c are_v2() and sql
2a6f0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
2a700 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 2() interfaces a
2a710 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 re.** recommende
2a720 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 d for all new pr
2a730 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 ograms. The two
2a740 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 older interfaces
2a750 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a are retained.**
2a760 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 for backwards c
2a770 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 ompatibility, bu
2a780 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 t their use is d
2a790 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e iscouraged..** ^
2a7a0 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 In the "v2" inte
2a7b0 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 rfaces, the prep
2a7c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a ared statement.*
2a7d0 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e * that is return
2a7e0 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 ed (the [sqlite3
2a7f0 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 _stmt] object) c
2a800 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f ontains a copy o
2a810 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 f the.** origina
2a820 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 l SQL text. This
2a830 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c causes the [sql
2a840 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 ite3_step()] int
2a850 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 erface to.** beh
2a860 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 ave differently
2a870 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a in three ways:.*
2a880 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ol>.** <li
2a890 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 >.** ^If the dat
2a8a0 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 abase schema cha
2a8b0 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 nges, instead of
2a8c0 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 returning [SQLI
2a8d0 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 TE_SCHEMA] as it
2a8e0 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 .** always used
2a8f0 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f to do, [sqlite3_
2a900 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 step()] will aut
2a910 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d omatically recom
2a920 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 pile the SQL.**
2a930 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 statement and tr
2a940 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 y to run it agai
2a950 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 n. As many as [S
2a960 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 QLITE_MAX_SCHEMA
2a970 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 _RETRY].** retri
2a980 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 es will occur be
2a990 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65 fore sqlite3_ste
2a9a0 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e 64 p() gives up and
2a9b0 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f returns an erro
2a9c0 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a r..** </li>.**.*
2a9d0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 * <li>.** ^When
2a9e0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c an error occurs,
2a9f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
2aa00 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e ] will return on
2aa10 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 e of the detaile
2aa20 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 d.** [error code
2aa30 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 s] or [extended
2aa40 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e error codes]. ^
2aa50 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 The legacy behav
2aa60 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 ior was that.**
2aa70 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
2aa80 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 would only retu
2aa90 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 rn a generic [SQ
2aaa0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 LITE_ERROR] resu
2aab0 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 lt code.** and t
2aac0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 he application w
2aad0 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b ould have to mak
2aae0 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 e a second call
2aaf0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 to [sqlite3_rese
2ab00 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 t()].** in order
2ab10 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 to find the und
2ab20 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 erlying cause of
2ab30 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 the problem. Wi
2ab40 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 th the "v2" prep
2ab50 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 are.** interface
2ab60 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e s, the underlyin
2ab70 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 g reason for the
2ab80 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e error is return
2ab90 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a ed immediately..
2aba0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c ** </li>.**.** <
2abb0 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 li>.** ^If the s
2abc0 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f pecific value bo
2abd0 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 und to [paramete
2abe0 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 r | host paramet
2abf0 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 er] in the .** W
2ac00 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 HERE clause migh
2ac10 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 t influence the
2ac20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 choice of query
2ac30 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 plan for a state
2ac40 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 ment,.** then th
2ac50 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c e statement will
2ac60 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c be automaticall
2ac70 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 y recompiled, as
2ac80 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65 if there had be
2ac90 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 en .** a schema
2aca0 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 change, on the f
2acb0 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 irst [sqlite3_s
2acc0 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c tep()] call foll
2acd0 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 owing any change
2ace0 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 .** to the [sqli
2acf0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 te3_bind_text |
2ad00 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 bindings] of tha
2ad10 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a t [parameter]. .
2ad20 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 ** ^The specific
2ad30 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d value of WHERE-
2ad40 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 clause [paramete
2ad50 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e r] might influen
2ad60 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 ce the .** choic
2ad70 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 e of query plan
2ad80 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 if the parameter
2ad90 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e is the left-han
2ada0 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b d side of a [LIK
2adb0 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 E].** or [GLOB]
2adc0 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 operator or if t
2add0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 he parameter is
2ade0 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 compared to an i
2adf0 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a ndexed column.**
2ae00 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 and the [SQLITE
2ae10 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 _ENABLE_STAT3] c
2ae20 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
2ae30 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a on is enabled..*
2ae40 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e * </li>.** </ol>
2ae50 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
2ae60 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 prepare(. sqlit
2ae70 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
2ae80 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 /* Database h
2ae90 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
2aea0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 char *zSql,
2aeb0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d /* SQL statem
2aec0 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 ent, UTF-8 encod
2aed0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 ed */. int nByt
2aee0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 e,
2aef0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 /* Maximum lengt
2af00 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 h of zSql in byt
2af10 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 es. */. sqlite3
2af20 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 _stmt **ppStmt,
2af30 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 /* OUT: Stateme
2af40 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 nt handle */. c
2af50 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 onst char **pzTa
2af60 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 il /* OUT: P
2af70 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 ointer to unused
2af80 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c portion of zSql
2af90 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 */.);.int sqlit
2afa0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 e3_prepare_v2(.
2afb0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
2afc0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
2afd0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 base handle */.
2afe0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 const char *zSq
2aff0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 l, /* SQL
2b000 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 statement, UTF-8
2b010 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e encoded */. in
2b020 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 t nByte,
2b030 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d /* Maximum
2b040 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 length of zSql
2b050 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 in bytes. */. s
2b060 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 qlite3_stmt **pp
2b070 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 Stmt, /* OUT: S
2b080 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 tatement handle
2b090 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
2b0a0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 **pzTail /*
2b0b0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 OUT: Pointer to
2b0c0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f unused portion o
2b0d0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 f zSql */.);.int
2b0e0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
2b0f0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 16(. sqlite3 *d
2b100 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a b, /*
2b110 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 Database handle
2b120 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 */. const void
2b130 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a *zSql, /*
2b140 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 SQL statement,
2b150 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a UTF-16 encoded *
2b160 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 /. int nByte,
2b170 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d /* M
2b180 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
2b190 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 zSql in bytes.
2b1a0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d */. sqlite3_stm
2b1b0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 t **ppStmt, /*
2b1c0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 OUT: Statement h
2b1d0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
2b1e0 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 void **pzTail
2b1f0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 /* OUT: Point
2b200 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 er to unused por
2b210 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a tion of zSql */.
2b220 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 );.int sqlite3_p
2b230 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 repare16_v2(. s
2b240 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
2b250 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
2b260 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 se handle */. c
2b270 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c onst void *zSql,
2b280 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 /* SQL st
2b290 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 atement, UTF-16
2b2a0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 encoded */. int
2b2b0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 nByte,
2b2c0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 /* Maximum
2b2d0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 length of zSql i
2b2e0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 n bytes. */. sq
2b2f0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 lite3_stmt **ppS
2b300 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 tmt, /* OUT: St
2b310 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a atement handle *
2b320 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a /. const void *
2b330 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f *pzTail /* O
2b340 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 UT: Pointer to u
2b350 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 nused portion of
2b360 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a zSql */.);../*.
2b370 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 ** CAPI3REF: Ret
2b380 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e rieving Statemen
2b390 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a t SQL.** METHOD:
2b3a0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
2b3b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2b3c0 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61 63 _sql(P) interfac
2b3d0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e e returns a poin
2b3e0 74 65 72 20 74 6f 20 61 20 63 6f 70 79 20 6f 66 ter to a copy of
2b3f0 20 74 68 65 20 55 54 46 2d 38 0a 2a 2a 20 53 51 the UTF-8.** SQ
2b400 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 L text used to c
2b410 72 65 61 74 65 20 5b 70 72 65 70 61 72 65 64 20 reate [prepared
2b420 73 74 61 74 65 6d 65 6e 74 5d 20 50 20 69 66 20 statement] P if
2b430 50 20 77 61 73 0a 2a 2a 20 63 72 65 61 74 65 64 P was.** created
2b440 20 62 79 20 65 69 74 68 65 72 20 5b 73 71 6c 69 by either [sqli
2b450 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
2b460 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 ] or [sqlite3_pr
2b470 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a epare16_v2()]..*
2b480 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 * ^The sqlite3_e
2b490 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 20 69 xpanded_sql(P) i
2b4a0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
2b4b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
2b4c0 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 UTF-8.** string
2b4d0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 53 containing the S
2b4e0 51 4c 20 74 65 78 74 20 6f 66 20 70 72 65 70 61 QL text of prepa
2b4f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 red statement P
2b500 77 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64 20 70 with.** [bound p
2b510 61 72 61 6d 65 74 65 72 73 5d 20 65 78 70 61 6e arameters] expan
2b520 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 ded..**.** ^(For
2b530 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 20 70 example, if a p
2b540 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2b550 74 20 69 73 20 63 72 65 61 74 65 64 20 75 73 69 t is created usi
2b560 6e 67 20 74 68 65 20 53 51 4c 0a 2a 2a 20 74 65 ng the SQL.** te
2b570 78 74 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c xt "SELECT $abc,
2b580 3a 78 79 7a 22 20 61 6e 64 20 69 66 20 70 61 72 :xyz" and if par
2b590 61 6d 65 74 65 72 20 24 61 62 63 20 69 73 20 62 ameter $abc is b
2b5a0 6f 75 6e 64 20 74 6f 20 69 6e 74 65 67 65 72 20 ound to integer
2b5b0 32 33 34 35 0a 2a 2a 20 61 6e 64 20 70 61 72 61 2345.** and para
2b5c0 6d 65 74 65 72 20 3a 78 79 7a 20 69 73 20 75 6e meter :xyz is un
2b5d0 62 6f 75 6e 64 2c 20 74 68 65 6e 20 73 71 6c 69 bound, then sqli
2b5e0 74 65 33 5f 73 71 6c 28 29 20 77 69 6c 6c 20 72 te3_sql() will r
2b5f0 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 6f 72 69 eturn.** the ori
2b600 67 69 6e 61 6c 20 73 74 72 69 6e 67 2c 20 22 53 ginal string, "S
2b610 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 ELECT $abc,:xyz"
2b620 20 62 75 74 20 73 71 6c 69 74 65 33 5f 65 78 70 but sqlite3_exp
2b630 61 6e 64 65 64 5f 73 71 6c 28 29 0a 2a 2a 20 77 anded_sql().** w
2b640 69 6c 6c 20 72 65 74 75 72 6e 20 22 53 45 4c 45 ill return "SELE
2b650 43 54 20 32 33 34 35 2c 4e 55 4c 4c 22 2e 29 5e CT 2345,NULL".)^
2b660 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2b670 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c te3_expanded_sql
2b680 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 () interface ret
2b690 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69 6e 73 urns NULL if ins
2b6a0 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 ufficient memory
2b6b0 0a 2a 2a 20 69 73 20 61 76 61 69 6c 61 62 6c 65 .** is available
2b6c0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 to hold the res
2b6d0 75 6c 74 2c 20 6f 72 20 69 66 20 74 68 65 20 72 ult, or if the r
2b6e0 65 73 75 6c 74 20 77 6f 75 6c 64 20 65 78 63 65 esult would exce
2b6f0 65 64 20 74 68 65 0a 2a 2a 20 74 68 65 20 6d 61 ed the.** the ma
2b700 78 69 6d 75 6d 20 73 74 72 69 6e 67 20 6c 65 6e ximum string len
2b710 67 74 68 20 64 65 74 65 72 6d 69 6e 65 64 20 62 gth determined b
2b720 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4c 49 y the [SQLITE_LI
2b730 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 0a MIT_LENGTH]..**.
2b740 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f ** ^The [SQLITE_
2b750 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 TRACE_SIZE_LIMIT
2b760 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
2b770 70 74 69 6f 6e 20 6c 69 6d 69 74 73 20 74 68 65 ption limits the
2b780 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f 75 6e size of.** boun
2b790 64 20 70 61 72 61 6d 65 74 65 72 20 65 78 70 61 d parameter expa
2b7a0 6e 73 69 6f 6e 73 2e 20 20 5e 54 68 65 20 5b 53 nsions. ^The [S
2b7b0 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 41 43 45 QLITE_OMIT_TRACE
2b7c0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a ] compile-time.*
2b7d0 2a 20 6f 70 74 69 6f 6e 20 63 61 75 73 65 73 20 * option causes
2b7e0 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 sqlite3_expanded
2b7f0 5f 73 71 6c 28 29 20 74 6f 20 61 6c 77 61 79 73 _sql() to always
2b800 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a return NULL..**
2b810 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20 .** ^The string
2b820 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
2b830 74 65 33 5f 73 71 6c 28 50 29 20 69 73 20 6d 61 te3_sql(P) is ma
2b840 6e 61 67 65 64 20 62 79 20 53 51 4c 69 74 65 20 naged by SQLite
2b850 61 6e 64 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 and is.** automa
2b860 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20 77 68 tically freed wh
2b870 65 6e 20 74 68 65 20 70 72 65 70 61 72 65 64 20 en the prepared
2b880 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e statement is fin
2b890 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 alized..** ^The
2b8a0 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 string returned
2b8b0 62 79 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e by sqlite3_expan
2b8c0 64 65 64 5f 73 71 6c 28 50 29 2c 20 6f 6e 20 74 ded_sql(P), on t
2b8d0 68 65 20 6f 74 68 65 72 20 68 61 6e 64 2c 0a 2a he other hand,.*
2b8e0 2a 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 * is obtained fr
2b8f0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
2b900 6f 63 28 29 5d 20 61 6e 64 20 6d 75 73 74 20 62 oc()] and must b
2b910 65 20 66 72 65 65 20 62 79 20 74 68 65 20 61 70 e free by the ap
2b920 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 62 79 20 plication.** by
2b930 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 passing it to [s
2b940 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a qlite3_free()]..
2b950 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 */.const char *s
2b960 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 qlite3_sql(sqlit
2b970 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b e3_stmt *pStmt);
2b980 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 .char *sqlite3_e
2b990 78 70 61 6e 64 65 64 5f 73 71 6c 28 73 71 6c 69 xpanded_sql(sqli
2b9a0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
2b9b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2b9c0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 F: Determine If
2b9d0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 An SQL Statement
2b9e0 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 Writes The Data
2b9f0 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 base.** METHOD:
2ba00 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a sqlite3_stmt.**.
2ba10 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2ba20 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 stmt_readonly(X)
2ba30 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
2ba40 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 ns true (non-zer
2ba50 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c o) if.** and onl
2ba60 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 y if the [prepar
2ba70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 ed statement] X
2ba80 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 makes no direct
2ba90 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 changes to.** th
2baa0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 e content of the
2bab0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a database file..
2bac0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 **.** Note that
2bad0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 [application-def
2bae0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f ined SQL functio
2baf0 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 ns] or.** [virtu
2bb00 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 al tables] might
2bb10 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 change the data
2bb20 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 base indirectly
2bb30 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74 as a side effect
2bb40 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 . .** ^(For exa
2bb50 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c mple, if an appl
2bb60 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 ication defines
2bb70 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c a function "eval
2bb80 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c ()" that .** cal
2bb90 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 ls [sqlite3_exec
2bba0 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f ()], then the fo
2bbb0 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 llowing SQL stat
2bbc0 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 ement would.** c
2bbd0 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 hange the databa
2bbe0 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 se file through
2bbf0 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a side-effects:.**
2bc00 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
2bc10 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 <pre>.** SELE
2bc20 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 CT eval('DELETE
2bc30 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 FROM t1') FROM t
2bc40 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 2;.** </pre></bl
2bc50 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
2bc60 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20 But because the
2bc70 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 [SELECT] stateme
2bc80 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e nt does not chan
2bc90 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ge the database
2bca0 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 file.** directly
2bcb0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 , sqlite3_stmt_r
2bcc0 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 eadonly() would
2bcd0 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 still return tru
2bce0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e e.)^.**.** ^Tran
2bcf0 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 saction control
2bd00 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 statements such
2bd10 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d as [BEGIN], [COM
2bd20 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d MIT], [ROLLBACK]
2bd30 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d ,.** [SAVEPOINT]
2bd40 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 , and [RELEASE]
2bd50 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 cause sqlite3_st
2bd60 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f mt_readonly() to
2bd70 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a return true,.**
2bd80 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 since the state
2bd90 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 ments themselves
2bda0 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 do not actually
2bdb0 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 modify the data
2bdc0 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 base but.** rath
2bdd0 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 er they control
2bde0 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 the timing of wh
2bdf0 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 en other stateme
2be00 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a nts modify the .
2be10 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 ** database. ^T
2be20 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 he [ATTACH] and
2be30 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 [DETACH] stateme
2be40 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a nts also cause.*
2be50 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 * sqlite3_stmt_r
2be60 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 eadonly() to ret
2be70 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 urn true since,
2be80 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 while those stat
2be90 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 ements.** change
2bea0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 the configurati
2beb0 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 on of a database
2bec0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 connection, the
2bed0 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a y do not make .*
2bee0 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 * changes to the
2bef0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 content of the
2bf00 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f database files o
2bf10 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e 54 68 65 20 n disk..** ^The
2bf20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 sqlite3_stmt_rea
2bf30 64 6f 6e 6c 79 28 29 20 69 6e 74 65 72 66 61 63 donly() interfac
2bf40 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 66 e returns true f
2bf50 6f 72 20 5b 42 45 47 49 4e 5d 20 73 69 6e 63 65 or [BEGIN] since
2bf60 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20 6d 65 72 65 .** [BEGIN] mere
2bf70 6c 79 20 73 65 74 73 20 69 6e 74 65 72 6e 61 6c ly sets internal
2bf80 20 66 6c 61 67 73 2c 20 62 75 74 20 74 68 65 20 flags, but the
2bf90 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 49 4d 4d [BEGIN|BEGIN IMM
2bfa0 45 44 49 41 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b EDIATE] and.** [
2bfb0 42 45 47 49 4e 7c 42 45 47 49 4e 20 45 58 43 4c BEGIN|BEGIN EXCL
2bfc0 55 53 49 56 45 5d 20 63 6f 6d 6d 61 6e 64 73 20 USIVE] commands
2bfd0 64 6f 20 74 6f 75 63 68 20 74 68 65 20 64 61 74 do touch the dat
2bfe0 61 62 61 73 65 20 61 6e 64 20 73 6f 0a 2a 2a 20 abase and so.**
2bff0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 sqlite3_stmt_rea
2c000 64 6f 6e 6c 79 28 29 20 72 65 74 75 72 6e 73 20 donly() returns
2c010 66 61 6c 73 65 20 66 6f 72 20 74 68 6f 73 65 20 false for those
2c020 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 commands..*/.int
2c030 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 sqlite3_stmt_re
2c040 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 adonly(sqlite3_s
2c050 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
2c060 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
2c070 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 termine If A Pre
2c080 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 pared Statement
2c090 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a Has Been Reset.*
2c0a0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
2c0b0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 3_stmt.**.** ^Th
2c0c0 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 e sqlite3_stmt_b
2c0d0 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 usy(S) interface
2c0e0 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e returns true (n
2c0f0 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a on-zero) if the.
2c100 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
2c110 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 tement] S has be
2c120 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 en stepped at le
2c130 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a ast once using .
2c140 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ** [sqlite3_step
2c150 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 65 69 (S)] but has nei
2c160 74 68 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d 70 ther run to comp
2c170 6c 65 74 69 6f 6e 20 28 72 65 74 75 72 6e 65 64 letion (returned
2c180 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 .** [SQLITE_DONE
2c190 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f ] from [sqlite3_
2c1a0 73 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a step(S)]) nor.**
2c1b0 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e been reset usin
2c1c0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 g [sqlite3_reset
2c1d0 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 (S)]. ^The sqli
2c1e0 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 te3_stmt_busy(S)
2c1f0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 .** interface re
2c200 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 turns false if S
2c210 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
2c220 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 er. If S is not
2c230 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e a .** NULL poin
2c240 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 ter and is not a
2c250 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 pointer to a va
2c260 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 lid [prepared st
2c270 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 atement].** obje
2c280 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 ct, then the beh
2c290 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e avior is undefin
2c2a0 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 ed and probably
2c2b0 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a undesirable..**.
2c2c0 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 ** This interfac
2c2d0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e e can be used in
2c2e0 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 combination [sq
2c2f0 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 lite3_next_stmt(
2c300 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 )].** to locate
2c310 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 all prepared sta
2c320 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 tements associat
2c330 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61 ed with a databa
2c340 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f se .** connectio
2c350 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 n that are in ne
2c360 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 ed of being rese
2c370 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 t. This can be
2c380 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 used,.** for exa
2c390 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 mple, in diagnos
2c3a0 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 tic routines to
2c3b0 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 search for prepa
2c3c0 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e red .** statemen
2c3d0 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 ts that are hold
2c3e0 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f ing a transactio
2c3f0 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 n open..*/.int s
2c400 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 qlite3_stmt_busy
2c410 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b (sqlite3_stmt*);
2c420 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2c430 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 : Dynamically Ty
2c440 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 ped Value Object
2c450 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 .** KEYWORDS: {p
2c460 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
2c470 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 _value} {unprote
2c480 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
2c490 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 ue}.**.** SQLite
2c4a0 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 uses the sqlite
2c4b0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 3_value object t
2c4c0 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 o represent all
2c4d0 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 values.** that c
2c4e0 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 an be stored in
2c4f0 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 a database table
2c500 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 . SQLite uses dy
2c510 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 namic typing.**
2c520 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 for the values i
2c530 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 t stores. ^Valu
2c540 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c es stored in sql
2c550 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
2c560 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 ts.** can be int
2c570 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 egers, floating
2c580 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 point values, st
2c590 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 rings, BLOBs, or
2c5a0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 NULL..**.** An
2c5b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
2c5c0 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 ject may be eith
2c5d0 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f er "protected" o
2c5e0 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e r "unprotected".
2c5f0 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 .** Some interfa
2c600 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 ces require a pr
2c610 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
2c620 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e value. Other in
2c630 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c terfaces.** will
2c640 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 accept either a
2c650 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e protected or an
2c660 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c unprotected sql
2c670 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 ite3_value..** E
2c680 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 very interface t
2c690 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 hat accepts sqli
2c6a0 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 te3_value argume
2c6b0 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a nts specifies.**
2c6c0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
2c6d0 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 it requires a pr
2c6e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
2c6f0 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b value. The.** [
2c700 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 sqlite3_value_du
2c710 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 p()] interface c
2c720 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f an be used to co
2c730 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a nstruct a new .*
2c740 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 * protected sqli
2c750 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61 te3_value from a
2c760 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 n unprotected sq
2c770 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a lite3_value..**.
2c780 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 ** The terms "pr
2c790 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e otected" and "un
2c7a0 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 protected" refer
2c7b0 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e to whether or n
2c7c0 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 ot.** a mutex is
2c7d0 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 held. An inter
2c7e0 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c nal mutex is hel
2c7f0 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 d for a protecte
2c800 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c d.** sqlite3_val
2c810 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f ue object but no
2c820 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 mutex is held f
2c830 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 or an unprotecte
2c840 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c d.** sqlite3_val
2c850 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 ue object. If S
2c860 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
2c870 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 d to be single-t
2c880 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 hreaded.** (with
2c890 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
2c8a0 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 AFE=0] and with
2c8b0 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 [sqlite3_threads
2c8c0 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 afe()] returning
2c8d0 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 0).** or if SQL
2c8e0 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e ite is run in on
2c8f0 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 e of reduced mut
2c900 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 ex modes .** [SQ
2c910 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
2c920 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 LETHREAD] or [SQ
2c930 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 LITE_CONFIG_MULT
2c940 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e ITHREAD].** then
2c950 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 there is no dis
2c960 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e tinction between
2c970 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 protected and u
2c980 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 nprotected.** sq
2c990 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
2c9a0 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e cts and they can
2c9b0 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 be used interch
2c9c0 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 angeably. Howev
2c9d0 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d er,.** for maxim
2c9e0 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c um code portabil
2c9f0 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d ity it is recomm
2ca00 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 ended that appli
2ca10 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c cations.** still
2ca20 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e make the distin
2ca30 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 ction between pr
2ca40 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 otected and unpr
2ca50 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 otected.** sqlit
2ca60 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
2ca70 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 even when not s
2ca80 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 trictly required
2ca90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
2caa0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
2cab0 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 ts that are pass
2cac0 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 ed as parameters
2cad0 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 into the.** imp
2cae0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b lementation of [
2caf0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
2cb00 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ned SQL function
2cb10 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 s] are protected
2cb20 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 ..** ^The sqlite
2cb30 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 3_value object r
2cb40 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 eturned by.** [s
2cb50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 qlite3_column_va
2cb60 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 lue()] is unprot
2cb70 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 ected..** Unprot
2cb80 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
2cb90 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 lue objects may
2cba0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 only be used wit
2cbb0 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 h.** [sqlite3_re
2cbc0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e sult_value()] an
2cbd0 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f d [sqlite3_bind_
2cbe0 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 value()]..** The
2cbf0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
2cc00 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 blob | sqlite3_v
2cc10 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d alue_type()] fam
2cc20 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 ily of.** interf
2cc30 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f aces require pro
2cc40 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
2cc50 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f alue objects..*/
2cc60 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
2cc70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 73 71 sqlite3_value sq
2cc80 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a lite3_value;../*
2cc90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 .** CAPI3REF: SQ
2cca0 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 L Function Conte
2ccb0 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 xt Object.**.**
2ccc0 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 The context in w
2ccd0 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 hich an SQL func
2cce0 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 tion executes is
2ccf0 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a stored in an.**
2cd00 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
2cd10 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 object. ^A poi
2cd20 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 nter to an sqlit
2cd30 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 e3_context objec
2cd40 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 t.** is always f
2cd50 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 irst parameter t
2cd60 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 o [application-d
2cd70 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
2cd80 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 ions]..** The ap
2cd90 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
2cda0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 d SQL function i
2cdb0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 mplementation wi
2cdc0 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 ll pass this.**
2cdd0 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 pointer through
2cde0 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 into calls to [s
2cdf0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e qlite3_result_in
2ce00 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 t | sqlite3_resu
2ce10 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 lt()],.** [sqlit
2ce20 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
2ce30 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 text()], [sqlite
2ce40 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 3_user_data()],.
2ce50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ** [sqlite3_cont
2ce60 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d ext_db_handle()]
2ce70 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 , [sqlite3_get_a
2ce80 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e uxdata()],.** an
2ce90 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 d/or [sqlite3_se
2cea0 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f t_auxdata()]..*/
2ceb0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
2cec0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 sqlite3_context
2ced0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b sqlite3_context;
2cee0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2cef0 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 : Binding Values
2cf00 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 To Prepared Sta
2cf10 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f tements.** KEYWO
2cf20 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d RDS: {host param
2cf30 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 eter} {host para
2cf40 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 meters} {host pa
2cf50 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a rameter name}.**
2cf60 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 KEYWORDS: {SQL
2cf70 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 parameter} {SQL
2cf80 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 parameters} {par
2cf90 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a ameter binding}.
2cfa0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
2cfb0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 e3_stmt.**.** ^(
2cfc0 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 In the SQL state
2cfd0 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 ment text input
2cfe0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 to [sqlite3_prep
2cff0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 are_v2()] and it
2d000 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c s variants,.** l
2d010 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 iterals may be r
2d020 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 eplaced by a [pa
2d030 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 rameter] that ma
2d040 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c tches one of fol
2d050 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 lowing.** templa
2d060 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a tes:.**.** <ul>.
2d070 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c ** <li> ?.** <l
2d080 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e i> ?NNN.** <li>
2d090 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 :VVV.** <li>
2d0a0 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 @VVV.** <li> $V
2d0b0 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a VV.** </ul>.**.*
2d0c0 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 * In the templat
2d0d0 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 es above, NNN re
2d0e0 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 presents an inte
2d0f0 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 ger literal,.**
2d100 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e and VVV represen
2d110 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 ts an alphanumer
2d120 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e ic identifier.)^
2d130 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 ^The values of
2d140 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 these.** parame
2d150 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 ters (also calle
2d160 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 d "host paramete
2d170 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c r names" or "SQL
2d180 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a parameters").**
2d190 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e can be set usin
2d1a0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 g the sqlite3_bi
2d1b0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 nd_*() routines
2d1c0 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a defined here..**
2d1d0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 .** ^The first a
2d1e0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 rgument to the s
2d1f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 qlite3_bind_*()
2d200 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 routines is alwa
2d210 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 ys.** a pointer
2d220 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
2d230 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 stmt] object ret
2d240 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 urned from.** [s
2d250 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
2d260 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 2()] or its vari
2d270 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ants..**.** ^The
2d280 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
2d290 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 is the index of
2d2a0 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 the SQL paramet
2d2b0 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a er to be set..**
2d2c0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 ^The leftmost S
2d2d0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 QL parameter has
2d2e0 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 an index of 1.
2d2f0 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 ^When the same
2d300 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 named.** SQL par
2d310 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d ameter is used m
2d320 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 ore than once, s
2d330 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 econd and subseq
2d340 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e uent.** occurren
2d350 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d ces have the sam
2d360 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 e index as the f
2d370 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e irst occurrence.
2d380 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 .** ^The index f
2d390 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 or named paramet
2d3a0 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 ers can be looke
2d3b0 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a d up using the.*
2d3c0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
2d3d0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 parameter_index(
2d3e0 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 )] API if desire
2d3f0 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a d. ^The index.*
2d400 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 * for "?NNN" par
2d410 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 ameters is the v
2d420 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 alue of NNN..**
2d430 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d ^The NNN value m
2d440 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 ust be between 1
2d450 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 and the [sqlite
2d460 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 3_limit()].** pa
2d470 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f rameter [SQLITE_
2d480 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e LIMIT_VARIABLE_N
2d490 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 UMBER] (default
2d4a0 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a value: 999)..**.
2d4b0 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 ** ^The third ar
2d4c0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 gument is the va
2d4d0 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 lue to bind to t
2d4e0 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a he parameter..**
2d4f0 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 ^If the third p
2d500 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
2d510 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 te3_bind_text()
2d520 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f or sqlite3_bind_
2d530 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 text16().** or s
2d540 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
2d550 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 () is a NULL poi
2d560 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f nter then the fo
2d570 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a urth parameter.*
2d580 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 * is ignored and
2d590 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 the end result
2d5a0 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 is the same as s
2d5b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c qlite3_bind_null
2d5c0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 ()..**.** ^(In t
2d5d0 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 hose routines th
2d5e0 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 at have a fourth
2d5f0 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 argument, its v
2d600 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e alue is the.** n
2d610 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 umber of bytes i
2d620 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e n the parameter.
2d630 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 To be clear: t
2d640 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a he value is the.
2d650 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e ** number of <u>
2d660 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 bytes</u> in the
2d670 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 value, not the
2d680 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 number of charac
2d690 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 ters.)^.** ^If t
2d6a0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
2d6b0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 ter to sqlite3_b
2d6c0 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 ind_text() or sq
2d6d0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 lite3_bind_text1
2d6e0 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 6().** is negati
2d6f0 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e ve, then the len
2d700 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e gth of the strin
2d710 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 g is.** the numb
2d720 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 er of bytes up t
2d730 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f o the first zero
2d740 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 terminator..**
2d750 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 If the fourth pa
2d760 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
2d770 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 e3_bind_blob() i
2d780 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e s negative, then
2d790 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 .** the behavior
2d7a0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
2d7b0 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 * If a non-negat
2d7c0 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d ive fourth param
2d7d0 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 eter is provided
2d7e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
2d7f0 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 _text().** or sq
2d800 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 lite3_bind_text1
2d810 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 6() or sqlite3_b
2d820 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68 65 ind_text64() the
2d830 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65 n.** that parame
2d840 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 ter must be the
2d850 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 byte offset.** w
2d860 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 here the NUL ter
2d870 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 minator would oc
2d880 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 cur assuming the
2d890 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c string were NUL
2d8a0 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 .** terminated.
2d8b0 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 If any NUL char
2d8c0 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 acters occur at
2d8d0 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 byte offsets les
2d8e0 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 s than .** the v
2d8f0 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 alue of the four
2d900 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 th parameter the
2d910 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 n the resulting
2d920 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c string value wil
2d930 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 l.** contain emb
2d940 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 edded NULs. The
2d950 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 result of expre
2d960 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 ssions involving
2d970 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 strings.** with
2d980 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 embedded NULs i
2d990 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a s undefined..**.
2d9a0 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 ** ^The fifth ar
2d9b0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c gument to the BL
2d9c0 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69 OB and string bi
2d9d0 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 nding interfaces
2d9e0 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75 63 .** is a destruc
2d9f0 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 tor used to disp
2da00 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 ose of the BLOB
2da10 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 or.** string aft
2da20 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 er SQLite has fi
2da30 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 nished with it.
2da40 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 ^The destructor
2da50 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f is called.** to
2da60 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 dispose of the
2da70 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 BLOB or string e
2da80 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 ven if the call
2da90 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c to bind API fail
2daa0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 s..** ^If the fi
2dab0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a fth argument is.
2dac0 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 ** the special v
2dad0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 alue [SQLITE_STA
2dae0 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 TIC], then SQLit
2daf0 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 e assumes that t
2db00 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f he.** informatio
2db10 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 n is in static,
2db20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 unmanaged space
2db30 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 and does not nee
2db40 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a d to be freed..*
2db50 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 * ^If the fifth
2db60 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 argument has the
2db70 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 value [SQLITE_T
2db80 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a RANSIENT], then.
2db90 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 ** SQLite makes
2dba0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 its own private
2dbb0 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 copy of the data
2dbc0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 immediately, be
2dbd0 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 fore.** the sqli
2dbe0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
2dbf0 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a tine returns..**
2dc00 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61 .** ^The sixth a
2dc10 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
2dc20 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 e3_bind_text64()
2dc30 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a must be one of.
2dc40 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d ** [SQLITE_UTF8]
2dc50 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d , [SQLITE_UTF16]
2dc60 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 , [SQLITE_UTF16B
2dc70 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 E], or [SQLITE_U
2dc80 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 TF16LE].** to sp
2dc90 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69 ecify the encodi
2dca0 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74 20 69 ng of the text i
2dcb0 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 n the third para
2dcc0 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 meter. If.** th
2dcd0 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 e sixth argument
2dce0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
2dcf0 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74 _text64() is not
2dd00 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 one of the.** a
2dd10 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68 llowed values sh
2dd20 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 own above, or if
2dd30 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 the text encodi
2dd40 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a ng is different.
2dd50 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f ** from the enco
2dd60 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 20 62 ding specified b
2dd70 79 20 74 68 65 20 73 69 78 74 68 20 70 61 72 61 y the sixth para
2dd80 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 meter, then the
2dd90 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 behavior.** is u
2dda0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
2ddb0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e ^The sqlite3_bin
2ddc0 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 d_zeroblob() rou
2ddd0 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f tine binds a BLO
2dde0 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 B of length N th
2ddf0 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 at.** is filled
2de00 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 with zeroes. ^A
2de10 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 zeroblob uses a
2de20 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 fixed amount of
2de30 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 memory.** (just
2de40 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 an integer to h
2de50 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 old its size) wh
2de60 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 ile it is being
2de70 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 processed..** Ze
2de80 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 roblobs are inte
2de90 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 nded to serve as
2dea0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f placeholders fo
2deb0 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a r BLOBs whose.**
2dec0 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 content is late
2ded0 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a r written using.
2dee0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 ** [sqlite3_blob
2def0 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e _open | incremen
2df00 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f tal BLOB I/O] ro
2df10 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 utines..** ^A ne
2df20 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 gative value for
2df30 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 the zeroblob re
2df40 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d sults in a zero-
2df50 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a length BLOB..**.
2df60 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 ** ^If any of th
2df70 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
2df80 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 () routines are
2df90 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 called with a NU
2dfa0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f LL pointer.** fo
2dfb0 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 r the [prepared
2dfc0 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 statement] or wi
2dfd0 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74 th a prepared st
2dfe0 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 atement for whic
2dff0 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 h.** [sqlite3_st
2e000 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 ep()] has been c
2e010 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e alled more recen
2e020 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 tly than [sqlite
2e030 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 3_reset()],.** t
2e040 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c hen the call wil
2e050 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 l return [SQLITE
2e060 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e _MISUSE]. If an
2e070 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 y sqlite3_bind_(
2e080 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 ).** routine is
2e090 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 passed a [prepar
2e0a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
2e0b0 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 at has been fina
2e0c0 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 lized, the.** re
2e0d0 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 sult is undefine
2e0e0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 d and probably h
2e0f0 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 armful..**.** ^B
2e100 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 indings are not
2e110 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b cleared by the [
2e120 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
2e130 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e routine..** ^Un
2e140 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 bound parameters
2e150 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 are interpreted
2e160 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 as NULL..**.**
2e170 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e ^The sqlite3_bin
2e180 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 d_* routines ret
2e190 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 urn [SQLITE_OK]
2e1a0 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e on success or an
2e1b0 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d .** [error code]
2e1c0 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 if anything goe
2e1d0 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 s wrong..** ^[SQ
2e1e0 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 LITE_TOOBIG] mig
2e1f0 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 ht be returned i
2e200 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 f the size of a
2e210 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a string or BLOB.*
2e220 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73 * exceeds limits
2e230 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c imposed by [sql
2e240 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c ite3_limit]([SQL
2e250 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 ITE_LIMIT_LENGTH
2e260 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 ]) or.** [SQLITE
2e270 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a _MAX_LENGTH]..**
2e280 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d ^[SQLITE_RANGE]
2e290 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 is returned if
2e2a0 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a the parameter.**
2e2b0 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 index is out of
2e2c0 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 range. ^[SQLIT
2e2d0 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 E_NOMEM] is retu
2e2e0 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 rned if malloc()
2e2f0 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 fails..**.** Se
2e300 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
2e310 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
2e320 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 count()],.** [sq
2e330 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
2e340 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e eter_name()], an
2e350 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f d [sqlite3_bind_
2e360 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 parameter_index(
2e370 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 )]..*/.int sqlit
2e380 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c e3_bind_blob(sql
2e390 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
2e3a0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
2e3b0 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 t n, void(*)(voi
2e3c0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 d*));.int sqlite
2e3d0 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71 3_bind_blob64(sq
2e3e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2e3f0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73 , const void*, s
2e400 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 qlite3_uint64,.
2e410 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2e420 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 void(*)(v
2e430 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 oid*));.int sqli
2e440 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 te3_bind_double(
2e450 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2e460 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 nt, double);.int
2e470 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e sqlite3_bind_in
2e480 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c t(sqlite3_stmt*,
2e490 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 int, int);.int
2e4a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 sqlite3_bind_int
2e4b0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 64(sqlite3_stmt*
2e4c0 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 , int, sqlite3_i
2e4d0 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 nt64);.int sqlit
2e4e0 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c e3_bind_null(sql
2e4f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 ite3_stmt*, int)
2e500 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 ;.int sqlite3_bi
2e510 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f nd_text(sqlite3_
2e520 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 stmt*,int,const
2e530 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a char*,int,void(*
2e540 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 )(void*));.int s
2e550 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
2e560 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
2e570 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 , int, const voi
2e580 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 d*, int, void(*)
2e590 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 (void*));.int sq
2e5a0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 lite3_bind_text6
2e5b0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 4(sqlite3_stmt*,
2e5c0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 int, const char
2e5d0 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 *, sqlite3_uint6
2e5e0 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 4,.
2e5f0 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 void
2e600 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 (*)(void*), unsi
2e610 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69 gned char encodi
2e620 6e 67 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ng);.int sqlite3
2e630 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 _bind_value(sqli
2e640 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
2e650 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 const sqlite3_va
2e660 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 lue*);.int sqlit
2e670 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 e3_bind_zeroblob
2e680 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2e690 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 69 6e 74 int, int n);.int
2e6a0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 sqlite3_bind_ze
2e6b0 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 roblob64(sqlite3
2e6c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c _stmt*, int, sql
2e6d0 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f ite3_uint64);../
2e6e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e *.** CAPI3REF: N
2e6f0 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 umber Of SQL Par
2e700 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f ameters.** METHO
2e710 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a D: sqlite3_stmt.
2e720 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 **.** ^This rout
2e730 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ine can be used
2e740 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 to find the numb
2e750 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d er of [SQL param
2e760 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b eters].** in a [
2e770 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2e780 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 nt]. SQL parame
2e790 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 ters are tokens
2e7a0 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 of the.** form "
2e7b0 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 ?", "?NNN", ":AA
2e7c0 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 A", "$AAA", or "
2e7d0 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 @AAA" that serve
2e7e0 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 as.** placehold
2e7f0 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 ers for values t
2e800 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 hat are [sqlite3
2e810 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 _bind_blob | bou
2e820 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 nd].** to the pa
2e830 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 rameters at a la
2e840 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 ter time..**.**
2e850 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 ^(This routine a
2e860 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 ctually returns
2e870 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 the index of the
2e880 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d largest (rightm
2e890 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 ost).** paramete
2e8a0 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 r. For all forms
2e8b0 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 except ?NNN, th
2e8c0 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f is will correspo
2e8d0 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d nd to the.** num
2e8e0 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 ber of unique pa
2e8f0 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 rameters. If pa
2e900 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 rameters of the
2e910 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 ?NNN form are us
2e920 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 ed,.** there may
2e930 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 be gaps in the
2e940 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 list.)^.**.** Se
2e950 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
2e960 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 _bind_blob|sqlit
2e970 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b e3_bind()],.** [
2e980 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
2e990 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 ameter_name()],
2e9a0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
2e9b0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 bind_parameter_i
2e9c0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 ndex()]..*/.int
2e9d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
2e9e0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c ameter_count(sql
2e9f0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a ite3_stmt*);../*
2ea00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 .** CAPI3REF: Na
2ea10 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 me Of A Host Par
2ea20 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 ameter.** METHOD
2ea30 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a : sqlite3_stmt.*
2ea40 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
2ea50 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
2ea60 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 _name(P,N) inter
2ea70 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 face returns.**
2ea80 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
2ea90 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 N-th [SQL parame
2eaa0 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 ter] in the [pre
2eab0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2eac0 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 P..** ^(SQL par
2ead0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 ameters of the f
2eae0 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a orm "?NNN" or ":
2eaf0 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f AAA" or "@AAA" o
2eb00 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 r "$AAA".** have
2eb10 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 a name which is
2eb20 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e the string "?NN
2eb30 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 N" or ":AAA" or
2eb40 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 "@AAA" or "$AAA"
2eb50 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 .** respectively
2eb60 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f ..** In other wo
2eb70 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c rds, the initial
2eb80 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 ":" or "$" or "
2eb90 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 @" or "?".** is
2eba0 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 included as part
2ebb0 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a of the name.)^.
2ebc0 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f ** ^Parameters o
2ebd0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 f the form "?" w
2ebe0 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 ithout a followi
2ebf0 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 ng integer have
2ec00 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 no name.** and a
2ec10 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 re referred to a
2ec20 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 s "nameless" or
2ec30 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d "anonymous param
2ec40 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 eters"..**.** ^T
2ec50 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 he first host pa
2ec60 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 rameter has an i
2ec70 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 ndex of 1, not 0
2ec80 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
2ec90 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f value N is out o
2eca0 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 f range or if th
2ecb0 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 e N-th parameter
2ecc0 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c is.** nameless,
2ecd0 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 then NULL is re
2ece0 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 turned. ^The re
2ecf0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 turned string is
2ed00 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 .** always in UT
2ed10 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 F-8 encoding eve
2ed20 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 n if the named p
2ed30 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 arameter was.**
2ed40 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 originally speci
2ed50 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 fied as UTF-16 i
2ed60 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 n [sqlite3_prepa
2ed70 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 re16()] or.** [s
2ed80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
2ed90 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 _v2()]..**.** Se
2eda0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
2edb0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 _bind_blob|sqlit
2edc0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b e3_bind()],.** [
2edd0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
2ede0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c ameter_count()],
2edf0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
2ee00 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
2ee10 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e index()]..*/.con
2ee20 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
2ee30 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
2ee40 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d name(sqlite3_stm
2ee50 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a t*, int);../*.**
2ee60 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 CAPI3REF: Index
2ee70 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 Of A Parameter
2ee80 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d With A Given Nam
2ee90 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c e.** METHOD: sql
2eea0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
2eeb0 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 ^Return the inde
2eec0 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 x of an SQL para
2eed0 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 meter given its
2eee0 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 name. ^The.** i
2eef0 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 ndex value retur
2ef00 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 ned is suitable
2ef10 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 for use as the s
2ef20 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 econd.** paramet
2ef30 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 er to [sqlite3_b
2ef40 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 ind_blob|sqlite3
2ef50 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 _bind()]. ^A ze
2ef60 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 ro.** is returne
2ef70 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 d if no matching
2ef80 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f parameter is fo
2ef90 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d und. ^The param
2efa0 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 eter.** name mus
2efb0 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 t be given in UT
2efc0 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 F-8 even if the
2efd0 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 original stateme
2efe0 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 nt.** was prepar
2eff0 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 ed from UTF-16 t
2f000 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ext using [sqlit
2f010 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
2f020 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c )]..**.** See al
2f030 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e so: [sqlite3_bin
2f040 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 d_blob|sqlite3_b
2f050 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 ind()],.** [sqli
2f060 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
2f070 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 er_count()], and
2f080 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
2f090 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
2f0a0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ()]..*/.int sqli
2f0b0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
2f0c0 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 er_index(sqlite3
2f0d0 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 _stmt*, const ch
2f0e0 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a ar *zName);../*.
2f0f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 ** CAPI3REF: Res
2f100 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 et All Bindings
2f110 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 On A Prepared St
2f120 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f atement.** METHO
2f130 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a D: sqlite3_stmt.
2f140 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 **.** ^Contrary
2f150 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e to the intuition
2f160 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 of many, [sqlit
2f170 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 e3_reset()] does
2f180 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 not reset.** th
2f190 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f e [sqlite3_bind_
2f1a0 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d blob | bindings]
2f1b0 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 on a [prepared
2f1c0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e statement]..** ^
2f1d0 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 Use this routine
2f1e0 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f to reset all ho
2f1f0 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f st parameters to
2f200 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 NULL..*/.int sq
2f210 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 lite3_clear_bind
2f220 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d ings(sqlite3_stm
2f230 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
2f240 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 3REF: Number Of
2f250 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 Columns In A Res
2f260 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f ult Set.** METHO
2f270 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a D: sqlite3_stmt.
2f280 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 **.** ^Return th
2f290 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 e number of colu
2f2a0 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c mns in the resul
2f2b0 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 t set returned b
2f2c0 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 y the.** [prepar
2f2d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e ed statement]. ^
2f2e0 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 If this routine
2f2f0 72 65 74 75 72 6e 73 20 30 2c 20 74 68 61 74 20 returns 0, that
2f300 6d 65 61 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 70 means the .** [p
2f310 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2f320 74 5d 20 72 65 74 75 72 6e 73 20 6e 6f 20 64 61 t] returns no da
2f330 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 ta (for example
2f340 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a an [UPDATE])..**
2f350 20 5e 48 6f 77 65 76 65 72 2c 20 6a 75 73 74 20 ^However, just
2f360 62 65 63 61 75 73 65 20 74 68 69 73 20 72 6f 75 because this rou
2f370 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 tine returns a p
2f380 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 20 64 ositive number d
2f390 6f 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e 20 oes not.** mean
2f3a0 74 68 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 that one or more
2f3b0 20 72 6f 77 73 20 6f 66 20 64 61 74 61 20 77 69 rows of data wi
2f3c0 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 ll be returned.
2f3d0 20 5e 41 20 53 45 4c 45 43 54 20 73 74 61 74 65 ^A SELECT state
2f3e0 6d 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 ment.** will alw
2f3f0 61 79 73 20 68 61 76 65 20 61 20 70 6f 73 69 74 ays have a posit
2f400 69 76 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ive sqlite3_colu
2f410 6d 6e 5f 63 6f 75 6e 74 28 29 20 62 75 74 20 64 mn_count() but d
2f420 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 0a epending on the.
2f430 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 ** WHERE clause
2f440 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 constraints and
2f450 74 68 65 20 74 61 62 6c 65 20 63 6f 6e 74 65 6e the table conten
2f460 74 2c 20 69 74 20 6d 69 67 68 74 20 72 65 74 75 t, it might retu
2f470 72 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a 2a rn no rows..**.*
2f480 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
2f490 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 ite3_data_count(
2f4a0 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 )].*/.int sqlite
2f4b0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 3_column_count(s
2f4c0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
2f4d0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
2f4e0 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 3REF: Column Nam
2f4f0 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 es In A Result S
2f500 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 et.** METHOD: sq
2f510 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a lite3_stmt.**.**
2f520 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 ^These routines
2f530 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 return the name
2f540 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 assigned to a p
2f550 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e articular column
2f560 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c .** in the resul
2f570 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 t set of a [SELE
2f580 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 CT] statement.
2f590 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c ^The sqlite3_col
2f5a0 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e umn_name().** in
2f5b0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
2f5c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a a pointer to a z
2f5d0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 ero-terminated U
2f5e0 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 TF-8 string.** a
2f5f0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
2f600 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 n_name16() retur
2f610 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
2f620 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
2f630 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 d.** UTF-16 stri
2f640 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 ng. ^The first
2f650 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
2f660 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2f670 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d ment].** that im
2f680 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 plements the [SE
2f690 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e LECT] statement.
2f6a0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 ^The second par
2f6b0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a ameter is the.**
2f6c0 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 column number.
2f6d0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 ^The leftmost c
2f6e0 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 olumn is number
2f6f0 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 0..**.** ^The re
2f700 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f turned string po
2f710 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 inter is valid u
2f720 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 ntil either the
2f730 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2f740 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 ent].** is destr
2f750 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 oyed by [sqlite3
2f760 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 _finalize()] or
2f770 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d until the statem
2f780 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 ent is automatic
2f790 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 ally.** reprepar
2f7a0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 ed by the first
2f7b0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
2f7c0 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 _step()] for a p
2f7d0 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a articular run.**
2f7e0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 or until the ne
2f7f0 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 xt call to.** sq
2f800 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
2f810 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 e() or sqlite3_c
2f820 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f olumn_name16() o
2f830 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d n the same colum
2f840 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c n..**.** ^If sql
2f850 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 ite3_malloc() fa
2f860 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 ils during the p
2f870 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 rocessing of eit
2f880 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 her routine.** (
2f890 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 for example duri
2f8a0 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 ng a conversion
2f8b0 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 from UTF-8 to UT
2f8c0 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 F-16) then a.**
2f8d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 NULL pointer is
2f8e0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
2f8f0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 ^The name of a r
2f900 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 esult column is
2f910 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 the value of the
2f920 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 "AS" clause for
2f930 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c .** that column,
2f940 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 if there is an
2f950 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 AS clause. If t
2f960 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c here is no AS cl
2f970 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ause.** then the
2f980 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c name of the col
2f990 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 umn is unspecifi
2f9a0 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 ed and may chang
2f9b0 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 e from.** one re
2f9c0 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 lease of SQLite
2f9d0 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a to the next..*/.
2f9e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 const char *sqli
2f9f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 te3_column_name(
2fa00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2fa10 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 nt N);.const voi
2fa20 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
2fa30 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 n_name16(sqlite3
2fa40 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a _stmt*, int N);.
2fa50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2fa60 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 Source Of Data
2fa70 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c In A Query Resul
2fa80 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c t.** METHOD: sql
2fa90 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
2faa0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
2fab0 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 provide a means
2fac0 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 to determine the
2fad0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 database, table
2fae0 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 , and.** table c
2faf0 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 olumn that is th
2fb00 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 e origin of a pa
2fb10 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 rticular result
2fb20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 column in.** [SE
2fb30 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e LECT] statement.
2fb40 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 .** ^The name of
2fb50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 the database or
2fb60 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e table or column
2fb70 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 can be returned
2fb80 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 as.** either a
2fb90 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 UTF-8 or UTF-16
2fba0 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 string. ^The _d
2fbb0 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 atabase_ routine
2fbc0 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 s return.** the
2fbd0 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 database name, t
2fbe0 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 he _table_ routi
2fbf0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 nes return the t
2fc00 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a able name, and.*
2fc10 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f * the origin_ ro
2fc20 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 utines return th
2fc30 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a e column name..*
2fc40 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 * ^The returned
2fc50 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 string is valid
2fc60 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 until the [prepa
2fc70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 red statement] i
2fc80 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 s destroyed.** u
2fc90 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 sing [sqlite3_fi
2fca0 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 nalize()] or unt
2fcb0 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 il the statement
2fcc0 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c is automaticall
2fcd0 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 y.** reprepared
2fce0 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c by the first cal
2fcf0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 l to [sqlite3_st
2fd00 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 ep()] for a part
2fd10 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 icular run.** or
2fd20 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 until the same
2fd30 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 information is r
2fd40 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 equested.** agai
2fd50 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 n in a different
2fd60 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a encoding..**.**
2fd70 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 ^The names retu
2fd80 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 rned are the ori
2fd90 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 ginal un-aliased
2fda0 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a names of the.**
2fdb0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 database, table
2fdc0 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a , and column..**
2fdd0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 .** ^The first a
2fde0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 rgument to these
2fdf0 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 interfaces is a
2fe00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2fe10 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 ment]..** ^These
2fe20 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 functions retur
2fe30 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 n information ab
2fe40 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 out the Nth resu
2fe50 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e lt column return
2fe60 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 ed by.** the sta
2fe70 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 tement, where N
2fe80 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 is the second fu
2fe90 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e nction argument.
2fea0 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f .** ^The left-mo
2feb0 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c st column is col
2fec0 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 umn 0 for these
2fed0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 routines..**.**
2fee0 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 ^If the Nth colu
2fef0 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 mn returned by t
2ff00 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 he statement is
2ff10 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 an expression or
2ff20 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 .** subquery and
2ff30 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e is not a column
2ff40 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c value, then all
2ff50 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 of these functi
2ff60 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 ons return.** NU
2ff70 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 LL. ^These rout
2ff80 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 ine might also r
2ff90 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 eturn NULL if a
2ffa0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
2ffb0 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 n error.** occur
2ffc0 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 s. ^Otherwise,
2ffd0 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 they return the
2ffe0 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 name of the atta
2fff0 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 ched database, t
30000 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 able,.** or colu
30010 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 mn that query re
30020 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 sult column was
30030 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a extracted from..
30040 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 **.** ^As with a
30050 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 ll other SQLite
30060 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 APIs, those whos
30070 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 e names end with
30080 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 "16" return.**
30090 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 UTF-16 encoded s
300a0 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f trings and the o
300b0 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 ther functions r
300c0 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a eturn UTF-8..**.
300d0 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 ** ^These APIs a
300e0 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c re only availabl
300f0 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 e if the library
30100 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 was compiled wi
30110 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 th the.** [SQLIT
30120 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f E_ENABLE_COLUMN_
30130 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 METADATA] C-prep
30140 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e rocessor symbol.
30150 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 .**.** If two or
30160 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 more threads ca
30170 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f ll one or more o
30180 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
30190 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d against the sam
301a0 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 e.** prepared st
301b0 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 atement and colu
301c0 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 mn at the same t
301d0 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 ime then the res
301e0 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 ults are.** unde
301f0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 fined..**.** If
30200 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 two or more thre
30210 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 ads call one or
30220 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 more.** [sqlite3
30230 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 _column_database
30240 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d _name | column m
30250 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 etadata interfac
30260 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 es].** for the s
30270 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 ame [prepared st
30280 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 atement] and res
30290 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 ult column.** at
302a0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 the same time t
302b0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 hen the results
302c0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a are undefined..*
302d0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 /.const char *sq
302e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 lite3_column_dat
302f0 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 abase_name(sqlit
30300 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 e3_stmt*,int);.c
30310 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
30320 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 e3_column_databa
30330 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 se_name16(sqlite
30340 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 3_stmt*,int);.co
30350 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
30360 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 3_column_table_n
30370 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ame(sqlite3_stmt
30380 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f *,int);.const vo
30390 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 id *sqlite3_colu
303a0 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 mn_table_name16(
303b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
303c0 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a t);.const char *
303d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f sqlite3_column_o
303e0 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 rigin_name(sqlit
303f0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 e3_stmt*,int);.c
30400 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
30410 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e e3_column_origin
30420 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f _name16(sqlite3_
30430 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a stmt*,int);../*.
30440 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 ** CAPI3REF: Dec
30450 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f lared Datatype O
30460 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 f A Query Result
30470 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
30480 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e te3_stmt.**.** ^
30490 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d (The first param
304a0 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 eter is a [prepa
304b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a red statement]..
304c0 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 ** If this state
304d0 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 ment is a [SELEC
304e0 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 T] statement and
304f0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
30500 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e of the.** return
30510 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 ed result set of
30520 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 that [SELECT] i
30530 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e s a table column
30540 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 (not an.** expr
30550 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 ession or subque
30560 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 ry) then the dec
30570 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 lared type of th
30580 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d e table.** colum
30590 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e n is returned.)^
305a0 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f ^If the Nth co
305b0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 lumn of the resu
305c0 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 lt set is an.**
305d0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 expression or su
305e0 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e bquery, then a N
305f0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 ULL pointer is r
30600 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 eturned..** ^The
30610 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 returned string
30620 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 is always UTF-8
30630 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 encoded..**.**
30640 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 ^(For example, g
30650 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 iven the databas
30660 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 e schema:.**.**
30670 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 CREATE TABLE t1(
30680 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a c1 VARIANT);.**.
30690 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f ** and the follo
306a0 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 wing statement t
306b0 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a o be compiled:.*
306c0 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b *.** SELECT c1 +
306d0 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 1, c1 FROM t1;.
306e0 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 **.** this routi
306f0 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 ne would return
30700 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 the string "VARI
30710 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 ANT" for the sec
30720 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f ond result.** co
30730 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 lumn (i==1), and
30740 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
30750 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 for the first re
30760 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d sult column (i==
30770 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 0).)^.**.** ^SQL
30780 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 ite uses dynamic
30790 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 run-time typing
307a0 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 . ^So just beca
307b0 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 use a column.**
307c0 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 is declared to c
307d0 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 ontain a particu
307e0 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f lar type does no
307f0 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a t mean that the.
30800 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 ** data stored i
30810 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 n that column is
30820 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 of the declared
30830 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 type. SQLite i
30840 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 s.** strongly ty
30850 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 ped, but the typ
30860 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e ing is dynamic n
30870 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 ot static. ^Typ
30880 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 e.** is associat
30890 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 ed with individu
308a0 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 al values, not w
308b0 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 ith the containe
308c0 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f rs.** used to ho
308d0 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e ld those values.
308e0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a .*/.const char *
308f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
30900 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f ecltype(sqlite3_
30910 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 stmt*,int);.cons
30920 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
30930 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 column_decltype1
30940 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
30950 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 int);../*.** CAP
30960 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 I3REF: Evaluate
30970 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 An SQL Statement
30980 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
30990 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 te3_stmt.**.** A
309a0 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 fter a [prepared
309b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 statement] has
309c0 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 been prepared us
309d0 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 ing either.** [s
309e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
309f0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 2()] or [sqlite3
30a00 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
30a10 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c or one of the l
30a20 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 egacy.** interfa
30a30 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 ces [sqlite3_pre
30a40 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 pare()] or [sqli
30a50 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d te3_prepare16()]
30a60 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a , this function.
30a70 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 ** must be calle
30a80 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 d one or more ti
30a90 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 mes to evaluate
30aa0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a the statement..*
30ab0 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 *.** The details
30ac0 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 of the behavior
30ad0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f of the sqlite3_
30ae0 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 step() interface
30af0 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 depend.** on wh
30b00 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d ether the statem
30b10 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 ent was prepared
30b20 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 using the newer
30b30 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a "v2" interface.
30b40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
30b50 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 are_v2()] and [s
30b60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
30b70 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c _v2()] or the ol
30b80 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e der legacy.** in
30b90 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 terface [sqlite3
30ba0 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 _prepare()] and
30bb0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
30bc0 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 16()]. The use
30bd0 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 of the.** new "v
30be0 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 2" interface is
30bf0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 recommended for
30c00 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 new applications
30c10 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a but the legacy.
30c20 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c ** interface wil
30c30 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 l continue to be
30c40 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a supported..**.*
30c50 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 * ^In the legacy
30c60 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 interface, the
30c70 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c return value wil
30c80 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c l be either [SQL
30c90 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 ITE_BUSY],.** [S
30ca0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 QLITE_DONE], [SQ
30cb0 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 LITE_ROW], [SQLI
30cc0 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 TE_ERROR], or [S
30cd0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a QLITE_MISUSE]..*
30ce0 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 * ^With the "v2"
30cf0 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 interface, any
30d00 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 of the other [re
30d10 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a sult codes] or.*
30d20 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 * [extended resu
30d30 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 lt codes] might
30d40 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 be returned as w
30d50 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c ell..**.** ^[SQL
30d60 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 ITE_BUSY] means
30d70 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 that the databas
30d80 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 e engine was una
30d90 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 ble to acquire t
30da0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c he.** database l
30db0 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f ocks it needs to
30dc0 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 do its job. ^I
30dd0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 f the statement
30de0 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a is a [COMMIT].**
30df0 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 or occurs outsi
30e00 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 de of an explici
30e10 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 t transaction, t
30e20 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 hen you can retr
30e30 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 y the.** stateme
30e40 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 nt. If the stat
30e50 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b ement is not a [
30e60 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 COMMIT] and occu
30e70 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 rs within an.**
30e80 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 explicit transac
30e90 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 tion then you sh
30ea0 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 ould rollback th
30eb0 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 e transaction be
30ec0 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 fore.** continui
30ed0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 ng..**.** ^[SQLI
30ee0 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 TE_DONE] means t
30ef0 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e hat the statemen
30f00 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 t has finished e
30f10 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 xecuting.** succ
30f20 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 essfully. sqlit
30f30 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 e3_step() should
30f40 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 not be called a
30f50 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 gain on this vir
30f60 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 tual.** machine
30f70 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 without first ca
30f80 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 lling [sqlite3_r
30f90 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 eset()] to reset
30fa0 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 the virtual.**
30fb0 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 machine back to
30fc0 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 its initial stat
30fd0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 e..**.** ^If the
30fe0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 SQL statement b
30ff0 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 eing executed re
31000 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 turns any data,
31010 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 then [SQLITE_ROW
31020 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 ].** is returned
31030 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 each time a new
31040 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 row of data is
31050 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 ready for proces
31060 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 sing by the.** c
31070 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 aller. The value
31080 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 s may be accesse
31090 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c d using the [col
310a0 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 umn access funct
310b0 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 ions]..** sqlite
310c0 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 3_step() is call
310d0 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 ed again to retr
310e0 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f ieve the next ro
310f0 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a w of data..**.**
31100 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d ^[SQLITE_ERROR]
31110 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 means that a ru
31120 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 n-time error (su
31130 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 ch as a constrai
31140 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 nt.** violation)
31150 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 has occurred.
31160 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 sqlite3_step() s
31170 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c hould not be cal
31180 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 led again on.**
31190 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 the VM. More inf
311a0 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 ormation may be
311b0 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 found by calling
311c0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
311d0 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 ()]..** ^With th
311e0 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 e legacy interfa
311f0 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 ce, a more speci
31200 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 fic error code (
31210 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 for example,.**
31220 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 [SQLITE_INTERRUP
31230 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 T], [SQLITE_SCHE
31240 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 MA], [SQLITE_COR
31250 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f RUPT], and so fo
31260 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f rth).** can be o
31270 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 btained by calli
31280 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ng [sqlite3_rese
31290 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b t()] on the.** [
312a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
312b0 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 nt]. ^In the "v
312c0 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 2" interface,.**
312d0 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 the more specif
312e0 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 ic error code is
312f0 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 returned direct
31300 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 ly by sqlite3_st
31310 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c ep()..**.** [SQL
31320 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e ITE_MISUSE] mean
31330 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 s that the this
31340 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c routine was call
31350 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 ed inappropriate
31360 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 ly..** Perhaps i
31370 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 t was called on
31380 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
31390 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a ement] that has.
313a0 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 ** already been
313b0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
313c0 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f e | finalized] o
313d0 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 r on one that ha
313e0 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 d.** previously
313f0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 returned [SQLITE
31400 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 _ERROR] or [SQLI
31410 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 TE_DONE]. Or it
31420 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 could.** be the
31430 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 case that the s
31440 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e ame database con
31450 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 nection is being
31460 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a used by two or.
31470 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 ** more threads
31480 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 at the same mome
31490 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a nt in time..**.*
314a0 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f * For all versio
314b0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 ns of SQLite up
314c0 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 to and including
314d0 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 3.6.23.1, a cal
314e0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 l to.** [sqlite3
314f0 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 _reset()] was re
31500 71 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c quired after sql
31510 69 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 ite3_step() retu
31520 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a rned anything.**
31530 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c other than [SQL
31540 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 ITE_ROW] before
31550 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 any subsequent i
31560 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 nvocation of.**
31570 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 sqlite3_step().
31580 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 Failure to rese
31590 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 t the prepared s
315a0 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a tatement using .
315b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ** [sqlite3_rese
315c0 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c t()] would resul
315d0 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f t in an [SQLITE_
315e0 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 MISUSE] return f
315f0 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 rom.** sqlite3_s
31600 74 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 tep(). But afte
31610 72 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 r [version 3.6.2
31620 33 2e 31 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 3.1] ([dateof:3.
31630 36 2e 32 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c 69 6.23.1],.** sqli
31640 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e te3_step() began
31650 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c .** calling [sql
31660 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 ite3_reset()] au
31670 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 tomatically in t
31680 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 his circumstance
31690 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 rather.** than
316a0 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 returning [SQLIT
316b0 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 E_MISUSE]. This
316c0 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 is not consider
316d0 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 ed a compatibili
316e0 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 ty.** break beca
316f0 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 use any applicat
31700 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 ion that ever re
31710 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 ceives an SQLITE
31720 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a _MISUSE error.**
31730 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 is broken by de
31740 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b finition. The [
31750 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f SQLITE_OMIT_AUTO
31760 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 RESET] compile-t
31770 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 ime option.** ca
31780 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 n be used to res
31790 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 tore the legacy
317a0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 behavior..**.**
317b0 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 <b>Goofy Interfa
317c0 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e ce Alert:</b> In
317d0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 the legacy inte
317e0 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 rface, the sqlit
317f0 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 e3_step().** API
31800 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 always returns
31810 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 a generic error
31820 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 code, [SQLITE_ER
31830 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 ROR], following
31840 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 any.** error oth
31850 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
31860 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 BUSY] and [SQLIT
31870 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 E_MISUSE]. You
31880 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 must call.** [sq
31890 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f lite3_reset()] o
318a0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c r [sqlite3_final
318b0 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 ize()] in order
318c0 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 to find one of t
318d0 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b he.** specific [
318e0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 error codes] tha
318f0 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 t better describ
31900 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a es the error..**
31910 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 We admit that t
31920 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 his is a goofy d
31930 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 esign. The prob
31940 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 lem has been fix
31950 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 ed.** with the "
31960 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 v2" interface.
31970 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 If you prepare a
31980 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 ll of your SQL s
31990 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 tatements.** usi
319a0 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 ng either [sqlit
319b0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
319c0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 or [sqlite3_pre
319d0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 pare16_v2()] ins
319e0 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c tead.** of the l
319f0 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 egacy [sqlite3_p
31a00 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 repare()] and [s
31a10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
31a20 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a ()] interfaces,.
31a30 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 ** then the more
31a40 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 specific [error
31a50 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 codes] are retu
31a60 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a rned directly.**
31a70 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 by sqlite3_step
31a80 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 (). The use of
31a90 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
31aa0 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 ce is recommende
31ab0 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 d..*/.int sqlite
31ac0 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 3_step(sqlite3_s
31ad0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 tmt*);../*.** CA
31ae0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f PI3REF: Number o
31af0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 f columns in a r
31b00 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 esult set.** MET
31b10 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d HOD: sqlite3_stm
31b20 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c t.**.** ^The sql
31b30 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 ite3_data_count(
31b40 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 P) interface ret
31b50 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
31b60 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 of columns in th
31b70 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 e.** current row
31b80 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 of the result s
31b90 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 et of [prepared
31ba0 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a statement] P..**
31bb0 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74 ^If prepared st
31bc0 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e atement P does n
31bd0 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 ot have results
31be0 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a ready to return.
31bf0 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f ** (via calls to
31c00 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f the [sqlite3_co
31c10 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 lumn_int | sqlit
31c20 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f e3_column_*()] o
31c30 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 f.** interfaces)
31c40 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 then sqlite3_da
31c50 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 ta_count(P) retu
31c60 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 rns 0..** ^The s
31c70 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
31c80 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 t(P) routine als
31c90 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 o returns 0 if P
31ca0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
31cb0 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 er..** ^The sqli
31cc0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 te3_data_count(P
31cd0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ) routine return
31ce0 73 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69 s 0 if the previ
31cf0 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b ous call to.** [
31d00 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 sqlite3_step](P)
31d10 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 returned [SQLIT
31d20 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 E_DONE]. ^The s
31d30 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
31d40 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 t(P).** will ret
31d50 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 urn non-zero if
31d60 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f previous call to
31d70 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 [sqlite3_step](
31d80 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b P) returned.** [
31d90 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 SQLITE_ROW], exc
31da0 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 ept in the case
31db0 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 of the [PRAGMA i
31dc0 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 ncremental_vacuu
31dd0 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 m].** where it a
31de0 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 lways returns ze
31df0 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 ro since each st
31e00 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 ep of that multi
31e10 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 -step.** pragma
31e20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e returns 0 column
31e30 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a s of data..**.**
31e40 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
31e50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 te3_column_count
31e60 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ()].*/.int sqlit
31e70 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 e3_data_count(sq
31e80 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d lite3_stmt *pStm
31e90 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
31ea0 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c REF: Fundamental
31eb0 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 Datatypes.** KE
31ec0 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 YWORDS: SQLITE_T
31ed0 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 EXT.**.** ^(Ever
31ee0 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 y value in SQLit
31ef0 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 e has one of fiv
31f00 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 e fundamental da
31f10 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c tatypes:.**.** <
31f20 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 ul>.** <li> 64-b
31f30 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 it signed intege
31f40 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 r.** <li> 64-bit
31f50 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 IEEE floating p
31f60 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c oint number.** <
31f70 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c li> string.** <l
31f80 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 i> BLOB.** <li>
31f90 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a NULL.** </ul>)^.
31fa0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
31fb0 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 tants are codes
31fc0 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 for each of thos
31fd0 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e e types..**.** N
31fe0 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c ote that the SQL
31ff0 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e ITE_TEXT constan
32000 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 t was also used
32010 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f in SQLite versio
32020 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d n 2.** for a com
32030 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e pletely differen
32040 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 t meaning. Soft
32050 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 ware that links
32060 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 against both.**
32070 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 SQLite version 2
32080 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 and SQLite vers
32090 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 ion 3 should use
320a0 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e SQLITE3_TEXT, n
320b0 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 ot.** SQLITE_TEX
320c0 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 T..*/.#define SQ
320d0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a LITE_INTEGER 1.
320e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
320f0 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e LOAT 2.#defin
32100 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 e SQLITE_BLOB
32110 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 4.#define SQLI
32120 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 TE_NULL 5.#i
32130 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 fdef SQLITE_TEXT
32140 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f .# undef SQLITE_
32150 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 TEXT.#else.# def
32160 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 ine SQLITE_TEXT
32170 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 3.#endif.#de
32180 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 fine SQLITE3_TEX
32190 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 T 3../*.** C
321a0 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 API3REF: Result
321b0 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 Values From A Qu
321c0 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ery.** KEYWORDS:
321d0 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 {column access
321e0 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 functions}.** ME
321f0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 THOD: sqlite3_st
32200 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 mt.**.** ^These
32210 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
32220 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 information abou
32230 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d t a single colum
32240 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 n of the current
32250 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f .** result row o
32260 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 f a query. ^In
32270 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 every case the f
32280 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 irst argument is
32290 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f a pointer.** to
322a0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
322b0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 tatement] that i
322c0 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 s being evaluate
322d0 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f d (the [sqlite3_
322e0 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 stmt*].** that w
322f0 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d as returned from
32300 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
32310 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f e_v2()] or one o
32320 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a f its variants).
32330 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e ** and the secon
32340 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
32350 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 e index of the c
32360 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 olumn for which
32370 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 information.** s
32380 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 hould be returne
32390 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 d. ^The leftmost
323a0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 column of the r
323b0 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 esult set has th
323c0 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 e index 0..** ^T
323d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c he number of col
323e0 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 umns in the resu
323f0 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d lt can be determ
32400 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 ined using.** [s
32410 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f qlite3_column_co
32420 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 unt()]..**.** If
32430 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
32440 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 nt does not curr
32450 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 ently point to a
32460 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 valid row, or i
32470 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 f the.** column
32480 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 index is out of
32490 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c range, the resul
324a0 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a t is undefined..
324b0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
324c0 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 s may only be ca
324d0 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f lled when the mo
324e0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 st recent call t
324f0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 o.** [sqlite3_st
32500 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e ep()] has return
32510 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 ed [SQLITE_ROW]
32520 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b and neither.** [
32530 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
32540 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 nor [sqlite3_fi
32550 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 nalize()] have b
32560 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 een called subse
32570 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 quently..** If a
32580 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ny of these rout
32590 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 ines are called
325a0 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 after [sqlite3_r
325b0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 eset()] or.** [s
325c0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
325d0 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c )] or after [sql
325e0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 ite3_step()] has
325f0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d returned.** som
32600 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 ething other tha
32610 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 n [SQLITE_ROW],
32620 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 the results are
32630 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 undefined..** If
32640 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
32650 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ] or [sqlite3_re
32660 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 set()] or [sqlit
32670 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a e3_finalize()].*
32680 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f * are called fro
32690 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 m a different th
326a0 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f read while any o
326b0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
326c0 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c .** are pending,
326d0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 then the result
326e0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e s are undefined.
326f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
32700 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
32710 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ) routine return
32720 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 s the.** [SQLITE
32730 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 _INTEGER | datat
32740 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 ype code] for th
32750 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 e initial data t
32760 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 ype.** of the re
32770 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 sult column. ^T
32780 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 he returned valu
32790 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c e is one of [SQL
327a0 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a ITE_INTEGER],.**
327b0 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c [SQLITE_FLOAT],
327c0 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 [SQLITE_TEXT],
327d0 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f [SQLITE_BLOB], o
327e0 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e r [SQLITE_NULL].
327f0 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 The value.** r
32800 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
32810 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 e3_column_type()
32820 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 is only meaning
32830 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a ful if no type.*
32840 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 * conversions ha
32850 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 ve occurred as d
32860 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 escribed below.
32870 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f After a type co
32880 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 nversion,.** the
32890 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
328a0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d by sqlite3_colum
328b0 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 n_type() is unde
328c0 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a fined. Future.*
328d0 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 * versions of SQ
328e0 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 Lite may change
328f0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 the behavior of
32900 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
32910 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 ype().** followi
32920 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 ng a type conver
32930 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 sion..**.** ^If
32940 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 the result is a
32950 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 BLOB or UTF-8 st
32960 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 ring then the sq
32970 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
32980 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 es().** routine
32990 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
329a0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
329b0 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 hat BLOB or stri
329c0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 ng..** ^If the r
329d0 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 esult is a UTF-1
329e0 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 6 string, then s
329f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
32a00 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a tes() converts.*
32a10 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 * the string to
32a20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 UTF-8 and then r
32a30 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
32a40 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e r of bytes..** ^
32a50 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 If the result is
32a60 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 a numeric value
32a70 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f then sqlite3_co
32a80 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 lumn_bytes() use
32a90 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e s.** [sqlite3_sn
32aa0 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e printf()] to con
32ab0 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 vert that value
32ac0 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e to a UTF-8 strin
32ad0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a g and returns.**
32ae0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
32af0 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 ytes in that str
32b00 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ing..** ^If the
32b10 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 result is NULL,
32b20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
32b30 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 umn_bytes() retu
32b40 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 rns zero..**.**
32b50 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
32b60 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d s a BLOB or UTF-
32b70 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 16 string then t
32b80 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d he sqlite3_colum
32b90 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 n_bytes16().** r
32ba0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 outine returns t
32bb0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
32bc0 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 es in that BLOB
32bd0 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 or string..** ^I
32be0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
32bf0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 a UTF-8 string,
32c00 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
32c10 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f umn_bytes16() co
32c20 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 nverts.** the st
32c30 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 ring to UTF-16 a
32c40 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 nd then returns
32c50 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
32c60 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 tes..** ^If the
32c70 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 result is a nume
32c80 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 ric value then s
32c90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
32ca0 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 tes16() uses.**
32cb0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 [sqlite3_snprint
32cc0 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 f()] to convert
32cd0 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 that value to a
32ce0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e UTF-16 string an
32cf0 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 d returns.** the
32d00 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
32d10 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e in that string.
32d20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
32d30 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e lt is NULL, then
32d40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
32d50 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e bytes16() return
32d60 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 s zero..**.** ^T
32d70 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e he values return
32d80 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 ed by [sqlite3_c
32d90 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 olumn_bytes()] a
32da0 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f nd .** [sqlite3_
32db0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
32dc0 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 ] do not include
32dd0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e the zero termin
32de0 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 ators at the end
32df0 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e .** of the strin
32e00 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 g. ^For clarity
32e10 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 : the values ret
32e20 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c urned by.** [sql
32e30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
32e40 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 s()] and [sqlite
32e50 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
32e60 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 ()] are the numb
32e70 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 er of.** bytes i
32e80 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f n the string, no
32e90 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 t the number of
32ea0 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a characters..**.*
32eb0 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 * ^Strings retur
32ec0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 ned by sqlite3_c
32ed0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 olumn_text() and
32ee0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
32ef0 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 text16(),.** eve
32f00 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c n empty strings,
32f10 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f are always zero
32f20 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 -terminated. ^T
32f30 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c he return.** val
32f40 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ue from sqlite3_
32f50 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f column_blob() fo
32f60 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 r a zero-length
32f70 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 BLOB is a NULL p
32f80 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 ointer..**.** <b
32f90 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 >Warning:</b> ^T
32fa0 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e he object return
32fb0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 ed by [sqlite3_c
32fc0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 olumn_value()] i
32fd0 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 s an.** [unprote
32fe0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
32ff0 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 ue] object. In
33000 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 a multithreaded
33010 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 environment,.**
33020 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 an unprotected s
33030 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
33040 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 ect may only be
33050 75 73 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 used safely with
33060 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
33070 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b d_value()] and [
33080 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
33090 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 alue()]..** If t
330a0 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 he [unprotected
330b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
330c0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 bject returned b
330d0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f y.** [sqlite3_co
330e0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 lumn_value()] is
330f0 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 used in any oth
33100 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e er way, includin
33110 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f g calls.** to ro
33120 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c utines like [sql
33130 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 ite3_value_int()
33140 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ], [sqlite3_valu
33150 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 e_text()],.** or
33160 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
33170 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 bytes()], the be
33180 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 havior is not th
33190 72 65 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 readsafe..**.**
331a0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
331b0 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 ttempt to conver
331c0 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 t the value wher
331d0 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 e appropriate.
331e0 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c ^For.** example,
331f0 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c if the internal
33200 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 representation
33210 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 is FLOAT and a t
33220 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 ext result.** is
33230 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c requested, [sql
33240 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d ite3_snprintf()]
33250 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 is used interna
33260 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 lly to perform t
33270 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e he.** conversion
33280 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 automatically.
33290 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 ^(The following
332a0 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 table details t
332b0 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a he conversions.*
332c0 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 * that are appli
332d0 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b ed:.**.** <block
332e0 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 quote>.** <table
332f0 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 border="1">.**
33300 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 <tr><th> Interna
33310 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 l<br>Type <th> R
33320 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 equested<br>Type
33330 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f <th> Conversio
33340 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e n.**.** <tr><td>
33350 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 NULL <td> I
33360 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 NTEGER <td> Re
33370 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 sult is 0.** <tr
33380 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c ><td> NULL <
33390 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 td> FLOAT <t
333a0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 d> Result is 0.0
333b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 .** <tr><td> NU
333c0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 LL <td> TEX
333d0 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 T <td> Result
333e0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
333f0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 er.** <tr><td>
33400 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 NULL <td> B
33410 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 LOB <td> Resu
33420 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 lt is a NULL poi
33430 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e nter.** <tr><td>
33440 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 INTEGER <td>
33450 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f FLOAT <td> Co
33460 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 nvert from integ
33470 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c er to float.** <
33480 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 tr><td> INTEGER
33490 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 <td> TEXT
334a0 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 <td> ASCII rende
334b0 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 ring of the inte
334c0 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 ger.** <tr><td>
334d0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 INTEGER <td>
334e0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d BLOB <td> Sam
334f0 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 e as INTEGER->TE
33500 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 XT.** <tr><td>
33510 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 FLOAT <td> INT
33520 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 EGER <td> [CAS
33530 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a T] to INTEGER.**
33540 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 <tr><td> FLOAT
33550 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 <td> TEXT
33560 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e <td> ASCII ren
33570 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c dering of the fl
33580 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 oat.** <tr><td>
33590 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 FLOAT <td>
335a0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 BLOB <td> [CA
335b0 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c ST] to BLOB.** <
335c0 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 tr><td> TEXT
335d0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 <td> INTEGER
335e0 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 <td> [CAST] to I
335f0 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 NTEGER.** <tr><t
33600 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e d> TEXT <td>
33610 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 FLOAT <td>
33620 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a [CAST] to REAL.*
33630 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 * <tr><td> TEXT
33640 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 <td> BLOB
33650 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 <td> No chang
33660 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 e.** <tr><td> B
33670 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 LOB <td> INTE
33680 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 GER <td> [CAST
33690 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 ] to INTEGER.**
336a0 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 <tr><td> BLOB
336b0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 <td> FLOAT
336c0 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 <td> [CAST] to
336d0 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e REAL.** <tr><td>
336e0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 BLOB <td>
336f0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 TEXT <td> Ad
33700 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 d a zero termina
33710 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a tor if needed.**
33720 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 </table>.** </b
33730 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a lockquote>)^.**.
33740 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 ** Note that whe
33750 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f n type conversio
33760 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 ns occur, pointe
33770 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 rs returned by p
33780 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f rior.** calls to
33790 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
337a0 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f blob(), sqlite3_
337b0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 column_text(), a
337c0 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 nd/or.** sqlite3
337d0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
337e0 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 may be invalida
337f0 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e ted..** Type con
33800 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 versions and poi
33810 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f nter invalidatio
33820 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a ns might occur.*
33830 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 * in the followi
33840 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 ng cases:.**.**
33850 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 <ul>.** <li> The
33860 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 initial content
33870 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 is a BLOB and s
33880 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
33890 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 xt() or.**
338a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
338b0 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 ext16() is calle
338c0 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 d. A zero-termi
338d0 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 nator might.**
338e0 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 need to be a
338f0 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 dded to the stri
33900 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e ng.</li>.** <li>
33910 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e The initial con
33920 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 tent is UTF-8 te
33930 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 xt and sqlite3_c
33940 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 olumn_bytes16()
33950 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 or.** sqlit
33960 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
33970 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 () is called. T
33980 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 he content must
33990 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 be converted.**
339a0 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c to UTF-16.<
339b0 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 /li>.** <li> The
339c0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 initial content
339d0 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 is UTF-16 text
339e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 and sqlite3_colu
339f0 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a mn_bytes() or.**
33a00 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f sqlite3_co
33a10 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 lumn_text() is c
33a20 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 alled. The cont
33a30 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 ent must be conv
33a40 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f erted.** to
33a50 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 UTF-8.</li>.**
33a60 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e </ul>.**.** ^Con
33a70 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e versions between
33a80 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 UTF-16be and UT
33a90 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 F-16le are alway
33aa0 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 s done in place
33ab0 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e and do.** not in
33ac0 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 validate a prior
33ad0 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 pointer, though
33ae0 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 of course the c
33af0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 ontent of the bu
33b00 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 ffer.** that the
33b10 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 prior pointer r
33b20 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 eferences will h
33b30 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 ave been modifie
33b40 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a d. Other kinds.
33b50 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e ** of conversion
33b60 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 are done in pla
33b70 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f ce when it is po
33b80 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 ssible, but some
33b90 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 times they.** ar
33ba0 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 e not possible a
33bb0 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 nd in those case
33bc0 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 s prior pointers
33bd0 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 are invalidated
33be0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 ..**.** The safe
33bf0 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 st policy is to
33c00 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 invoke these rou
33c10 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 tines.** in one
33c20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 of the following
33c30 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c ways:.**.** <ul
33c40 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 >.** <li>sqlite
33c50 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 3_column_text()
33c60 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 followed by sqli
33c70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
33c80 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e ()</li>.** <li>
33c90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
33ca0 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 lob() followed b
33cb0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e y sqlite3_column
33cc0 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a _bytes()</li>.**
33cd0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f <li>sqlite3_co
33ce0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f lumn_text16() fo
33cf0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 llowed by sqlite
33d00 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
33d10 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e ()</li>.** </ul>
33d20 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 .**.** In other
33d30 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c words, you shoul
33d40 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 d call sqlite3_c
33d50 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a olumn_text(),.**
33d60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
33d70 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 blob(), or sqlit
33d80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
33d90 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 () first to forc
33da0 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 e the result.**
33db0 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 into the desired
33dc0 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e format, then in
33dd0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c voke sqlite3_col
33de0 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a umn_bytes() or.*
33df0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e * sqlite3_column
33e00 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 _bytes16() to fi
33e10 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 nd the size of t
33e20 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e he result. Do n
33e30 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 ot mix calls.**
33e40 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d to sqlite3_colum
33e50 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 n_text() or sqli
33e60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
33e70 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a ) with calls to.
33e80 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ** sqlite3_colum
33e90 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 n_bytes16(), and
33ea0 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c do not mix call
33eb0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c s to sqlite3_col
33ec0 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 umn_text16().**
33ed0 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 with calls to sq
33ee0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
33ef0 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 es()..**.** ^The
33f00 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e pointers return
33f10 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 ed are valid unt
33f20 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 il a type conver
33f30 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a sion occurs as.*
33f40 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 * described abov
33f50 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c e, or until [sql
33f60 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 ite3_step()] or
33f70 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
33f80 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ] or.** [sqlite3
33f90 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 _finalize()] is
33fa0 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 called. ^The me
33fb0 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 mory space used
33fc0 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a to hold strings.
33fd0 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 ** and BLOBs is
33fe0 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 freed automatica
33ff0 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74 lly. Do <em>not
34000 3c 2f 65 6d 3e 20 70 61 73 73 20 74 68 65 20 70 </em> pass the p
34010 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 ointers returned
34020 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 .** from [sqlite
34030 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 3_column_blob()]
34040 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d , [sqlite3_colum
34050 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 n_text()], etc.
34060 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 into.** [sqlite3
34070 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 _free()]..**.**
34080 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c ^(If a memory al
34090 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f location error o
340a0 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 ccurs during the
340b0 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 evaluation of a
340c0 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 ny.** of these r
340d0 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 outines, a defau
340e0 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 lt value is retu
340f0 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 rned. The defau
34100 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 lt value.** is e
34110 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 ither the intege
34120 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e r 0, the floatin
34130 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 g point number 0
34140 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a .0, or a NULL.**
34150 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 pointer. Subse
34160 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b quent calls to [
34170 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
34180 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a )] will return.*
34190 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d * [SQLITE_NOMEM]
341a0 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 .)^.*/.const voi
341b0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
341c0 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 n_blob(sqlite3_s
341d0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
341e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c .int sqlite3_col
341f0 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 umn_bytes(sqlite
34200 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
34210 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f l);.int sqlite3_
34220 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 column_bytes16(s
34230 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
34240 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 t iCol);.double
34250 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
34260 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 ouble(sqlite3_st
34270 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
34280 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 int sqlite3_colu
34290 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 mn_int(sqlite3_s
342a0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
342b0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 .sqlite3_int64 s
342c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e qlite3_column_in
342d0 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 t64(sqlite3_stmt
342e0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f *, int iCol);.co
342f0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 nst unsigned cha
34300 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d r *sqlite3_colum
34310 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 n_text(sqlite3_s
34320 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
34330 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
34340 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
34350 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
34360 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 , int iCol);.int
34370 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
34380 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d type(sqlite3_stm
34390 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 t*, int iCol);.s
343a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 qlite3_value *sq
343b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c lite3_column_val
343c0 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ue(sqlite3_stmt*
343d0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a , int iCol);../*
343e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
343f0 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 stroy A Prepared
34400 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 Statement Objec
34410 74 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a t.** DESTRUCTOR:
34420 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
34430 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
34440 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 _finalize() func
34450 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 tion is called t
34460 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 o delete a [prep
34470 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
34480 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 .** ^If the most
34490 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 recent evaluati
344a0 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d on of the statem
344b0 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 ent encountered
344c0 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 no errors.** or
344d0 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 if the statement
344e0 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 is never been e
344f0 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 valuated, then s
34500 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
34510 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c ) returns.** SQL
34520 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 ITE_OK. ^If the
34530 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 most recent eva
34540 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 luation of state
34550 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 ment S failed, t
34560 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 hen.** sqlite3_f
34570 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 inalize(S) retur
34580 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 ns the appropria
34590 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 te [error code]
345a0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 or.** [extended
345b0 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a error code]..**.
345c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
345d0 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 finalize(S) rout
345e0 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 ine can be calle
345f0 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 d at any point d
34600 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 uring.** the lif
34610 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 e cycle of [prep
34620 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
34630 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 S:.** before sta
34640 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 tement S is ever
34650 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 evaluated, afte
34660 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 r.** one or more
34670 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
34680 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 e3_reset()], or
34690 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a after any call.*
346a0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 * to [sqlite3_st
346b0 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 ep()] regardless
346c0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e of whether or n
346d0 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 ot the statement
346e0 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 has.** complete
346f0 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a d execution..**.
34700 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c ** ^Invoking sql
34710 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 ite3_finalize()
34720 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 on a NULL pointe
34730 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 r is a harmless
34740 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 no-op..**.** The
34750 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
34760 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 t finalize every
34770 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
34780 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 ment] in order t
34790 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 o avoid.** resou
347a0 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 rce leaks. It i
347b0 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 s a grievous err
347c0 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 or for the appli
347d0 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f cation to try to
347e0 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 use.** a prepar
347f0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 ed statement aft
34800 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 er it has been f
34810 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 inalized. Any u
34820 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 se of a prepared
34830 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 .** statement af
34840 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 ter it has been
34850 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 finalized can re
34860 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 sult in undefine
34870 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 d and.** undesir
34880 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 able behavior su
34890 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 ch as segfaults
348a0 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 and heap corrupt
348b0 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ion..*/.int sqli
348c0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c te3_finalize(sql
348d0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
348e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
348f0 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 EF: Reset A Prep
34900 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f ared Statement O
34910 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a bject.** METHOD:
34920 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
34930 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
34940 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e reset() function
34950 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 is called to re
34960 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 set a [prepared
34970 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 statement].** ob
34980 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 ject back to its
34990 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 initial state,
349a0 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 ready to be re-e
349b0 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 xecuted..** ^Any
349c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 SQL statement v
349d0 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 ariables that ha
349e0 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 d values bound t
349f0 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 o them using.**
34a00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e the [sqlite3_bin
34a10 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 d_blob | sqlite3
34a20 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 _bind_*() API] r
34a30 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 etain their valu
34a40 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 es..** Use [sqli
34a50 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e te3_clear_bindin
34a60 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 gs()] to reset t
34a70 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a he bindings..**.
34a80 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 ** ^The [sqlite3
34a90 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 _reset(S)] inter
34aa0 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 face resets the
34ab0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
34ac0 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 ent] S.** back t
34ad0 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 o the beginning
34ae0 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a of its program..
34af0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f **.** ^If the mo
34b00 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 st recent call t
34b10 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 o [sqlite3_step(
34b20 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b S)] for the.** [
34b30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
34b40 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b nt] S returned [
34b50 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b SQLITE_ROW] or [
34b60 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a SQLITE_DONE],.**
34b70 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f or if [sqlite3_
34b80 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 step(S)] has nev
34b90 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 er before been c
34ba0 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 alled on S,.** t
34bb0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 hen [sqlite3_res
34bc0 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b et(S)] returns [
34bd0 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a SQLITE_OK]..**.*
34be0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 * ^If the most r
34bf0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 ecent call to [s
34c00 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 qlite3_step(S)]
34c10 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 for the.** [prep
34c20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
34c30 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 S indicated an e
34c40 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 rror, then.** [s
34c50 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d qlite3_reset(S)]
34c60 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 returns an appr
34c70 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 opriate [error c
34c80 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ode]..**.** ^The
34c90 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
34ca0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f S)] interface do
34cb0 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 es not change th
34cc0 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 e values.** of a
34cd0 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ny [sqlite3_bind
34ce0 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 _blob|bindings]
34cf0 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 on the [prepared
34d00 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a statement] S..*
34d10 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 /.int sqlite3_re
34d20 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 set(sqlite3_stmt
34d30 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
34d40 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 CAPI3REF: Creat
34d50 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 e Or Redefine SQ
34d60 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b L Functions.** K
34d70 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 EYWORDS: {functi
34d80 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 on creation rout
34d90 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 ines}.** KEYWORD
34da0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d S: {application-
34db0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
34dc0 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 tion}.** KEYWORD
34dd0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d S: {application-
34de0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
34df0 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 tions}.** METHOD
34e00 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
34e10 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 ^These functions
34e20 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b (collectively k
34e30 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f nown as "functio
34e40 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 n creation routi
34e50 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 nes").** are use
34e60 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e d to add SQL fun
34e70 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 ctions or aggreg
34e80 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 ates or to redef
34e90 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 ine the behavior
34ea0 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 .** of existing
34eb0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 SQL functions or
34ec0 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 aggregates. Th
34ed0 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 e only differenc
34ee0 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 es between.** th
34ef0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
34f00 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 the text encodi
34f10 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a ng expected for.
34f20 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 ** the second pa
34f30 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d rameter (the nam
34f40 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f e of the functio
34f50 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 n being created)
34f60 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 .** and the pres
34f70 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 ence or absence
34f80 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 of a destructor
34f90 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 callback for.**
34fa0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
34fb0 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a data pointer..**
34fc0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 .** ^The first p
34fd0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 arameter is the
34fe0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
34ff0 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 tion] to which t
35000 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 he SQL.** functi
35010 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 on is to be adde
35020 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 d. ^If an appli
35030 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 cation uses more
35040 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 than one databa
35050 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e se.** connection
35060 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f then applicatio
35070 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 n-defined SQL fu
35080 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 nctions must be
35090 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 added.** to each
350a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
350b0 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e tion separately.
350c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f .**.** ^The seco
350d0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
350e0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
350f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 SQL function to
35100 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a be created or.**
35110 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 redefined. ^Th
35120 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 e length of the
35130 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 name is limited
35140 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 to 255 bytes in
35150 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 a UTF-8.** repre
35160 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 sentation, exclu
35170 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f sive of the zero
35180 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e -terminator. ^N
35190 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d ote that the nam
351a0 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 e.** length limi
351b0 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 t is in UTF-8 by
351c0 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 tes, not charact
351d0 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 ers nor UTF-16 b
351e0 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 ytes. .** ^Any
351f0 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 attempt to creat
35200 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 e a function wit
35210 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a h a longer name.
35220 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 ** will result i
35230 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 n [SQLITE_MISUSE
35240 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 ] being returned
35250 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 ..**.** ^The thi
35260 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 rd parameter (nA
35270 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 rg).** is the nu
35280 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 mber of argument
35290 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 s that the SQL f
352a0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 unction or.** ag
352b0 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e gregate takes. ^
352c0 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 If this paramete
352d0 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 r is -1, then th
352e0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f e SQL function o
352f0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d r.** aggregate m
35300 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 ay take any numb
35310 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 er of arguments
35320 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 between 0 and th
35330 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 e limit.** set b
35340 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 y [sqlite3_limit
35350 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ]([SQLITE_LIMIT_
35360 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 FUNCTION_ARG]).
35370 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a If the third.**
35380 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 parameter is le
35390 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 ss than -1 or gr
353a0 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 eater than 127 t
353b0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
353c0 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 is.** undefined
353d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 ..**.** ^The fou
353e0 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 rth parameter, e
353f0 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 TextRep, specifi
35400 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 es what.** [SQLI
35410 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 TE_UTF8 | text e
35420 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 ncoding] this SQ
35430 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 L function prefe
35440 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 rs for.** its pa
35450 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 rameters. The a
35460 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
35470 64 20 73 65 74 20 74 68 69 73 20 70 61 72 61 6d d set this param
35480 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 eter to.** [SQLI
35490 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 TE_UTF16LE] if t
354a0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c he function impl
354b0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b ementation invok
354c0 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f es .** [sqlite3_
354d0 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 value_text16le()
354e0 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f ] on an input, o
354f0 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 r [SQLITE_UTF16B
35500 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 E] if the.** imp
35510 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f lementation invo
35520 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c kes [sqlite3_val
35530 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f ue_text16be()] o
35540 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a n an input, or.*
35550 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d * [SQLITE_UTF16]
35560 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c if [sqlite3_val
35570 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 ue_text16()] is
35580 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 used, or [SQLITE
35590 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 _UTF8].** otherw
355a0 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 ise. ^The same
355b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 SQL function may
355c0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d be registered m
355d0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 ultiple times us
355e0 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 ing.** different
355f0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 preferred text
35600 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 encodings, with
35610 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d different implem
35620 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a entations for.**
35630 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a each encoding..
35640 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c ** ^When multipl
35650 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
35660 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 s of the same fu
35670 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c nction are avail
35680 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 able, SQLite.**
35690 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e will pick the on
356a0 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 e that involves
356b0 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 the least amount
356c0 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 of data convers
356d0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ion..**.** ^The
356e0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
356f0 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 may optionally
35700 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 be ORed with [SQ
35710 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 LITE_DETERMINIST
35720 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c IC].** to signal
35730 20 74 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 that the functi
35740 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 on will always r
35750 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 eturn the same r
35760 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 esult given.** t
35770 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 he same inputs w
35780 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 ithin a single S
35790 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d QL statement. M
357a0 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ost SQL function
357b0 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 s are.** determi
357c0 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 nistic. The bui
357d0 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d lt-in [random()]
357e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 SQL function is
357f0 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 an example of a
35800 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 .** function tha
35810 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 t is not determi
35820 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c nistic. The SQL
35830 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 ite query planne
35840 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 r is able to.**
35850 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e perform addition
35860 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 al optimizations
35870 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 on deterministi
35880 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 c functions, so
35890 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 use.** of the [S
358a0 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 QLITE_DETERMINIS
358b0 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 TIC] flag is rec
358c0 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 ommended where p
358d0 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e ossible..**.** ^
358e0 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d (The fifth param
358f0 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 eter is an arbit
35900 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 rary pointer. T
35910 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
35920 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 n of the.** func
35930 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 tion can gain ac
35940 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 cess to this poi
35950 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 nter using [sqli
35960 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d te3_user_data()]
35970 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 .)^.**.** ^The s
35980 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e ixth, seventh an
35990 64 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 d eighth paramet
359a0 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 ers, xFunc, xSte
359b0 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 p and xFinal, ar
359c0 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f e.** pointers to
359d0 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 C-language func
359e0 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 tions that imple
359f0 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e ment the SQL fun
35a00 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 ction or.** aggr
35a10 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 egate. ^A scalar
35a20 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 SQL function re
35a30 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d quires an implem
35a40 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 entation of the
35a50 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 xFunc.** callbac
35a60 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 k only; NULL poi
35a70 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 nters must be pa
35a80 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 ssed as the xSte
35a90 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 p and xFinal.**
35aa0 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 parameters. ^An
35ab0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 aggregate SQL fu
35ac0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 nction requires
35ad0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f an implementatio
35ae0 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e n of xStep.** an
35af0 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c d xFinal and NUL
35b00 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 L pointer must b
35b10 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 e passed for xFu
35b20 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 nc. ^To delete a
35b30 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 n existing.** SQ
35b40 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 L function or ag
35b50 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 gregate, pass NU
35b60 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 LL pointers for
35b70 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 all three functi
35b80 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e on.** callbacks.
35b90 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 .**.** ^(If the
35ba0 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 ninth parameter
35bb0 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 to sqlite3_creat
35bc0 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 e_function_v2()
35bd0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 is not NULL,.**
35be0 74 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 then it is destr
35bf0 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 uctor for the ap
35c00 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 plication data p
35c10 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 ointer. .** The
35c20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e destructor is in
35c30 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 voked when the f
35c40 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 unction is delet
35c50 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 ed, either by be
35c60 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 ing.** overloade
35c70 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 d or when the da
35c80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
35c90 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e n closes.)^.** ^
35ca0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 The destructor i
35cb0 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 s also invoked i
35cc0 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a f the call to.**
35cd0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
35ce0 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 function_v2() fa
35cf0 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 ils..** ^When th
35d00 65 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c e destructor cal
35d10 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e lback of the ten
35d20 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 th parameter is
35d30 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 invoked, it.** i
35d40 73 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c s passed a singl
35d50 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
35d60 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 is a copy of th
35d70 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 e application da
35d80 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 ta .** pointer w
35d90 68 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66 hich was the fif
35da0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
35db0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
35dc0 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a unction_v2()..**
35dd0 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 .** ^It is permi
35de0 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 tted to register
35df0 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d multiple implem
35e00 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 entations of the
35e10 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f same.** functio
35e20 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 ns with the same
35e30 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 name but with e
35e40 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 ither differing
35e50 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 numbers of.** ar
35e60 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 guments or diffe
35e70 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 ring preferred t
35e80 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 ext encodings.
35e90 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 ^SQLite will use
35ea0 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e .** the implemen
35eb0 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 tation that most
35ec0 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 closely matches
35ed0 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 the way in whic
35ee0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e h the.** SQL fun
35ef0 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 ction is used.
35f00 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c ^A function impl
35f10 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 ementation with
35f20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a a non-negative.*
35f30 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 * nArg parameter
35f40 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 is a better mat
35f50 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 ch than a functi
35f60 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f on implementatio
35f70 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 n with.** a nega
35f80 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 tive nArg. ^A f
35f90 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 unction where th
35fa0 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 e preferred text
35fb0 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 encoding.** mat
35fc0 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 ches the databas
35fd0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 e encoding is a
35fe0 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 better.** match
35ff0 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 than a function
36000 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 where the encodi
36010 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e ng is different.
36020 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f .** ^A functio
36030 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f n where the enco
36040 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 ding difference
36050 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 is between UTF16
36060 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a le and UTF16be.*
36070 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 * is a closer ma
36080 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 tch than a funct
36090 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e ion where the en
360a0 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 coding differenc
360b0 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 e is.** between
360c0 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a UTF8 and UTF16..
360d0 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 **.** ^Built-in
360e0 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 functions may be
360f0 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e overloaded by n
36100 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 ew application-d
36110 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 efined functions
36120 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c ..**.** ^An appl
36130 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
36140 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d function is perm
36150 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 itted to call ot
36160 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e her.** SQLite in
36170 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 terfaces. Howev
36180 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d er, such calls m
36190 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 ust not.** close
361a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
361b0 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e nnection nor fin
361c0 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 alize or reset t
361d0 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 he prepared.** s
361e0 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 tatement in whic
361f0 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 h the function i
36200 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e s running..*/.in
36210 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
36220 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c _function(. sql
36230 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 ite3 *db,. cons
36240 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f t char *zFunctio
36250 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 nName,. int nAr
36260 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 g,. int eTextRe
36270 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c p,. void *pApp,
36280 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 . void (*xFunc)
36290 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
362a0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
362b0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
362c0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f *xStep)(sqlite3_
362d0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c context*,int,sql
362e0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 ite3_value**),.
362f0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 void (*xFinal)(
36300 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
36310 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ).);.int sqlite3
36320 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
36330 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 16(. sqlite3 *d
36340 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 b,. const void
36350 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a *zFunctionName,.
36360 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e int nArg,. in
36370 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f t eTextRep,. vo
36380 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 id *pApp,. void
36390 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 (*xFunc)(sqlite
363a0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 3_context*,int,s
363b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c qlite3_value**),
363c0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 . void (*xStep)
363d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
363e0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
363f0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
36400 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 *xFinal)(sqlite3
36410 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e _context*).);.in
36420 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
36430 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 _function_v2(.
36440 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 sqlite3 *db,. c
36450 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 onst char *zFunc
36460 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 tionName,. int
36470 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 nArg,. int eTex
36480 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 tRep,. void *pA
36490 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 pp,. void (*xFu
364a0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 nc)(sqlite3_cont
364b0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
364c0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
364d0 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 d (*xStep)(sqlit
364e0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c e3_context*,int,
364f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 sqlite3_value**)
36500 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 ,. void (*xFina
36510 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 l)(sqlite3_conte
36520 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 xt*),. void(*xD
36530 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 estroy)(void*).)
36540 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
36550 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 F: Text Encoding
36560 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f s.**.** These co
36570 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e nstant define in
36580 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 teger codes that
36590 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 represent the v
365a0 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 arious.** text e
365b0 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 ncodings support
365c0 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f ed by SQLite..*/
365d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
365e0 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 UTF8 1
365f0 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 /* IMP: R-37
36600 35 31 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 514-35566 */.#de
36610 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 fine SQLITE_UTF1
36620 36 4c 45 20 20 20 20 20 20 20 20 32 20 20 20 20 6LE 2
36630 2f 2a 20 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d /* IMP: R-03371-
36640 33 37 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 37637 */.#define
36650 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 SQLITE_UTF16BE
36660 20 20 20 20 20 20 20 33 20 20 20 20 2f 2a 20 49 3 /* I
36670 4d 50 3a 20 52 2d 35 31 39 37 31 2d 33 34 31 35 MP: R-51971-3415
36680 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 4 */.#define SQL
36690 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 ITE_UTF16
366a0 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 4 /* Use n
366b0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
366c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
366d0 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 TE_ANY
366e0 20 20 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63 5 /* Deprec
366f0 61 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ated */.#define
36700 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 SQLITE_UTF16_ALI
36710 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 GNED 8 /* sq
36720 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
36730 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a lation only */..
36740 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
36750 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a Function Flags.*
36760 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 *.** These const
36770 61 6e 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64 ants may be ORed
36780 20 74 6f 67 65 74 68 65 72 20 77 69 74 68 20 74 together with t
36790 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 he .** [SQLITE_U
367a0 54 46 38 20 7c 20 70 72 65 66 65 72 72 65 64 20 TF8 | preferred
367b0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 text encoding] a
367c0 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 s the fourth arg
367d0 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c ument.** to [sql
367e0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
367f0 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 tion()], [sqlite
36800 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
36810 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 n16()], or.** [s
36820 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
36830 6e 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f nction_v2()]..*/
36840 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
36850 44 45 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20 DETERMINISTIC
36860 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 0x800../*.** CA
36870 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 PI3REF: Deprecat
36880 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 ed Functions.**
36890 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a DEPRECATED.**.**
368a0 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 These functions
368b0 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 are [deprecated
368c0 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 ]. In order to
368d0 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b maintain.** back
368e0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c wards compatibil
368f0 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 ity with older c
36900 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 ode, these funct
36910 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a ions continue .*
36920 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 * to be supporte
36930 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 d. However, new
36940 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 applications sh
36950 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 ould avoid.** th
36960 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 e use of these f
36970 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 65 6e unctions. To en
36980 63 6f 75 72 61 67 65 20 70 72 6f 67 72 61 6d 6d courage programm
36990 65 72 73 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 ers to avoid.**
369a0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c these functions,
369b0 20 77 65 20 77 69 6c 6c 20 6e 6f 74 20 65 78 70 we will not exp
369c0 6c 61 69 6e 20 77 68 61 74 20 74 68 65 79 20 64 lain what they d
369d0 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 o..*/.#ifndef SQ
369e0 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 LITE_OMIT_DEPREC
369f0 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 ATED.SQLITE_DEPR
36a00 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 ECATED int sqlit
36a10 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 e3_aggregate_cou
36a20 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 nt(sqlite3_conte
36a30 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 xt*);.SQLITE_DEP
36a40 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 RECATED int sqli
36a50 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 te3_expired(sqli
36a60 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 te3_stmt*);.SQLI
36a70 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e TE_DEPRECATED in
36a80 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 t sqlite3_transf
36a90 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 er_bindings(sqli
36aa0 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 te3_stmt*, sqlit
36ab0 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 e3_stmt*);.SQLIT
36ac0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 E_DEPRECATED int
36ad0 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f sqlite3_global_
36ae0 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 recover(void);.S
36af0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 QLITE_DEPRECATED
36b00 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 void sqlite3_th
36b10 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 read_cleanup(voi
36b20 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 d);.SQLITE_DEPRE
36b30 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 CATED int sqlite
36b40 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 3_memory_alarm(v
36b50 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c oid(*)(void*,sql
36b60 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c ite3_int64,int),
36b70 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 .
36b80 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c void*,sql
36b90 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e ite3_int64);.#en
36ba0 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 dif../*.** CAPI3
36bb0 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 REF: Obtaining S
36bc0 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 QL Values.** MET
36bd0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c HOD: sqlite3_val
36be0 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c ue.**.** The C-l
36bf0 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e anguage implemen
36c00 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 tation of SQL fu
36c10 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 nctions and aggr
36c20 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 egates uses.** t
36c30 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 his set of inter
36c40 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f face routines to
36c50 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 access the para
36c60 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a meter values on.
36c70 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 ** the function
36c80 6f 72 20 61 67 67 72 65 67 61 74 65 2e 20 20 0a or aggregate. .
36c90 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 **.** The xFunc
36ca0 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 (for scalar func
36cb0 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 tions) or xStep
36cc0 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 (for aggregates)
36cd0 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 parameters.** t
36ce0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 o [sqlite3_creat
36cf0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e e_function()] an
36d00 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 d [sqlite3_creat
36d10 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a e_function16()].
36d20 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 ** define callba
36d30 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 cks that impleme
36d40 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 nt the SQL funct
36d50 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 ions and aggrega
36d60 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 tes..** The 3rd
36d70 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
36d80 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 se callbacks is
36d90 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e an array of poin
36da0 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 ters to.** [prot
36db0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
36dc0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 lue] objects. T
36dd0 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c here is one [sql
36de0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
36df0 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 ct for.** each p
36e00 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
36e10 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 SQL function. T
36e20 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
36e30 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 e used to.** ext
36e40 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d ract values from
36e50 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 the [sqlite3_va
36e60 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a lue] objects..**
36e70 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
36e80 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 es work only wit
36e90 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c h [protected sql
36ea0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
36eb0 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 cts..** Any atte
36ec0 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 mpt to use these
36ed0 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 routines on an
36ee0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
36ef0 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f ite3_value].** o
36f00 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e bject results in
36f10 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 undefined behav
36f20 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 ior..**.** ^Thes
36f30 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 e routines work
36f40 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f just like the co
36f50 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c rresponding [col
36f60 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 umn access funct
36f70 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 ions].** except
36f80 74 68 61 74 20 74 68 65 73 65 20 72 6f 75 74 69 that these routi
36f90 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c nes take a singl
36fa0 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c e [protected sql
36fb0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
36fc0 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e ct.** pointer in
36fd0 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 stead of a [sqli
36fe0 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 te3_stmt*] point
36ff0 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 er and an intege
37000 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e r column number.
37010 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
37020 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
37030 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 () interface ext
37040 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 racts a UTF-16 s
37050 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 tring.** in the
37060 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 native byte-orde
37070 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 r of the host ma
37080 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 chine. ^The.**
37090 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
370a0 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c xt16be() and sql
370b0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
370c0 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 6le() interfaces
370d0 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d .** extract UTF-
370e0 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 16 strings as bi
370f0 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 g-endian and lit
37100 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 tle-endian respe
37110 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e ctively..**.** ^
37120 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c (The sqlite3_val
37130 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 ue_numeric_type(
37140 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 ) interface atte
37150 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a mpts to apply.**
37160 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 numeric affinit
37170 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 y to the value.
37180 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 This means that
37190 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a an attempt is.*
371a0 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 * made to conver
371b0 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 t the value to a
371c0 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f n integer or flo
371d0 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 ating point. If
371e0 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 .** such a conve
371f0 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c rsion is possibl
37200 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f e without loss o
37210 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 f information (i
37220 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 n other.** words
37230 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 , if the value i
37240 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 s a string that
37250 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d looks like a num
37260 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ber).** then the
37270 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 conversion is p
37280 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 erformed. Other
37290 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 wise no conversi
372a0 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 on occurs..** Th
372b0 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 e [SQLITE_INTEGE
372c0 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 R | datatype] af
372d0 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 ter conversion i
372e0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a s returned.)^.**
372f0 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 .** Please pay p
37300 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 articular attent
37310 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 ion to the fact
37320 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 that the pointer
37330 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f returned.** fro
37340 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 m [sqlite3_value
37350 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 _blob()], [sqlit
37360 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d e3_value_text()]
37370 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 , or.** [sqlite3
37380 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d _value_text16()]
37390 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 can be invalida
373a0 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 ted by a subsequ
373b0 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b ent call to.** [
373c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
373d0 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 tes()], [sqlite3
373e0 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 _value_bytes16()
373f0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ], [sqlite3_valu
37400 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 e_text()],.** or
37410 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
37420 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a text16()]..**.**
37430 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
37440 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 must be called f
37450 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 rom the same thr
37460 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 ead as.** the SQ
37470 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 L function that
37480 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 supplied the [sq
37490 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 lite3_value*] pa
374a0 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e rameters..*/.con
374b0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
374c0 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 _value_blob(sqli
374d0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 te3_value*);.int
374e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 sqlite3_value_b
374f0 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c ytes(sqlite3_val
37500 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 ue*);.int sqlite
37510 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 3_value_bytes16(
37520 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
37530 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f .double sqlite3_
37540 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c value_double(sql
37550 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e ite3_value*);.in
37560 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f t sqlite3_value_
37570 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 int(sqlite3_valu
37580 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 e*);.sqlite3_int
37590 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 64 sqlite3_value
375a0 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 _int64(sqlite3_v
375b0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e alue*);.const un
375c0 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c signed char *sql
375d0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 ite3_value_text(
375e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
375f0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
37600 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
37610 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 6(sqlite3_value*
37620 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
37630 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
37640 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 t16le(sqlite3_va
37650 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 lue*);.const voi
37660 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 d *sqlite3_value
37670 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 _text16be(sqlite
37680 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 3_value*);.int s
37690 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 qlite3_value_typ
376a0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a e(sqlite3_value*
376b0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 );.int sqlite3_v
376c0 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 alue_numeric_typ
376d0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a e(sqlite3_value*
376e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
376f0 45 46 3a 20 46 69 6e 64 69 6e 67 20 54 68 65 20 EF: Finding The
37700 53 75 62 74 79 70 65 20 4f 66 20 53 51 4c 20 56 Subtype Of SQL V
37710 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a alues.** METHOD:
37720 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a sqlite3_value.*
37730 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
37740 5f 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28 56 _value_subtype(V
37750 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 ) function retur
37760 6e 73 20 74 68 65 20 73 75 62 74 79 70 65 20 66 ns the subtype f
37770 6f 72 0a 2a 2a 20 61 6e 20 5b 61 70 70 6c 69 63 or.** an [applic
37780 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
37790 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 61 72 67 75 L function] argu
377a0 6d 65 6e 74 20 56 2e 20 20 54 68 65 20 73 75 62 ment V. The sub
377b0 74 79 70 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 type.** informat
377c0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 ion can be used
377d0 74 6f 20 70 61 73 73 20 61 20 6c 69 6d 69 74 65 to pass a limite
377e0 64 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 d amount of cont
377f0 65 78 74 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 ext from.** one
37800 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 SQL function to
37810 61 6e 6f 74 68 65 72 2e 20 20 55 73 65 20 74 68 another. Use th
37820 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c e [sqlite3_resul
37830 74 5f 73 75 62 74 79 70 65 28 29 5d 0a 2a 2a 20 t_subtype()].**
37840 72 6f 75 74 69 6e 65 20 74 6f 20 73 65 74 20 74 routine to set t
37850 68 65 20 73 75 62 74 79 70 65 20 66 6f 72 20 74 he subtype for t
37860 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
37870 6f 66 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 of an SQL functi
37880 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 on..**.** SQLite
37890 20 6d 61 6b 65 73 20 6e 6f 20 75 73 65 20 6f 66 makes no use of
378a0 20 73 75 62 74 79 70 65 20 69 74 73 65 6c 66 2e subtype itself.
378b0 20 20 49 74 20 6d 65 72 65 6c 79 20 70 61 73 73 It merely pass
378c0 65 73 20 74 68 65 20 73 75 62 74 79 70 65 0a 2a es the subtype.*
378d0 2a 20 66 72 6f 6d 20 74 68 65 20 72 65 73 75 6c * from the resul
378e0 74 20 6f 66 20 6f 6e 65 20 5b 61 70 70 6c 69 63 t of one [applic
378f0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
37900 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 69 6e 74 6f L function] into
37910 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20 6f 66 the.** input of
37920 20 61 6e 6f 74 68 65 72 2e 0a 2a 2f 0a 75 6e 73 another..*/.uns
37930 69 67 6e 65 64 20 69 6e 74 20 73 71 6c 69 74 65 igned int sqlite
37940 33 5f 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28 3_value_subtype(
37950 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
37960 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
37970 3a 20 43 6f 70 79 20 41 6e 64 20 46 72 65 65 20 : Copy And Free
37980 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 SQL Values.** ME
37990 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 THOD: sqlite3_va
379a0 6c 75 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 lue.**.** ^The s
379b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 qlite3_value_dup
379c0 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 (V) interface ma
379d0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 kes a copy of th
379e0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
379f0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 44 20 61 6e ].** object D an
37a00 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e d returns a poin
37a10 74 65 72 20 74 6f 20 74 68 61 74 20 63 6f 70 79 ter to that copy
37a20 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 . ^The [sqlite3
37a30 5f 76 61 6c 75 65 5d 20 72 65 74 75 72 6e 65 64 _value] returned
37a40 0a 2a 2a 20 69 73 20 61 20 5b 70 72 6f 74 65 63 .** is a [protec
37a50 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
37a60 65 5d 20 6f 62 6a 65 63 74 20 65 76 65 6e 20 69 e] object even i
37a70 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 6e f the input is n
37a80 6f 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 ot..** ^The sqli
37a90 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 te3_value_dup(V)
37aa0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
37ab0 6e 73 20 4e 55 4c 4c 20 69 66 20 56 20 69 73 20 ns NULL if V is
37ac0 4e 55 4c 4c 20 6f 72 20 69 66 20 61 0a 2a 2a 20 NULL or if a.**
37ad0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
37ae0 6e 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e n fails..**.** ^
37af0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 The sqlite3_valu
37b00 65 5f 66 72 65 65 28 56 29 20 69 6e 74 65 72 66 e_free(V) interf
37b10 61 63 65 20 66 72 65 65 73 20 61 6e 20 5b 73 71 ace frees an [sq
37b20 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
37b30 65 63 74 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c ect.** previousl
37b40 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
37b50 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 [sqlite3_value_d
37b60 75 70 28 29 5d 2e 20 20 5e 49 66 20 56 20 69 73 up()]. ^If V is
37b70 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a a NULL pointer.
37b80 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f ** then sqlite3_
37b90 76 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69 73 value_free(V) is
37ba0 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f a harmless no-o
37bb0 70 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 61 p..*/.sqlite3_va
37bc0 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c lue *sqlite3_val
37bd0 75 65 5f 64 75 70 28 63 6f 6e 73 74 20 73 71 6c ue_dup(const sql
37be0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f ite3_value*);.vo
37bf0 69 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 id sqlite3_value
37c00 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 76 61 _free(sqlite3_va
37c10 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 lue*);../*.** CA
37c20 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 PI3REF: Obtain A
37c30 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f ggregate Functio
37c40 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 20 4d 45 54 n Context.** MET
37c50 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e HOD: sqlite3_con
37c60 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 text.**.** Imple
37c70 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 mentations of ag
37c80 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 gregate SQL func
37c90 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a tions use this.*
37ca0 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c * routine to all
37cb0 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 ocate memory for
37cc0 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 storing their s
37cd0 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 tate..**.** ^The
37ce0 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 first time the
37cf0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
37d00 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 e_context(C,N) r
37d10 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 outine is called
37d20 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 .** for a parti
37d30 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 cular aggregate
37d40 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 function, SQLite
37d50 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 .** allocates N
37d60 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 of memory, zeroe
37d70 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 s out that memor
37d80 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 y, and returns a
37d90 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 pointer.** to t
37da0 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e he new memory. ^
37db0 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 On second and su
37dc0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 bsequent calls t
37dd0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 o.** sqlite3_agg
37de0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 regate_context()
37df0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 for the same ag
37e00 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e gregate function
37e10 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 instance,.** th
37e20 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 e same buffer is
37e30 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 returned. Sqli
37e40 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
37e50 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 ntext() is norma
37e60 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e lly.** called on
37e70 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f ce for each invo
37e80 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 cation of the xS
37e90 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 tep callback and
37ea0 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 then one.** las
37eb0 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 t time when the
37ec0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 xFinal callback
37ed0 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 is invoked. ^(W
37ee0 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 hen no rows matc
37ef0 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 h.** an aggregat
37f00 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 e query, the xSt
37f10 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 ep() callback of
37f20 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 the aggregate f
37f30 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 unction.** imple
37f40 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 mentation is nev
37f50 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 er called and xF
37f60 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 inal() is called
37f70 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a exactly once..*
37f80 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 * In those cases
37f90 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 , sqlite3_aggreg
37fa0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 ate_context() mi
37fb0 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f ght be called fo
37fc0 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 r the.** first t
37fd0 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 ime from within
37fe0 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a xFinal().)^.**.*
37ff0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 * ^The sqlite3_a
38000 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
38010 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 (C,N) routine re
38020 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 turns a NULL poi
38030 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 nter .** when fi
38040 72 73 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 rst called if N
38050 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 is less than or
38060 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 equal to zero or
38070 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 if a memory.**
38080 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f allocate error o
38090 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 ccurs..**.** ^(T
380a0 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 he amount of spa
380b0 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 ce allocated by
380c0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
380d0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 e_context(C,N) i
380e0 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 s.** determined
380f0 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 by the N paramet
38100 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 er on first succ
38110 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 essful call. Ch
38120 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 anging the.** va
38130 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 lue of N in subs
38140 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 equent call to s
38150 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
38160 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 _context() withi
38170 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 n.** the same ag
38180 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e gregate function
38190 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e instance will n
381a0 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 ot resize the me
381b0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 mory.** allocati
381c0 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68 on.)^ Within th
381d0 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 e xFinal callbac
381e0 6b 2c 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61 k, it is customa
381f0 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 ry to set.** N=0
38200 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c in calls to sql
38210 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
38220 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 ontext(C,N) so t
38230 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 hat no .** point
38240 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f less memory allo
38250 63 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a cations occur..*
38260 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 *.** ^SQLite aut
38270 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 omatically frees
38280 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f the memory allo
38290 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c cated by .** sql
382a0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
382b0 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 ontext() when th
382c0 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 e aggregate quer
382d0 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a y concludes..**.
382e0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 ** The first par
382f0 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 ameter must be a
38300 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 copy of the.**
38310 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 [sqlite3_context
38320 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 | SQL function
38330 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 context] that is
38340 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
38350 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 eter.** to the x
38360 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 Step or xFinal c
38370 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 allback routine
38380 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 that implements
38390 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a the aggregate.**
383a0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a function..**.**
383b0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 This routine mu
383c0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f st be called fro
383d0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 m the same threa
383e0 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 d in which.** th
383f0 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 e aggregate SQL
38400 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e function is runn
38410 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 ing..*/.void *sq
38420 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
38430 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f context(sqlite3_
38440 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 context*, int nB
38450 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ytes);../*.** CA
38460 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 PI3REF: User Dat
38470 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a a For Functions.
38480 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
38490 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a e3_context.**.**
384a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 ^The sqlite3_us
384b0 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 er_data() interf
384c0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f ace returns a co
384d0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 py of.** the poi
384e0 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 nter that was th
384f0 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 e pUserData para
38500 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 meter (the 5th p
38510 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 arameter).** of
38520 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 the [sqlite3_cre
38530 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a ate_function()].
38540 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ** and [sqlite3_
38550 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
38560 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 6()] routines th
38570 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a at originally.**
38580 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 registered the
38590 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 application defi
385a0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a ned function..**
385b0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
385c0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 must be called
385d0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 from the same th
385e0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a read in which.**
385f0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
38600 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
38610 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f n is running..*/
38620 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 .void *sqlite3_u
38630 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 ser_data(sqlite3
38640 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a _context*);../*.
38650 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 ** CAPI3REF: Dat
38660 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e abase Connection
38670 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a For Functions.*
38680 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
38690 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 3_context.**.**
386a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e ^The sqlite3_con
386b0 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 text_db_handle()
386c0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
386d0 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 ns a copy of.**
386e0 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 the pointer to t
386f0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
38700 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 nection] (the 1s
38710 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 t parameter).**
38720 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
38730 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
38740 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 )].** and [sqlit
38750 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
38760 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 on16()] routines
38770 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 that originally
38780 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 .** registered t
38790 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 he application d
387a0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e efined function.
387b0 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c .*/.sqlite3 *sql
387c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f ite3_context_db_
387d0 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 handle(sqlite3_c
387e0 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a ontext*);../*.**
387f0 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 CAPI3REF: Funct
38800 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 ion Auxiliary Da
38810 74 61 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 ta.** METHOD: sq
38820