0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65 /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69 e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20 ms copyright to
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a . In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73 , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d sing:.**.** M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 nd not evil..**
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 May you find
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20 forgiveness for
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 give others..**
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65 May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 aking more than
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68 ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65 that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73 library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70 ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43 rograms. If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63 -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64 ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69 ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20 s file, then it
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20 ite, is subject
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64 t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72 should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53 grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74 e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70 arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70 erimental". Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65 y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64 s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20 to SQLite. We
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74 do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 e changes.** to
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65 erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69 ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69 ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67 n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73 est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20 C-language API
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69 r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73 e. This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69 the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20 ve source.** on
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72 how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73 faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 ion number) and
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 to "sqlite3.h"
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 .*/.#ifndef SQLI
05e0: 54 45 33 5f 48 0a 23 64 65 66 69 6e 65 20 53 51 TE3_H.#define SQ
05f0: 4c 49 54 45 33 5f 48 0a 23 69 6e 63 6c 75 64 65 LITE3_H.#include
0600: 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20 <stdarg.h>
0610: 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68 /* Needed for th
0620: 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20 e definition of
0630: 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a va_list */../*.*
0640: 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63 * Make sure we c
0650: 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75 an call this stu
0660: 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a ff from C++..*/.
0670: 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c #ifdef __cpluspl
0680: 75 73 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a us.extern "C" {.
0690: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 50 #endif.../*.** P
06a0: 72 6f 76 69 64 65 20 74 68 65 20 61 62 69 6c 69 rovide the abili
06b0: 74 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 6c ty to override l
06c0: 69 6e 6b 61 67 65 20 66 65 61 74 75 72 65 73 20 inkage features
06d0: 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 of the interface
06e0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c ..*/.#ifndef SQL
06f0: 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 ITE_EXTERN.# def
0700: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52 ine SQLITE_EXTER
0710: 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a N extern.#endif.
0720: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 #ifndef SQLITE_A
0730: 50 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 PI.# define SQLI
0740: 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 23 69 TE_API.#endif.#i
0750: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 43 44 45 fndef SQLITE_CDE
0760: 43 4c 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 CL.# define SQLI
0770: 54 45 5f 43 44 45 43 4c 0a 23 65 6e 64 69 66 0a TE_CDECL.#endif.
0780: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 #ifndef SQLITE_A
0790: 50 49 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 PICALL.# define
07a0: 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 SQLITE_APICALL.#
07b0: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 endif.#ifndef SQ
07c0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 LITE_STDCALL.# d
07d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 efine SQLITE_STD
07e0: 43 41 4c 4c 20 53 51 4c 49 54 45 5f 41 50 49 43 CALL SQLITE_APIC
07f0: 41 4c 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 ALL.#endif.#ifnd
0800: 65 66 20 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41 ef SQLITE_CALLBA
0810: 43 4b 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 CK.# define SQLI
0820: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 65 6e 64 TE_CALLBACK.#end
0830: 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 if.#ifndef SQLIT
0840: 45 5f 53 59 53 41 50 49 0a 23 20 64 65 66 69 6e E_SYSAPI.# defin
0850: 65 20 53 51 4c 49 54 45 5f 53 59 53 41 50 49 0a e SQLITE_SYSAPI.
0860: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 #endif../*.** Th
0870: 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 ese no-op macros
0880: 20 61 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f are used in fro
0890: 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 nt of interfaces
08a0: 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a to mark those.*
08b0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 * interfaces as
08c0: 65 69 74 68 65 72 20 64 65 70 72 65 63 61 74 65 either deprecate
08d0: 64 20 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 d or experimenta
08e0: 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 l. New applicat
08f0: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e ions.** should n
0900: 6f 74 20 75 73 65 20 64 65 70 72 65 63 61 74 65 ot use deprecate
0910: 64 20 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 d interfaces - t
0920: 68 65 79 20 61 72 65 20 73 75 70 70 6f 72 74 65 hey are supporte
0930: 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a d for backwards.
0940: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ** compatibility
0950: 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 only. Applicat
0960: 69 6f 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75 ion writers shou
0970: 6c 64 20 62 65 20 61 77 61 72 65 20 74 68 61 74 ld be aware that
0980: 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c .** experimental
0990: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
09a0: 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 subject to chang
09b0: 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61 e in point relea
09c0: 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ses..**.** These
09d0: 20 6d 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20 macros used to
09e0: 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f resolve to vario
09f0: 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70 us kinds of comp
0a00: 69 6c 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a iler magic that.
0a10: 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74 ** would generat
0a20: 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67 e warning messag
0a30: 65 73 20 77 68 65 6e 20 74 68 65 79 20 77 65 72 es when they wer
0a40: 65 20 75 73 65 64 2e 20 20 42 75 74 20 74 68 61 e used. But tha
0a50: 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61 t.** compiler ma
0a60: 67 69 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e gic ended up gen
0a70: 65 72 61 74 69 6e 67 20 73 75 63 68 20 61 20 66 erating such a f
0a80: 6c 75 72 72 79 20 6f 66 20 62 75 67 20 72 65 70 lurry of bug rep
0a90: 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20 orts.** that we
0aa0: 68 61 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c have taken it al
0ab0: 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62 l out and gone b
0ac0: 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d ack to using sim
0ad0: 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 ple.** noop macr
0ae0: 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 os..*/.#define S
0af0: 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 QLITE_DEPRECATED
0b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
0b10: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a EXPERIMENTAL../*
0b20: 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65 .** Ensure these
0b30: 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f symbols were no
0b40: 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d t defined by som
0b50: 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 64 65 e previous heade
0b60: 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 r file..*/.#ifde
0b70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e f SQLITE_VERSION
0b80: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f .# undef SQLITE_
0b90: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 VERSION.#endif.#
0ba0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 ifdef SQLITE_VER
0bb0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e SION_NUMBER.# un
0bc0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 def SQLITE_VERSI
0bd0: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66 ON_NUMBER.#endif
0be0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
0bf0: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c : Compile-Time L
0c00: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e ibrary Version N
0c10: 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 umbers.**.** ^(T
0c20: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 he [SQLITE_VERSI
0c30: 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 ON] C preprocess
0c40: 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20 or macro in the
0c50: 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72 sqlite3.h header
0c60: 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f .** evaluates to
0c70: 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 a string litera
0c80: 6c 20 74 68 61 74 20 69 73 20 74 68 65 20 53 51 l that is the SQ
0c90: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20 Lite version in
0ca0: 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58 the.** format "X
0cb0: 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73 .Y.Z" where X is
0cc0: 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69 the major versi
0cd0: 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79 on number (alway
0ce0: 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 s 3 for.** SQLit
0cf0: 65 33 29 20 61 6e 64 20 59 20 69 73 20 74 68 65 e3) and Y is the
0d00: 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e minor version n
0d10: 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74 umber and Z is t
0d20: 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 he release numbe
0d30: 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 r.)^.** ^(The [S
0d40: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 QLITE_VERSION_NU
0d50: 4d 42 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65 MBER] C preproce
0d60: 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c ssor macro resol
0d70: 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 ves to an intege
0d80: 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61 r.** with the va
0d90: 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b lue (X*1000000 +
0da0: 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 Y*1000 + Z) whe
0db0: 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61 re X, Y, and Z a
0dc0: 72 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e re the same.** n
0dd0: 75 6d 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b umbers used in [
0de0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e SQLITE_VERSION].
0df0: 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 )^.** The SQLITE
0e00: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 _VERSION_NUMBER
0e10: 66 6f 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65 for any given re
0e20: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 lease of SQLite
0e30: 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 will also.** be
0e40: 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 larger than the
0e50: 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69 release from whi
0e60: 63 68 20 69 74 20 69 73 20 64 65 72 69 76 65 64 ch it is derived
0e70: 2e 20 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c . Either Y will
0e80: 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73 .** be held cons
0e90: 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20 tant and Z will
0ea0: 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f be incremented o
0eb0: 72 20 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65 r else Y will be
0ec0: 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 incremented.**
0ed0: 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65 and Z will be re
0ee0: 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a set to zero..**.
0ef0: 2a 2a 20 53 69 6e 63 65 20 5b 76 65 72 73 69 6f ** Since [versio
0f00: 6e 20 33 2e 36 2e 31 38 5d 20 28 5b 64 61 74 65 n 3.6.18] ([date
0f10: 6f 66 3a 33 2e 36 2e 31 38 5d 29 2c 20 0a 2a 2a of:3.6.18]), .**
0f20: 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 SQLite source c
0f30: 6f 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f ode has been sto
0f40: 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61 red in the.** <a
0f50: 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 href="http://ww
0f60: 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67 w.fossil-scm.org
0f70: 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67 /">Fossil config
0f80: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 uration manageme
0f90: 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e nt.** system</a>
0fa0: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 . ^The SQLITE_S
0fb0: 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 6f 20 65 OURCE_ID macro e
0fc0: 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61 valuates to.** a
0fd0: 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 64 string which id
0fe0: 65 6e 74 69 66 69 65 73 20 61 20 70 61 72 74 69 entifies a parti
0ff0: 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f cular check-in o
1000: 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68 f SQLite.** with
1010: 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61 in its configura
1020: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 tion management
1030: 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 53 51 system. ^The SQ
1040: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a LITE_SOURCE_ID.*
1050: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e * string contain
1060: 73 20 74 68 65 20 64 61 74 65 20 61 6e 64 20 74 s the date and t
1070: 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65 63 6b ime of the check
1080: 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20 61 6e -in (UTC) and an
1090: 20 53 48 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66 SHA1.** hash of
10a0: 20 74 68 65 20 65 6e 74 69 72 65 20 73 6f 75 72 the entire sour
10b0: 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 ce tree..**.** S
10c0: 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
10d0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c 3_libversion()],
10e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 .** [sqlite3_lib
10f0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 version_number()
1100: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72 ], [sqlite3_sour
1110: 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c ceid()],.** [sql
1120: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 ite_version()] a
1130: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 nd [sqlite_sourc
1140: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 e_id()]..*/.#def
1150: 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 ine SQLITE_VERSI
1160: 4f 4e 20 20 20 20 20 20 20 20 22 2d 2d 56 45 52 ON "--VER
1170: 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20 53 51 4c S--".#define SQL
1180: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 ITE_VERSION_NUMB
1190: 45 52 20 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d ER --VERSION-NUM
11a0: 42 45 52 2d 2d 0a 23 64 65 66 69 6e 65 20 53 51 BER--.#define SQ
11b0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 LITE_SOURCE_ID
11c0: 20 20 20 20 22 2d 2d 53 4f 55 52 43 45 2d 49 44 "--SOURCE-ID
11d0: 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 --"../*.** CAPI3
11e0: 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 REF: Run-Time Li
11f0: 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 brary Version Nu
1200: 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 mbers.** KEYWORD
1210: 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 S: sqlite3_versi
1220: 6f 6e 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 on sqlite3_sourc
1230: 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 eid.**.** These
1240: 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f 76 69 interfaces provi
1250: 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f de the same info
1260: 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b rmation as the [
1270: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c SQLITE_VERSION],
1280: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 .** [SQLITE_VERS
1290: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 ION_NUMBER], and
12a0: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f [SQLITE_SOURCE_
12b0: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 ID] C preprocess
12c0: 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74 or macros.** but
12d0: 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 20 are associated
12e0: 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 with the library
12f0: 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 instead of the
1300: 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28 header file. ^(
1310: 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 Cautious.** prog
1320: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e rammers might in
1330: 63 6c 75 64 65 20 61 73 73 65 72 74 28 29 20 73 clude assert() s
1340: 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 tatements in the
1350: 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 ir application t
1360: 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74 o.** verify that
1370: 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 values returned
1380: 20 62 79 20 74 68 65 73 65 20 69 6e 74 65 72 66 by these interf
1390: 61 63 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d aces match the m
13a0: 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20 acros in.** the
13b0: 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73 header, and thus
13c0: 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 ensure that the
13d0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a application is.
13e0: 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 ** compiled with
13f0: 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72 matching librar
1400: 79 20 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c y and header fil
1410: 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b es..**.** <block
1420: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 quote><pre>.** a
1430: 73 73 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c ssert( sqlite3_l
1440: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 ibversion_number
1450: 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49 ()==SQLITE_VERSI
1460: 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 ON_NUMBER );.**
1470: 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 assert( strcmp(s
1480: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 qlite3_sourceid(
1490: 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f ),SQLITE_SOURCE_
14a0: 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 ID)==0 );.** ass
14b0: 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 ert( strcmp(sqli
14c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 te3_libversion()
14d0: 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 ,SQLITE_VERSION)
14e0: 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e ==0 );.** </pre>
14f0: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a </blockquote>)^.
1500: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
1510: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 e3_version[] str
1520: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e ing constant con
1530: 74 61 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f tains the text o
1540: 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f f [SQLITE_VERSIO
1550: 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 N].** macro. ^T
1560: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 he sqlite3_libve
1570: 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e rsion() function
1580: 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
1590: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 er to the.** to
15a0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 the sqlite3_vers
15b0: 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e ion[] string con
15c0: 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 stant. The sqli
15d0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 te3_libversion()
15e0: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 .** function is
15f0: 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 provided for use
1600: 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 in DLLs since D
1610: 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 LL users usually
1620: 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 do not have.**
1630: 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74 6f direct access to
1640: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 string constant
1650: 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c s within the DLL
1660: 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 . ^The.** sqlit
1670: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 e3_libversion_nu
1680: 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 mber() function
1690: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 returns an integ
16a0: 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b er equal to.** [
16b0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e SQLITE_VERSION_N
16c0: 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71 UMBER]. ^The sq
16d0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 lite3_sourceid()
16e0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e function return
16f0: 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 s .** a pointer
1700: 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 to a string cons
1710: 74 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 tant whose value
1720: 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 is the same as
1730: 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the .** [SQLITE_
1740: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 SOURCE_ID] C pre
1750: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e processor macro.
1760: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
1770: 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e [sqlite_version
1780: 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f ()] and [sqlite_
1790: 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f source_id()]..*/
17a0: 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 .SQLITE_EXTERN c
17b0: 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74 65 onst char sqlite
17c0: 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 3_version[];.con
17d0: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
17e0: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 _libversion(void
17f0: 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 );.const char *s
1800: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 qlite3_sourceid(
1810: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 void);.int sqlit
1820: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 e3_libversion_nu
1830: 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a mber(void);../*.
1840: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e ** CAPI3REF: Run
1850: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 43 6f -Time Library Co
1860: 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f 6e mpilation Option
1870: 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a 2a s Diagnostics.**
1880: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1890: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 _compileoption_u
18a0: 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 sed() function r
18b0: 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20 0a 2a eturns 0 or 1 .*
18c0: 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77 68 65 * indicating whe
18d0: 74 68 65 72 20 74 68 65 20 73 70 65 63 69 66 69 ther the specifi
18e0: 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 64 65 ed option was de
18f0: 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f 6d fined at .** com
1900: 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68 65 pile time. ^The
1910: 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69 78 20 SQLITE_ prefix
1920: 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 66 may be omitted f
1930: 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74 69 rom the .** opti
1940: 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 20 74 on name passed t
1950: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c o sqlite3_compil
1960: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e 20 eoption_used().
1970: 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c .**.** ^The sql
1980: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 ite3_compileopti
1990: 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 69 6f on_get() functio
19a0: 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 74 69 n allows iterati
19b0: 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c ng.** over the l
19c0: 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74 ist of options t
19d0: 68 61 74 20 77 65 72 65 20 64 65 66 69 6e 65 64 hat were defined
19e0: 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 at compile time
19f0: 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67 by.** returning
1a00: 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c the N-th compil
1a10: 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74 e time option st
1a20: 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73 20 ring. ^If N is
1a30: 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a out of range,.**
1a40: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 sqlite3_compile
1a50: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 65 74 option_get() ret
1a60: 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e urns a NULL poin
1a70: 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 ter. ^The SQLIT
1a80: 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 69 73 E_ .** prefix is
1a90: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 61 6e omitted from an
1aa0: 79 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e y strings return
1ab0: 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 ed by .** sqlite
1ac0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 3_compileoption_
1ad0: 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 get()..**.** ^Su
1ae0: 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20 64 69 pport for the di
1af0: 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 69 6f agnostic functio
1b00: 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 ns sqlite3_compi
1b10: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a leoption_used().
1b20: 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 ** and sqlite3_c
1b30: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 ompileoption_get
1b40: 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 () may be omitte
1b50: 64 20 62 79 20 73 70 65 63 69 66 79 69 6e 67 20 d by specifying
1b60: 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the .** [SQLITE_
1b70: 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 OMIT_COMPILEOPTI
1b80: 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f 6e ON_DIAGS] option
1b90: 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 at compile time
1ba0: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
1bb0: 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 : SQL functions
1bc0: 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f [sqlite_compileo
1bd0: 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61 6e ption_used()] an
1be0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f 6d d.** [sqlite_com
1bf0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 pileoption_get()
1c00: 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70 69 ] and the [compi
1c10: 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d le_options pragm
1c20: 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 a]..*/.#ifndef S
1c30: 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 QLITE_OMIT_COMPI
1c40: 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a 69 LEOPTION_DIAGS.i
1c50: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 nt sqlite3_compi
1c60: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f leoption_used(co
1c70: 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 nst char *zOptNa
1c80: 6d 65 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 me);.const char
1c90: 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 *sqlite3_compile
1ca0: 6f 70 74 69 6f 6e 5f 67 65 74 28 69 6e 74 20 4e option_get(int N
1cb0: 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a );.#endif../*.**
1cc0: 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 CAPI3REF: Test
1cd0: 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c 69 To See If The Li
1ce0: 62 72 61 72 79 20 49 73 20 54 68 72 65 61 64 73 brary Is Threads
1cf0: 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 afe.**.** ^The s
1d00: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 qlite3_threadsaf
1d10: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 e() function ret
1d20: 75 72 6e 73 20 7a 65 72 6f 20 69 66 20 61 6e 64 urns zero if and
1d30: 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 4c 69 only if.** SQLi
1d40: 74 65 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 te was compiled
1d50: 77 69 74 68 20 6d 75 74 65 78 69 6e 67 20 63 6f with mutexing co
1d60: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74 de omitted due t
1d70: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 o the.** [SQLITE
1d80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d _THREADSAFE] com
1d90: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
1da0: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e being set to 0.
1db0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 .**.** SQLite ca
1dc0: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 n be compiled wi
1dd0: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 th or without mu
1de0: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 texes. When.**
1df0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 the [SQLITE_THRE
1e00: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f ADSAFE] C prepro
1e10: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 cessor macro is
1e20: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 1 or 2, mutexes.
1e30: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 ** are enabled a
1e40: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 nd SQLite is thr
1e50: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 eadsafe. When t
1e60: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 he.** [SQLITE_TH
1e70: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 READSAFE] macro
1e80: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 is 0, .** the mu
1e90: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 texes are omitte
1ea0: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 d. Without the
1eb0: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e mutexes, it is n
1ec0: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 ot safe.** to us
1ed0: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 e SQLite concurr
1ee0: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 ently from more
1ef0: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e than one thread.
1f00: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 .**.** Enabling
1f10: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61 mutexes incurs a
1f20: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 measurable perf
1f30: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e ormance penalty.
1f40: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20 .** So if speed
1f50: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 is of utmost imp
1f60: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 ortance, it make
1f70: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62 s sense to disab
1f80: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 le.** the mutexe
1f90: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69 s. But for maxi
1fa0: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65 mum safety, mute
1fb0: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e xes should be en
1fc0: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 abled..** ^The d
1fd0: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 efault behavior
1fe0: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 is for mutexes t
1ff0: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a o be enabled..**
2000: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 .** This interfa
2010: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 ce can be used b
2020: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e y an application
2030: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 to make sure th
2040: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f at the.** versio
2050: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 n of SQLite that
2060: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 it is linking a
2070: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 gainst was compi
2080: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 led with.** the
2090: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 desired setting
20a0: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 of the [SQLITE_T
20b0: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f HREADSAFE] macro
20c0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 ..**.** This int
20d0: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f erface only repo
20e0: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 rts on the compi
20f0: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 le-time mutex se
2100: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 tting.** of the
2110: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
2120: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 FE] flag. If SQ
2130: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
2140: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f with.** SQLITE_
2150: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20 THREADSAFE=1 or
2160: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 =2 then mutexes
2170: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 are enabled by d
2180: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 efault but.** ca
2190: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 n be fully or pa
21a0: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 rtially disabled
21b0: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f using a call to
21c0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
21d0: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 ()].** with the
21e0: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f verbs [SQLITE_CO
21f0: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 NFIG_SINGLETHREA
2200: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 D], [SQLITE_CONF
2210: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c IG_MULTITHREAD],
2220: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 .** or [SQLITE_C
2230: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 ONFIG_SERIALIZED
2240: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e ]. ^(The return
2250: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a value of the.**
2260: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 sqlite3_threads
2270: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73 afe() function s
2280: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f hows only the co
2290: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 mpile-time setti
22a0: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20 ng of.** thread
22b0: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20 safety, not any
22c0: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 run-time changes
22d0: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67 to that setting
22e0: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69 made by.** sqli
22f0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e te3_config(). In
2300: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 other words, th
2310: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 e return value f
2320: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65 rom sqlite3_thre
2330: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75 adsafe().** is u
2340: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c nchanged by call
2350: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e s to sqlite3_con
2360: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 fig().)^.**.** S
2370: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e ee the [threadin
2380: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 g mode] document
2390: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 ation for additi
23a0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
23b0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
23c0: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 _threadsafe(void
23d0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
23e0: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e EF: Database Con
23f0: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a nection Handle.*
2400: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 * KEYWORDS: {dat
2410: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2420: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e } {database conn
2430: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 ections}.**.** E
2440: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 ach open SQLite
2450: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 database is repr
2460: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 esented by a poi
2470: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 nter to an insta
2480: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 nce of.** the op
2490: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e aque structure n
24a0: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 amed "sqlite3".
24b0: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f It is useful to
24c0: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c think of an sql
24d0: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 ite3.** pointer
24e0: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 as an object. T
24f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e he [sqlite3_open
2500: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ()], [sqlite3_op
2510: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 en16()], and.**
2520: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
2530: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 ()] interfaces a
2540: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 re its construct
2550: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 ors, and [sqlite
2560: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 3_close()].** an
2570: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 d [sqlite3_close
2580: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64 _v2()] are its d
2590: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65 estructors. The
25a0: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 re are many othe
25b0: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 r.** interfaces
25c0: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c (such as.** [sql
25d0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
25e0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 )], [sqlite3_cre
25f0: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c ate_function()],
2600: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
2610: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d _busy_timeout()]
2620: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 to name but thr
2630: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 ee) that are met
2640: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 hods on an.** sq
2650: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f lite3 object..*/
2660: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
2670: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b sqlite3 sqlite3;
2680: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2690: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72 : 64-Bit Integer
26a0: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 Types.** KEYWOR
26b0: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 DS: sqlite_int64
26c0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a sqlite_uint64.*
26d0: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 *.** Because the
26e0: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 re is no cross-p
26f0: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 latform way to s
2700: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e pecify 64-bit in
2710: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 teger types.** S
2720: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 QLite includes t
2730: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 ypedefs for 64-b
2740: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e it signed and un
2750: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e signed integers.
2760: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
2770: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c e3_int64 and sql
2780: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 ite3_uint64 are
2790: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79 the preferred ty
27a0: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a pe definitions..
27b0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e ** The sqlite_in
27c0: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 t64 and sqlite_u
27d0: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20 int64 types are
27e0: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 supported for ba
27f0: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 ckwards.** compa
2800: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a tibility only..*
2810: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
2820: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 3_int64 and sqli
2830: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63 te_int64 types c
2840: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 an store integer
2850: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 values.** betwe
2860: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35 en -922337203685
2870: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32 4775808 and +922
2880: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37 3372036854775807
2890: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 inclusive. ^Th
28a0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e e.** sqlite3_uin
28b0: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 t64 and sqlite_u
28c0: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 int64 types can
28d0: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 store integer va
28e0: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e lues .** between
28f0: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34 0 and +18446744
2900: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63 073709551615 inc
2910: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 lusive..*/.#ifde
2920: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 f SQLITE_INT64_T
2930: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 YPE. typedef SQ
2940: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 LITE_INT64_TYPE
2950: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 23 20 sqlite_int64;.#
2960: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 55 49 4e ifdef SQLITE_UIN
2970: 54 36 34 5f 54 59 50 45 0a 20 20 20 20 74 79 70 T64_TYPE. typ
2980: 65 64 65 66 20 53 51 4c 49 54 45 5f 55 49 4e 54 edef SQLITE_UINT
2990: 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 64_TYPE sqlite_u
29a0: 69 6e 74 36 34 3b 0a 23 20 65 6c 73 65 20 20 0a int64;.# else .
29b0: 20 20 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 typedef unsi
29c0: 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 gned SQLITE_INT6
29d0: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 4_TYPE sqlite_ui
29e0: 6e 74 36 34 3b 0a 23 20 65 6e 64 69 66 0a 23 65 nt64;.# endif.#e
29f0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 lif defined(_MSC
2a00: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 _VER) || defined
2a10: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 (__BORLANDC__).
2a20: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 typedef __int64
2a30: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 sqlite_int64;.
2a40: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 typedef unsigne
2a50: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 d __int64 sqlite
2a60: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 _uint64;.#else.
2a70: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f typedef long lo
2a80: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e ng int sqlite_in
2a90: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 t64;. typedef u
2aa0: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e nsigned long lon
2ab0: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e g int sqlite_uin
2ac0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 t64;.#endif.type
2ad0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 def sqlite_int64
2ae0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a sqlite3_int64;.
2af0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 typedef sqlite_u
2b00: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 int64 sqlite3_ui
2b10: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 nt64;../*.** If
2b20: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 compiling for a
2b30: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c processor that l
2b40: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f acks floating po
2b50: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 int support,.**
2b60: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 substitute integ
2b70: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d er for floating-
2b80: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 point..*/.#ifdef
2b90: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f SQLITE_OMIT_FLO
2ba0: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 ATING_POINT.# de
2bb0: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 fine double sqli
2bc0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 te3_int64.#endif
2bd0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2be0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 : Closing A Data
2bf0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a base Connection.
2c00: 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73 ** DESTRUCTOR: s
2c10: 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 qlite3.**.** ^Th
2c20: 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 e sqlite3_close(
2c30: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c ) and sqlite3_cl
2c40: 6f 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 ose_v2() routine
2c50: 73 20 61 72 65 20 64 65 73 74 72 75 63 74 6f 72 s are destructor
2c60: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 s.** for the [sq
2c70: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a lite3] object..*
2c80: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 * ^Calls to sqli
2c90: 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 te3_close() and
2ca0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 sqlite3_close_v2
2cb0: 28 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 () return [SQLIT
2cc0: 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20 E_OK] if.** the
2cd0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 [sqlite3] object
2ce0: 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79 is successfully
2cf0: 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61 destroyed and a
2d00: 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a ll associated.**
2d10: 20 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64 resources are d
2d20: 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a eallocated..**.*
2d30: 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 * ^If the databa
2d40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
2d50: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
2d60: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 unfinalized pre
2d70: 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 pared.** stateme
2d80: 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65 nts or unfinishe
2d90: 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 d sqlite3_backup
2da0: 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71 objects then sq
2db0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a lite3_close().**
2dc0: 20 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 will leave the
2dd0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2de0: 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74 ion open and ret
2df0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 urn [SQLITE_BUSY
2e00: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 ]..** ^If sqlite
2e10: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 3_close_v2() is
2e20: 63 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69 called with unfi
2e30: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 nalized prepared
2e40: 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 statements.** a
2e50: 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 nd/or unfinished
2e60: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73 sqlite3_backups
2e70: 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 , then the datab
2e80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 ase connection b
2e90: 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 ecomes.** an unu
2ea0: 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77 sable "zombie" w
2eb0: 68 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61 hich will automa
2ec0: 74 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c tically be deall
2ed0: 6f 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a ocated when the.
2ee0: 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65 64 ** last prepared
2ef0: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69 statement is fi
2f00: 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c nalized or the l
2f10: 61 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b ast sqlite3_back
2f20: 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65 up is.** finishe
2f30: 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f d. The sqlite3_
2f40: 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72 close_v2() inter
2f50: 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64 face is intended
2f60: 20 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a for use with.**
2f70: 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20 host languages
2f80: 74 68 61 74 20 61 72 65 20 67 61 72 62 61 67 65 that are garbage
2f90: 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20 collected, and
2fa0: 77 68 65 72 65 20 74 68 65 20 6f 72 64 65 72 20 where the order
2fb0: 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74 in which.** dest
2fc0: 72 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c ructors are call
2fd0: 65 64 20 69 73 20 61 72 62 69 74 72 61 72 79 2e ed is arbitrary.
2fe0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 .**.** Applicati
2ff0: 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 ons should [sqli
3000: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 te3_finalize | f
3010: 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 inalize] all [pr
3020: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
3030: 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f s],.** [sqlite3_
3040: 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f blob_close | clo
3050: 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 se] all [BLOB ha
3060: 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 ndles], and .**
3070: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f [sqlite3_backup_
3080: 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d finish | finish]
3090: 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61 all [sqlite3_ba
30a0: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73 ckup] objects as
30b0: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 sociated.** with
30c0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f the [sqlite3] o
30d0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 bject prior to a
30e0: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f ttempting to clo
30f0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 se the object.
3100: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 ^If.** sqlite3_c
3110: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c lose_v2() is cal
3120: 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 led on a [databa
3130: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 se connection] t
3140: 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a hat still has.**
3150: 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 outstanding [pr
3160: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
3170: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 s], [BLOB handle
3180: 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 s], and/or.** [s
3190: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f qlite3_backup] o
31a0: 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72 bjects then it r
31b0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
31c0: 4b 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c K] and the deall
31d0: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 ocation.** of re
31e0: 73 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72 sources is defer
31f0: 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 red until all [p
3200: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
3210: 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c ts], [BLOB handl
3220: 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c es],.** and [sql
3230: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a ite3_backup] obj
3240: 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65 ects are also de
3250: 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e stroyed..**.** ^
3260: 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 If an [sqlite3]
3270: 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f object is destro
3280: 79 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e yed while a tran
3290: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c saction is open,
32a0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 .** the transact
32b0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 ion is automatic
32c0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b ally rolled back
32d0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 ..**.** The C pa
32e0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
32f0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e te3_close(C)] an
3300: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 d [sqlite3_close
3310: 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 _v2(C)].** must
3320: 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c be either a NULL
3330: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 .** pointer or a
3340: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 n [sqlite3] obje
3350: 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 ct pointer obtai
3360: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c ned.** from [sql
3370: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 ite3_open()], [s
3380: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
3390: 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 , or.** [sqlite3
33a0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 _open_v2()], and
33b0: 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 not previously
33c0: 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c closed..** ^Call
33d0: 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 ing sqlite3_clos
33e0: 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 e() or sqlite3_c
33f0: 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61 lose_v2() with a
3400: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a NULL pointer.**
3410: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68 argument is a h
3420: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a armless no-op..*
3430: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c /.int sqlite3_cl
3440: 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69 ose(sqlite3*);.i
3450: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 nt sqlite3_close
3460: 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a _v2(sqlite3*);..
3470: 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 /*.** The type f
3480: 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 or a callback fu
3490: 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 nction..** This
34a0: 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 is legacy and de
34b0: 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 precated. It is
34c0: 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 included for hi
34d0: 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 storical.** comp
34e0: 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 atibility and is
34f0: 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e not documented.
3500: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 .*/.typedef int
3510: 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 (*sqlite3_callba
3520: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 ck)(void*,int,ch
3530: 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a ar**, char**);..
3540: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
3550: 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 One-Step Query E
3560: 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 xecution Interfa
3570: 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 ce.** METHOD: sq
3580: 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 lite3.**.** The
3590: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
35a0: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f nterface is a co
35b0: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65 nvenience wrappe
35c0: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c r around.** [sql
35d0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
35e0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 )], [sqlite3_ste
35f0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 p()], and [sqlit
3600: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a e3_finalize()],.
3610: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 ** that allows a
3620: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f n application to
3630: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 run multiple st
3640: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a atements of SQL.
3650: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e ** without havin
3660: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f g to use a lot o
3670: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a f C code. .**.**
3680: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 ^The sqlite3_ex
3690: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 ec() interface r
36a0: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 uns zero or more
36b0: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a UTF-8 encoded,.
36c0: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 ** semicolon-sep
36d0: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d arate SQL statem
36e0: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f ents passed into
36f0: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e its 2nd argumen
3700: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e t,.** in the con
3710: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74 text of the [dat
3720: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
3730: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69 ] passed in as i
3740: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 ts 1st.** argume
3750: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c nt. ^If the cal
3760: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f lback function o
3770: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 f the 3rd argume
3780: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 nt to.** sqlite3
3790: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e _exec() is not N
37a0: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20 ULL, then it is
37b0: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 invoked for each
37c0: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 result row.** c
37d0: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 oming out of the
37e0: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73 evaluated SQL s
37f0: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 tatements. ^The
3800: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 4th argument to
3810: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 .** sqlite3_exec
3820: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 () is relayed th
3830: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 rough to the 1st
3840: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 argument of eac
3850: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e h.** callback in
3860: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 vocation. ^If t
3870: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e he callback poin
3880: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 ter to sqlite3_e
3890: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c xec().** is NULL
38a0: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 , then no callba
38b0: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b ck is ever invok
38c0: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f ed and result ro
38d0: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 ws are.** ignore
38e0: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 d..**.** ^If an
38f0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 error occurs whi
3900: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 le evaluating th
3910: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 e SQL statements
3920: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 passed into.**
3930: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 sqlite3_exec(),
3940: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f then execution o
3950: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 f the current st
3960: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e atement stops an
3970: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 d.** subsequent
3980: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 statements are s
3990: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 kipped. ^If the
39a0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 5th parameter t
39b0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 o sqlite3_exec()
39c0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 .** is not NULL
39d0: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d then any error m
39e0: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 essage is writte
39f0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 n into memory ob
3a00: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b tained.** from [
3a10: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
3a20: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 ] and passed bac
3a30: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 k through the 5t
3a40: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 h parameter..**
3a50: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 To avoid memory
3a60: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 leaks, the appli
3a70: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e cation should in
3a80: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 voke [sqlite3_fr
3a90: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f ee()].** on erro
3aa0: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 r message string
3ab0: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 s returned throu
3ac0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d gh the 5th param
3ad0: 65 74 65 72 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 eter of.** sqlit
3ae0: 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20 e3_exec() after
3af0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 the error messag
3b00: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c e string is no l
3b10: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a onger needed..**
3b20: 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 ^If the 5th par
3b30: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
3b40: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 3_exec() is not
3b50: 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f NULL and no erro
3b60: 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 rs.** occur, the
3b70: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 n sqlite3_exec()
3b80: 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65 sets the pointe
3b90: 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72 r in its 5th par
3ba0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c ameter to.** NUL
3bb0: 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 L before returni
3bc0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e ng..**.** ^If an
3bd0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
3be0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
3bf0: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 non-zero, the s
3c00: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a qlite3_exec().**
3c10: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
3c20: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 SQLITE_ABORT wi
3c30: 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 thout invoking t
3c40: 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 he callback agai
3c50: 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 n and.** without
3c60: 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 running any sub
3c70: 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 sequent SQL stat
3c80: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ements..**.** ^T
3c90: 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 he 2nd argument
3ca0: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 to the sqlite3_e
3cb0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 xec() callback f
3cc0: 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a unction is the.*
3cd0: 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 * number of colu
3ce0: 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c mns in the resul
3cf0: 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67 t. ^The 3rd arg
3d00: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c ument to the sql
3d10: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 ite3_exec().** c
3d20: 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 allback is an ar
3d30: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 ray of pointers
3d40: 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69 to strings obtai
3d50: 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a ned as if from.*
3d60: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
3d70: 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 n_text()], one f
3d80: 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 or each column.
3d90: 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 ^If an element
3da0: 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 of a.** result r
3db0: 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 ow is NULL then
3dc0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
3dd0: 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 g string pointer
3de0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 for the.** sqli
3df0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 te3_exec() callb
3e00: 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f ack is a NULL po
3e10: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68 inter. ^The 4th
3e20: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
3e30: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 .** sqlite3_exec
3e40: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 () callback is a
3e50: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 n array of point
3e60: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77 ers to strings w
3e70: 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 here each.** ent
3e80: 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68 ry represents th
3e90: 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 e name of corres
3ea0: 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63 ponding result c
3eb0: 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 olumn as obtaine
3ec0: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 d.** from [sqlit
3ed0: 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 e3_column_name()
3ee0: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 ]..**.** ^If the
3ef0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 2nd parameter t
3f00: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 o sqlite3_exec()
3f10: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
3f20: 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a er, a pointer.**
3f30: 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 to an empty str
3f40: 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 ing, or a pointe
3f50: 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 r that contains
3f60: 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 only whitespace
3f70: 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 and/or .** SQL c
3f80: 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f omments, then no
3f90: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
3fa0: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e are evaluated an
3fb0: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a d the database.*
3fc0: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 * is not changed
3fd0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 ..**.** Restrict
3fe0: 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ions:.**.** <ul>
3ff0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 .** <li> The app
4000: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 65 6e lication must en
4010: 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73 sure that the 1s
4020: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 t parameter to s
4030: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a qlite3_exec().**
4040: 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64 is a valid
4050: 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 and open [datab
4060: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e ase connection].
4070: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 .** <li> The app
4080: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f lication must no
4090: 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61 74 t close the [dat
40a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
40b0: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a ] specified by.*
40c0: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70 * the 1st p
40d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
40e0: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 te3_exec() while
40f0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
4100: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c is running..** <
4110: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 li> The applicat
4120: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 ion must not mod
4130: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 ify the SQL stat
4140: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 ement text passe
4150: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 d into.** t
4160: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
4170: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 of sqlite3_exec
4180: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 () while sqlite3
4190: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 _exec() is runni
41a0: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a ng..** </ul>.*/.
41b0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 int sqlite3_exec
41c0: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 (. sqlite3*,
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
41f0: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 * An open databa
4200: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 se */. const ch
4210: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 ar *sql,
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4230: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 /* SQL to be
4240: 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 evaluated */. i
4250: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 nt (*callback)(v
4260: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c oid*,int,char**,
4270: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c char**), /* Cal
4280: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a lback function *
4290: 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 /. void *,
42a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
42b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
42c0: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 * 1st argument t
42d0: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 o callback */.
42e0: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 char **errmsg
42f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4300: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 /* Er
4310: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 ror msg written
4320: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a here */.);../*.*
4330: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 * CAPI3REF: Resu
4340: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 lt Codes.** KEYW
4350: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f ORDS: {result co
4360: 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a de definitions}.
4370: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 **.** Many SQLit
4380: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 e functions retu
4390: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65 rn an integer re
43a0: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 sult code from t
43b0: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 he set shown.**
43c0: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f here in order to
43d0: 20 69 6e 64 69 63 61 74 65 20 73 75 63 63 65 73 indicate succes
43e0: 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a s or failure..**
43f0: 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f .** New error co
4400: 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 des may be added
4410: 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 in future versi
4420: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a ons of SQLite..*
4430: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
4440: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
4450: 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 code definitions
4460: 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ].*/.#define SQL
4470: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 ITE_OK
4480: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 0 /* Successf
4490: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 ul result */./*
44a0: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 beginning-of-err
44b0: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 or-codes */.#def
44c0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 ine SQLITE_ERROR
44d0: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 1 /* S
44e0: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 QL error or miss
44f0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a ing database */.
4500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
4510: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 NTERNAL 2
4520: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 /* Internal logi
4530: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 c error in SQLit
4540: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
4550: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20 ITE_PERM
4560: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70 3 /* Access p
4570: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 ermission denied
4580: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4590: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20 TE_ABORT
45a0: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 4 /* Callback
45b0: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 routine requeste
45c0: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 d an abort */.#d
45d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 efine SQLITE_BUS
45e0: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a Y 5 /*
45f0: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69 The database fi
4600: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a le is locked */.
4610: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
4620: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20 OCKED 6
4630: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68 /* A table in th
4640: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f e database is lo
4650: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 cked */.#define
4660: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 SQLITE_NOMEM
4670: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 7 /* A mal
4680: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a loc() failed */.
4690: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
46a0: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 EADONLY 8
46b0: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72 /* Attempt to wr
46c0: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 ite a readonly d
46d0: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 atabase */.#defi
46e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 ne SQLITE_INTERR
46f0: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 UPT 9 /* Op
4700: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 eration terminat
4710: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e ed by sqlite3_in
4720: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 terrupt()*/.#def
4730: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
4740: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53 10 /* S
4750: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b ome kind of disk
4760: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 I/O error occur
4770: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 red */.#define S
4780: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20 QLITE_CORRUPT
4790: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61 11 /* The da
47a0: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67 tabase disk imag
47b0: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a e is malformed *
47c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
47d0: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20 _NOTFOUND 12
47e0: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 /* Unknown opc
47f0: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 ode in sqlite3_f
4800: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f ile_control() */
4810: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4820: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 FULL 13
4830: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 /* Insertion fa
4840: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74 iled because dat
4850: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f abase is full */
4860: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4870: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 CANTOPEN 14
4880: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 /* Unable to op
4890: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
48a0: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 file */.#define
48b0: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 SQLITE_PROTOCOL
48c0: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62 15 /* Datab
48d0: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f ase lock protoco
48e0: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 l error */.#defi
48f0: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 ne SQLITE_EMPTY
4900: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 16 /* Da
4910: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 tabase is empty
4920: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4930: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 E_SCHEMA 17
4940: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 /* The databa
4950: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 se schema change
4960: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
4970: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 ITE_TOOBIG
4980: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 18 /* String o
4990: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 r BLOB exceeds s
49a0: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 ize limit */.#de
49b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
49c0: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 TRAINT 19 /*
49d0: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e Abort due to con
49e0: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f straint violatio
49f0: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c n */.#define SQL
4a00: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 ITE_MISMATCH
4a10: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 20 /* Data typ
4a20: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 e mismatch */.#d
4a30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 efine SQLITE_MIS
4a40: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a USE 21 /*
4a50: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e Library used in
4a60: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 correctly */.#de
4a70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 fine SQLITE_NOLF
4a80: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 S 22 /*
4a90: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 Uses OS features
4aa0: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f not supported o
4ab0: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e n host */.#defin
4ac0: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 e SQLITE_AUTH
4ad0: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 23 /* Aut
4ae0: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 horization denie
4af0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
4b00: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 ITE_FORMAT
4b10: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 24 /* Auxiliar
4b20: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 y database forma
4b30: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 t error */.#defi
4b40: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 ne SQLITE_RANGE
4b50: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 25 /* 2n
4b60: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 d parameter to s
4b70: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 qlite3_bind out
4b80: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 of range */.#def
4b90: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 ine SQLITE_NOTAD
4ba0: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 B 26 /* F
4bb0: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 ile opened that
4bc0: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 is not a databas
4bd0: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e e file */.#defin
4be0: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 e SQLITE_NOTICE
4bf0: 20 20 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 27 /* Not
4c00: 69 66 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 ifications from
4c10: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f sqlite3_log() */
4c20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4c30: 57 41 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20 WARNING 28
4c40: 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f /* Warnings fro
4c50: 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 m sqlite3_log()
4c60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4c70: 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 E_ROW 10
4c80: 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 0 /* sqlite3_st
4c90: 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 ep() has another
4ca0: 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 row ready */.#d
4cb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e efine SQLITE_DON
4cc0: 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a E 101 /*
4cd0: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
4ce0: 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 has finished exe
4cf0: 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 cuting */./* end
4d00: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 -of-error-codes
4d10: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
4d20: 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 EF: Extended Res
4d30: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 ult Codes.** KEY
4d40: 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 WORDS: {extended
4d50: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 result code def
4d60: 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 initions}.**.**
4d70: 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 In its default c
4d80: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 onfiguration, SQ
4d90: 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 Lite API routine
4da0: 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 s return one of
4db0: 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 30 integer.** [r
4dc0: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 esult codes]. H
4dd0: 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e owever, experien
4de0: 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 ce has shown tha
4df0: 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 t many of.** the
4e00: 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 se result codes
4e10: 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 are too coarse-g
4e20: 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f rained. They do
4e30: 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a not provide as.
4e40: 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 ** much informat
4e50: 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 ion about proble
4e60: 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 ms as programmer
4e70: 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 s might like. I
4e80: 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a n an effort to.*
4e90: 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 * address this,
4ea0: 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f newer versions o
4eb0: 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f f SQLite (versio
4ec0: 6e 20 33 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a n 3.3.8 [dateof:
4ed0: 33 2e 33 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 3.3.8].** and la
4ee0: 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 ter) include.**
4ef0: 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 support for addi
4f00: 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f tional result co
4f10: 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 des that provide
4f20: 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 more detailed i
4f30: 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 nformation.** ab
4f40: 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 73 out errors. Thes
4f50: 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 e [extended resu
4f60: 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20 65 6e lt codes] are en
4f70: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 abled or disable
4f80: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 d.** on a per da
4f90: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
4fa0: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 n basis using th
4fb0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 e.** [sqlite3_ex
4fc0: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f tended_result_co
4fd0: 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c des()] API. Or,
4fe0: 20 74 68 65 20 65 78 74 65 6e 64 65 64 20 63 6f the extended co
4ff0: 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f de for.** the mo
5000: 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f 72 20 st recent error
5010: 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 can be obtained
5020: 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 using.** [sqlite
5030: 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 3_extended_errco
5040: 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e de()]..*/.#defin
5050: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 e SQLITE_IOERR_R
5060: 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 EAD
5070: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
5080: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (1<<8)).#define
5090: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 SQLITE_IOERR_SH
50a0: 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 ORT_READ
50b0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
50c0: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (2<<8)).#define
50d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 SQLITE_IOERR_WRI
50e0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28 TE (
50f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
5100: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 3<<8)).#define S
5110: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e QLITE_IOERR_FSYN
5120: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 C (S
5130: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 QLITE_IOERR | (4
5140: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5150: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 LITE_IOERR_DIR_F
5160: 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 SYNC (SQ
5170: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c LITE_IOERR | (5<
5180: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5190: 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 ITE_IOERR_TRUNCA
51a0: 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51 4c TE (SQL
51b0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c ITE_IOERR | (6<<
51c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
51d0: 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 TE_IOERR_FSTAT
51e0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
51f0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 TE_IOERR | (7<<8
5200: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5210: 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 E_IOERR_UNLOCK
5220: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
5230: 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 E_IOERR | (8<<8)
5240: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5250: 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 _IOERR_RDLOCK
5260: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5270: 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 _IOERR | (9<<8))
5280: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5290: 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 IOERR_DELETE
52a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
52b0: 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 IOERR | (10<<8))
52c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
52d0: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 IOERR_BLOCKED
52e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
52f0: 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 IOERR | (11<<8))
5300: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5310: 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 IOERR_NOMEM
5320: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5330: 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 IOERR | (12<<8))
5340: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5350: 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 IOERR_ACCESS
5360: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5370: 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 IOERR | (13<<8))
5380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5390: 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 IOERR_CHECKRESER
53a0: 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f VEDLOCK (SQLITE_
53b0: 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 IOERR | (14<<8))
53c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
53d0: 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 IOERR_LOCK
53e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
53f0: 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 IOERR | (15<<8))
5400: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5410: 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 IOERR_CLOSE
5420: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5430: 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 IOERR | (16<<8))
5440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5450: 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 IOERR_DIR_CLOSE
5460: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5470: 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 IOERR | (17<<8))
5480: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5490: 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 IOERR_SHMOPEN
54a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
54b0: 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 IOERR | (18<<8))
54c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
54d0: 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 IOERR_SHMSIZE
54e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
54f0: 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 IOERR | (19<<8))
5500: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5510: 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 IOERR_SHMLOCK
5520: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5530: 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 IOERR | (20<<8))
5540: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5550: 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 IOERR_SHMMAP
5560: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5570: 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 IOERR | (21<<8))
5580: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5590: 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20 IOERR_SEEK
55a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
55b0: 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 IOERR | (22<<8))
55c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
55d0: 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 IOERR_DELETE_NOE
55e0: 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f NT (SQLITE_
55f0: 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 IOERR | (23<<8))
5600: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5610: 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20 20 20 IOERR_MMAP
5620: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5630: 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38 29 29 IOERR | (24<<8))
5640: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5650: 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50 41 54 IOERR_GETTEMPPAT
5660: 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f H (SQLITE_
5670: 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38 29 29 IOERR | (25<<8))
5680: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5690: 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48 20 20 IOERR_CONVPATH
56a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
56b0: 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38 29 29 IOERR | (26<<8))
56c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
56d0: 49 4f 45 52 52 5f 56 4e 4f 44 45 20 20 20 20 20 IOERR_VNODE
56e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
56f0: 49 4f 45 52 52 20 7c 20 28 32 37 3c 3c 38 29 29 IOERR | (27<<8))
5700: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5710: 49 4f 45 52 52 5f 41 55 54 48 20 20 20 20 20 20 IOERR_AUTH
5720: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5730: 49 4f 45 52 52 20 7c 20 28 32 38 3c 3c 38 29 29 IOERR | (28<<8))
5740: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5750: 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 LOCKED_SHAREDCAC
5760: 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f HE (SQLITE_
5770: 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 LOCKED | (1<<8)
5780: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5790: 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20 _BUSY_RECOVERY
57a0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
57b0: 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 _BUSY | (1<<8
57c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
57d0: 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f 54 20 E_BUSY_SNAPSHOT
57e0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
57f0: 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32 3c 3c E_BUSY | (2<<
5800: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5810: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 TE_CANTOPEN_NOTE
5820: 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 4c 49 MPDIR (SQLI
5830: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 TE_CANTOPEN | (1
5840: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5850: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 LITE_CANTOPEN_IS
5860: 44 49 52 20 20 20 20 20 20 20 20 20 20 28 53 51 DIR (SQ
5870: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 LITE_CANTOPEN |
5880: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (2<<8)).#define
5890: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f SQLITE_CANTOPEN_
58a0: 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20 28 FULLPATH (
58b0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 SQLITE_CANTOPEN
58c0: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (3<<8)).#defin
58d0: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 e SQLITE_CANTOPE
58e0: 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 N_CONVPATH
58f0: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 (SQLITE_CANTOPE
5900: 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 N | (4<<8)).#def
5910: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 ine SQLITE_CORRU
5920: 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 PT_VTAB
5930: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 (SQLITE_CORRU
5940: 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 PT | (1<<8)).#de
5950: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 fine SQLITE_READ
5960: 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20 ONLY_RECOVERY
5970: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 (SQLITE_READ
5980: 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 ONLY | (1<<8)).#
5990: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 define SQLITE_RE
59a0: 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 ADONLY_CANTLOCK
59b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 (SQLITE_RE
59c0: 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 ADONLY | (2<<8))
59d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
59e0: 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 READONLY_ROLLBAC
59f0: 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f K (SQLITE_
5a00: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 READONLY | (3<<8
5a10: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5a20: 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 E_READONLY_DBMOV
5a30: 45 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 ED (SQLIT
5a40: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c E_READONLY | (4<
5a50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5a60: 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 ITE_ABORT_ROLLBA
5a70: 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 4c CK (SQL
5a80: 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c ITE_ABORT | (2<<
5a90: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5aa0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 TE_CONSTRAINT_CH
5ab0: 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49 ECK (SQLI
5ac0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 TE_CONSTRAINT |
5ad0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (1<<8)).#define
5ae0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5af0: 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 T_COMMITHOOK (
5b00: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5b10: 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 T | (2<<8)).#def
5b20: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 ine SQLITE_CONST
5b30: 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 RAINT_FOREIGNKEY
5b40: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 (SQLITE_CONST
5b50: 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a RAINT | (3<<8)).
5b60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
5b70: 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 ONSTRAINT_FUNCTI
5b80: 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 ON (SQLITE_C
5b90: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c ONSTRAINT | (4<<
5ba0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5bb0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f TE_CONSTRAINT_NO
5bc0: 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 TNULL (SQLI
5bd0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 TE_CONSTRAINT |
5be0: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (5<<8)).#define
5bf0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5c00: 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28 T_PRIMARYKEY (
5c10: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5c20: 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 T | (6<<8)).#def
5c30: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 ine SQLITE_CONST
5c40: 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20 20 RAINT_TRIGGER
5c50: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 (SQLITE_CONST
5c60: 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a RAINT | (7<<8)).
5c70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
5c80: 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 ONSTRAINT_UNIQUE
5c90: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 (SQLITE_C
5ca0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c ONSTRAINT | (8<<
5cb0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5cc0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 TE_CONSTRAINT_VT
5cd0: 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 AB (SQLI
5ce0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 TE_CONSTRAINT |
5cf0: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (9<<8)).#define
5d00: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5d10: 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20 28 T_ROWID (
5d20: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5d30: 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 T |(10<<8)).#def
5d40: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 ine SQLITE_NOTIC
5d50: 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 E_RECOVER_WAL
5d60: 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 (SQLITE_NOTIC
5d70: 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 E | (1<<8)).#def
5d80: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 ine SQLITE_NOTIC
5d90: 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 E_RECOVER_ROLLBA
5da0: 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 CK (SQLITE_NOTIC
5db0: 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 E | (2<<8)).#def
5dc0: 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 ine SQLITE_WARNI
5dd0: 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20 NG_AUTOINDEX
5de0: 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 (SQLITE_WARNI
5df0: 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 NG | (1<<8)).#de
5e00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 fine SQLITE_AUTH
5e10: 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20 20 _USER
5e20: 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54 48 (SQLITE_AUTH
5e30: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 | (1<<8)).#defi
5e40: 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 ne SQLITE_OK_LOA
5e50: 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 20 20 D_PERMANENTLY
5e60: 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 28 (SQLITE_OK | (
5e70: 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 1<<8))../*.** CA
5e80: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f PI3REF: Flags Fo
5e90: 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 r File Open Oper
5ea0: 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 ations.**.** The
5eb0: 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 se bit values ar
5ec0: 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 e intended for u
5ed0: 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 se in the.** 3rd
5ee0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
5ef0: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f e [sqlite3_open_
5f00: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 v2()] interface
5f10: 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 and.** in the 4t
5f20: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
5f30: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e he [sqlite3_vfs.
5f40: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a xOpen] method..*
5f50: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
5f60: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 _OPEN_READONLY
5f70: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 0x0000000
5f80: 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 1 /* Ok for sql
5f90: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a ite3_open_v2() *
5fa0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
5fb0: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 _OPEN_READWRITE
5fc0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 0x0000000
5fd0: 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 2 /* Ok for sql
5fe0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a ite3_open_v2() *
5ff0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6000: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 _OPEN_CREATE
6010: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 0x0000000
6020: 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 4 /* Ok for sql
6030: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a ite3_open_v2() *
6040: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6050: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c _OPEN_DELETEONCL
6060: 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 OSE 0x0000000
6070: 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 8 /* VFS only *
6080: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6090: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 _OPEN_EXCLUSIVE
60a0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 0x0000001
60b0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 0 /* VFS only *
60c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
60d0: 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 _OPEN_AUTOPROXY
60e0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 0x0000002
60f0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 0 /* VFS only *
6100: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6110: 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 _OPEN_URI
6120: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 0x0000004
6130: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 0 /* Ok for sql
6140: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a ite3_open_v2() *
6150: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6160: 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 _OPEN_MEMORY
6170: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 0x0000008
6180: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 0 /* Ok for sql
6190: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a ite3_open_v2() *
61a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
61b0: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 _OPEN_MAIN_DB
61c0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 0x0000010
61d0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 0 /* VFS only *
61e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
61f0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 _OPEN_TEMP_DB
6200: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 0x0000020
6210: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 0 /* VFS only *
6220: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6230: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f _OPEN_TRANSIENT_
6240: 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 DB 0x0000040
6250: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 0 /* VFS only *
6260: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6270: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e _OPEN_MAIN_JOURN
6280: 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 AL 0x0000080
6290: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 0 /* VFS only *
62a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
62b0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e _OPEN_TEMP_JOURN
62c0: 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 AL 0x0000100
62d0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 0 /* VFS only *
62e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
62f0: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c _OPEN_SUBJOURNAL
6300: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 0x0000200
6310: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 0 /* VFS only *
6320: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6330: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 _OPEN_MASTER_JOU
6340: 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 RNAL 0x0000400
6350: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 0 /* VFS only *
6360: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6370: 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 _OPEN_NOMUTEX
6380: 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 0x0000800
6390: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 0 /* Ok for sql
63a0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a ite3_open_v2() *
63b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
63c0: 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 _OPEN_FULLMUTEX
63d0: 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 0x0001000
63e0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 0 /* Ok for sql
63f0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a ite3_open_v2() *
6400: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6410: 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 _OPEN_SHAREDCACH
6420: 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 E 0x0002000
6430: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 0 /* Ok for sql
6440: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a ite3_open_v2() *
6450: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6460: 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 _OPEN_PRIVATECAC
6470: 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 HE 0x0004000
6480: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 0 /* Ok for sql
6490: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a ite3_open_v2() *
64a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
64b0: 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 _OPEN_WAL
64c0: 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 0x0008000
64d0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 0 /* VFS only *
64e0: 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 /../* Reserved:
64f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6500: 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 0x00F000
6510: 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 00 */../*.** CAP
6520: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 I3REF: Device Ch
6530: 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a aracteristics.**
6540: 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 .** The xDeviceC
6550: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d haracteristics m
6560: 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 ethod of the [sq
6570: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
6580: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 ].** object retu
6590: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 rns an integer w
65a0: 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 hich is a vector
65b0: 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 of these.** bit
65c0: 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 values expressi
65d0: 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 ng I/O character
65e0: 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 istics of the ma
65f0: 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 ss storage.** de
6600: 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 vice that holds
6610: 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 the file that th
6620: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 e [sqlite3_io_me
6630: 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 thods].** refers
6640: 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 to..**.** The S
6650: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
6660: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e IC property mean
6670: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 s that all write
6680: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 s of.** any size
6690: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 are atomic. Th
66a0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
66b0: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a TOMICnnn values.
66c0: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 ** mean that wri
66d0: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 tes of blocks th
66e0: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 at are nnn bytes
66f0: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 in size and.**
6700: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 are aligned to a
6710: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 n address which
6720: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 is an integer mu
6730: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e ltiple of.** nnn
6740: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 are atomic. Th
6750: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 e SQLITE_IOCAP_S
6760: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 AFE_APPEND value
6770: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 means.** that w
6780: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 hen data is appe
6790: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 nded to a file,
67a0: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 the data is appe
67b0: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 nded.** first th
67c0: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 en the size of t
67d0: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e he file is exten
67e0: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f ded, never the o
67f0: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 ther.** way arou
6800: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f nd. The SQLITE_
6810: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c IOCAP_SEQUENTIAL
6820: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 property means
6830: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 that.** informat
6840: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 ion is written t
6850: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 o disk in the sa
6860: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c me order as call
6870: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 s.** to xWrite()
6880: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
6890: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 CAP_POWERSAFE_OV
68a0: 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 ERWRITE property
68b0: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 means that.** a
68c0: 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c fter reboot foll
68d0: 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 owing a crash or
68e0: 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 power loss, the
68f0: 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 only bytes in a
6900: 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 .** file that we
6910: 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 re written at th
6920: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 e application le
6930: 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 vel might have c
6940: 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 hanged.** and th
6950: 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 at adjacent byte
6960: 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 s, even bytes wi
6970: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 thin the same se
6980: 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 ctor are.** guar
6990: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 anteed to be unc
69a0: 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c hanged. The SQL
69b0: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 ITE_IOCAP_UNDELE
69c0: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a TABLE_WHEN_OPEN.
69d0: 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 ** flag indicate
69e0: 73 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61 s that a file ca
69f0: 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20 nnot be deleted
6a00: 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a when open. The.
6a10: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ** SQLITE_IOCAP_
6a20: 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69 IMMUTABLE flag i
6a30: 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68 ndicates that th
6a40: 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 e file is on.**
6a50: 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 read-only media
6a60: 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 and cannot be ch
6a70: 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 72 anged even by pr
6a80: 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 ocesses with.**
6a90: 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c 65 elevated privile
6aa0: 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ges..*/.#define
6ab0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
6ac0: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20 MIC
6ad0: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 0x00000001.#
6ae0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
6af0: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 CAP_ATOMIC512
6b00: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
6b10: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 00002.#define SQ
6b20: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
6b30: 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 C1K
6b40: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 0x00000004.#de
6b50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
6b60: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 P_ATOMIC2K
6b70: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
6b80: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 008.#define SQLI
6b90: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 TE_IOCAP_ATOMIC4
6ba0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 K
6bb0: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 0x00000010.#defi
6bc0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
6bd0: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 ATOMIC8K
6be0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 0x0000002
6bf0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
6c00: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b _IOCAP_ATOMIC16K
6c10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 0x
6c20: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 00000040.#define
6c30: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
6c40: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 OMIC32K
6c50: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 0x00000080.
6c60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
6c70: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 OCAP_ATOMIC64K
6c80: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
6c90: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 000100.#define S
6ca0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 QLITE_IOCAP_SAFE
6cb0: 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 _APPEND
6cc0: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 0x00000200.#d
6cd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
6ce0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 AP_SEQUENTIAL
6cf0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
6d00: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0400.#define SQL
6d10: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 ITE_IOCAP_UNDELE
6d20: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 TABLE_WHEN_OPEN
6d30: 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 0x00000800.#def
6d40: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
6d50: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 _POWERSAFE_OVERW
6d60: 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30 RITE 0x000010
6d70: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 00.#define SQLIT
6d80: 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c E_IOCAP_IMMUTABL
6d90: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 E 0
6da0: 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a x00002000../*.**
6db0: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 CAPI3REF: File
6dc0: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a Locking Levels.*
6dd0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 *.** SQLite uses
6de0: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e one of these in
6df0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 teger values as
6e00: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 the second.** ar
6e10: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 gument to calls
6e20: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 it makes to the
6e30: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c xLock() and xUnl
6e40: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a ock() methods.**
6e50: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f of an [sqlite3_
6e60: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 io_methods] obje
6e70: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ct..*/.#define S
6e80: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 QLITE_LOCK_NONE
6e90: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 0.#defi
6ea0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 ne SQLITE_LOCK_S
6eb0: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 HARED 1.#
6ec0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
6ed0: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 CK_RESERVED
6ee0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
6ef0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 E_LOCK_PENDING
6f00: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 3.#define S
6f10: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 QLITE_LOCK_EXCLU
6f20: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a SIVE 4../*.*
6f30: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 * CAPI3REF: Sync
6f40: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 hronization Type
6f50: 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 Flags.**.** Whe
6f60: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 n SQLite invokes
6f70: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 the xSync() met
6f80: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 hod of an.** [sq
6f90: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
6fa0: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 ] object it uses
6fb0: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f a combination o
6fc0: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 f.** these integ
6fd0: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 er values as the
6fe0: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
6ff0: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 ..**.** When the
7000: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 SQLITE_SYNC_DAT
7010: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 AONLY flag is us
7020: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 ed, it means tha
7030: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 t the.** sync op
7040: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 eration only nee
7050: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 ds to flush data
7060: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 to mass storage
7070: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f . Inode.** info
7080: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 rmation need not
7090: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 be flushed. If
70a0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 the lower four b
70b0: 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a its of the flag.
70c0: 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f ** equal SQLITE_
70d0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 SYNC_NORMAL, tha
70e0: 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e t means to use n
70f0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 ormal fsync() se
7100: 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 mantics..** If t
7110: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 he lower four bi
7120: 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f ts equal SQLITE_
7130: 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 SYNC_FULL, that
7140: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 means.** to use
7150: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 Mac OS X style f
7160: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 ullsync instead
7170: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a of fsync()..**.*
7180: 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 * Do not confuse
7190: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 the SQLITE_SYNC
71a0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 _NORMAL and SQLI
71b0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 TE_SYNC_FULL fla
71c0: 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b gs.** with the [
71d0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f PRAGMA synchrono
71e0: 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b us]=NORMAL and [
71f0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f PRAGMA synchrono
7200: 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 us]=FULL.** sett
7210: 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 ings. The [sync
7220: 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 hronous pragma]
7230: 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 determines when
7240: 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 calls to the.**
7250: 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 xSync VFS method
7260: 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 occur and appli
7270: 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 es uniformly acr
7280: 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d oss all platform
7290: 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 s..** The SQLITE
72a0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 _SYNC_NORMAL and
72b0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c SQLITE_SYNC_FUL
72c0: 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e L flags determin
72d0: 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 e how.** energet
72e0: 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f ic or rigorous o
72f0: 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 r forceful the s
7300: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 ync operations a
7310: 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d re and.** only m
7320: 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 ake a difference
7330: 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 on Mac OSX for
7340: 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 the default SQLi
7350: 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 te code..** (Thi
7360: 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 rd-party VFS imp
7370: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 lementations mig
7380: 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 ht also make the
7390: 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 distinction.**
73a0: 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 between SQLITE_S
73b0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 YNC_NORMAL and S
73c0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c QLITE_SYNC_FULL,
73d0: 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a but among the.*
73e0: 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 * operating syst
73f0: 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 ems natively sup
7400: 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 ported by SQLite
7410: 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a , only Mac OSX.*
7420: 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 * cares about th
7430: 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a e difference.).*
7440: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
7450: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 _SYNC_NORMAL
7460: 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 0x00002.#def
7470: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f ine SQLITE_SYNC_
7480: 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 FULL 0x
7490: 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 00003.#define SQ
74a0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e LITE_SYNC_DATAON
74b0: 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a LY 0x00010.
74c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
74d0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 OS Interface Op
74e0: 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a en File Handle.*
74f0: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 *.** An [sqlite3
7500: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 _file] object re
7510: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e presents an open
7520: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a file in the .**
7530: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 [sqlite3_vfs |
7540: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 OS interface lay
7550: 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c er]. Individual
7560: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a OS interface.**
7570: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
7580: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f will.** want to
7590: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f subclass this o
75a0: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 bject by appendi
75b0: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 ng additional fi
75c0: 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 elds.** for thei
75d0: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 r own use. The
75e0: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 pMethods entry i
75f0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
7600: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f n.** [sqlite3_io
7610: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 _methods] object
7620: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 that defines me
7630: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 thods for perfor
7640: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 ming.** I/O oper
7650: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 ations on the op
7660: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 en file..*/.type
7670: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
7680: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f e3_file sqlite3_
7690: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c file;.struct sql
76a0: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f ite3_file {. co
76b0: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 nst struct sqlit
76c0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 e3_io_methods *p
76d0: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 Methods; /* Met
76e0: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e hods for an open
76f0: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a file */.};../*.
7700: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 ** CAPI3REF: OS
7710: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 Interface File V
7720: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f irtual Methods O
7730: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 bject.**.** Ever
7740: 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 y file opened by
7750: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 the [sqlite3_vf
7760: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 s.xOpen] method
7770: 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 populates an.**
7780: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f [sqlite3_file] o
7790: 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 bject (or, more
77a0: 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 commonly, a subc
77b0: 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b lass of the.** [
77c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 sqlite3_file] ob
77d0: 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 ject) with a poi
77e0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 nter to an insta
77f0: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 nce of this obje
7800: 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 ct..** This obje
7810: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d ct defines the m
7820: 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 ethods used to p
7830: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f erform various o
7840: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 perations.** aga
7850: 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 inst the open fi
7860: 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 le represented b
7870: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 y the [sqlite3_f
7880: 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a ile] object..**.
7890: 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 ** If the [sqlit
78a0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 e3_vfs.xOpen] me
78b0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 thod sets the sq
78c0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 lite3_file.pMeth
78d0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 ods element .**
78e0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f to a non-NULL po
78f0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 inter, then the
7900: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
7910: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 ds.xClose method
7920: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b .** may be invok
7930: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b ed even if the [
7940: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 sqlite3_vfs.xOpe
7950: 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 n] reported that
7960: 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 it failed. The
7970: 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 .** only way to
7980: 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 prevent a call t
7990: 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 o xClose followi
79a0: 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c ng a failed [sql
79b0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a ite3_vfs.xOpen].
79c0: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 ** is for the [s
79d0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e qlite3_vfs.xOpen
79e0: 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c ] to set the sql
79f0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f ite3_file.pMetho
7a00: 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f ds element.** to
7a10: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 NULL..**.** The
7a20: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 flags argument
7a30: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 to xSync may be
7a40: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 one of [SQLITE_S
7a50: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a YNC_NORMAL] or.*
7a60: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 * [SQLITE_SYNC_F
7a70: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 ULL]. The first
7a80: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e choice is the n
7a90: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a ormal fsync()..*
7aa0: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f * The second cho
7ab0: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 ice is a Mac OS
7ac0: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 X style fullsync
7ad0: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 . The [SQLITE_S
7ae0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a YNC_DATAONLY].**
7af0: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 flag may be ORe
7b00: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 d in to indicate
7b10: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 that only the d
7b20: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a ata of the file.
7b30: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 ** and not its i
7b40: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 node needs to be
7b50: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 synced..**.** T
7b60: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 he integer value
7b70: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 s to xLock() and
7b80: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f xUnlock() are o
7b90: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a ne of.** <ul>.**
7ba0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f <li> [SQLITE_LO
7bb0: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 CK_NONE],.** <li
7bc0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 > [SQLITE_LOCK_S
7bd0: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 HARED],.** <li>
7be0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 [SQLITE_LOCK_RES
7bf0: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 ERVED],.** <li>
7c00: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e [SQLITE_LOCK_PEN
7c10: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 DING], or.** <li
7c20: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 > [SQLITE_LOCK_E
7c30: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f XCLUSIVE]..** </
7c40: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 ul>.** xLock() i
7c50: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 ncreases the loc
7c60: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 k. xUnlock() dec
7c70: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e reases the lock.
7c80: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 .** The xCheckRe
7c90: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 servedLock() met
7ca0: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 hod checks wheth
7cb0: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 er any database
7cc0: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 connection,.** e
7cd0: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 ither in this pr
7ce0: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 ocess or in some
7cf0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 other process,
7d00: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 is holding a RES
7d10: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e ERVED,.** PENDIN
7d20: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 G, or EXCLUSIVE
7d30: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 lock on the file
7d40: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 . It returns tr
7d50: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 ue.** if such a
7d60: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 lock exists and
7d70: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e false otherwise.
7d80: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 .**.** The xFile
7d90: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 Control() method
7da0: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e is a generic in
7db0: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c terface that all
7dc0: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 ows custom.** VF
7dd0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e S implementation
7de0: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f s to directly co
7df0: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 ntrol an open fi
7e00: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 le using the.**
7e10: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
7e20: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 ntrol()] interfa
7e30: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 ce. The second
7e40: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 "op" argument is
7e50: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f an.** integer o
7e60: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 pcode. The thir
7e70: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 d argument is a
7e80: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 generic pointer
7e90: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 intended to.** p
7ea0: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 oint to a struct
7eb0: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e ure that may con
7ec0: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f tain arguments o
7ed0: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 r space in which
7ee0: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 to.** write ret
7ef0: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 urn values. Pot
7f00: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 ential uses for
7f10: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d xFileControl() m
7f20: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 ight be.** funct
7f30: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 ions to enable b
7f40: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 locking locks wi
7f50: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 th timeouts, to
7f60: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f change the.** lo
7f70: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 cking strategy (
7f80: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 for example to u
7f90: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b se dot-file lock
7fa0: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a s), to inquire.*
7fb0: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 * about the stat
7fc0: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 us of a lock, or
7fd0: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 to break stale
7fe0: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 locks. The SQLi
7ff0: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 te.** core reser
8000: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 ves all opcodes
8010: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f less than 100 fo
8020: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a r its own use..*
8030: 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f * A [file contro
8040: 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 l opcodes | list
8050: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 of opcodes] les
8060: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 s than 100 is av
8070: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c ailable..** Appl
8080: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 ications that de
8090: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 fine a custom xF
80a0: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f ileControl metho
80b0: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 d should use opc
80c0: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 odes.** greater
80d0: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 than 100 to avoi
80e0: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 d conflicts. VF
80f0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e S implementation
8100: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 s should.** retu
8110: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f rn [SQLITE_NOTFO
8120: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f UND] for file co
8130: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 ntrol opcodes th
8140: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a at they do not.*
8150: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a * recognize..**.
8160: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 ** The xSectorSi
8170: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 ze() method retu
8180: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 rns the sector s
8190: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 ize of the.** de
81a0: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c vice that underl
81b0: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 ies the file. T
81c0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 he sector size i
81d0: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d s the.** minimum
81e0: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 write that can
81f0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 be performed wit
8200: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a hout disturbing.
8210: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 ** other bytes i
8220: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 n the file. The
8230: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 xDeviceCharacte
8240: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 ristics().** met
8250: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 hod returns a bi
8260: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 t vector describ
8270: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 ing behaviors of
8280: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 the.** underlyi
8290: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a ng device:.**.**
82a0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 <ul>.** <li> [S
82b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
82c0: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c IC].** <li> [SQL
82d0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
82e0: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 512].** <li> [SQ
82f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
8300: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 C1K].** <li> [SQ
8310: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
8320: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 C2K].** <li> [SQ
8330: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
8340: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 C4K].** <li> [SQ
8350: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
8360: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 C8K].** <li> [SQ
8370: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
8380: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 C16K].** <li> [S
8390: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
83a0: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b IC32K].** <li> [
83b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
83c0: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 MIC64K].** <li>
83d0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 [SQLITE_IOCAP_SA
83e0: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c FE_APPEND].** <l
83f0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
8400: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 _SEQUENTIAL].**
8410: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
8420: 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 AP_UNDELETABLE_W
8430: 48 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 HEN_OPEN].** <li
8440: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
8450: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 POWERSAFE_OVERWR
8460: 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 ITE].** <li> [SQ
8470: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 LITE_IOCAP_IMMUT
8480: 41 42 4c 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a ABLE].** </ul>.*
8490: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f *.** The SQLITE_
84a0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f IOCAP_ATOMIC pro
84b0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
84c0: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a all writes of.*
84d0: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 * any size are a
84e0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 tomic. The SQLI
84f0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e TE_IOCAP_ATOMICn
8500: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 nn values.** mea
8510: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 n that writes of
8520: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 blocks that are
8530: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 nnn bytes in si
8540: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c ze and.** are al
8550: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 igned to an addr
8560: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 ess which is an
8570: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 integer multiple
8580: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 of.** nnn are a
8590: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 tomic. The SQLI
85a0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 TE_IOCAP_SAFE_AP
85b0: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 PEND value means
85c0: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 .** that when da
85d0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 ta is appended t
85e0: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 o a file, the da
85f0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a ta is appended.*
8600: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 * first then the
8610: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c size of the fil
8620: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e e is extended, n
8630: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a ever the other.*
8640: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 * way around. T
8650: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
8660: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 SEQUENTIAL prope
8670: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a rty means that.*
8680: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 * information is
8690: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b written to disk
86a0: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 in the same ord
86b0: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 er as calls.** t
86c0: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a o xWrite()..**.*
86d0: 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74 * If xRead() ret
86e0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 urns SQLITE_IOER
86f0: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 R_SHORT_READ it
8700: 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a must also fill.*
8710: 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 * in the unread
8720: 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 portions of the
8730: 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f buffer with zero
8740: 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a s. A VFS that.*
8750: 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d * fails to zero-
8760: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 fill short reads
8770: 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 might seem to w
8780: 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a ork. However,.*
8790: 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 * failure to zer
87a0: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 o-fill short rea
87b0: 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c ds will eventual
87c0: 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 ly lead to.** da
87d0: 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f tabase corruptio
87e0: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 n..*/.typedef st
87f0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f ruct sqlite3_io_
8800: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f methods sqlite3_
8810: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 io_methods;.stru
8820: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 ct sqlite3_io_me
8830: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 thods {. int iV
8840: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a ersion;. int (*
8850: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f xClose)(sqlite3_
8860: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a file*);. int (*
8870: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 xRead)(sqlite3_f
8880: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 ile*, void*, int
8890: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 iAmt, sqlite3_i
88a0: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 nt64 iOfst);. i
88b0: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c nt (*xWrite)(sql
88c0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 ite3_file*, cons
88d0: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d t void*, int iAm
88e0: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 t, sqlite3_int64
88f0: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 iOfst);. int (
8900: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 *xTruncate)(sqli
8910: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 te3_file*, sqlit
8920: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a e3_int64 size);.
8930: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 int (*xSync)(s
8940: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
8950: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 t flags);. int
8960: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c (*xFileSize)(sql
8970: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 ite3_file*, sqli
8980: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 te3_int64 *pSize
8990: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b );. int (*xLock
89a0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
89b0: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 int);. int (*x
89c0: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f Unlock)(sqlite3_
89d0: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 file*, int);. i
89e0: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 nt (*xCheckReser
89f0: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 vedLock)(sqlite3
8a00: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 _file*, int *pRe
8a10: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 sOut);. int (*x
8a20: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c FileControl)(sql
8a30: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 ite3_file*, int
8a40: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b op, void *pArg);
8a50: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 . int (*xSector
8a60: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 Size)(sqlite3_fi
8a70: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 le*);. int (*xD
8a80: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 eviceCharacteris
8a90: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 tics)(sqlite3_fi
8aa0: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f le*);. /* Metho
8ab0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c ds above are val
8ac0: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 id for version 1
8ad0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d */. int (*xShm
8ae0: 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c Map)(sqlite3_fil
8af0: 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 e*, int iPg, int
8b00: 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 pgsz, int, void
8b10: 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 volatile**);.
8b20: 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 int (*xShmLock)(
8b30: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
8b40: 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e nt offset, int n
8b50: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 , int flags);.
8b60: 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 void (*xShmBarri
8b70: 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 er)(sqlite3_file
8b80: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d *);. int (*xShm
8b90: 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 Unmap)(sqlite3_f
8ba0: 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 ile*, int delete
8bb0: 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 Flag);. /* Meth
8bc0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 ods above are va
8bd0: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 lid for version
8be0: 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65 2 */. int (*xFe
8bf0: 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c tch)(sqlite3_fil
8c00: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 e*, sqlite3_int6
8c10: 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d 4 iOfst, int iAm
8c20: 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 t, void **pp);.
8c30: 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29 int (*xUnfetch)
8c40: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
8c50: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f sqlite3_int64 iO
8c60: 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20 fst, void *p);.
8c70: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 /* Methods abov
8c80: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 e are valid for
8c90: 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f version 3 */. /
8ca0: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 * Additional met
8cb0: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 hods may be adde
8cc0: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
8cd0: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a ases */.};../*.*
8ce0: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e * CAPI3REF: Stan
8cf0: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f dard File Contro
8d00: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 l Opcodes.** KEY
8d10: 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e WORDS: {file con
8d20: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66 trol opcodes} {f
8d30: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f ile control opco
8d40: 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 de}.**.** These
8d50: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 integer constant
8d60: 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f s are opcodes fo
8d70: 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 r the xFileContr
8d80: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 ol method.** of
8d90: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f the [sqlite3_io_
8da0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 methods] object
8db0: 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c and for the [sql
8dc0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
8dd0: 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 l()].** interfac
8de0: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a e..**.** <ul>.**
8df0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
8e00: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a NTL_LOCKSTATE]].
8e10: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
8e20: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 CNTL_LOCKSTATE]
8e30: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 opcode is used f
8e40: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 or debugging. T
8e50: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 his.** opcode ca
8e60: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f uses the xFileCo
8e70: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 ntrol method to
8e80: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e write the curren
8e90: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 t state of.** th
8ea0: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b e lock (one of [
8eb0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 SQLITE_LOCK_NONE
8ec0: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f ], [SQLITE_LOCK_
8ed0: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c SHARED],.** [SQL
8ee0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 ITE_LOCK_RESERVE
8ef0: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b D], [SQLITE_LOCK
8f00: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 _PENDING], or [S
8f10: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 QLITE_LOCK_EXCLU
8f20: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 SIVE]).** into a
8f30: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 n integer that t
8f40: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 he pArg argument
8f50: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 points to. This
8f60: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 capability.** i
8f70: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 s used during te
8f80: 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e 6c sting and is onl
8f90: 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68 65 6e y available when
8fa0: 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 53 54 the SQLITE_TEST
8fb0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 .** compile-time
8fc0: 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e option is used.
8fd0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
8fe0: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 ITE_FCNTL_SIZE_H
8ff0: 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 INT]].** The [SQ
9000: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f LITE_FCNTL_SIZE_
9010: 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 HINT] opcode is
9020: 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 used by SQLite t
9030: 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a o give the VFS.*
9040: 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f * layer a hint o
9050: 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 f how large the
9060: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 database file wi
9070: 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 ll grow to be du
9080: 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 ring the.** curr
9090: 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e ent transaction.
90a0: 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e This hint is n
90b0: 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f ot guaranteed to
90c0: 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74 be accurate but
90d0: 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 it.** is often
90e0: 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 close. The unde
90f0: 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 rlying VFS might
9100: 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c choose to preal
9110: 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a locate database.
9120: 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 ** file space ba
9130: 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 sed on this hint
9140: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c in order to hel
9150: 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 p writes to the
9160: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 database.** file
9170: 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a run faster..**.
9180: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
9190: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 FCNTL_CHUNK_SIZE
91a0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 ]].** The [SQLIT
91b0: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 E_FCNTL_CHUNK_SI
91c0: 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 ZE] opcode is us
91d0: 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 ed to request th
91e0: 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 at the VFS.** ex
91f0: 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 tends and trunca
9200: 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 tes the database
9210: 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 file in chunks
9220: 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 of a size specif
9230: 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 ied.** by the us
9240: 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 er. The fourth a
9250: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 rgument to [sqli
9260: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
9270: 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 ()] should .** p
9280: 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 oint to an integ
9290: 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f er (type int) co
92a0: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 ntaining the new
92b0: 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 chunk-size to u
92c0: 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f se.** for the no
92d0: 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 minated database
92e0: 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 . Allocating dat
92f0: 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 abase file space
9300: 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 in large.** chu
9310: 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 nks (say 1MB at
9320: 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 a time), may red
9330: 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 uce file-system
9340: 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e fragmentation an
9350: 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 d.** improve per
9360: 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 formance on some
9370: 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 systems..**.**
9380: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
9390: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d TL_FILE_POINTER]
93a0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
93b0: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e _FCNTL_FILE_POIN
93c0: 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 TER] opcode is u
93d0: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 sed to obtain a
93e0: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 pointer.** to th
93f0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d e [sqlite3_file]
9400: 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 object associat
9410: 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63 ed with a partic
9420: 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a ular database.**
9430: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 connection. Se
9440: 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 e also [SQLITE_F
9450: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 CNTL_JOURNAL_POI
9460: 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 NTER]..**.** <li
9470: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
9480: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d JOURNAL_POINTER]
9490: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
94a0: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 _FCNTL_JOURNAL_P
94b0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 OINTER] opcode i
94c0: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e s used to obtain
94d0: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f a pointer.** to
94e0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 the [sqlite3_fi
94f0: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 le] object assoc
9500: 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6a iated with the j
9510: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28 65 69 74 ournal file (eit
9520: 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c 6c her.** the [roll
9530: 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f 72 back journal] or
9540: 20 74 68 65 20 5b 77 72 69 74 65 2d 61 68 65 61 the [write-ahea
9550: 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70 61 d log]) for a pa
9560: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 rticular databas
9570: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e e.** connection.
9580: 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 See also [SQLI
9590: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f TE_FCNTL_FILE_PO
95a0: 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c INTER]..**.** <l
95b0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
95c0: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a _SYNC_OMITTED]].
95d0: 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 ** No longer in
95e0: 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b use..**.** <li>[
95f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 [SQLITE_FCNTL_SY
9600: 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c NC]].** The [SQL
9610: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 ITE_FCNTL_SYNC]
9620: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 opcode is genera
9630: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 ted internally b
9640: 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 y SQLite and.**
9650: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 sent to the VFS
9660: 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f immediately befo
9670: 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 re the xSync met
9680: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f hod is invoked o
9690: 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 n a.** database
96a0: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e file descriptor.
96b0: 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e Or, if the xSyn
96c0: 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 c method is not
96d0: 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 invoked .** beca
96e0: 75 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73 use the user has
96f0: 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 configured SQLi
9700: 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 te with .** [PRA
9710: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 GMA synchronous
9720: 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f | PRAGMA synchro
9730: 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 nous=OFF] it is
9740: 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 invoked in place
9750: 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e .** of the xSyn
9760: 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 c method. In mos
9770: 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 t cases, the poi
9780: 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 nter argument pa
9790: 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 ssed with.** thi
97a0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 s file-control i
97b0: 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c s NULL. However,
97c0: 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 if the database
97d0: 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 file is being s
97e0: 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 ynced.** as part
97f0: 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 of a multi-data
9800: 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 base commit, the
9810: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 argument points
9820: 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e to a nul-termin
9830: 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 ated.** string c
9840: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 ontaining the tr
9850: 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 ansactions maste
9860: 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e r-journal file n
9870: 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 ame. VFSes that
9880: 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 .** do not need
9890: 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 this signal shou
98a0: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f ld silently igno
98b0: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 re this opcode.
98c0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a Applications .**
98d0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c should not call
98e0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 [sqlite3_file_c
98f0: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 ontrol()] with t
9900: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f his opcode as do
9910: 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 ing so may .** d
9920: 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 isrupt the opera
9930: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 tion of the spec
9940: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 ialized VFSes th
9950: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 at do require it
9960: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b . .**.** <li>[[
9970: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d SQLITE_FCNTL_COM
9980: 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a MIT_PHASETWO]].*
9990: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 * The [SQLITE_FC
99a0: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 NTL_COMMIT_PHASE
99b0: 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 TWO] opcode is g
99c0: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 enerated interna
99d0: 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a lly by SQLite.**
99e0: 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 and sent to the
99f0: 20 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61 VFS after a tra
9a00: 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 nsaction has bee
9a10: 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 n committed imme
9a20: 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 diately.** but b
9a30: 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 efore the databa
9a40: 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 se is unlocked.
9a50: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f VFSes that do no
9a60: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e t need this sign
9a70: 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c al.** should sil
9a80: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 ently ignore thi
9a90: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 s opcode. Applic
9aa0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f ations should no
9ab0: 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 t call.** [sqlit
9ac0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
9ad0: 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 )] with this opc
9ae0: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 ode as doing so
9af0: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 may disrupt the
9b00: 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 .** operation of
9b10: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 the specialized
9b20: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 VFSes that do r
9b30: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a equire it. .**.
9b40: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
9b50: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 FCNTL_WIN32_AV_R
9b60: 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b ETRY]].** ^The [
9b70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e SQLITE_FCNTL_WIN
9b80: 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 32_AV_RETRY] opc
9b90: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 ode is used to c
9ba0: 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 onfigure automat
9bb0: 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e ic.** retry coun
9bc0: 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 ts and intervals
9bd0: 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 for certain dis
9be0: 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 k I/O operations
9bf0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 for the.** wind
9c00: 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 ows [VFS] in ord
9c10: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f er to provide ro
9c20: 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 bustness in the
9c30: 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 presence of.** a
9c40: 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 nti-virus progra
9c50: 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c ms. By default,
9c60: 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 the windows VFS
9c70: 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 will retry file
9c80: 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 read,.** file w
9c90: 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 rite, and file d
9ca0: 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 elete operations
9cb0: 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c up to 10 times,
9cc0: 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a with a delay.**
9cd0: 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f of 25 milliseco
9ce0: 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 nds before the f
9cf0: 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 irst retry and w
9d00: 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e ith the delay in
9d10: 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 creasing.** by a
9d20: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 n additional 25
9d30: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 milliseconds wit
9d40: 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e h each subsequen
9d50: 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a t retry. This.*
9d60: 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 * opcode allows
9d70: 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 these two values
9d80: 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 (10 retries and
9d90: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 25 milliseconds
9da0: 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f of delay).** to
9db0: 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 be adjusted. T
9dc0: 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 he values are ch
9dd0: 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 anged for all da
9de0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
9df0: 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 ns.** within the
9e00: 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 same process.
9e10: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 The argument is
9e20: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
9e30: 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 array of two.**
9e40: 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 integers where t
9e50: 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 he first integer
9e60: 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 i the new retry
9e70: 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 count and the s
9e80: 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 econd.** integer
9e90: 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 is the delay.
9ea0: 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 If either intege
9eb0: 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 r is negative, t
9ec0: 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a hen the setting.
9ed0: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 ** is not change
9ee0: 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 d but instead th
9ef0: 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 e prior value of
9f00: 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 that setting is
9f10: 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f written.** into
9f20: 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 the array entry
9f30: 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 , allowing the c
9f40: 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 urrent retry set
9f50: 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 tings to be.** i
9f60: 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 nterrogated. Th
9f70: 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 e zDbName parame
9f80: 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a ter is ignored..
9f90: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
9fa0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 TE_FCNTL_PERSIST
9fb0: 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b _WAL]].** ^The [
9fc0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 SQLITE_FCNTL_PER
9fd0: 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 SIST_WAL] opcode
9fe0: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 is used to set
9ff0: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 or query the.**
a000: 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 persistent [WAL
a010: 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f | Write Ahead Lo
a020: 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 g] setting. By
a030: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 default, the aux
a040: 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 iliary.** write
a050: 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 ahead log and sh
a060: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 ared memory file
a070: 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 s used for trans
a080: 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a action control.*
a090: 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 * are automatica
a0a0: 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e lly deleted when
a0b0: 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e the latest conn
a0c0: 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 ection to the da
a0d0: 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 tabase.** closes
a0e0: 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 . Setting persi
a0f0: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 stent WAL mode c
a100: 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 auses those file
a110: 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 s to persist aft
a120: 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 er.** close. Pe
a130: 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c rsisting the fil
a140: 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 es is useful whe
a150: 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 n other processe
a160: 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a s that do not.**
a170: 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d have write perm
a180: 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 ission on the di
a190: 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 rectory containi
a1a0: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ng the database
a1b0: 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 file want.** to
a1c0: 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 read the databas
a1d0: 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 e file, as the W
a1e0: 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 AL and shared me
a1f0: 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 mory files must
a200: 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 exist.** in orde
a210: 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 r for the databa
a220: 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c se to be readabl
a230: 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 e. The fourth p
a240: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b arameter to.** [
a250: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e sqlite3_file_con
a260: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 trol()] for this
a270: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 opcode should b
a280: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 e a pointer to a
a290: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 n integer..** Th
a2a0: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 at integer is 0
a2b0: 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 to disable persi
a2c0: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f stent WAL mode o
a2d0: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 r 1 to enable pe
a2e0: 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 rsistent.** WAL
a2f0: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e mode. If the in
a300: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 teger is -1, the
a310: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 n it is overwrit
a320: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 ten with the cur
a330: 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 rent.** WAL pers
a340: 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e istence setting.
a350: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
a360: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 ITE_FCNTL_POWERS
a370: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a AFE_OVERWRITE]].
a380: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f ** ^The [SQLITE_
a390: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f FCNTL_POWERSAFE_
a3a0: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 OVERWRITE] opcod
a3b0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 e is used to set
a3c0: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a or query the.**
a3d0: 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 persistent "pow
a3e0: 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 ersafe-overwrite
a3f0: 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 " or "PSOW" sett
a400: 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 ing. The PSOW s
a410: 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d etting.** determ
a420: 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 ines the [SQLITE
a430: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 _IOCAP_POWERSAFE
a440: 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 _OVERWRITE] bit
a450: 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 of the.** xDevic
a460: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 eCharacteristics
a470: 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f methods. The fo
a480: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 urth parameter t
a490: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 o.** [sqlite3_fi
a4a0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f le_control()] fo
a4b0: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 r this opcode sh
a4c0: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 ould be a pointe
a4d0: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e r to an integer.
a4e0: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 .** That integer
a4f0: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 is 0 to disable
a500: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 zero-damage mod
a510: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 e or 1 to enable
a520: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 zero-damage.**
a530: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e mode. If the in
a540: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 teger is -1, the
a550: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 n it is overwrit
a560: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 ten with the cur
a570: 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d rent.** zero-dam
a580: 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 age mode setting
a590: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
a5a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 LITE_FCNTL_OVERW
a5b0: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b RITE]].** ^The [
a5c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 SQLITE_FCNTL_OVE
a5d0: 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 RWRITE] opcode i
a5e0: 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c s invoked by SQL
a5f0: 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e ite after openin
a600: 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 g.** a write tra
a610: 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 nsaction to indi
a620: 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 cate that, unles
a630: 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 s it is rolled b
a640: 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 ack for some.**
a650: 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 reason, the enti
a660: 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 re database file
a670: 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 will be overwri
a680: 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 tten by the curr
a690: 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 ent .** transact
a6a0: 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 ion. This is use
a6b0: 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 d by VACUUM oper
a6c0: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c ations..**.** <l
a6d0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
a6e0: 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 _VFSNAME]].** ^T
a6f0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
a700: 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 _VFSNAME] opcode
a710: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
a720: 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 obtain the names
a730: 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 of.** all [VFSe
a740: 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 s] in the VFS st
a750: 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 ack. The names
a760: 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 are of all VFS s
a770: 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 hims and the.**
a780: 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 final bottom-lev
a790: 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 el VFS are writt
a7a0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f en into memory o
a7b0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a btained from .**
a7c0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
a7d0: 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 ()] and the resu
a7e0: 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 lt is stored in
a7f0: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 the char* variab
a800: 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 le.** that the f
a810: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
a820: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 of [sqlite3_file
a830: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e _control()] poin
a840: 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 ts to..** The ca
a850: 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 ller is responsi
a860: 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 ble for freeing
a870: 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 the memory when
a880: 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a done. As with.*
a890: 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 * all file-contr
a8a0: 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 ol actions, ther
a8b0: 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 e is no guarante
a8c0: 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c e that this will
a8d0: 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 actually.** do
a8e0: 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 anything. Calle
a8f0: 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 rs should initia
a900: 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 lize the char* v
a910: 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c ariable to a NUL
a920: 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 L.** pointer in
a930: 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 case this file-c
a940: 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d ontrol is not im
a950: 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 plemented. This
a960: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a file-control.**
a970: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 is intended for
a980: 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 diagnostic use
a990: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e only..**.** <li>
a9a0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 [[SQLITE_FCNTL_V
a9b0: 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 FS_POINTER]].**
a9c0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e ^The [SQLITE_FCN
a9d0: 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 20 TL_VFS_POINTER]
a9e0: 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 61 20 70 opcode finds a p
a9f0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f ointer to the to
aa00: 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53 65 p-level.** [VFSe
aa10: 73 5d 20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20 s] currently in
aa20: 75 73 65 2e 20 20 5e 28 54 68 65 20 61 72 67 75 use. ^(The argu
aa30: 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71 6c ment X in.** sql
aa40: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
aa50: 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e 54 l(db,SQLITE_FCNT
aa60: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58 29 L_VFS_POINTER,X)
aa70: 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20 74 must be.** of t
aa80: 79 70 65 20 22 5b 73 71 6c 69 74 65 33 5f 76 66 ype "[sqlite3_vf
aa90: 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f 70 s] **". This op
aaa0: 63 6f 64 65 73 20 77 69 6c 6c 20 73 65 74 20 2a codes will set *
aab0: 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74 65 X.** to a pointe
aac0: 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 r to the top-lev
aad0: 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57 68 el VFS.)^.** ^Wh
aae0: 65 6e 20 74 68 65 72 65 20 61 72 65 20 6d 75 6c en there are mul
aaf0: 74 69 70 6c 65 20 56 46 53 20 73 68 69 6d 73 20 tiple VFS shims
ab00: 69 6e 20 74 68 65 20 73 74 61 63 6b 2c 20 74 68 in the stack, th
ab10: 69 73 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 is opcode finds
ab20: 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f 73 the.** upper-mos
ab30: 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a t shim only..**.
ab40: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
ab50: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a FCNTL_PRAGMA]].*
ab60: 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50 * ^Whenever a [P
ab70: 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 RAGMA] statement
ab80: 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b is parsed, an [
ab90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 SQLITE_FCNTL_PRA
aba0: 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f GMA] .** file co
abb0: 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f ntrol is sent to
abc0: 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 the open [sqlit
abd0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 e3_file] object
abe0: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a corresponding.**
abf0: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 to the database
ac00: 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74 file to which t
ac10: 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d he pragma statem
ac20: 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65 ent refers. ^The
ac30: 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 argument.** to
ac40: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 the [SQLITE_FCNT
ac50: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 L_PRAGMA] file c
ac60: 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 ontrol is an arr
ac70: 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 ay of.** pointer
ac80: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68 s to strings (ch
ac90: 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74 ar**) in which t
aca0: 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e he second elemen
acb0: 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a t of the array.*
acc0: 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 * is the name of
acd0: 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20 the pragma and
ace0: 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e the third elemen
acf0: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e t is the argumen
ad00: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 t to the.** prag
ad10: 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 ma or NULL if th
ad20: 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 e pragma has no
ad30: 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 argument. ^The
ad40: 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a handler for an.*
ad50: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f * [SQLITE_FCNTL_
ad60: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e PRAGMA] file con
ad70: 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 trol can optiona
ad80: 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72 lly make the fir
ad90: 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 st element.** of
ada0: 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75 the char** argu
adb0: 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 ment point to a
adc0: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 string obtained
add0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 from [sqlite3_mp
ade0: 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 rintf()].** or t
adf0: 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e he equivalent an
ae00: 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69 d that string wi
ae10: 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65 ll become the re
ae20: 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67 sult of the prag
ae30: 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 ma or.** the err
ae40: 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68 or message if th
ae50: 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 e pragma fails.
ae60: 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ^If the.** [SQLI
ae70: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d TE_FCNTL_PRAGMA]
ae80: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 file control re
ae90: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f turns [SQLITE_NO
aea0: 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f TFOUND], then no
aeb0: 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 rmal .** [PRAGMA
aec0: 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e ] processing con
aed0: 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65 tinues. ^If the
aee0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 [SQLITE_FCNTL_P
aef0: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 RAGMA].** file c
af00: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b ontrol returns [
af10: 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e SQLITE_OK], then
af20: 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75 the parser assu
af30: 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 mes that the.**
af40: 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20 VFS has handled
af50: 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c the PRAGMA itsel
af60: 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72 f and the parser
af70: 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d generates a no-
af80: 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 op.** prepared s
af90: 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75 tatement if resu
afa0: 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c lt string is NUL
afb0: 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72 L, or that retur
afc0: 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 ns a copy.** of
afd0: 74 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e the result strin
afe0: 67 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 g if the string
aff0: 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 is non-NULL..**
b000: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ^If the [SQLITE_
b010: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 FCNTL_PRAGMA] fi
b020: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 le control retur
b030: 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 ns.** any result
b040: 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e code other than
b050: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 [SQLITE_OK] or
b060: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 [SQLITE_NOTFOUND
b070: 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a ], that means.**
b080: 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e that the VFS en
b090: 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 countered an err
b0a0: 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e or while handlin
b0b0: 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 g the [PRAGMA] a
b0c0: 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c nd the.** compil
b0d0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 ation of the PRA
b0e0: 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 GMA fails with a
b0f0: 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b n error. ^The [
b100: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 SQLITE_FCNTL_PRA
b110: 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e GMA].** file con
b120: 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 trol occurs at t
b130: 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 he beginning of
b140: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 pragma statement
b150: 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f analysis and so
b160: 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 .** it is able t
b170: 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 o override built
b180: 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 -in [PRAGMA] sta
b190: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c tements..**.** <
b1a0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
b1b0: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a L_BUSYHANDLER]].
b1c0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f ** ^The [SQLITE_
b1d0: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 FCNTL_BUSYHANDLE
b1e0: 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 R].** file-contr
b1f0: 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 ol may be invoke
b200: 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 d by SQLite on t
b210: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
b220: 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 handle.** short
b230: 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f ly after it is o
b240: 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 pened in order t
b250: 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 o provide a cust
b260: 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65 om VFS with acce
b270: 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e ss.** to the con
b280: 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 nections busy-ha
b290: 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 ndler callback.
b2a0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 The argument is
b2b0: 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a of type (void **
b2c0: 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 ).** - an array
b2d0: 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 of two (void *)
b2e0: 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 values. The firs
b2f0: 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 t (void *) actua
b300: 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f lly points.** to
b310: 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 a function of t
b320: 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 ype (int (*)(voi
b330: 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 d *)). In order
b340: 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f to invoke the co
b350: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 nnections.** bus
b360: 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 y-handler, this
b370: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 function should
b380: 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 be invoked with
b390: 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 the second (void
b3a0: 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 *) in.** the ar
b3b0: 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 ray as the only
b3c0: 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 argument. If it
b3d0: 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f returns non-zero
b3e0: 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 , then the opera
b3f0: 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 tion.** should b
b400: 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 e retried. If it
b410: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 returns zero, t
b420: 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 he custom VFS sh
b430: 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 ould abandon the
b440: 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 .** current oper
b450: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 ation..**.** <li
b460: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
b470: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a TEMPFILENAME]].*
b480: 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 * ^Application c
b490: 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 an invoke the [S
b4a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 QLITE_FCNTL_TEMP
b4b0: 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 FILENAME] file-c
b4c0: 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 ontrol.** to hav
b4d0: 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 e SQLite generat
b4e0: 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 e a.** temporary
b4f0: 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 filename using
b500: 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 the same algorit
b510: 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f hm that is follo
b520: 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a wed to generate.
b530: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c ** temporary fil
b540: 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 enames for TEMP
b550: 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 tables and other
b560: 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 internal uses.
b570: 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 The.** argument
b580: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 should be a cha
b590: 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 r** which will b
b5a0: 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 e filled with th
b5b0: 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 e filename.** wr
b5c0: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 itten into memor
b5d0: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
b5e0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
b5f0: 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 )]. The caller
b600: 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 should.** invoke
b610: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
b620: 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 ] on the result
b630: 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 to avoid a memor
b640: 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c y leak..**.** <l
b650: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
b660: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 _MMAP_SIZE]].**
b670: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
b680: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c L_MMAP_SIZE] fil
b690: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 e control is use
b6a0: 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 d to query or se
b6b0: 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d t the.** maximum
b6c0: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
b6d0: 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 that will be us
b6e0: 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 ed for memory-ma
b6f0: 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 pped I/O..** The
b700: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 argument is a p
b710: 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 ointer to a valu
b720: 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 e of type sqlite
b730: 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 3_int64 that.**
b740: 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d is an advisory m
b750: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
b760: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 bytes in the fi
b770: 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 le to memory map
b780: 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 . The.** pointe
b790: 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e r is overwritten
b7a0: 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 with the old va
b7b0: 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 lue. The limit
b7c0: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 is not changed i
b7d0: 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f f.** the value o
b7e0: 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 riginally pointe
b7f0: 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 d to is negative
b800: 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 , and so the cur
b810: 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 rent limit .** c
b820: 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79 an be queried by
b830: 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f passing in a po
b840: 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 inter to a negat
b850: 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 ive number. Thi
b860: 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f s.** file-contro
b870: 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e l is used intern
b880: 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e ally to implemen
b890: 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 t [PRAGMA mmap_s
b8a0: 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e ize]..**.** <li>
b8b0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 [[SQLITE_FCNTL_T
b8c0: 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 RACE]].** The [S
b8d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 QLITE_FCNTL_TRAC
b8e0: 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 E] file control
b8f0: 70 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 provides advisor
b900: 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a y information.**
b910: 20 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 to the VFS abou
b920: 74 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65 t what the highe
b930: 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 r layers of the
b940: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 SQLite stack are
b950: 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 doing..** This
b960: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 file control is
b970: 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 used by some VFS
b980: 20 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e activity tracin
b990: 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 g [shims]..** Th
b9a0: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 e argument is a
b9b0: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
b9c0: 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 string. Higher
b9d0: 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a layers in the.**
b9e0: 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 SQLite stack ma
b9f0: 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 y generate insta
ba00: 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c nces of this fil
ba10: 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 e control if.**
ba20: 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f the [SQLITE_USE_
ba30: 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d FCNTL_TRACE] com
ba40: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
ba50: 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a is enabled..**.
ba60: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
ba70: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d FCNTL_HAS_MOVED]
ba80: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
ba90: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 _FCNTL_HAS_MOVED
baa0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 ] file control i
bab0: 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 nterprets its ar
bac0: 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 gument as a.** p
bad0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 ointer to an int
bae0: 65 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 eger and it writ
baf0: 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 es a boolean int
bb00: 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 o that integer d
bb10: 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 epending.** on w
bb20: 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 hether or not th
bb30: 65 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 e file has been
bb40: 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 renamed, moved,
bb50: 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 or deleted since
bb60: 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 it.** was first
bb70: 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c opened..**.** <
bb80: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
bb90: 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 L_WIN32_GET_HAND
bba0: 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c LE]].** The [SQL
bbb0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f ITE_FCNTL_WIN32_
bbc0: 47 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f GET_HANDLE] opco
bbd0: 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 de can be used t
bbe0: 6f 20 6f 62 74 61 69 6e 20 74 68 65 0a 2a 2a 20 o obtain the.**
bbf0: 75 6e 64 65 72 6c 79 69 6e 67 20 6e 61 74 69 76 underlying nativ
bc00: 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61 73 e file handle as
bc10: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 sociated with a
bc20: 66 69 6c 65 20 68 61 6e 64 6c 65 2e 20 20 54 68 file handle. Th
bc30: 69 73 20 66 69 6c 65 0a 2a 2a 20 63 6f 6e 74 72 is file.** contr
bc40: 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 ol interprets it
bc50: 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 20 s argument as a
bc60: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 61 74 pointer to a nat
bc70: 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 ive file handle
bc80: 61 6e 64 0a 2a 2a 20 77 72 69 74 65 73 20 74 68 and.** writes th
bc90: 65 20 72 65 73 75 6c 74 69 6e 67 20 76 61 6c 75 e resulting valu
bca0: 65 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c e there..**.** <
bcb0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
bcc0: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 L_WIN32_SET_HAND
bcd0: 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c LE]].** The [SQL
bce0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f ITE_FCNTL_WIN32_
bcf0: 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f SET_HANDLE] opco
bd00: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 de is used for d
bd10: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a ebugging. This.
bd20: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 ** opcode causes
bd30: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f the xFileContro
bd40: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 l method to swap
bd50: 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 the file handle
bd60: 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a with the one.**
bd70: 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 pointed to by t
bd80: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 he pArg argument
bd90: 2e 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 . This capabili
bda0: 74 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e ty is used durin
bdb0: 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 g testing.** and
bdc0: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 only needs to b
bdd0: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e e supported when
bde0: 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 SQLITE_TEST is
bdf0: 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c defined..**.** <
be00: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
be10: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a L_WAL_BLOCK]].**
be20: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
be30: 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 TL_WAL_BLOCK] is
be40: 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 a signal to the
be50: 20 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20 VFS layer that
be60: 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61 it might.** be a
be70: 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62 dvantageous to b
be80: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74 lock on the next
be90: 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65 WAL lock if the
bea0: 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d lock is not imm
beb0: 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69 ediately.** avai
bec0: 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20 lable. The WAL
bed0: 73 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73 subsystem issues
bee0: 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72 this signal dur
bef0: 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63 ing rare.** circ
bf00: 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64 umstances in ord
bf10: 65 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62 er to fix a prob
bf20: 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74 lem with priorit
bf30: 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 y inversion..**
bf40: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f Applications sho
bf50: 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e uld <em>not</em>
bf60: 20 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 use this file-c
bf70: 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c ontrol..**.** <l
bf80: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
bf90: 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 _ZIPVFS]].** The
bfa0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a [SQLITE_FCNTL_Z
bfb0: 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73 IPVFS] opcode is
bfc0: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 implemented by
bfd0: 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c zipvfs only. All
bfe0: 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68 other.** VFS sh
bff0: 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 ould return SQLI
c000: 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20 TE_NOTFOUND for
c010: 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a this opcode..**.
c020: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
c030: 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54 FCNTL_RBU]].** T
c040: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
c050: 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 20 _RBU] opcode is
c060: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74 implemented by t
c070: 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 75 he special VFS u
c080: 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 42 sed by.** the RB
c090: 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 U extension only
c0a0: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53 . All other VFS
c0b0: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 should return S
c0c0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 QLITE_NOTFOUND f
c0d0: 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64 or.** this opcod
c0e0: 65 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f e. .** </ul>.*/
c0f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
c100: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 FCNTL_LOCKSTATE
c110: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 1.
c120: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
c130: 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f CNTL_GET_LOCKPRO
c140: 58 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 XYFILE 2.#
c150: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
c160: 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 NTL_SET_LOCKPROX
c170: 59 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 YFILE 3.#d
c180: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
c190: 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 TL_LAST_ERRNO
c1a0: 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 4.#de
c1b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
c1c0: 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 L_SIZE_HINT
c1d0: 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 5.#def
c1e0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
c1f0: 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 _CHUNK_SIZE
c200: 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6.#defi
c210: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
c220: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 FILE_POINTER
c230: 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 7.#defin
c240: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 e SQLITE_FCNTL_S
c250: 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 YNC_OMITTED
c260: 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 8.#define
c270: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 SQLITE_FCNTL_WI
c280: 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 N32_AV_RETRY
c290: 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 9.#define
c2a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 SQLITE_FCNTL_PER
c2b0: 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 SIST_WAL
c2c0: 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 10.#define S
c2d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 QLITE_FCNTL_OVER
c2e0: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 WRITE
c2f0: 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 11.#define SQ
c300: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 LITE_FCNTL_VFSNA
c310: 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ME
c320: 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 12.#define SQL
c330: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 ITE_FCNTL_POWERS
c340: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 AFE_OVERWRITE
c350: 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 13.#define SQLI
c360: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 TE_FCNTL_PRAGMA
c370: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
c380: 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 14.#define SQLIT
c390: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 E_FCNTL_BUSYHAND
c3a0: 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31 LER 1
c3b0: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5.#define SQLITE
c3c0: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e _FCNTL_TEMPFILEN
c3d0: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36 AME 16
c3e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
c3f0: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 FCNTL_MMAP_SIZE
c400: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 18.
c410: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
c420: 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 CNTL_TRACE
c430: 20 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 19.#
c440: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
c450: 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 NTL_HAS_MOVED
c460: 20 20 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 20.#d
c470: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
c480: 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 TL_SYNC
c490: 20 20 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 21.#de
c4a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
c4b0: 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 L_COMMIT_PHASETW
c4c0: 4f 20 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 O 22.#def
c4d0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
c4e0: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c _WIN32_SET_HANDL
c4f0: 45 20 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 E 23.#defi
c500: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
c510: 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 WAL_BLOCK
c520: 20 20 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e 24.#defin
c530: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a e SQLITE_FCNTL_Z
c540: 49 50 56 46 53 20 20 20 20 20 20 20 20 20 20 20 IPVFS
c550: 20 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65 25.#define
c560: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 SQLITE_FCNTL_RB
c570: 55 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 U
c580: 20 20 20 20 20 32 36 0a 23 64 65 66 69 6e 65 20 26.#define
c590: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 SQLITE_FCNTL_VFS
c5a0: 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 _POINTER
c5b0: 20 20 20 20 32 37 0a 23 64 65 66 69 6e 65 20 53 27.#define S
c5c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 QLITE_FCNTL_JOUR
c5d0: 4e 41 4c 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 NAL_POINTER
c5e0: 20 20 20 32 38 0a 23 64 65 66 69 6e 65 20 53 51 28.#define SQ
c5f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 LITE_FCNTL_WIN32
c600: 5f 47 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 _GET_HANDLE
c610: 20 20 32 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 29.#define SQL
c620: 49 54 45 5f 46 43 4e 54 4c 5f 50 44 42 20 20 20 ITE_FCNTL_PDB
c630: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
c640: 20 33 30 0a 0a 2f 2a 20 64 65 70 72 65 63 61 74 30../* deprecat
c650: 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 64 65 66 ed names */.#def
c660: 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c ine SQLITE_GET_L
c670: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 OCKPROXYFILE
c680: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 SQLITE_FCNTL_G
c690: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 ET_LOCKPROXYFILE
c6a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
c6b0: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c SET_LOCKPROXYFIL
c6c0: 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 E SQLITE_FC
c6d0: 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 NTL_SET_LOCKPROX
c6e0: 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 YFILE.#define SQ
c6f0: 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 LITE_LAST_ERRNO
c700: 20 20 20 20 20 20 20 20 20 20 20 20 53 51 4c 49 SQLI
c710: 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 TE_FCNTL_LAST_ER
c720: 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 RNO.../*.** CAPI
c730: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 3REF: Mutex Hand
c740: 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 le.**.** The mut
c750: 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e ex module within
c760: 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 SQLite defines
c770: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 [sqlite3_mutex]
c780: 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 to be an.** abst
c790: 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 ract type for a
c7a0: 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 mutex object. T
c7b0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e he SQLite core n
c7c0: 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 ever looks.** at
c7d0: 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 the internal re
c7e0: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 presentation of
c7f0: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 an [sqlite3_mute
c800: 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 x]. It only.**
c810: 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 deals with point
c820: 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 ers to the [sqli
c830: 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 te3_mutex] objec
c840: 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 t..**.** Mutexes
c850: 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69 are created usi
c860: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 ng [sqlite3_mute
c870: 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 x_alloc()]..*/.t
c880: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
c890: 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 lite3_mutex sqli
c8a0: 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a te3_mutex;../*.*
c8b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 * CAPI3REF: Load
c8c0: 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 54 able Extension T
c8d0: 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 hunk.**.** A poi
c8e0: 6e 74 65 72 20 74 6f 20 74 68 65 20 6f 70 61 71 nter to the opaq
c8f0: 75 65 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 ue sqlite3_api_r
c900: 6f 75 74 69 6e 65 73 20 73 74 72 75 63 74 75 72 outines structur
c910: 65 20 69 73 20 70 61 73 73 65 64 20 61 73 0a 2a e is passed as.*
c920: 2a 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 * the third para
c930: 6d 65 74 65 72 20 74 6f 20 65 6e 74 72 79 20 70 meter to entry p
c940: 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f 61 64 61 62 oints of [loadab
c950: 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73 5d 2e 20 le extensions].
c960: 20 54 68 69 73 0a 2a 2a 20 73 74 72 75 63 74 75 This.** structu
c970: 72 65 20 6d 75 73 74 20 62 65 20 74 79 70 65 64 re must be typed
c980: 65 66 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f efed in order to
c990: 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 63 6f 6d work around com
c9a0: 70 69 6c 65 72 20 77 61 72 6e 69 6e 67 73 0a 2a piler warnings.*
c9b0: 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c 61 74 66 6f * on some platfo
c9c0: 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 rms..*/.typedef
c9d0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 61 struct sqlite3_a
c9e0: 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 71 6c 69 pi_routines sqli
c9f0: 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 te3_api_routines
ca00: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
ca10: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 F: OS Interface
ca20: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 Object.**.** An
ca30: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
ca40: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 sqlite3_vfs obje
ca50: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 ct defines the i
ca60: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e nterface between
ca70: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 .** the SQLite c
ca80: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 ore and the unde
ca90: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 rlying operating
caa0: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 system. The "v
cab0: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 fs".** in the na
cac0: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 me of the object
cad0: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 stands for "vir
cae0: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d tual file system
caf0: 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b ". See.** the [
cb00: 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 VFS | VFS docume
cb10: 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 ntation] for fur
cb20: 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e ther information
cb30: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 ..**.** The valu
cb40: 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f e of the iVersio
cb50: 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 n field is initi
cb60: 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 ally 1 but may b
cb70: 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 e larger in.** f
cb80: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
cb90: 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 f SQLite. Addit
cba0: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 ional fields may
cbb0: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 be appended to
cbc0: 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 this.** object w
cbd0: 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e hen the iVersion
cbe0: 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 value is increa
cbf0: 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 sed. Note that
cc00: 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a the structure.**
cc10: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f of the sqlite3_
cc20: 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 vfs object chang
cc30: 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 es in the transa
cc40: 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a ction between.**
cc50: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
cc60: 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 3.5.9 and 3.6.0
cc70: 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72 and yet the iVer
cc80: 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e sion field was n
cc90: 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a ot.** modified..
cca0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 **.** The szOsFi
ccb0: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 le field is the
ccc0: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 size of the subc
ccd0: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f lassed [sqlite3_
cce0: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 file].** structu
ccf0: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20 re used by this
cd00: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 VFS. mxPathname
cd10: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 is the maximum
cd20: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 length of.** a p
cd30: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 athname in this
cd40: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 VFS..**.** Regis
cd50: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 tered sqlite3_vf
cd60: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 s objects are ke
cd70: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c pt on a linked l
cd80: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a ist formed by.**
cd90: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 the pNext point
cda0: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 er. The [sqlite
cdb0: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 3_vfs_register()
cdc0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 ].** and [sqlite
cdd0: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 3_vfs_unregister
cde0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d ()] interfaces m
cdf0: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a anage this list.
ce00: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 ** in a thread-s
ce10: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 afe way. The [s
ce20: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 qlite3_vfs_find(
ce30: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 )] interface.**
ce40: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 searches the lis
ce50: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 t. Neither the
ce60: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 application code
ce70: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 nor the VFS.**
ce80: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 implementation s
ce90: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e hould use the pN
cea0: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a ext pointer..**.
ceb0: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 ** The pNext fie
cec0: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 ld is the only f
ced0: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 ield in the sqli
cee0: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 te3_vfs.** struc
cef0: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 ture that SQLite
cf00: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 will ever modif
cf10: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 y. SQLite will
cf20: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f only access.** o
cf30: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 r modify this fi
cf40: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e eld while holdin
cf50: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 g a particular s
cf60: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 tatic mutex..**
cf70: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
cf80: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 should never mod
cf90: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 ify anything wit
cfa0: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f hin the sqlite3_
cfb0: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e vfs.** object on
cfc0: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 ce the object ha
cfd0: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 s been registere
cfe0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 d..**.** The zNa
cff0: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 me field holds t
d000: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 he name of the V
d010: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 FS module. The
d020: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 name must.** be
d030: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c unique across al
d040: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a l VFS modules..*
d050: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 *.** [[sqlite3_v
d060: 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 fs.xOpen]].** ^S
d070: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 QLite guarantees
d080: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e that the zFilen
d090: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f ame parameter to
d0a0: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 xOpen.** is eit
d0b0: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 her a NULL point
d0c0: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 er or string obt
d0d0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 ained.** from xF
d0e0: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 ullPathname() wi
d0f0: 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 th an optional s
d100: 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 uffix added..**
d110: 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20 ^If a suffix is
d120: 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 added to the zFi
d130: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 lename parameter
d140: 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e , it will.** con
d150: 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 sist of a single
d160: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 "-" character f
d170: 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f ollowed by no mo
d180: 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c re than.** 11 al
d190: 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f phanumeric and/o
d1a0: 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 r "-" characters
d1b0: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 ..** ^SQLite fur
d1c0: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 ther guarantees
d1d0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 that.** the stri
d1e0: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 ng will be valid
d1f0: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 and unchanged u
d200: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 ntil xClose() is
d210: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 .** called. Beca
d220: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 use of the previ
d230: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a ous sentence,.**
d240: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 the [sqlite3_fi
d250: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 le] can safely s
d260: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 tore a pointer t
d270: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d o the.** filenam
d280: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f e if it needs to
d290: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 remember the fi
d2a0: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 lename for some
d2b0: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 reason..** If th
d2c0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 e zFilename para
d2d0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 meter to xOpen i
d2e0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
d2f0: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d then xOpen.** m
d300: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f ust invent its o
d310: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d wn temporary nam
d320: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 e for the file.
d330: 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a ^Whenever the .
d340: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 ** xFilename par
d350: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 ameter is NULL i
d360: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 t will also be t
d370: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 he case that the
d380: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 .** flags parame
d390: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 ter will include
d3a0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 [SQLITE_OPEN_DE
d3b0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a LETEONCLOSE]..**
d3c0: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 .** The flags ar
d3d0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 gument to xOpen(
d3e0: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 ) includes all b
d3f0: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 its set in.** th
d400: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 e flags argument
d410: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 to [sqlite3_ope
d420: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 n_v2()]. Or if
d430: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
d440: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f .** or [sqlite3_
d450: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 open16()] is use
d460: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e d, then flags in
d470: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a cludes at least.
d480: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ** [SQLITE_OPEN_
d490: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 READWRITE] | [SQ
d4a0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
d4b0: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 ]. .** If xOpen(
d4c0: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 ) opens a file r
d4d0: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 ead-only then it
d4e0: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 sets *pOutFlags
d4f0: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b to.** include [
d500: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
d510: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 ONLY]. Other bi
d520: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 ts in *pOutFlags
d530: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a may be set..**.
d540: 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c ** ^(SQLite will
d550: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 also add one of
d560: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 the following f
d570: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 lags to the xOpe
d580: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 n().** call, dep
d590: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 ending on the ob
d5a0: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 ject being opene
d5b0: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a d:.**.** <ul>.**
d5c0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
d5d0: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 PEN_MAIN_DB].**
d5e0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
d5f0: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d EN_MAIN_JOURNAL]
d600: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
d610: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a E_OPEN_TEMP_DB].
d620: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
d630: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e _OPEN_TEMP_JOURN
d640: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 AL].** <li> [SQ
d650: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 LITE_OPEN_TRANSI
d660: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 ENT_DB].** <li>
d670: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 [SQLITE_OPEN_SU
d680: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 BJOURNAL].** <li
d690: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
d6a0: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a MASTER_JOURNAL].
d6b0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
d6c0: 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f _OPEN_WAL].** </
d6d0: 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ul>)^.**.** The
d6e0: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 file I/O impleme
d6f0: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 ntation can use
d700: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 the object type
d710: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e flags to.** chan
d720: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 ge the way it de
d730: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 als with files.
d740: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e For example, an
d750: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 application.**
d760: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 that does not ca
d770: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 re about crash r
d780: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 ecovery or rollb
d790: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a ack might make.*
d7a0: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 * the open of a
d7b0: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e journal file a n
d7c0: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f o-op. Writes to
d7d0: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f this journal wo
d7e0: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e uld.** also be n
d7f0: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 o-ops, and any a
d800: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 ttempt to read t
d810: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 he journal would
d820: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 return.** SQLIT
d830: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 E_IOERR. Or the
d840: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
d850: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 might recognize
d860: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a that a database.
d870: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 ** file will be
d880: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e doing page-align
d890: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 ed sector reads
d8a0: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 and writes in a
d8b0: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 random.** order
d8c0: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 and set up its I
d8d0: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 /O subsystem acc
d8e0: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ordingly..**.**
d8f0: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 SQLite might als
d900: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 o add one of the
d910: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 following flags
d920: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 to the xOpen me
d930: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e thod:.**.** <ul>
d940: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
d950: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c _OPEN_DELETEONCL
d960: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 OSE].** <li> [SQ
d970: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 LITE_OPEN_EXCLUS
d980: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a IVE].** </ul>.**
d990: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
d9a0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f OPEN_DELETEONCLO
d9b0: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 SE] flag means t
d9c0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 he file should b
d9d0: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 e.** deleted whe
d9e0: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 n it is closed.
d9f0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 ^The [SQLITE_OP
da00: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 EN_DELETEONCLOSE
da10: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 ].** will be set
da20: 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 for TEMP databa
da30: 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f ses and their jo
da40: 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e urnals, transien
da50: 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 t.** databases,
da60: 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e and subjournals.
da70: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c .**.** ^The [SQL
da80: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 ITE_OPEN_EXCLUSI
da90: 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 VE] flag is alwa
daa0: 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 ys used in conju
dab0: 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 nction.** with t
dac0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f he [SQLITE_OPEN_
dad0: 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 CREATE] flag, wh
dae0: 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 ich are both dir
daf0: 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f ectly.** analogo
db00: 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c us to the O_EXCL
db10: 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 and O_CREAT fla
db20: 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 gs of the POSIX
db30: 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 open().** API.
db40: 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f The SQLITE_OPEN_
db50: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 EXCLUSIVE flag,
db60: 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 when paired with
db70: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f the .** SQLITE_
db80: 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 OPEN_CREATE, is
db90: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 used to indicate
dba0: 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c that file shoul
dbb0: 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 d always.** be c
dbc0: 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 reated, and that
dbd0: 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 it is an error
dbe0: 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 if it already ex
dbf0: 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c ists..** It is <
dc00: 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 i>not</i> used t
dc10: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 o indicate the f
dc20: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 ile should be op
dc30: 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 ened .** for exc
dc40: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a lusive access..*
dc50: 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 *.** ^At least s
dc60: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 zOsFile bytes of
dc70: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f memory are allo
dc80: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a cated by SQLite.
dc90: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 ** to hold the
dca0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 [sqlite3_file] s
dcb0: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 tructure passed
dcc0: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 as the third.**
dcd0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 argument to xOpe
dce0: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 n. The xOpen me
dcf0: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 thod does not ha
dd00: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 ve to.** allocat
dd10: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b e the structure;
dd20: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 it should just
dd30: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 fill it in. Not
dd40: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f e that.** the xO
dd50: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 pen method must
dd60: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f set the sqlite3_
dd70: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f file.pMethods to
dd80: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c either.** a val
dd90: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d id [sqlite3_io_m
dda0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f ethods] object o
ddb0: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 r to NULL. xOpe
ddc0: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 n must do.** thi
ddd0: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 s even if the op
dde0: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 en fails. SQLit
ddf0: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74 e expects that t
de00: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e he sqlite3_file.
de10: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d pMethods.** elem
de20: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 ent will be vali
de30: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 d after xOpen re
de40: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 turns regardless
de50: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a of the success.
de60: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 ** or failure of
de70: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e the xOpen call.
de80: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 .**.** [[sqlite3
de90: 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a _vfs.xAccess]].*
dea0: 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 * ^The flags arg
deb0: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 ument to xAccess
dec0: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 () may be [SQLIT
ded0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d E_ACCESS_EXISTS]
dee0: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 .** to test for
def0: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 the existence of
df00: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c a file, or [SQL
df10: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 ITE_ACCESS_READW
df20: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 RITE] to.** test
df30: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 whether a file
df40: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 is readable and
df50: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 writable, or [SQ
df60: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
df70: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 ].** to test whe
df80: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 ther a file is a
df90: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 t least readable
dfa0: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e . The file can
dfb0: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f be a.** directo
dfc0: 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 ry..**.** ^SQLit
dfd0: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c e will always al
dfe0: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 locate at least
dff0: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 mxPathname+1 byt
e000: 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 es for the.** ou
e010: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c tput buffer xFul
e020: 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 lPathname. The
e030: 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 exact size of th
e040: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a e output buffer.
e050: 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 ** is also passe
e060: 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 d as a parameter
e070: 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 to both method
e080: 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 s. If the output
e090: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f buffer.** is no
e0a0: 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 t large enough,
e0b0: 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e [SQLITE_CANTOPEN
e0c0: 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 ] should be retu
e0d0: 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 rned. Since this
e0e0: 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 is.** handled a
e0f0: 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 s a fatal error
e100: 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 by SQLite, vfs i
e110: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 mplementations s
e120: 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a hould endeavor.*
e130: 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 * to prevent thi
e140: 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 s by setting mxP
e150: 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 athname to a suf
e160: 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 ficiently large
e170: 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 value..**.** The
e180: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 xRandomness(),
e190: 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 xSleep(), xCurre
e1a0: 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 ntTime(), and xC
e1b0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 urrentTimeInt64(
e1c0: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 ).** interfaces
e1d0: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 are not strictly
e1e0: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 a part of the f
e1f0: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 ilesystem, but t
e200: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 hey are.** inclu
e210: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 ded in the VFS s
e220: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d tructure for com
e230: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 pleteness..** Th
e240: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 e xRandomness()
e250: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 function attempt
e260: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 s to return nByt
e270: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 es bytes.** of g
e280: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 ood-quality rand
e290: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 omness into zOut
e2a0: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 . The return va
e2b0: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 lue is.** the ac
e2c0: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 tual number of b
e2d0: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 ytes of randomne
e2e0: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 ss obtained..**
e2f0: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 The xSleep() met
e300: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63 hod causes the c
e310: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f alling thread to
e320: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a sleep for at.**
e330: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 least the numbe
e340: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 r of microsecond
e350: 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 s given. ^The x
e360: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a CurrentTime().**
e370: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 method returns
e380: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d a Julian Day Num
e390: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 ber for the curr
e3a0: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d ent date and tim
e3b0: 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 e as.** a floati
e3c0: 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a ng point value..
e3d0: 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 ** ^The xCurrent
e3e0: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 TimeInt64() meth
e3f0: 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 od returns, as a
e400: 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a n integer, the J
e410: 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d ulian.** Day Num
e420: 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 ber multiplied b
e430: 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20 y 86400000 (the
e440: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 number of millis
e450: 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 econds in .** a
e460: 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 24-hour day). .
e470: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 ** ^SQLite will
e480: 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 use the xCurrent
e490: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 TimeInt64() meth
e4a0: 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 od to get the cu
e4b0: 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e rrent.** date an
e4c0: 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d d time if that m
e4d0: 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 ethod is availab
e4e0: 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 le (if iVersion
e4f0: 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 is 2 or .** grea
e500: 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 ter and the func
e510: 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 tion pointer is
e520: 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 not NULL) and wi
e530: 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 ll fall back.**
e540: 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 to xCurrentTime(
e550: 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d ) if xCurrentTim
e560: 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 eInt64() is unav
e570: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e ailable..**.** ^
e580: 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 The xSetSystemCa
e590: 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d ll(), xGetSystem
e5a0: 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 Call(), and xNes
e5b0: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e tSystemCall() in
e5c0: 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 terfaces.** are
e5d0: 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20 not used by the
e5e0: 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 SQLite core. Th
e5f0: 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 ese optional int
e600: 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 erfaces are prov
e610: 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 ided.** by some
e620: 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 VFSes to facilit
e630: 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 ate testing of t
e640: 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 he VFS code. By
e650: 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 overriding .** s
e660: 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 ystem calls with
e670: 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 functions under
e680: 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 its control, a
e690: 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e test program can
e6a0: 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 .** simulate fau
e6b0: 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f lts and error co
e6c0: 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f nditions that wo
e6d0: 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 uld otherwise be
e6e0: 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 difficult.** or
e6f0: 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 impossible to i
e700: 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 nduce. The set
e710: 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 of system calls
e720: 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 that can be over
e730: 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 ridden.** varies
e740: 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f from one VFS to
e750: 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 another, and fr
e760: 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f om one version o
e770: 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 f the same VFS t
e780: 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 o the.** next.
e790: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 Applications tha
e7a0: 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 t use these inte
e7b0: 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 rfaces must be p
e7c0: 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a repared for any.
e7d0: 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 ** or all of the
e7e0: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f se interfaces to
e7f0: 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 be NULL or for
e800: 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 their behavior t
e810: 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d o change.** from
e820: 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 one release to
e830: 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 the next. Appli
e840: 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 cations must not
e850: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 attempt to acce
e860: 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 ss.** any of the
e870: 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 se methods if th
e880: 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 e iVersion of th
e890: 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 e VFS is less th
e8a0: 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 an 3..*/.typedef
e8b0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
e8c0: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b vfs sqlite3_vfs;
e8d0: 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a .typedef void (*
e8e0: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f sqlite3_syscall_
e8f0: 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 ptr)(void);.stru
e900: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b ct sqlite3_vfs {
e910: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b . int iVersion;
e920: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 /* S
e930: 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e tructure version
e940: 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 number (current
e950: 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 ly 3) */. int s
e960: 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 zOsFile;
e970: 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 /* Size of s
e980: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 ubclassed sqlite
e990: 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 3_file */. int
e9a0: 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 mxPathname;
e9b0: 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 /* Maximum
e9c0: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 file pathname le
e9d0: 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 ngth */. sqlite
e9e0: 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 3_vfs *pNext;
e9f0: 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 /* Next regis
ea00: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 tered VFS */. c
ea10: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
ea20: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 ; /* Name
ea30: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 of this virtual
ea40: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 file system */.
ea50: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b void *pAppData;
ea60: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 /* Poi
ea70: 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 nter to applicat
ea80: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 ion-specific dat
ea90: 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 a */. int (*xOp
eaa0: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a en)(sqlite3_vfs*
eab0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
eac0: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c ame, sqlite3_fil
ead0: 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 e*,.
eae0: 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e int flags, in
eaf0: 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 t *pOutFlags);.
eb00: 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 int (*xDelete)(
eb10: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
eb20: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
eb30: 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 int syncDir);.
eb40: 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 int (*xAccess)(
eb50: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
eb60: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
eb70: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 int flags, int
eb80: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 *pResOut);. int
eb90: 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 (*xFullPathname
eba0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
ebb0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
ebc0: 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 e, int nOut, cha
ebd0: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 r *zOut);. void
ebe0: 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c *(*xDlOpen)(sql
ebf0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
ec00: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 char *zFilename
ec10: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 );. void (*xDlE
ec20: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 rror)(sqlite3_vf
ec30: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 s*, int nByte, c
ec40: 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 har *zErrMsg);.
ec50: 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d void (*(*xDlSym
ec60: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 )(sqlite3_vfs*,v
ec70: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 oid*, const char
ec80: 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 *zSymbol))(void
ec90: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 );. void (*xDlC
eca0: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 lose)(sqlite3_vf
ecb0: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e s*, void*);. in
ecc0: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 t (*xRandomness)
ecd0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 (sqlite3_vfs*, i
ece0: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a nt nByte, char *
ecf0: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 zOut);. int (*x
ed00: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 Sleep)(sqlite3_v
ed10: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 fs*, int microse
ed20: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a conds);. int (*
ed30: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 xCurrentTime)(sq
ed40: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 lite3_vfs*, doub
ed50: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 le*);. int (*xG
ed60: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c etLastError)(sql
ed70: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 ite3_vfs*, int,
ed80: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 char *);. /*.
ed90: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 ** The methods a
eda0: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 bove are in vers
edb0: 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c ion 1 of the sql
edc0: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 ite_vfs object.
edd0: 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 ** definition.
ede0: 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c Those that foll
edf0: 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 ow are added in
ee00: 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 version 2 or lat
ee10: 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a er. */. int (*
ee20: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 xCurrentTimeInt6
ee30: 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 4)(sqlite3_vfs*,
ee40: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 sqlite3_int64*)
ee50: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 ;. /*. ** The
ee60: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 methods above ar
ee70: 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 e in versions 1
ee80: 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c and 2 of the sql
ee90: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a ite_vfs object..
eea0: 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 ** Those below
eeb0: 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e are for version
eec0: 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 3 and greater..
eed0: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 */. int (*xSe
eee0: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c tSystemCall)(sql
eef0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
ef00: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 char *zName, sq
ef10: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 lite3_syscall_pt
ef20: 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 r);. sqlite3_sy
ef30: 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 scall_ptr (*xGet
ef40: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 SystemCall)(sqli
ef50: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
ef60: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 char *zName);.
ef70: 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e const char *(*xN
ef80: 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 extSystemCall)(s
ef90: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
efa0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b st char *zName);
efb0: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d . /*. ** The m
efc0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 ethods above are
efd0: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 in versions 1 t
efe0: 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 hrough 3 of the
eff0: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 sqlite_vfs objec
f000: 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c t.. ** New fiel
f010: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 ds may be append
f020: 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 ed in future ver
f030: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 sions. The iVer
f040: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 sion. ** value
f050: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 will increment w
f060: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 henever this hap
f070: 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a pens. . */.};..
f080: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
f090: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 Flags for the xA
f0a0: 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 ccess VFS method
f0b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 .**.** These int
f0c0: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 eger constants c
f0d0: 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 an be used as th
f0e0: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
f0f0: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 r to.** the xAcc
f100: 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e ess method of an
f110: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f [sqlite3_vfs] o
f120: 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 bject. They det
f130: 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b ermine.** what k
f140: 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f ind of permissio
f150: 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d ns the xAccess m
f160: 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 ethod is looking
f170: 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 for..** With SQ
f180: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 LITE_ACCESS_EXIS
f190: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 TS, the xAccess
f1a0: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 method.** simply
f1b0: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 checks whether
f1c0: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e the file exists.
f1d0: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f .** With SQLITE_
f1e0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 ACCESS_READWRITE
f1f0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 , the xAccess me
f200: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 thod.** checks w
f210: 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 hether the named
f220: 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f directory is bo
f230: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 th readable and
f240: 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 writable.** (in
f250: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 other words, if
f260: 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 files can be add
f270: 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 ed, removed, and
f280: 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a renamed within.
f290: 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 ** the directory
f2a0: 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 )..** The SQLITE
f2b0: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 _ACCESS_READWRIT
f2c0: 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 E constant is cu
f2d0: 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c rrently used onl
f2e0: 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d y by the.** [tem
f2f0: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 p_store_director
f300: 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 y pragma], thoug
f310: 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 h this could cha
f320: 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a nge in a future.
f330: 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 ** release of SQ
f340: 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 Lite..** With SQ
f350: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
f360: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 , the xAccess me
f370: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 thod.** checks w
f380: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 hether the file
f390: 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 is readable. Th
f3a0: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f e SQLITE_ACCESS_
f3b0: 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 READ constant is
f3c0: 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e .** currently un
f3d0: 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 used, though it
f3e0: 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e might be used in
f3f0: 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 a future releas
f400: 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a e of.** SQLite..
f410: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
f420: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 E_ACCESS_EXISTS
f430: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0.#define SQL
f440: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 ITE_ACCESS_READW
f450: 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 RITE 1 /* Used
f460: 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f by PRAGMA temp_
f470: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 store_directory
f480: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
f490: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 E_ACCESS_READ
f4a0: 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 2 /* Unused
f4b0: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
f4c0: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 REF: Flags for t
f4d0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 he xShmLock VFS
f4e0: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 method.**.** The
f4f0: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 se integer const
f500: 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 ants define the
f510: 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 various locking
f520: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c operations.** al
f530: 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68 lowed by the xSh
f540: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 mLock method of
f550: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
f560: 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f ods]. The.** fo
f570: 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 llowing are the
f580: 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 only legal combi
f590: 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 nations of flags
f5a0: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c to the.** xShmL
f5b0: 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a ock method:.**.*
f5c0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 * <ul>.** <li>
f5d0: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 SQLITE_SHM_LOCK
f5e0: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 | SQLITE_SHM_SHA
f5f0: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c RED.** <li> SQL
f600: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 ITE_SHM_LOCK | S
f610: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 QLITE_SHM_EXCLUS
f620: 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c IVE.** <li> SQL
f630: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c ITE_SHM_UNLOCK |
f640: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 SQLITE_SHM_SHAR
f650: 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 ED.** <li> SQLI
f660: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 TE_SHM_UNLOCK |
f670: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 SQLITE_SHM_EXCLU
f680: 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a SIVE.** </ul>.**
f690: 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 .** When unlocki
f6a0: 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 ng, the same SHA
f6b0: 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 RED or EXCLUSIVE
f6c0: 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 flag must be su
f6d0: 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 pplied as.** was
f6e0: 20 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f given on the co
f6f0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b rresponding lock
f700: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 . .**.** The xS
f710: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 hmLock method ca
f720: 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 n transition bet
f730: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e ween unlocked an
f740: 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 d SHARED or.** b
f750: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 etween unlocked
f760: 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 and EXCLUSIVE.
f770: 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 It cannot transi
f780: 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 tion between SHA
f790: 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 RED.** and EXCLU
f7a0: 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 SIVE..*/.#define
f7b0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f SQLITE_SHM_UNLO
f7c0: 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 CK 1.#defi
f7d0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f ne SQLITE_SHM_LO
f7e0: 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 CK 2.#de
f7f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f fine SQLITE_SHM_
f800: 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 SHARED 4.#
f810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 define SQLITE_SH
f820: 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 M_EXCLUSIVE 8
f830: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
f840: 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f : Maximum xShmLo
f850: 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 ck index.**.** T
f860: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 he xShmLock meth
f870: 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 od on [sqlite3_i
f880: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 o_methods] may u
f890: 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 se values.** bet
f8a0: 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 ween 0 and this
f8b0: 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 upper bound as i
f8c0: 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 ts "offset" argu
f8d0: 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c ment..** The SQL
f8e0: 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 ite core will ne
f8f0: 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 ver attempt to a
f900: 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 cquire or releas
f910: 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 e a.** lock outs
f920: 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 ide of this rang
f930: 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e.*/.#define SQL
f940: 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 ITE_SHM_NLOCK
f950: 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 8.../*.** C
f960: 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c API3REF: Initial
f970: 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c ize The SQLite L
f980: 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 ibrary.**.** ^Th
f990: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
f9a0: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 lize() routine i
f9b0: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a nitializes the.*
f9c0: 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 * SQLite library
f9d0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f . ^The sqlite3_
f9e0: 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 shutdown() routi
f9f0: 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 ne.** deallocate
fa00: 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 s any resources
fa10: 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 that were alloca
fa20: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 ted by sqlite3_i
fa30: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 nitialize()..**
fa40: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
fa50: 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 re designed to a
fa60: 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e id in process in
fa70: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 itialization and
fa80: 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 .** shutdown on
fa90: 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 embedded systems
faa0: 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 . Workstation a
fab0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e pplications usin
fac0: 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d g.** SQLite norm
fad0: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 ally do not need
fae0: 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 to invoke eithe
faf0: 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 r of these routi
fb00: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c nes..**.** A cal
fb10: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 l to sqlite3_ini
fb20: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 tialize() is an
fb30: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c "effective" call
fb40: 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 if it is.** the
fb50: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 first time sqli
fb60: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
fb70: 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 is invoked duri
fb80: 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 ng the lifetime
fb90: 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 of.** the proces
fba0: 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 s, or if it is t
fbb0: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 he first time sq
fbc0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
fbd0: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a () is invoked.**
fbe0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c following a cal
fbf0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 l to sqlite3_shu
fc00: 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 tdown(). ^(Only
fc10: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 an effective ca
fc20: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 ll.** of sqlite3
fc30: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f _initialize() do
fc40: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a es any initializ
fc50: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 ation. All othe
fc60: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 r calls.** are h
fc70: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 armless no-ops.)
fc80: 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 ^.**.** A call t
fc90: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f o sqlite3_shutdo
fca0: 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 wn() is an "effe
fcb0: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 ctive" call if i
fcc0: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a t is the first.*
fcd0: 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 * call to sqlite
fce0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 3_shutdown() sin
fcf0: 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 ce the last sqli
fd00: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
fd10: 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 . ^(Only.** an
fd20: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 effective call t
fd30: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f o sqlite3_shutdo
fd40: 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 wn() does any de
fd50: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a initialization..
fd60: 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c ** All other val
fd70: 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 id calls to sqli
fd80: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 te3_shutdown() a
fd90: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f re harmless no-o
fda0: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ps.)^.**.** The
fdb0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
fdc0: 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 ze() interface i
fdd0: 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 s threadsafe, bu
fde0: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f t sqlite3_shutdo
fdf0: 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 wn().** is not.
fe00: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 The sqlite3_shu
fe10: 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 tdown() interfac
fe20: 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 e must only be c
fe30: 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 alled from a.**
fe40: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 single thread.
fe50: 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 All open [databa
fe60: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 se connections]
fe70: 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 must be closed a
fe80: 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 nd all.** other
fe90: 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 SQLite resources
fea0: 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 must be dealloc
feb0: 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e ated prior to in
fec0: 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 voking.** sqlite
fed0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 3_shutdown()..**
fee0: 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 .** Among other
fef0: 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 things, ^sqlite3
ff00: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 _initialize() wi
ff10: 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c ll invoke.** sql
ff20: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 ite3_os_init().
ff30: 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c Similarly, ^sql
ff40: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a ite3_shutdown().
ff50: 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 ** will invoke s
ff60: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e qlite3_os_end().
ff70: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
ff80: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
ff90: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
ffa0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 [SQLITE_OK] on
ffb0: 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 success..** ^If
ffc0: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c for some reason,
ffd0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
ffe0: 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 ize() is unable
fff0: 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a to initialize.**
10000 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 the library (pe
10010 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 rhaps it is unab
10020 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 le to allocate a
10030 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 needed resource
10040 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 such.** as a mu
10050 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 tex) it returns
10060 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 an [error code]
10070 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 other than [SQLI
10080 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 TE_OK]..**.** ^T
10090 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 he sqlite3_initi
100a0 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 alize() routine
100b0 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e is called intern
100c0 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 ally by many oth
100d0 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 er.** SQLite int
100e0 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 erfaces so that
100f0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 an application u
10100 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 sually does not
10110 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b need to.** invok
10120 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
10130 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e lize() directly.
10140 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b For example, [
10150 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a sqlite3_open()].
10160 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 ** calls sqlite3
10170 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f _initialize() so
10180 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 the SQLite libr
10190 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f ary will be auto
101a0 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 matically.** ini
101b0 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 tialized when [s
101c0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 qlite3_open()] i
101d0 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 s called if it h
101e0 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 as not be initia
101f0 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 lized.** already
10200 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 . ^However, if
10210 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
10220 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c ed with the [SQL
10230 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 ITE_OMIT_AUTOINI
10240 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 T].** compile-ti
10250 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 me option, then
10260 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 the automatic ca
10270 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 lls to sqlite3_i
10280 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 nitialize().** a
10290 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 re omitted and t
102a0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d he application m
102b0 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 ust call sqlite3
102c0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 _initialize() di
102d0 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 rectly.** prior
102e0 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 to using any oth
102f0 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 er SQLite interf
10300 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 ace. For maximu
10310 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a m portability,.*
10320 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e * it is recommen
10330 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 ded that applica
10340 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 tions always inv
10350 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 oke sqlite3_init
10360 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 ialize().** dire
10370 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 ctly prior to us
10380 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 ing any other SQ
10390 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 Lite interface.
103a0 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 Future releases
103b0 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 .** of SQLite ma
103c0 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 y require this.
103d0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c In other words,
103e0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 the behavior ex
103f0 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 hibited.** when
10400 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
10410 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f ed with [SQLITE_
10420 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d OMIT_AUTOINIT] m
10430 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a ight become the.
10440 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 ** default behav
10450 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 ior in some futu
10460 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 re release of SQ
10470 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 Lite..**.** The
10480 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
10490 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f ) routine does o
104a0 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 perating-system
104b0 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 specific.** init
104c0 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 ialization of th
104d0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 e SQLite library
104e0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f . The sqlite3_o
104f0 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 s_end().** routi
10500 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 ne undoes the ef
10510 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f fect of sqlite3_
10520 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 os_init(). Typi
10530 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 cal tasks.** per
10540 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 formed by these
10550 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 routines include
10560 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 allocation or d
10570 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f eallocation.** o
10580 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 f static resourc
10590 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 es, initializati
105a0 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 on of global var
105b0 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 iables,.** setti
105c0 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 ng up a default
105d0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f [sqlite3_vfs] mo
105e0 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 dule, or setting
105f0 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 up.** a default
10600 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 configuration u
10610 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f sing [sqlite3_co
10620 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 nfig()]..**.** T
10630 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 he application s
10640 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f hould never invo
10650 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 ke either sqlite
10660 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 3_os_init().** o
10670 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 r sqlite3_os_end
10680 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 () directly. Th
10690 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 e application sh
106a0 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 ould only invoke
106b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 .** sqlite3_init
106c0 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c ialize() and sql
106d0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e ite3_shutdown().
106e0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 The sqlite3_os
106f0 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 _init().** inter
10700 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 face is called a
10710 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 utomatically by
10720 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
10730 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 ze() and.** sqli
10740 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 te3_os_end() is
10750 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 called by sqlite
10760 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 3_shutdown(). A
10770 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d ppropriate.** im
10780 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f plementations fo
10790 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 r sqlite3_os_ini
107a0 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f t() and sqlite3_
107b0 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 os_end().** are
107c0 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 built into SQLit
107d0 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d e when it is com
107e0 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 piled for Unix,
107f0 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 Windows, or OS/2
10800 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f ..** When [custo
10810 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 m builds | built
10820 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 for other platf
10830 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 orms].** (using
10840 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f the [SQLITE_OS_O
10850 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d THER=1] compile-
10860 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 time.** option)
10870 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
10880 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 must supply a su
10890 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 itable implement
108a0 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c ation for.** sql
108b0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 ite3_os_init() a
108c0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e nd sqlite3_os_en
108d0 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 d(). An applica
108e0 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a tion-supplied.**
108f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
10900 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e of sqlite3_os_in
10910 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f it() or sqlite3_
10920 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 os_end().** must
10930 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
10940 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 OK] on success a
10950 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 nd some other [e
10960 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a rror code] upon.
10970 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 ** failure..*/.i
10980 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 nt sqlite3_initi
10990 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 alize(void);.int
109a0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
109b0 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c n(void);.int sql
109c0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 ite3_os_init(voi
109d0 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f d);.int sqlite3_
109e0 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f os_end(void);../
109f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
10a00 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 onfiguring The S
10a10 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a QLite Library.**
10a20 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
10a30 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 config() interfa
10a40 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 ce is used to ma
10a50 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 ke global config
10a60 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 uration.** chang
10a70 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 es to SQLite in
10a80 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 order to tune SQ
10a90 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 Lite to the spec
10aa0 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a ific needs of.**
10ab0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
10ac0 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 . The default c
10ad0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 onfiguration is
10ae0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 recommended for
10af0 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 most.** applicat
10b00 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 ions and so this
10b10 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 routine is usua
10b20 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 lly not necessar
10b30 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f y. It is.** pro
10b40 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 vided to support
10b50 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f rare applicatio
10b60 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 ns with unusual
10b70 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e needs..**.** <b>
10b80 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 The sqlite3_conf
10b90 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 ig() interface i
10ba0 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 s not threadsafe
10bb0 2e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f . The applicatio
10bc0 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 n.** must ensure
10bd0 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 that no other S
10be0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 QLite interfaces
10bf0 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 are invoked by
10c00 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 other.** threads
10c10 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 while sqlite3_c
10c20 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 onfig() is runni
10c30 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 ng.</b>.**.** Th
10c40 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 e sqlite3_config
10c50 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 () interface.**
10c60 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f may only be invo
10c70 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 ked prior to lib
10c80 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 rary initializat
10c90 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 ion using.** [sq
10ca0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
10cb0 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 ()] or after shu
10cc0 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 tdown by [sqlite
10cd0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 3_shutdown()]..*
10ce0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f * ^If sqlite3_co
10cf0 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 nfig() is called
10d00 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f after [sqlite3_
10d10 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e initialize()] an
10d20 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c d before.** [sql
10d30 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d ite3_shutdown()]
10d40 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 then it will re
10d50 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 turn SQLITE_MISU
10d60 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 SE..** Note, how
10d70 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 ever, that ^sqli
10d80 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e te3_config() can
10d90 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 be called as pa
10da0 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 rt of the.** imp
10db0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 lementation of a
10dc0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 n application-de
10dd0 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f fined [sqlite3_o
10de0 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a s_init()]..**.**
10df0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
10e00 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 ent to sqlite3_c
10e10 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e onfig() is an in
10e20 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 teger.** [config
10e30 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 uration option]
10e40 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a that determines.
10e50 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 ** what property
10e60 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f of SQLite is to
10e70 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 be configured.
10e80 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 Subsequent argu
10e90 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 ments.** vary de
10ea0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b pending on the [
10eb0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
10ec0 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 tion].** in the
10ed0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a first argument..
10ee0 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f **.** ^When a co
10ef0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
10f00 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 on is set, sqlit
10f10 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 e3_config() retu
10f20 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e rns [SQLITE_OK].
10f30 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 .** ^If the opti
10f40 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 on is unknown or
10f50 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c SQLite is unabl
10f60 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 e to set the opt
10f70 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 ion.** then this
10f80 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
10f90 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 a non-zero [err
10fa0 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 or code]..*/.int
10fb0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
10fc0 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a int, ...);../*.*
10fd0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 * CAPI3REF: Conf
10fe0 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 igure database c
10ff0 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 onnections.** ME
11000 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a THOD: sqlite3.**
11010 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
11020 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 db_config() inte
11030 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f rface is used to
11040 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 make configurat
11050 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 ion.** changes t
11060 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f o a [database co
11070 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 nnection]. The
11080 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d interface is sim
11090 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 ilar to.** [sqli
110a0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 te3_config()] ex
110b0 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 cept that the ch
110c0 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 anges apply to a
110d0 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 single.** [data
110e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
110f0 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 (specified in t
11100 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
11110 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 t)..**.** The se
11120 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
11130 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 sqlite3_db_conf
11140 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 ig(D,V,...) is
11150 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 the.** [SQLITE_D
11160 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
11170 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f E | configuratio
11180 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 n verb] - an int
11190 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 eger code .** th
111a0 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 at indicates wha
111b0 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 t aspect of the
111c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
111d0 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 tion] is being c
111e0 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 onfigured..** Su
111f0 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e bsequent argumen
11200 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e ts vary dependin
11210 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 g on the configu
11220 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a ration verb..**.
11230 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c ** ^Calls to sql
11240 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
11250 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f return SQLITE_O
11260 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 K if and only if
11270 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 .** the call is
11280 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 considered succe
11290 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ssful..*/.int sq
112a0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
112b0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 sqlite3*, int op
112c0 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 , ...);../*.** C
112d0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 API3REF: Memory
112e0 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 Allocation Routi
112f0 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 nes.**.** An ins
11300 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 tance of this ob
11310 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 ject defines the
11320 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 interface betwe
11330 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 en SQLite.** and
11340 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 low-level memor
11350 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 y allocation rou
11360 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 tines..**.** Thi
11370 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 s object is used
11380 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 in only one pla
11390 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 ce in the SQLite
113a0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 interface..** A
113b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
113c0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
113d0 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 object is the ar
113e0 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 gument to.** [sq
113f0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
11400 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 when the configu
11410 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 ration option is
11420 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 .** [SQLITE_CONF
11430 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 IG_MALLOC] or [S
11440 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
11450 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 MALLOC]. .** By
11460 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 creating an ins
11470 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 tance of this ob
11480 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 ject.** and pass
11490 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 ing it to [sqlit
114a0 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 e3_config]([SQLI
114b0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
114c0 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e ]).** during con
114d0 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 figuration, an a
114e0 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 pplication can s
114f0 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e pecify an altern
11500 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 ative.** memory
11510 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 allocation subsy
11520 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 stem for SQLite
11530 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f to use for all o
11540 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 f its.** dynamic
11550 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a memory needs..*
11560 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 *.** Note that S
11570 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 QLite comes with
11580 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d several [built-
11590 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 in memory alloca
115a0 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 tors].** that ar
115b0 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 e perfectly adeq
115c0 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 uate for the ove
115d0 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 rwhelming majori
115e0 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f ty of applicatio
115f0 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 ns.** and that t
11600 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e his object is on
11610 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 ly useful to a t
11620 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 iny minority of
11630 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 applications.**
11640 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 with specialized
11650 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
11660 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e on requirements.
11670 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 This object is
11680 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 .** also used du
11690 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 ring testing of
116a0 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 SQLite in order
116b0 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c to specify an al
116c0 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d ternative.** mem
116d0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 ory allocator th
116e0 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d at simulates mem
116f0 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 ory out-of-memor
11700 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a y conditions in.
11710 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 ** order to veri
11720 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 fy that SQLite r
11730 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c ecovers graceful
11740 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 ly from such.**
11750 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a conditions..**.*
11760 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 * The xMalloc, x
11770 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 Realloc, and xFr
11780 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 ee methods must
11790 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a work like the.**
117a0 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c malloc(), reall
117b0 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 oc() and free()
117c0 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 functions from t
117d0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 he standard C li
117e0 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 brary..** ^SQLit
117f0 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 e guarantees tha
11800 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 t the second arg
11810 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 ument to.** xRea
11820 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 lloc is always a
11830 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
11840 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 by a prior call
11850 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a to xRoundup..**.
11860 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 ** xSize should
11870 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 return the alloc
11880 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d ated size of a m
11890 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
118a0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f .** previously o
118b0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 btained from xMa
118c0 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 lloc or xRealloc
118d0 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 . The allocated
118e0 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 size.** is alwa
118f0 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 ys at least as b
11900 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 ig as the reques
11910 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 ted size but may
11920 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a be larger..**.*
11930 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d * The xRoundup m
11940 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 ethod returns wh
11950 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 at would be the
11960 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f allocated size o
11970 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c f.** a memory al
11980 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 location given a
11990 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 particular requ
119a0 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 ested size. Mos
119b0 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f t memory.** allo
119c0 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 cators round up
119d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
119e0 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 ns at least to t
119f0 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 he next multiple
11a00 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 .** of 8. Some
11a10 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 allocators round
11a20 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 up to a larger
11a30 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 multiple or to a
11a40 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 power of 2..**
11a50 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c Every memory all
11a60 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 ocation request
11a70 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 coming in throug
11a80 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f h [sqlite3_mallo
11a90 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 c()].** or [sqli
11aa0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 te3_realloc()] f
11ab0 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e irst calls xRoun
11ac0 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 dup. If xRoundu
11ad0 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a p returns 0, .**
11ae0 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 that causes the
11af0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d corresponding m
11b00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
11b10 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 to fail..**.**
11b20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 The xInit method
11b30 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 initializes the
11b40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
11b50 72 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c r. For example,
11b60 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c .** it might all
11b70 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 ocate any requir
11b80 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 e mutexes or ini
11b90 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c tialize internal
11ba0 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 data.** structu
11bb0 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 res. The xShutd
11bc0 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e own method is in
11bd0 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c voked (indirectl
11be0 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 y) by.** [sqlite
11bf0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 3_shutdown()] an
11c00 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 d should dealloc
11c10 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 ate any resource
11c20 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 s acquired.** by
11c30 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 xInit. The pAp
11c40 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 pData pointer is
11c50 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c used as the onl
11c60 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a y parameter to.*
11c70 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 * xInit and xShu
11c80 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c tdown..**.** SQL
11c90 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 ite holds the [S
11ca0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 QLITE_MUTEX_STAT
11cb0 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 IC_MASTER] mutex
11cc0 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 when it invokes
11cd0 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 .** the xInit me
11ce0 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e thod, so the xIn
11cf0 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e it method need n
11d00 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 ot be threadsafe
11d10 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 . The.** xShutd
11d20 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e own method is on
11d30 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b ly called from [
11d40 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
11d50 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a ()] so it does.*
11d60 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 * not need to be
11d70 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 threadsafe eith
11d80 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 er. For all oth
11d90 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 er methods, SQLi
11da0 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 te.** holds the
11db0 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 [SQLITE_MUTEX_ST
11dc0 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 ATIC_MEM] mutex
11dd0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a as long as the.*
11de0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 * [SQLITE_CONFIG
11df0 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 _MEMSTATUS] conf
11e00 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
11e10 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 is turned on (w
11e20 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 hich.** it is by
11e30 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f default) and so
11e40 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 the methods are
11e50 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 automatically s
11e60 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f erialized..** Ho
11e70 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 wever, if [SQLIT
11e80 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
11e90 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c US] is disabled,
11ea0 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a then the other.
11eb0 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 ** methods must
11ec0 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 be threadsafe or
11ed0 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 else make their
11ee0 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 own arrangement
11ef0 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 s for.** seriali
11f00 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 zation..**.** SQ
11f10 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 Lite will never
11f20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d invoke xInit() m
11f30 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 ore than once wi
11f40 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 thout an interve
11f50 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 ning.** call to
11f60 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a xShutdown()..*/.
11f70 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
11f80 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
11f90 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d ds sqlite3_mem_m
11fa0 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 ethods;.struct s
11fb0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
11fc0 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 ds {. void *(*x
11fd0 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 Malloc)(int);
11fe0 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 /* Memory
11ff0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 allocation funct
12000 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a ion */. void (*
12010 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 xFree)(void*);
12020 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 /* Free
12030 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 a prior allocati
12040 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a on */. void *(*
12050 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c xRealloc)(void*,
12060 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 int); /* Resize
12070 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a an allocation *
12080 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 /. int (*xSize)
12090 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 (void*);
120a0 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 /* Return the
120b0 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f size of an allo
120c0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 cation */. int
120d0 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 (*xRoundup)(int)
120e0 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f ; /* Ro
120f0 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 und up request s
12100 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f ize to allocatio
12110 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 n size */. int
12120 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b (*xInit)(void*);
12130 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e /* In
12140 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d itialize the mem
12150 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f ory allocator */
12160 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 . void (*xShutd
12170 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 own)(void*);
12180 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a /* Deinitializ
12190 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c e the memory all
121a0 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 ocator */. void
121b0 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 *pAppData;
121c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 /* Ar
121d0 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 gument to xInit(
121e0 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 ) and xShutdown(
121f0 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ) */.};../*.** C
12200 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 API3REF: Configu
12210 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a ration Options.*
12220 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e * KEYWORDS: {con
12230 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
12240 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 n}.**.** These c
12250 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 onstants are the
12260 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 available integ
12270 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e er configuration
12280 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a options that.**
12290 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 can be passed a
122a0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 s the first argu
122b0 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c ment to the [sql
122c0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 ite3_config()] i
122d0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 nterface..**.**
122e0 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f New configuratio
122f0 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 n options may be
12300 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 added in future
12310 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c releases of SQL
12320 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 ite..** Existing
12330 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
12340 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 ptions might be
12350 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 discontinued. A
12360 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 pplications.** s
12370 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 hould check the
12380 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d return code from
12390 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
123a0 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 ()] to make sure
123b0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c that.** the cal
123c0 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b l worked. The [
123d0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
123e0 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c ] interface will
123f0 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e return a.** non
12400 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 -zero [error cod
12410 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 e] if a disconti
12420 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 nued or unsuppor
12430 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ted configuratio
12440 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 n option.** is i
12450 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 nvoked..**.** <d
12460 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 l>.** [[SQLITE_C
12470 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
12480 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f AD]] <dt>SQLITE_
12490 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 CONFIG_SINGLETHR
124a0 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e EAD</dt>.** <dd>
124b0 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 There are no arg
124c0 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f uments to this o
124d0 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 ption. ^This op
124e0 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a tion sets the.**
124f0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
12500 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 ] to Single-thre
12510 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f ad. In other wo
12520 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 rds, it disables
12530 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 .** all mutexing
12540 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 and puts SQLite
12550 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 into a mode whe
12560 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 re it can only b
12570 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 e used.** by a s
12580 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 ingle thread.
12590 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f ^If SQLite is co
125a0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 mpiled with.** t
125b0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 he [SQLITE_THREA
125c0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 DSAFE | SQLITE_T
125d0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d HREADSAFE=0] com
125e0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
125f0 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e then.** it is n
12600 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 ot possible to c
12610 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 hange the [threa
12620 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 ding mode] from
12630 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 its default.** v
12640 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 alue of Single-t
12650 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 hread and so [sq
12660 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
12670 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 will return .**
12680 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 [SQLITE_ERROR] i
12690 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 f called with th
126a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
126b0 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 SINGLETHREAD.**
126c0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
126d0 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a tion.</dd>.**.**
126e0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
126f0 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c _MULTITHREAD]] <
12700 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
12710 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 _MULTITHREAD</dt
12720 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 >.** <dd>There a
12730 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 re no arguments
12740 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 to this option.
12750 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 ^This option se
12760 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 ts the.** [threa
12770 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 ding mode] to Mu
12780 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 lti-thread. In
12790 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 other words, it
127a0 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 disables.** mute
127b0 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 xing on [databas
127c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e e connection] an
127d0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
127e0 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a ement] objects..
127f0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
12800 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c on is responsibl
12810 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e e for serializin
12820 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b g access to.** [
12830 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
12840 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 ions] and [prepa
12850 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e red statements].
12860 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 But other mute
12870 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c xes.** are enabl
12880 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 ed so that SQLit
12890 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 e will be safe t
128a0 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 o use in a multi
128b0 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 -threaded.** env
128c0 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 ironment as long
128d0 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 as no two threa
128e0 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 ds attempt to us
128f0 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 e the same.** [d
12900 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
12910 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 on] at the same
12920 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 time. ^If SQLit
12930 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
12940 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 th.** the [SQLIT
12950 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 E_THREADSAFE | S
12960 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
12970 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 =0] compile-time
12980 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 option then.**
12990 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 it is not possib
129a0 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 le to set the Mu
129b0 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 lti-thread [thre
129c0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a ading mode] and.
129d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ** [sqlite3_conf
129e0 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 ig()] will retur
129f0 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d n [SQLITE_ERROR]
12a00 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 if called with
12a10 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f the.** SQLITE_CO
12a20 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 NFIG_MULTITHREAD
12a30 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
12a40 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ption.</dd>.**.*
12a50 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
12a60 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c G_SERIALIZED]] <
12a70 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
12a80 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e _SERIALIZED</dt>
12a90 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 .** <dd>There ar
12aa0 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 e no arguments t
12ab0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 o this option.
12ac0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 ^This option set
12ad0 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 s the.** [thread
12ae0 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 ing mode] to Ser
12af0 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 ialized. In othe
12b00 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 r words, this op
12b10 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 tion enables.**
12b20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c all mutexes incl
12b30 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 uding the recurs
12b40 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f ive.** mutexes o
12b50 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e n [database conn
12b60 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 ection] and [pre
12b70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
12b80 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 objects..** In
12b90 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 this mode (which
12ba0 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 is the default
12bb0 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 when SQLite is c
12bc0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 ompiled with.**
12bd0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
12be0 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 FE=1]) the SQLit
12bf0 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 e library will i
12c00 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 tself serialize
12c10 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 access.** to [da
12c20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
12c30 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 ns] and [prepare
12c40 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f d statements] so
12c50 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 that the.** app
12c60 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 lication is free
12c70 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 to use the same
12c80 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
12c90 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a ction] or the.**
12ca0 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 same [prepared
12cb0 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 statement] in di
12cc0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 fferent threads
12cd0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 at the same time
12ce0 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 ..** ^If SQLite
12cf0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
12d00 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f .** the [SQLITE_
12d10 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c THREADSAFE | SQL
12d20 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 ITE_THREADSAFE=0
12d30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
12d40 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 ption then.** it
12d50 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 is not possible
12d60 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 to set the Seri
12d70 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e alized [threadin
12d80 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b g mode] and.** [
12d90 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
12da0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 ] will return [S
12db0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 QLITE_ERROR] if
12dc0 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a called with the.
12dd0 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ** SQLITE_CONFIG
12de0 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 _SERIALIZED conf
12df0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
12e00 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 .</dd>.**.** [[S
12e10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
12e20 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 LOC]] <dt>SQLITE
12e30 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f _CONFIG_MALLOC</
12e40 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 dt>.** <dd> ^(Th
12e50 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
12e60 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 MALLOC option ta
12e70 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
12e80 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a ument which is .
12e90 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ** a pointer to
12ea0 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 an instance of t
12eb0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f he [sqlite3_mem_
12ec0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
12ed0 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d re..** The argum
12ee0 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a ent specifies.**
12ef0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 alternative low
12f00 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c -level memory al
12f10 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 location routine
12f20 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 s to be used in
12f30 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 place of.** the
12f40 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
12f50 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 n routines built
12f60 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 into SQLite.)^
12f70 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a ^SQLite makes.**
12f80 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 its own private
12f90 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e copy of the con
12fa0 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c tent of the [sql
12fb0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
12fc0 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 ] structure.** b
12fd0 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 efore the [sqlit
12fe0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c e3_config()] cal
12ff0 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a l returns.</dd>.
13000 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
13010 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d ONFIG_GETMALLOC]
13020 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
13030 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 FIG_GETMALLOC</d
13040 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 t>.** <dd> ^(The
13050 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 SQLITE_CONFIG_G
13060 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 ETMALLOC option
13070 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
13080 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a rgument which.**
13090 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
130a0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 an instance of
130b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d the [sqlite3_mem
130c0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
130d0 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c ure..** The [sql
130e0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
130f0 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 ].** structure i
13100 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 s filled with th
13110 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 e currently defi
13120 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ned memory alloc
13130 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 ation routines.)
13140 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e ^.** This option
13150 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
13160 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 overload the def
13170 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ault memory allo
13180 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e cation.** routin
13190 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 es with a wrappe
131a0 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f r that simulatio
131b0 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ns memory alloca
131c0 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a tion failure or.
131d0 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 ** tracks memory
131e0 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d usage, for exam
131f0 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ple. </dd>.**.**
13200 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
13210 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 _MEMSTATUS]] <dt
13220 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d >SQLITE_CONFIG_M
13230 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a EMSTATUS</dt>.**
13240 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 <dd> ^The SQLIT
13250 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
13260 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 US option takes
13270 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
13280 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 of type int,.**
13290 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 interpreted as a
132a0 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 boolean, which
132b0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 enables or disab
132c0 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 les the collecti
132d0 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 on of.** memory
132e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 allocation stati
132f0 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 stics. ^(When me
13300 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
13310 73 74 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a statistics are.*
13320 2a 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 * disabled, the
13330 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 following SQLite
13340 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f interfaces beco
13350 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e me non-operation
13360 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a al:.** <ul>.**
13370 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 <li> [sqlite3
13380 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a _memory_used()].
13390 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 ** <li> [sqlit
133a0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
133b0 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e ter()].** <li>
133c0 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 [sqlite3_soft_h
133d0 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a eap_limit64()].*
133e0 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 * <li> [sqlite
133f0 33 5f 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 3_status64()].**
13400 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d </ul>)^.** ^M
13410 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
13420 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 statistics are
13430 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 enabled by defau
13440 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 lt unless SQLite
13450 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 is.** compiled
13460 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 with [SQLITE_DEF
13470 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d AULT_MEMSTATUS]=
13480 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 0 in which case
13490 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 memory.** alloca
134a0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 tion statistics
134b0 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 are disabled by
134c0 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 default..** </dd
134d0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
134e0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d _CONFIG_SCRATCH]
134f0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
13500 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e FIG_SCRATCH</dt>
13510 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 .** <dd> ^The SQ
13520 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 LITE_CONFIG_SCRA
13530 54 43 48 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 TCH option speci
13540 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 fies a static me
13550 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a 20 74 mory buffer.** t
13560 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 hat SQLite can u
13570 73 65 20 66 6f 72 20 73 63 72 61 74 63 68 20 6d se for scratch m
13580 65 6d 6f 72 79 2e 20 20 5e 28 54 68 65 72 65 20 emory. ^(There
13590 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 are three argume
135a0 6e 74 73 0a 2a 2a 20 74 6f 20 53 51 4c 49 54 45 nts.** to SQLITE
135b0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3a _CONFIG_SCRATCH:
135c0 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 A pointer an 8
135d0 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 -byte.** aligned
135e0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 memory buffer f
135f0 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 rom which the sc
13600 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e ratch allocation
13610 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 s will be.** dra
13620 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 wn, the size of
13630 65 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c each scratch all
13640 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a ocation (sz),.**
13650 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d and the maximum
13660 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 number of scrat
13670 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 ch allocations (
13680 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65 20 66 69 72 N).)^.** The fir
13690 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 st argument must
136a0 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f be a pointer to
136b0 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e an 8-byte align
136c0 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 ed buffer.** of
136d0 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 at least sz*N by
136e0 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a tes of memory..*
136f0 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e * ^SQLite will n
13700 6f 74 20 75 73 65 20 6d 6f 72 65 20 74 68 61 6e ot use more than
13710 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 one scratch buf
13720 66 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e fers per thread.
13730 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c .** ^SQLite will
13740 20 6e 65 76 65 72 20 72 65 71 75 65 73 74 20 61 never request a
13750 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 scratch buffer
13760 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 that is more tha
13770 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 n 6.** times the
13780 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 database page s
13790 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 ize..** ^If SQLi
137a0 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 te needs needs a
137b0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 dditional.** scr
137c0 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f atch memory beyo
137d0 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 nd what is provi
137e0 64 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 ded by this conf
137f0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
13800 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 , then .** [sqli
13810 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 te3_malloc()] wi
13820 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 ll be used to ob
13830 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 tain the memory
13840 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 needed.<p>.** ^W
13850 68 65 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74 hen the applicat
13860 69 6f 6e 20 70 72 6f 76 69 64 65 73 20 61 6e 79 ion provides any
13870 20 61 6d 6f 75 6e 74 20 6f 66 20 73 63 72 61 74 amount of scrat
13880 63 68 20 6d 65 6d 6f 72 79 20 75 73 69 6e 67 0a ch memory using.
13890 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ** SQLITE_CONFIG
138a0 5f 53 43 52 41 54 43 48 2c 20 53 51 4c 69 74 65 _SCRATCH, SQLite
138b0 20 61 76 6f 69 64 73 20 75 6e 6e 65 63 65 73 73 avoids unnecess
138c0 61 72 79 20 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 ary large.** [sq
138d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 lite3_malloc|hea
138e0 70 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a p allocations]..
138f0 2a 2a 20 54 68 69 73 20 63 61 6e 20 68 65 6c 70 ** This can help
13900 20 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 [Robson proof|p
13910 72 65 76 65 6e 74 20 6d 65 6d 6f 72 79 20 61 6c revent memory al
13920 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 location failure
13930 73 5d 20 64 75 65 20 74 6f 20 68 65 61 70 0a 2a s] due to heap.*
13940 2a 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 * fragmentation
13950 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d in low-memory em
13960 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 0a bedded systems..
13970 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b ** </dd>.**.** [
13980 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 [SQLITE_CONFIG_P
13990 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 AGECACHE]] <dt>S
139a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 QLITE_CONFIG_PAG
139b0 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c ECACHE</dt>.** <
139c0 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f dd> ^The SQLITE_
139d0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
139e0 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 option specifie
139f0 73 20 61 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a s a memory pool.
13a00 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 ** that SQLite c
13a10 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65 20 64 an use for the d
13a20 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63 atabase page cac
13a30 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61 he with the defa
13a40 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 ult page.** cach
13a50 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
13a60 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 . .** This conf
13a70 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
13a80 20 69 73 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61 is a no-op if a
13a90 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 n application-de
13aa0 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 fine page.** cac
13ab0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
13ac0 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e n is loaded usin
13ad0 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f g the [SQLITE_CO
13ae0 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a NFIG_PCACHE2]..*
13af0 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 * ^There are thr
13b00 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 ee arguments to
13b10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 SQLITE_CONFIG_PA
13b20 47 45 43 41 43 48 45 3a 20 41 20 70 6f 69 6e 74 GECACHE: A point
13b30 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 er to.** 8-byte
13b40 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28 aligned memory (
13b50 70 4d 65 6d 29 2c 20 74 68 65 20 73 69 7a 65 20 pMem), the size
13b60 6f 66 20 65 61 63 68 20 70 61 67 65 20 63 61 63 of each page cac
13b70 68 65 20 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a he line (sz),.**
13b80 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 and the number
13b90 6f 66 20 63 61 63 68 65 20 6c 69 6e 65 73 20 28 of cache lines (
13ba0 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 N)..** The sz ar
13bb0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 gument should be
13bc0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 the size of the
13bd0 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73 largest databas
13be0 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 e page.** (a pow
13bf0 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 er of two betwee
13c00 6e 20 35 31 32 20 61 6e 64 20 36 35 35 33 36 29 n 512 and 65536)
13c10 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 74 72 61 plus some extra
13c20 20 62 79 74 65 73 20 66 6f 72 20 65 61 63 68 0a bytes for each.
13c30 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 ** page header.
13c40 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 ^The number of
13c50 65 78 74 72 61 20 62 79 74 65 73 20 6e 65 65 64 extra bytes need
13c60 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20 68 ed by the page h
13c70 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20 eader.** can be
13c80 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 determined using
13c90 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
13ca0 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a PCACHE_HDRSZ]..*
13cb0 2a 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 * ^It is harmles
13cc0 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 s, apart from th
13cd0 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c e wasted memory,
13ce0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70 .** for the sz p
13cf0 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c arameter to be l
13d00 61 72 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73 arger than neces
13d10 73 61 72 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a sary. The pMem.
13d20 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 ** argument must
13d30 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c be either a NUL
13d40 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 20 70 L pointer or a p
13d50 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 ointer to an 8-b
13d60 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62 yte.** aligned b
13d70 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f lock of memory o
13d80 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 f at least sz*N
13d90 62 79 74 65 73 2c 20 6f 74 68 65 72 77 69 73 65 bytes, otherwise
13da0 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 62 .** subsequent b
13db0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 ehavior is undef
13dc0 69 6e 65 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 ined..** ^When p
13dd0 4d 65 6d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c Mem is not NULL,
13de0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 73 74 72 SQLite will str
13df0 69 76 65 20 74 6f 20 75 73 65 20 74 68 65 20 6d ive to use the m
13e00 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 0a 2a emory provided.*
13e10 2a 20 74 6f 20 73 61 74 69 73 66 79 20 70 61 67 * to satisfy pag
13e20 65 20 63 61 63 68 65 20 6e 65 65 64 73 2c 20 66 e cache needs, f
13e30 61 6c 6c 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b alling back to [
13e40 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
13e50 5d 20 69 66 0a 2a 2a 20 61 20 70 61 67 65 20 63 ] if.** a page c
13e60 61 63 68 65 20 6c 69 6e 65 20 69 73 20 6c 61 72 ache line is lar
13e70 67 65 72 20 74 68 61 6e 20 73 7a 20 62 79 74 65 ger than sz byte
13e80 73 20 6f 72 20 69 66 20 61 6c 6c 20 6f 66 20 74 s or if all of t
13e90 68 65 20 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a he pMem buffer.*
13ea0 2a 20 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a * is exhausted..
13eb0 2a 2a 20 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e ** ^If pMem is N
13ec0 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e ULL and N is non
13ed0 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 65 61 63 68 -zero, then each
13ee0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
13ef0 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 tion.** does an
13f00 69 6e 69 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c initial bulk all
13f10 6f 63 61 74 69 6f 6e 20 66 6f 72 20 70 61 67 65 ocation for page
13f20 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a cache memory.**
13f30 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
13f40 61 6c 6c 6f 63 28 29 5d 20 73 75 66 66 69 63 69 alloc()] suffici
13f50 65 6e 74 20 66 6f 72 20 4e 20 63 61 63 68 65 20 ent for N cache
13f60 6c 69 6e 65 73 20 69 66 20 4e 20 69 73 20 70 6f lines if N is po
13f70 73 69 74 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 sitive or.** of
13f80 2d 31 30 32 34 2a 4e 20 62 79 74 65 73 20 69 66 -1024*N bytes if
13f90 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 N is negative,
13fa0 2e 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c . ^If additional
13fb0 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d .** page cache m
13fc0 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 emory is needed
13fd0 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 beyond what is p
13fe0 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 69 rovided by the i
13ff0 6e 69 74 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 nitial.** alloca
14000 74 69 6f 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74 tion, then SQLit
14010 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 e goes to [sqlit
14020 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70 e3_malloc()] sep
14030 61 72 61 74 65 6c 79 20 66 6f 72 20 65 61 63 68 arately for each
14040 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 .** additional c
14050 61 63 68 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e ache line. </dd>
14060 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
14070 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 CONFIG_HEAP]] <d
14080 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
14090 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 HEAP</dt>.** <dd
140a0 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f > ^The SQLITE_CO
140b0 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e NFIG_HEAP option
140c0 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 specifies a sta
140d0 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 tic memory buffe
140e0 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 r .** that SQLit
140f0 65 20 77 69 6c 6c 20 75 73 65 20 66 6f 72 20 61 e will use for a
14100 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 ll of its dynami
14110 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 c memory allocat
14120 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79 ion needs.** bey
14130 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 ond those provid
14140 65 64 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 ed for by [SQLIT
14150 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 E_CONFIG_SCRATCH
14160 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 ] and.** [SQLITE
14170 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 _CONFIG_PAGECACH
14180 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 E]..** ^The SQLI
14190 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f TE_CONFIG_HEAP o
141a0 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 ption is only av
141b0 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 ailable if SQLit
141c0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a e is compiled.**
141d0 20 77 69 74 68 20 65 69 74 68 65 72 20 5b 53 51 with either [SQ
141e0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 LITE_ENABLE_MEMS
141f0 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f YS3] or [SQLITE_
14200 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 ENABLE_MEMSYS5]
14210 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b and returns.** [
14220 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 SQLITE_ERROR] if
14230 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 invoked otherwi
14240 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 se..** ^There ar
14250 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 e three argument
14260 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 s to SQLITE_CONF
14270 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 IG_HEAP:.** An 8
14280 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f -byte aligned po
14290 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d inter to the mem
142a0 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 ory,.** the numb
142b0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
142c0 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 he memory buffer
142d0 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 , and the minimu
142e0 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a m allocation siz
142f0 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 e..** ^If the fi
14300 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 rst pointer (the
14310 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 memory pointer)
14320 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 is NULL, then S
14330 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a QLite reverts.**
14340 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 to using its de
14350 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c fault memory all
14360 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 ocator (the syst
14370 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c em malloc() impl
14380 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 ementation),.**
14390 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f undoing any prio
143a0 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 r invocation of
143b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
143c0 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 ALLOC]. ^If the
143d0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 .** memory point
143e0 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 er is not NULL t
143f0 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 hen the alternat
14400 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c ive memory.** al
14410 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 locator is engag
14420 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c ed to handle all
14430 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f of SQLites memo
14440 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 ry allocation ne
14450 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 eds..** The firs
14460 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d t pointer (the m
14470 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d emory pointer) m
14480 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 ust be aligned t
14490 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 o an 8-byte.** b
144a0 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 oundary or subse
144b0 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f quent behavior o
144c0 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 f SQLite will be
144d0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 undefined..** T
144e0 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 he minimum alloc
144f0 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 ation size is ca
14500 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 pped at 2**12. R
14510 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 easonable values
14520 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 .** for the mini
14530 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 mum allocation s
14540 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 ize are 2**5 thr
14550 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a ough 2**8.</dd>.
14560 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
14570 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 ONFIG_MUTEX]] <d
14580 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
14590 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 MUTEX</dt>.** <d
145a0 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f d> ^(The SQLITE_
145b0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 CONFIG_MUTEX opt
145c0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
145d0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 le argument whic
145e0 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 h is a.** pointe
145f0 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 r to an instance
14600 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
14610 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 _mutex_methods]
14620 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 structure..** Th
14630 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 e argument speci
14640 66 69 65 73 20 61 6c 74 65 72 6e 61 74 69 76 65 fies alternative
14650 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 low-level mutex
14660 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 routines to be
14670 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 used.** in place
14680 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 the mutex routi
14690 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 nes built into S
146a0 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 QLite.)^ ^SQLit
146b0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f e makes a copy o
146c0 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 f.** the content
146d0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
146e0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 _mutex_methods]
146f0 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 structure before
14700 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 the call to.**
14710 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
14720 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 )] returns. ^If
14730 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
14740 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b ed with.** the [
14750 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
14760 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 E | SQLITE_THREA
14770 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 DSAFE=0] compile
14780 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 -time option the
14790 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 n.** the entire
147a0 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 mutexing subsyst
147b0 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 em is omitted fr
147c0 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 om the build and
147d0 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a hence calls to.
147e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ** [sqlite3_conf
147f0 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 ig()] with the S
14800 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 QLITE_CONFIG_MUT
14810 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e EX configuration
14820 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 option will.**
14830 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 return [SQLITE_E
14840 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a RROR].</dd>.**.*
14850 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
14860 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 G_GETMUTEX]] <dt
14870 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 >SQLITE_CONFIG_G
14880 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 ETMUTEX</dt>.**
14890 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 <dd> ^(The SQLIT
148a0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 E_CONFIG_GETMUTE
148b0 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 X option takes a
148c0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
148d0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 which.** is a p
148e0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 ointer to an ins
148f0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 tance of the [sq
14900 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 lite3_mutex_meth
14910 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 ods] structure.
14920 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 The.** [sqlite3
14930 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a _mutex_methods].
14940 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 ** structure is
14950 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 filled with the
14960 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 currently define
14970 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 d mutex routines
14980 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 .)^.** This opti
14990 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 on can be used t
149a0 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 o overload the d
149b0 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c efault mutex all
149c0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 ocation.** routi
149d0 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 nes with a wrapp
149e0 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b er used to track
149f0 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 mutex usage for
14a00 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 performance.**
14a10 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 profiling or tes
14a20 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c ting, for exampl
14a30 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 e. ^If SQLite
14a40 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
14a50 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f .** the [SQLITE_
14a60 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c THREADSAFE | SQL
14a70 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 ITE_THREADSAFE=0
14a80 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
14a90 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 ption then.** th
14aa0 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e e entire mutexin
14ab0 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f g subsystem is o
14ac0 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 mitted from the
14ad0 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 build and hence
14ae0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c calls to.** [sql
14af0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 ite3_config()] w
14b00 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 ith the SQLITE_C
14b10 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 ONFIG_GETMUTEX c
14b20 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
14b30 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 ion will.** retu
14b40 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 rn [SQLITE_ERROR
14b50 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b ].</dd>.**.** [[
14b60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f SQLITE_CONFIG_LO
14b70 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 OKASIDE]] <dt>SQ
14b80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b LITE_CONFIG_LOOK
14b90 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ASIDE</dt>.** <d
14ba0 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f d> ^(The SQLITE_
14bb0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
14bc0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 option takes tw
14bd0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 o arguments that
14be0 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 determine.** th
14bf0 65 20 64 65 66 61 75 6c 74 20 73 69 7a 65 20 6f e default size o
14c00 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f f lookaside memo
14c10 72 79 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 ry on each [data
14c20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
14c30 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 ..** The first a
14c40 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a rgument is the.*
14c50 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c * size of each l
14c60 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 ookaside buffer
14c70 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 slot and the sec
14c80 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 ond is the numbe
14c90 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c r of.** slots al
14ca0 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 located to each
14cb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
14cc0 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 ion.)^ ^(SQLITE
14cd0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 _CONFIG_LOOKASID
14ce0 45 0a 2a 2a 20 73 65 74 73 20 74 68 65 20 3c 69 E.** sets the <i
14cf0 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f >default</i> loo
14d00 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 kaside size. The
14d10 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 [SQLITE_DBCONFI
14d20 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 G_LOOKASIDE].**
14d30 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 option to [sqlit
14d40 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 e3_db_config()]
14d50 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 can be used to c
14d60 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 hange the lookas
14d70 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 ide.** configura
14d80 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 tion on individu
14d90 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 al connections.)
14da0 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b ^ </dd>.**.** [[
14db0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
14dc0 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 ACHE2]] <dt>SQLI
14dd0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
14de0 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 2</dt>.** <dd> ^
14df0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 (The SQLITE_CONF
14e00 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f IG_PCACHE2 optio
14e10 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
14e20 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
14e30 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 is .** a pointer
14e40 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f to an [sqlite3_
14e50 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d pcache_methods2]
14e60 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f object. This o
14e70 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 0a bject specifies.
14e80 2a 2a 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 ** the interface
14e90 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 to a custom pag
14ea0 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e e cache implemen
14eb0 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 tation.)^.** ^SQ
14ec0 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 Lite makes a cop
14ed0 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 y of the [sqlite
14ee0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3_pcache_methods
14ef0 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2] object.</dd>.
14f00 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
14f10 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 ONFIG_GETPCACHE2
14f20 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
14f30 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c NFIG_GETPCACHE2<
14f40 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 /dt>.** <dd> ^(T
14f50 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
14f60 5f 47 45 54 50 43 41 43 48 45 32 20 6f 70 74 69 _GETPCACHE2 opti
14f70 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
14f80 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
14f90 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 .** is a pointer
14fa0 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f to an [sqlite3_
14fb0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d pcache_methods2]
14fc0 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 object. SQLite
14fd0 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 copies of.** th
14fe0 65 20 63 75 72 72 65 6e 74 20 70 61 67 65 20 63 e current page c
14ff0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ache implementat
15000 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 ion into that ob
15010 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a ject.)^ </dd>.**
15020 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
15030 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 FIG_LOG]] <dt>SQ
15040 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c LITE_CONFIG_LOG<
15050 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 /dt>.** <dd> The
15060 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c SQLITE_CONFIG_L
15070 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 OG option is use
15080 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 d to configure t
15090 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f he SQLite.** glo
150a0 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e bal [error log].
150b0 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45 .** (^The SQLITE
150c0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 _CONFIG_LOG opti
150d0 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 on takes two arg
150e0 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 uments: a pointe
150f0 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 r to a.** functi
15100 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 on with a call s
15110 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 ignature of void
15120 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f (*)(void*,int,co
15130 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 nst char*), .**
15140 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f and a pointer to
15150 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 void. ^If the f
15160 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 unction pointer
15170 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 is not NULL, it
15180 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 is.** invoked by
15190 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d [sqlite3_log()]
151a0 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 to process each
151b0 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 logging event.
151c0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 ^If the.** func
151d0 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 tion pointer is
151e0 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 NULL, the [sqlit
151f0 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 e3_log()] interf
15200 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f ace becomes a no
15210 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 -op..** ^The voi
15220 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 d pointer that i
15230 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 s the second arg
15240 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f ument to SQLITE_
15250 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a CONFIG_LOG is.**
15260 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 passed through
15270 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 as the first par
15280 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 ameter to the ap
15290 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
152a0 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 d logger.** func
152b0 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 tion whenever th
152c0 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 at function is i
152d0 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 nvoked. ^The se
152e0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 cond parameter t
152f0 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 o.** the logger
15300 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f function is a co
15310 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 py of the first
15320 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
15330 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a corresponding.*
15340 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 * [sqlite3_log()
15350 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e ] call and is in
15360 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b tended to be a [
15370 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 result code] or
15380 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 an.** [extended
15390 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e result code]. ^
153a0 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 The third parame
153b0 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 ter passed to th
153c0 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c e logger is.** l
153d0 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 og message after
153e0 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 formatting via
153f0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 [sqlite3_snprint
15400 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c f()]..** The SQL
15410 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 ite logging inte
15420 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 rface is not ree
15430 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 ntrant; the logg
15440 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 er function.** s
15450 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 upplied by the a
15460 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
15470 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 not invoke any S
15480 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e QLite interface.
15490 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 .** In a multi-t
154a0 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 hreaded applicat
154b0 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 ion, the applica
154c0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 tion-defined log
154d0 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ger.** function
154e0 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 must be threadsa
154f0 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 fe. </dd>.**.**
15500 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
15510 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 URI]] <dt>SQLITE
15520 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c _CONFIG_URI.** <
15530 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f dd>^(The SQLITE_
15540 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 6f CONFIG_URI optio
15550 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
15560 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 argument of typ
15570 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e e int..** If non
15580 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 -zero, then URI
15590 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 handling is glob
155a0 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 ally enabled. If
155b0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 the parameter i
155c0 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 s zero,.** then
155d0 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 URI handling is
155e0 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 globally disable
155f0 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e d.)^ ^If URI han
15600 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c dling is globall
15610 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c y.** enabled, al
15620 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 l filenames pass
15630 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f ed to [sqlite3_o
15640 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 pen()], [sqlite3
15650 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 _open_v2()],.**
15660 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 [sqlite3_open16(
15670 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 )] or.** specifi
15680 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 ed as part of [A
15690 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 TTACH] commands
156a0 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 are interpreted
156b0 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c as URIs, regardl
156c0 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 ess.** of whethe
156d0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 r or not the [SQ
156e0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 LITE_OPEN_URI] f
156f0 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 lag is set when
15700 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 the database.**
15710 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 connection is op
15720 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20 ened. ^If it is
15730 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 globally disable
15740 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 d, filenames are
15750 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 .** only interpr
15760 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20 eted as URIs if
15770 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f the SQLITE_OPEN_
15780 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 URI flag is set
15790 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 when the.** data
157a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
157b0 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 is opened. ^(By
157c0 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e default, URI han
157d0 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c dling is globall
157e0 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 y.** disabled. T
157f0 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 he default value
15800 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 may be changed
15810 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 by compiling wit
15820 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 h the.** [SQLITE
15830 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c _USE_URI] symbol
15840 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a defined.)^.**.*
15850 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
15860 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 G_COVERING_INDEX
15870 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 _SCAN]] <dt>SQLI
15880 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 TE_CONFIG_COVERI
15890 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a NG_INDEX_SCAN.**
158a0 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 <dd>^The SQLITE
158b0 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 _CONFIG_COVERING
158c0 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 _INDEX_SCAN opti
158d0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
158e0 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 e integer.** arg
158f0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 ument which is i
15900 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 nterpreted as a
15910 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 boolean in order
15920 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 to enable or di
15930 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 sable.** the use
15940 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 of covering ind
15950 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 ices for full ta
15960 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65 ble scans in the
15970 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 query optimizer
15980 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c ..** ^The defaul
15990 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 t setting is det
159a0 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 ermined.** by th
159b0 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f e [SQLITE_ALLOW_
159c0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 COVERING_INDEX_S
159d0 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d CAN] compile-tim
159e0 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 e option, or is
159f0 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 "on".** if that
15a00 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
15a10 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a ion is omitted..
15a20 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 ** The ability t
15a30 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 o disable the us
15a40 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e e of covering in
15a50 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 dices for full t
15a60 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 able scans.** is
15a70 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e because some in
15a80 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 correctly coded
15a90 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 legacy applicati
15aa0 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e ons might malfun
15ab0 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 ction.** when th
15ac0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 e optimization i
15ad0 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 s enabled. Prov
15ae0 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 iding the abilit
15af0 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 y to.** disable
15b00 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e the optimization
15b10 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 allows the olde
15b20 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 r, buggy applica
15b30 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 tion code to wor
15b40 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 k.** without cha
15b50 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 nge even with ne
15b60 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 wer versions of
15b70 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b SQLite..**.** [[
15b80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
15b90 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f ACHE]] [[SQLITE_
15ba0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 CONFIG_GETPCACHE
15bb0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 ]].** <dt>SQLITE
15bc0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 _CONFIG_PCACHE a
15bd0 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 nd SQLITE_CONFIG
15be0 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 _GETPCACHE.** <d
15bf0 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 d> These options
15c00 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e are obsolete an
15c10 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 d should not be
15c20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 used by new code
15c30 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 ..** They are re
15c40 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 tained for backw
15c50 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 ards compatibili
15c60 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e ty but are now n
15c70 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a o-ops..** </dd>.
15c80 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
15c90 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a ONFIG_SQLLOG]].*
15ca0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
15cb0 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 FIG_SQLLOG.** <d
15cc0 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 d>This option is
15cd0 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 only available
15ce0 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d if sqlite is com
15cf0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a piled with the.*
15d00 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 * [SQLITE_ENABLE
15d10 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f _SQLLOG] pre-pro
15d20 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 cessor macro def
15d30 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 ined. The first
15d40 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a argument should.
15d50 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 ** be a pointer
15d60 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 to a function of
15d70 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f type void(*)(vo
15d80 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e id*,sqlite3*,con
15d90 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a st char*, int)..
15da0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 ** The second sh
15db0 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 ould be of type
15dc0 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c (void*). The cal
15dd0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
15de0 20 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a by the library.
15df0 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 ** in three sepa
15e00 72 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 rate circumstanc
15e10 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 es, identified b
15e20 79 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 y the value pass
15e30 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 ed as the.** fou
15e40 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 rth parameter. I
15e50 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 f the fourth par
15e60 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 ameter is 0, the
15e70 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
15e80 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 onnection.** pas
15e90 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e sed as the secon
15ea0 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a d argument has j
15eb0 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e ust been opened.
15ec0 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d The third argum
15ed0 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f ent.** points to
15ee0 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 a buffer contai
15ef0 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 ning the name of
15f00 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 the main databa
15f10 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a se file. If the.
15f20 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 ** fourth parame
15f30 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 ter is 1, then t
15f40 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
15f50 20 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20 that the third
15f60 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 parameter.** poi
15f70 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 nts to has just
15f80 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f been executed. O
15f90 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 r, if the fourth
15fa0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c parameter is 2,
15fb0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e then.** the con
15fc0 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 nection being pa
15fd0 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f ssed as the seco
15fe0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
15ff0 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 being closed. Th
16000 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d e.** third param
16010 65 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e eter is passed N
16020 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 ULL In this case
16030 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 . An example of
16040 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 using this.** c
16050 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
16060 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20 ion can be seen
16070 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c in the "test_sql
16080 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69 log.c" source fi
16090 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e le in.** the can
160a0 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f onical SQLite so
160b0 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a urce tree.</dd>.
160c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
160d0 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d ONFIG_MMAP_SIZE]
160e0 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f ].** <dt>SQLITE_
160f0 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 CONFIG_MMAP_SIZE
16100 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f .** <dd>^SQLITE_
16110 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 CONFIG_MMAP_SIZE
16120 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 takes two 64-bi
16130 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74 t integer (sqlit
16140 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73 e3_int64) values
16150 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68 65 .** that are the
16160 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 default mmap si
16170 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 ze limit (the de
16180 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f fault setting fo
16190 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 r.** [PRAGMA mma
161a0 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 p_size]) and the
161b0 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 maximum allowed
161c0 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 mmap size limit
161d0 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c ..** ^The defaul
161e0 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 t setting can be
161f0 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 overridden by e
16200 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e ach database con
16210 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a nection using.**
16220 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 either the [PRA
16230 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 GMA mmap_size] c
16240 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 ommand, or by us
16250 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ing the.** [SQLI
16260 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 TE_FCNTL_MMAP_SI
16270 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c ZE] file control
16280 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d . ^(The maximum
16290 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 allowed mmap si
162a0 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 ze.** will be si
162b0 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 lently truncated
162c0 20 69 66 20 6e 65 63 65 73 73 61 72 79 20 73 6f if necessary so
162d0 20 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f that it does no
162e0 74 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 t exceed the.**
162f0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 compile-time max
16300 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 imum mmap size s
16310 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 et by the.** [SQ
16320 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 LITE_MAX_MMAP_SI
16330 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 ZE] compile-time
16340 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 option.)^.** ^I
16350 66 20 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e f either argumen
16360 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e t to this option
16370 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 is negative, th
16380 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74 en that argument
16390 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 is.** changed t
163a0 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 o its compile-ti
163b0 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a me default..**.*
163c0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
163d0 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 G_WIN32_HEAPSIZE
163e0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 ]].** <dt>SQLITE
163f0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 _CONFIG_WIN32_HE
16400 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 APSIZE.** <dd>^T
16410 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
16420 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 _WIN32_HEAPSIZE
16430 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 option is only a
16440 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 vailable if SQLi
16450 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 te is.** compile
16460 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 d for Windows wi
16470 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 th the [SQLITE_W
16480 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 IN32_MALLOC] pre
16490 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f -processor macro
164a0 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 .** defined. ^SQ
164b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 LITE_CONFIG_WIN3
164c0 32 5f 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73 2_HEAPSIZE takes
164d0 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e a 32-bit unsign
164e0 65 64 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 ed integer value
164f0 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 69 66 69 .** that specifi
16500 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 es the maximum s
16510 69 7a 65 20 6f 66 20 74 68 65 20 63 72 65 61 74 ize of the creat
16520 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b ed heap..**.** [
16530 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 [SQLITE_CONFIG_P
16540 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a CACHE_HDRSZ]].**
16550 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
16560 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a IG_PCACHE_HDRSZ.
16570 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 ** <dd>^The SQLI
16580 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
16590 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 _HDRSZ option ta
165a0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 kes a single par
165b0 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 ameter which.**
165c0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
165d0 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77 an integer and w
165e0 72 69 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20 rites into that
165f0 69 6e 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62 integer the numb
16600 65 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 er of extra.** b
16610 79 74 65 73 20 70 65 72 20 70 61 67 65 20 72 65 ytes per page re
16620 71 75 69 72 65 64 20 66 6f 72 20 65 61 63 68 20 quired for each
16630 70 61 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f page in [SQLITE_
16640 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
16650 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 ]..** The amount
16660 20 6f 66 20 65 78 74 72 61 20 73 70 61 63 65 20 of extra space
16670 72 65 71 75 69 72 65 64 20 63 61 6e 20 63 68 61 required can cha
16680 6e 67 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e nge depending on
16690 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a the compiler,.*
166a0 2a 20 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72 * target platfor
166b0 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 m, and SQLite ve
166c0 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 rsion..**.** [[S
166d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 QLITE_CONFIG_PMA
166e0 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 SZ]].** <dt>SQLI
166f0 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a TE_CONFIG_PMASZ.
16700 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 ** <dd>^The SQLI
16710 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 TE_CONFIG_PMASZ
16720 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
16730 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 ingle parameter
16740 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 which.** is an u
16750 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 nsigned integer
16760 61 6e 64 20 73 65 74 73 20 74 68 65 20 22 4d 69 and sets the "Mi
16770 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 nimum PMA Size"
16780 66 6f 72 20 74 68 65 20 6d 75 6c 74 69 74 68 72 for the multithr
16790 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 eaded.** sorter
167a0 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e to that integer.
167b0 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 6d 69 The default mi
167c0 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 nimum PMA Size i
167d0 73 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 s set by the.**
167e0 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 [SQLITE_SORTER_P
167f0 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 MASZ] compile-ti
16800 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 me option. New
16810 74 68 72 65 61 64 73 20 61 72 65 20 6c 61 75 6e threads are laun
16820 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 ched.** to help
16830 77 69 74 68 20 73 6f 72 74 20 6f 70 65 72 61 74 with sort operat
16840 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 ions when multit
16850 68 72 65 61 64 65 64 20 73 6f 72 74 69 6e 67 0a hreaded sorting.
16860 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64 20 28 75 ** is enabled (u
16870 73 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 sing the [PRAGMA
16880 20 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e threads] comman
16890 64 29 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e d) and the amoun
168a0 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 t of content.**
168b0 74 6f 20 62 65 20 73 6f 72 74 65 64 20 65 78 63 to be sorted exc
168c0 65 65 64 73 20 74 68 65 20 70 61 67 65 20 73 69 eeds the page si
168d0 7a 65 20 74 69 6d 65 73 20 74 68 65 20 6d 69 6e ze times the min
168e0 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b imum of the.** [
168f0 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a PRAGMA cache_siz
16900 65 5d 20 73 65 74 74 69 6e 67 20 61 6e 64 20 74 e] setting and t
16910 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a his value..**.**
16920 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
16930 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d _STMTJRNL_SPILL]
16940 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f ].** <dt>SQLITE_
16950 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f CONFIG_STMTJRNL_
16960 53 50 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 SPILL.** <dd>^Th
16970 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
16980 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f STMTJRNL_SPILL o
16990 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
169a0 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 ngle parameter w
169b0 68 69 63 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 hich.** becomes
169c0 74 68 65 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a the [statement j
169d0 6f 75 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f ournal] spill-to
169e0 2d 64 69 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e -disk threshold.
169f0 20 20 0a 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74 .** [Statement
16a00 20 6a 6f 75 72 6e 61 6c 73 5d 20 61 72 65 20 68 journals] are h
16a10 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e eld in memory un
16a20 74 69 6c 20 74 68 65 69 72 20 73 69 7a 65 20 28 til their size (
16a30 69 6e 20 62 79 74 65 73 29 0a 2a 2a 20 65 78 63 in bytes).** exc
16a40 65 65 64 73 20 74 68 69 73 20 74 68 72 65 73 68 eeds this thresh
16a50 6f 6c 64 2c 20 61 74 20 77 68 69 63 68 20 70 6f old, at which po
16a60 69 6e 74 20 74 68 65 79 20 61 72 65 20 77 72 69 int they are wri
16a70 74 74 65 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a tten to disk..**
16a80 20 4f 72 20 69 66 20 74 68 65 20 74 68 72 65 73 Or if the thres
16a90 68 6f 6c 64 20 69 73 20 2d 31 2c 20 73 74 61 74 hold is -1, stat
16aa0 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61 ement journals a
16ab0 72 65 20 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a re always held.*
16ac0 2a 20 65 78 63 6c 75 73 69 76 65 6c 79 20 69 6e * exclusively in
16ad0 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 memory..** Sinc
16ae0 65 20 6d 61 6e 79 20 73 74 61 74 65 6d 65 6e 74 e many statement
16af0 20 6a 6f 75 72 6e 61 6c 73 20 6e 65 76 65 72 20 journals never
16b00 62 65 63 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65 become large, se
16b10 74 74 69 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a tting the spill.
16b20 2a 2a 20 74 68 72 65 73 68 6f 6c 64 20 74 6f 20 ** threshold to
16b30 61 20 76 61 6c 75 65 20 73 75 63 68 20 61 73 20 a value such as
16b40 36 34 4b 69 42 20 63 61 6e 20 67 72 65 61 74 6c 64KiB can greatl
16b50 79 20 72 65 64 75 63 65 20 74 68 65 20 61 6d 6f y reduce the amo
16b60 75 6e 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 unt of.** I/O re
16b70 71 75 69 72 65 64 20 74 6f 20 73 75 70 70 6f 72 quired to suppor
16b80 74 20 73 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c t statement roll
16b90 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66 back..** The def
16ba0 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 ault value for t
16bb0 68 69 73 20 73 65 74 74 69 6e 67 20 69 73 20 63 his setting is c
16bc0 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 74 68 65 ontrolled by the
16bd0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 .** [SQLITE_STMT
16be0 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 JRNL_SPILL] comp
16bf0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e ile-time option.
16c00 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 .** </dl>.*/.#de
16c10 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
16c20 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 IG_SINGLETHREAD
16c30 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 1 /* nil */.#d
16c40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
16c50 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 FIG_MULTITHREAD
16c60 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 2 /* nil */.#
16c70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
16c80 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 NFIG_SERIALIZED
16c90 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 3 /* nil */.
16ca0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
16cb0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 ONFIG_MALLOC
16cc0 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 4 /* sqlite
16cd0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 3_mem_methods* *
16ce0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
16cf0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f _CONFIG_GETMALLO
16d00 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 C 5 /* sqli
16d10 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a te3_mem_methods*
16d20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
16d30 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 TE_CONFIG_SCRATC
16d40 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f H 6 /* vo
16d50 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 id*, int sz, int
16d60 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 N */.#define SQ
16d70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 LITE_CONFIG_PAGE
16d80 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 CACHE 7 /*
16d90 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 void*, int sz, i
16da0 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nt N */.#define
16db0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 SQLITE_CONFIG_HE
16dc0 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f AP 8 /
16dd0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 * void*, int nBy
16de0 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 te, int min */.#
16df0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
16e00 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 NFIG_MEMSTATUS
16e10 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 9 /* boolean
16e20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
16e30 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 TE_CONFIG_MUTEX
16e40 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 10 /* sq
16e50 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 lite3_mutex_meth
16e60 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ods* */.#define
16e70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
16e80 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f TMUTEX 11 /
16e90 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f * sqlite3_mutex_
16ea0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 methods* */./* p
16eb0 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 reviously SQLITE
16ec0 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c _CONFIG_CHUNKALL
16ed0 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e OC 12 which is n
16ee0 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 ow unused. */ .#
16ef0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
16f00 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 NFIG_LOOKASIDE
16f10 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 13 /* int int
16f20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
16f30 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
16f40 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 14 /* no
16f50 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 -op */.#define S
16f60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
16f70 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a PCACHE 15 /*
16f80 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e no-op */.#defin
16f90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
16fa0 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20 LOG 16
16fb0 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a /* xFunc, void*
16fc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
16fd0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 TE_CONFIG_URI
16fe0 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 17 /* in
16ff0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
17000 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 ITE_CONFIG_PCACH
17010 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 E2 18 /* s
17020 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 qlite3_pcache_me
17030 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 thods2* */.#defi
17040 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
17050 5f 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39 _GETPCACHE2 19
17060 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 /* sqlite3_pca
17070 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f che_methods2* */
17080 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
17090 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f CONFIG_COVERING_
170a0 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f INDEX_SCAN 20 /
170b0 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 * int */.#define
170c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 SQLITE_CONFIG_S
170d0 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 QLLOG 21
170e0 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 /* xSqllog, void
170f0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
17100 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f ITE_CONFIG_MMAP_
17110 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73 SIZE 22 /* s
17120 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 qlite3_int64, sq
17130 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 lite3_int64 */.#
17140 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
17150 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 NFIG_WIN32_HEAPS
17160 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20 IZE 23 /*
17170 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 int nByte */.#de
17180 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
17190 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 IG_PCACHE_HDRSZ
171a0 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 24 /* in
171b0 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e t *psz */.#defin
171c0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
171d0 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20 20 20 PMASZ
171e0 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 25 /* unsig
171f0 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f ned int szPma */
17200 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
17210 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f CONFIG_STMTJRNL_
17220 53 50 49 4c 4c 20 20 20 20 20 20 32 36 20 20 2f SPILL 26 /
17230 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 0a * int nByte */..
17240 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
17250 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 Database Connect
17260 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f ion Configuratio
17270 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 n Options.**.**
17280 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 These constants
17290 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c are the availabl
172a0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 e integer config
172b0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 uration options
172c0 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 that.** can be p
172d0 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 assed as the sec
172e0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ond argument to
172f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f the [sqlite3_db_
17300 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
17310 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 ace..**.** New c
17320 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
17330 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 ions may be adde
17340 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
17350 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ases of SQLite..
17360 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 ** Existing conf
17370 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
17380 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f s might be disco
17390 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 ntinued. Applic
173a0 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 ations.** should
173b0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 check the retur
173c0 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c n code from [sql
173d0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
173e0 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 ] to make sure t
173f0 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 hat.** the call
17400 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 worked. ^The [s
17410 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
17420 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 ()] interface wi
17430 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e ll return a.** n
17440 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 on-zero [error c
17450 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e ode] if a discon
17460 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 tinued or unsupp
17470 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 orted configurat
17480 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 ion option.** is
17490 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 invoked..**.**
174a0 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 <dl>.** <dt>SQLI
174b0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
174c0 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ASIDE</dt>.** <d
174d0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 d> ^This option
174e0 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 takes three addi
174f0 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 tional arguments
17500 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 that determine
17510 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 the .** [lookasi
17520 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 de memory alloca
17530 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 tor] configurati
17540 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 on for the [data
17550 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
17560 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 ..** ^The first
17570 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 argument (the th
17580 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ird parameter to
17590 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e [sqlite3_db_con
175a0 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 fig()] is a.** p
175b0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f ointer to a memo
175c0 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 ry buffer to use
175d0 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d for lookaside m
175e0 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 emory..** ^The f
175f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 irst argument af
17600 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 ter the SQLITE_D
17610 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
17620 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 E verb.** may be
17630 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 NULL in which c
17640 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 ase SQLite will
17650 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 allocate the.**
17660 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 lookaside buffer
17670 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 itself using [s
17680 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
17690 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 . ^The second ar
176a0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a gument is the.**
176b0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f size of each lo
176c0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 okaside buffer s
176d0 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 lot. ^The third
176e0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
176f0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c number of.** sl
17700 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f ots. The size o
17710 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 f the buffer in
17720 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
17730 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 nt must be great
17740 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 er than.** or eq
17750 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 ual to the produ
17760 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 ct of the second
17770 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d and third argum
17780 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 ents. The buffe
17790 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 r.** must be ali
177a0 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 gned to an 8-byt
177b0 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 e boundary. ^If
177c0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
177d0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 ment to.** SQLIT
177e0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 E_DBCONFIG_LOOKA
177f0 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 SIDE is not a mu
17800 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 ltiple of 8, it
17810 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a is internally.**
17820 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f rounded down to
17830 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 the next smalle
17840 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e r multiple of 8.
17850 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 ^(The lookasid
17860 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 e memory.** conf
17870 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 iguration for a
17880 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
17890 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 ion can only be
178a0 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 changed when tha
178b0 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 t.** connection
178c0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 is not currently
178d0 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 using lookaside
178e0 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f memory, or in o
178f0 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 ther words.** wh
17900 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 en the "current
17910 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 value" returned
17920 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 by.** [sqlite3_d
17930 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c b_status](D,[SQL
17940 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 ITE_CONFIG_LOOKA
17950 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 SIDE],...) is ze
17960 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d ro..** Any attem
17970 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 pt to change the
17980 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 lookaside memor
17990 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 y configuration
179a0 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a when lookaside.*
179b0 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 * memory is in u
179c0 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f se leaves the co
179d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 nfiguration unch
179e0 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e anged and return
179f0 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 s .** [SQLITE_BU
17a00 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a SY].)^</dd>.**.*
17a10 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 * <dt>SQLITE_DBC
17a20 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 ONFIG_ENABLE_FKE
17a30 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e Y</dt>.** <dd> ^
17a40 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 This option is u
17a50 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 sed to enable or
17a60 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 disable the enf
17a70 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b orcement of.** [
17a80 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 foreign key cons
17a90 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 traints]. There
17aa0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 should be two a
17ab0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 dditional argume
17ac0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 nts..** The firs
17ad0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e t argument is an
17ae0 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 integer which i
17af0 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 s 0 to disable F
17b00 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a K enforcement,.*
17b10 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e * positive to en
17b20 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d able FK enforcem
17b30 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 ent or negative
17b40 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f to leave FK enfo
17b50 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 rcement.** uncha
17b60 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e nged. The secon
17b70 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 d parameter is a
17b80 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
17b90 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 nteger into whic
17ba0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 h.** is written
17bb0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 0 or 1 to indica
17bc0 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e te whether FK en
17bd0 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 forcement is off
17be0 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 or on.** follow
17bf0 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 ing this call.
17c00 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
17c10 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 eter may be a NU
17c20 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a LL pointer, in.*
17c30 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 * which case the
17c40 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 FK enforcement
17c50 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 setting is not r
17c60 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f eported back. </
17c70 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
17c80 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e LITE_DBCONFIG_EN
17c90 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 ABLE_TRIGGER</dt
17ca0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 >.** <dd> ^This
17cb0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 option is used t
17cc0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 o enable or disa
17cd0 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 ble [CREATE TRIG
17ce0 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e GER | triggers].
17cf0 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 .** There should
17d00 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e be two addition
17d10 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a al arguments..**
17d20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
17d30 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 ent is an intege
17d40 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 r which is 0 to
17d50 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 disable triggers
17d60 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f ,.** positive to
17d70 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 enable triggers
17d80 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 or negative to
17d90 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e leave the settin
17da0 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 g unchanged..**
17db0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
17dc0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 eter is a pointe
17dd0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 r to an integer
17de0 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 into which.** is
17df0 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 written 0 or 1
17e00 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 to indicate whet
17e10 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65 her triggers are
17e20 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 disabled or ena
17e30 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e bled.** followin
17e40 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 g this call. Th
17e50 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
17e60 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c er may be a NULL
17e70 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 pointer, in.**
17e80 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74 which case the t
17e90 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 rigger setting i
17ea0 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 s not reported b
17eb0 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ack. </dd>.**.**
17ec0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f <dt>SQLITE_DBCO
17ed0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 NFIG_ENABLE_FTS3
17ee0 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a _TOKENIZER</dt>.
17ef0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 ** <dd> ^This op
17f00 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 tion is used to
17f10 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c enable or disabl
17f20 65 20 74 68 65 20 74 77 6f 2d 61 72 67 75 6d 65 e the two-argume
17f30 6e 74 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 nt.** version of
17f40 20 74 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e the [fts3_token
17f50 69 7a 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e izer()] function
17f60 20 77 68 69 63 68 20 69 73 20 70 61 72 74 20 6f which is part o
17f70 66 20 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 f the.** [FTS3]
17f80 66 75 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68 full-text search
17f90 20 65 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 6f engine extensio
17fa0 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 n..** There shou
17fb0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 ld be two additi
17fc0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a onal arguments..
17fd0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 ** The first arg
17fe0 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 ument is an inte
17ff0 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 ger which is 0 t
18000 6f 20 64 69 73 61 62 6c 65 20 66 74 73 33 5f 74 o disable fts3_t
18010 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a okenizer() or.**
18020 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 positive to ena
18030 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a ble fts3_tokeniz
18040 65 72 28 29 20 6f 72 20 6e 65 67 61 74 69 76 65 er() or negative
18050 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 to leave the se
18060 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 tting.** unchang
18070 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e ed..** The secon
18080 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 d parameter is a
18090 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
180a0 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 nteger into whic
180b0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 h.** is written
180c0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 0 or 1 to indica
180d0 74 65 20 77 68 65 74 68 65 72 20 66 74 73 33 5f te whether fts3_
180e0 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 73 tokenizer is dis
180f0 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 abled or enabled
18100 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 .** following th
18110 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 is call. The se
18120 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d cond parameter m
18130 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 ay be a NULL poi
18140 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 nter, in.** whic
18150 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20 73 h case the new s
18160 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 etting is not re
18170 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 ported back. </d
18180 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c d>.**.** <dt>SQL
18190 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 ITE_DBCONFIG_ENA
181a0 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 BLE_LOAD_EXTENSI
181b0 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 ON</dt>.** <dd>
181c0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 ^This option is
181d0 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f used to enable o
181e0 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 5b 73 r disable the [s
181f0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 qlite3_load_exte
18200 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 nsion()].** inte
18210 72 66 61 63 65 20 69 6e 64 65 70 65 6e 64 65 6e rface independen
18220 74 6c 79 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64 tly of the [load
18230 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51 _extension()] SQ
18240 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 L function..** T
18250 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 he [sqlite3_enab
18260 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f le_load_extensio
18270 6e 28 29 5d 20 41 50 49 20 65 6e 61 62 6c 65 73 n()] API enables
18280 20 6f 72 20 64 69 73 61 62 6c 65 73 20 62 6f 74 or disables bot
18290 68 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b h the.** C-API [
182a0 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 sqlite3_load_ext
182b0 65 6e 73 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68 ension()] and th
182c0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b e SQL function [
182d0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 load_extension()
182e0 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 ]..** There shou
182f0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 ld be two additi
18300 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a onal arguments..
18310 2a 2a 20 57 68 65 6e 20 74 68 65 20 66 69 72 73 ** When the firs
18320 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 t argument to th
18330 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 is interface is
18340 31 2c 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65 1, then only the
18350 20 43 2d 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61 C-API is.** ena
18360 62 6c 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c bled and the SQL
18370 20 66 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e function remain
18380 73 20 64 69 73 61 62 6c 65 64 2e 20 20 49 66 20 s disabled. If
18390 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
183a0 6e 74 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e nt to.** this in
183b0 74 65 72 66 61 63 65 20 69 73 20 30 2c 20 74 68 terface is 0, th
183c0 65 6e 20 62 6f 74 68 20 74 68 65 20 43 2d 41 50 en both the C-AP
183d0 49 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 I and the SQL fu
183e0 6e 63 74 69 6f 6e 20 61 72 65 20 64 69 73 61 62 nction are disab
183f0 6c 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 led..** If the f
18400 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 irst argument is
18410 20 2d 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61 -1, then no cha
18420 6e 67 65 73 20 61 72 65 20 6d 61 64 65 20 74 6f nges are made to
18430 20 73 74 61 74 65 20 6f 66 20 65 69 74 68 65 72 state of either
18440 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 the.** C-API or
18450 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
18460 6e 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 n..** The second
18470 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 parameter is a
18480 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
18490 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 teger into which
184a0 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 .** is written 0
184b0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 or 1 to indicat
184c0 65 20 77 68 65 74 68 65 72 20 5b 73 71 6c 69 74 e whether [sqlit
184d0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f e3_load_extensio
184e0 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a n()] interface.*
184f0 2a 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 * is disabled or
18500 20 65 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 enabled followi
18510 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 ng this call. T
18520 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
18530 74 65 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20 ter may.** be a
18540 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e NULL pointer, in
18550 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 which case the
18560 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e new setting is n
18570 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b ot reported back
18580 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ..** </dd>.**.**
18590 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f <dt>SQLITE_DBCO
185a0 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c NFIG_MAINDBNAME<
185b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 /dt>.** <dd> ^Th
185c0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 is option is use
185d0 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 d to change the
185e0 6e 61 6d 65 20 6f 66 20 74 68 65 20 22 6d 61 69 name of the "mai
185f0 6e 22 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 73 n" database.** s
18600 63 68 65 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c chema. ^The sol
18610 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 e argument is a
18620 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e pointer to a con
18630 73 74 61 6e 74 20 55 54 46 38 20 73 74 72 69 6e stant UTF8 strin
18640 67 0a 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 g.** which will
18650 62 65 63 6f 6d 65 20 74 68 65 20 6e 65 77 20 73 become the new s
18660 63 68 65 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c chema name in pl
18670 61 63 65 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20 ace of "main".
18680 5e 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 ^SQLite.** does
18690 6e 6f 74 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 not make a copy
186a0 6f 66 20 74 68 65 20 6e 65 77 20 6d 61 69 6e 20 of the new main
186b0 73 63 68 65 6d 61 20 6e 61 6d 65 20 73 74 72 69 schema name stri
186c0 6e 67 2c 20 73 6f 20 74 68 65 20 61 70 70 6c 69 ng, so the appli
186d0 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 cation.** must e
186e0 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61 nsure that the a
186f0 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 rgument passed i
18700 6e 74 6f 20 74 68 69 73 20 44 42 43 4f 4e 46 49 nto this DBCONFI
18710 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 63 68 G option is unch
18720 61 6e 67 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 anged.** until a
18730 66 74 65 72 20 74 68 65 20 64 61 74 61 62 61 73 fter the databas
18740 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f e connection clo
18750 73 65 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a ses..** </dd>.**
18760 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 .** <dt>SQLITE_D
18770 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f BCONFIG_NO_CKPT_
18780 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a ON_CLOSE</dt>.**
18790 20 3c 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77 <dd> Usually, w
187a0 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 69 hen a database i
187b0 6e 20 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c n wal mode is cl
187c0 6f 73 65 64 20 6f 72 20 64 65 74 61 63 68 65 64 osed or detached
187d0 20 66 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61 from a .** data
187e0 62 61 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c base handle, SQL
187f0 69 74 65 20 63 68 65 63 6b 73 20 69 66 20 74 68 ite checks if th
18800 69 73 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61 is will mean tha
18810 74 20 74 68 65 72 65 20 61 72 65 20 6e 6f 77 20 t there are now
18820 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f no .** connectio
18830 6e 73 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 65 ns at all to the
18840 20 64 61 74 61 62 61 73 65 2e 20 49 66 20 73 6f database. If so
18850 2c 20 69 74 20 70 65 72 66 6f 72 6d 73 20 61 20 , it performs a
18860 63 68 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f checkpoint .** o
18870 70 65 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 20 peration before
18880 63 6c 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e closing the conn
18890 65 63 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74 ection. This opt
188a0 69 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20 ion may be used
188b0 74 6f 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 74 to.** override t
188c0 68 69 73 20 62 65 68 61 76 69 6f 75 72 2e 20 54 his behaviour. T
188d0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
188e0 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 er passed to thi
188f0 73 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 s operation.** i
18900 73 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 6e s an integer - n
18910 6f 6e 2d 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 on-zero to disab
18920 6c 65 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f le checkpoints-o
18930 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f n-close, or zero
18940 20 28 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 (the.** default
18950 29 20 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d ) to enable them
18960 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 . The second par
18970 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e ameter is a poin
18980 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 ter to an intege
18990 72 0a 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20 r.** into which
189a0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 is written 0 or
189b0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 1 to indicate wh
189c0 65 74 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74 ether checkpoint
189d0 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 s-on-close.** ha
189e0 76 65 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64 ve been disabled
189f0 20 2d 20 30 20 69 66 20 74 68 65 79 20 61 72 65 - 0 if they are
18a00 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31 not disabled, 1
18a10 20 69 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a if they are..**
18a20 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 </dd>.**.** </d
18a30 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 l>.*/.#define SQ
18a40 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 LITE_DBCONFIG_MA
18a50 49 4e 44 42 4e 41 4d 45 20 20 20 20 20 20 20 20 INDBNAME
18a60 20 20 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73 1000 /* cons
18a70 74 20 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69 t char* */.#defi
18a80 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 ne SQLITE_DBCONF
18a90 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 IG_LOOKASIDE
18aa0 20 20 20 20 20 20 20 20 20 31 30 30 31 20 2f 2a 1001 /*
18ab0 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a void* int int *
18ac0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
18ad0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 _DBCONFIG_ENABLE
18ae0 5f 46 4b 45 59 20 20 20 20 20 20 20 20 20 20 20 _FKEY
18af0 31 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 1002 /* int int*
18b00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
18b10 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 TE_DBCONFIG_ENAB
18b20 4c 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 LE_TRIGGER
18b30 20 20 31 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e 1003 /* int in
18b40 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 t* */.#define SQ
18b50 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e LITE_DBCONFIG_EN
18b60 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 ABLE_FTS3_TOKENI
18b70 5a 45 52 20 31 30 30 34 20 2f 2a 20 69 6e 74 20 ZER 1004 /* int
18b80 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 int* */.#define
18b90 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
18ba0 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 ENABLE_LOAD_EXTE
18bb0 4e 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e NSION 1005 /* in
18bc0 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e t int* */.#defin
18bd0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 e SQLITE_DBCONFI
18be0 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f G_NO_CKPT_ON_CLO
18bf0 53 45 20 20 20 20 20 20 31 30 30 36 20 2f 2a 20 SE 1006 /*
18c00 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a int int* */.../*
18c10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e .** CAPI3REF: En
18c20 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 able Or Disable
18c30 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 Extended Result
18c40 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a Codes.** METHOD:
18c50 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e sqlite3.**.** ^
18c60 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 The sqlite3_exte
18c70 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 nded_result_code
18c80 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 s() routine enab
18c90 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 les or disables
18ca0 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 the.** [extended
18cb0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 result codes] f
18cc0 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 eature of SQLite
18cd0 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 . ^The extended
18ce0 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 result.** codes
18cf0 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 are disabled by
18d00 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 default for hist
18d10 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 orical compatibi
18d20 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c lity..*/.int sql
18d30 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 ite3_extended_re
18d40 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 sult_codes(sqlit
18d50 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b e3*, int onoff);
18d60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
18d70 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f : Last Insert Ro
18d80 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 wid.** METHOD: s
18d90 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 qlite3.**.** ^Ea
18da0 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 ch entry in most
18db0 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 SQLite tables (
18dc0 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 except for [WITH
18dd0 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 OUT ROWID] table
18de0 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 s).** has a uniq
18df0 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 ue 64-bit signed
18e00 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 .** integer key
18e10 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 called the [ROWI
18e20 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 D | "rowid"]. ^T
18e30 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 he rowid is alwa
18e40 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 ys available.**
18e50 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 as an undeclared
18e60 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f column named RO
18e70 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f WID, OID, or _RO
18e80 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 WID_ as long as
18e90 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 those.** names a
18ea0 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 re not also used
18eb0 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 by explicitly d
18ec0 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e eclared columns.
18ed0 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c ^If.** the tabl
18ee0 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f e has a column o
18ef0 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 f type [INTEGER
18f00 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 PRIMARY KEY] the
18f10 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a n that column.**
18f20 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 is another alia
18f30 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e s for the rowid.
18f40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
18f50 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f te3_last_insert_
18f60 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 rowid(D) interfa
18f70 63 65 20 75 73 75 61 6c 6c 79 20 72 65 74 75 72 ce usually retur
18f80 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f ns the [rowid] o
18f90 66 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 f.** the most re
18fa0 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 cent successful
18fb0 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 [INSERT] into a
18fc0 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b rowid table or [
18fd0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a virtual table].*
18fe0 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f * on database co
18ff0 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 5e 49 6e 73 nnection D. ^Ins
19000 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f erts into [WITHO
19010 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 UT ROWID] tables
19020 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f are not.** reco
19030 72 64 65 64 2e 20 5e 49 66 20 6e 6f 20 73 75 63 rded. ^If no suc
19040 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d cessful [INSERT]
19050 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 s into rowid tab
19060 6c 65 73 20 68 61 76 65 20 65 76 65 72 20 6f 63 les have ever oc
19070 63 75 72 72 65 64 20 0a 2a 2a 20 6f 6e 20 74 68 curred .** on th
19080 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
19090 63 74 69 6f 6e 20 44 2c 20 74 68 65 6e 20 73 71 ction D, then sq
190a0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 lite3_last_inser
190b0 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 t_rowid(D) retur
190c0 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a ns .** zero..**.
190d0 2a 2a 20 41 73 20 77 65 6c 6c 20 61 73 20 62 65 ** As well as be
190e0 69 6e 67 20 73 65 74 20 61 75 74 6f 6d 61 74 69 ing set automati
190f0 63 61 6c 6c 79 20 61 73 20 72 6f 77 73 20 61 72 cally as rows ar
19100 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 e inserted into
19110 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c database.** tabl
19120 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 es, the value re
19130 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 turned by this f
19140 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 73 unction may be s
19150 65 74 20 65 78 70 6c 69 63 69 74 6c 79 20 62 79 et explicitly by
19160 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 .** [sqlite3_set
19170 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 _last_insert_row
19180 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 id()].**.** Some
19190 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 virtual table i
191a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d mplementations m
191b0 61 79 20 49 4e 53 45 52 54 20 72 6f 77 73 20 69 ay INSERT rows i
191c0 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 nto rowid tables
191d0 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 63 as.** part of c
191e0 6f 6d 6d 69 74 74 69 6e 67 20 61 20 74 72 61 6e ommitting a tran
191f0 73 61 63 74 69 6f 6e 20 28 65 2e 67 2e 20 74 6f saction (e.g. to
19200 20 66 6c 75 73 68 20 64 61 74 61 20 61 63 63 75 flush data accu
19210 6d 75 6c 61 74 65 64 20 69 6e 20 6d 65 6d 6f 72 mulated in memor
19220 79 0a 2a 2a 20 74 6f 20 64 69 73 6b 29 2e 20 49 y.** to disk). I
19230 6e 20 74 68 69 73 20 63 61 73 65 20 73 75 62 73 n this case subs
19240 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 equent calls to
19250 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 this function re
19260 74 75 72 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a turn the rowid.*
19270 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 * associated wit
19280 68 20 74 68 65 73 65 20 69 6e 74 65 72 6e 61 6c h these internal
19290 20 49 4e 53 45 52 54 20 6f 70 65 72 61 74 69 6f INSERT operatio
192a0 6e 73 2c 20 77 68 69 63 68 20 6c 65 61 64 73 20 ns, which leads
192b0 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74 75 69 74 69 to .** unintuiti
192c0 76 65 20 72 65 73 75 6c 74 73 2e 20 56 69 72 74 ve results. Virt
192d0 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d ual table implem
192e0 65 6e 74 61 74 69 6f 6e 73 20 74 68 61 74 20 64 entations that d
192f0 6f 20 77 72 69 74 65 20 74 6f 20 72 6f 77 69 64 o write to rowid
19300 0a 2a 2a 20 74 61 62 6c 65 73 20 69 6e 20 74 68 .** tables in th
19310 69 73 20 77 61 79 20 63 61 6e 20 61 76 6f 69 64 is way can avoid
19320 20 74 68 69 73 20 70 72 6f 62 6c 65 6d 20 62 79 this problem by
19330 20 72 65 73 74 6f 72 69 6e 67 20 74 68 65 20 6f restoring the o
19340 72 69 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69 riginal .** rowi
19350 64 20 76 61 6c 75 65 20 75 73 69 6e 67 20 5b 73 d value using [s
19360 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f qlite3_set_last_
19370 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 insert_rowid()]
19380 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 before returning
19390 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f 20 .** control to
193a0 74 68 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20 the user..**.**
193b0 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d ^(If an [INSERT]
193c0 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 occurs within a
193d0 20 74 72 69 67 67 65 72 20 74 68 65 6e 20 74 68 trigger then th
193e0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 is routine will
193f0 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 5b .** return the [
19400 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e rowid] of the in
19410 73 65 72 74 65 64 20 72 6f 77 20 61 73 20 6c 6f serted row as lo
19420 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 ng as the trigge
19430 72 20 69 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 r is .** running
19440 2e 20 4f 6e 63 65 20 74 68 65 20 74 72 69 67 67 . Once the trigg
19450 65 72 20 70 72 6f 67 72 61 6d 20 65 6e 64 73 2c er program ends,
19460 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
19470 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 ned .** by this
19480 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 routine reverts
19490 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 to what it was b
194a0 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 efore the trigge
194b0 72 20 77 61 73 20 66 69 72 65 64 2e 29 5e 0a 2a r was fired.)^.*
194c0 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 *.** ^An [INSERT
194d0 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 ] that fails due
194e0 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 to a constraint
194f0 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f violation is no
19500 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 t a.** successfu
19510 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 l [INSERT] and d
19520 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 oes not change t
19530 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
19540 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 d by this.** rou
19550 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 tine. ^Thus INS
19560 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 ERT OR FAIL, INS
19570 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 ERT OR IGNORE, I
19580 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 NSERT OR ROLLBAC
19590 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 K,.** and INSERT
195a0 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e OR ABORT make n
195b0 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 o changes to the
195c0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 return value of
195d0 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 this.** routine
195e0 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 when their inse
195f0 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 rtion fails. ^(
19600 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 When INSERT OR R
19610 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e EPLACE.** encoun
19620 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e ters a constrain
19630 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 t violation, it
19640 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 does not fail.
19650 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f The.** INSERT co
19660 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c ntinues to compl
19670 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 etion after dele
19680 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 ting rows that c
19690 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e aused.** the con
196a0 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 straint problem
196b0 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 so INSERT OR REP
196c0 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 LACE will always
196d0 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 change.** the r
196e0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 eturn value of t
196f0 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e his interface.)^
19700 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 .**.** ^For the
19710 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 purposes of this
19720 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e routine, an [IN
19730 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 SERT] is conside
19740 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 red to.** be suc
19750 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 cessful even if
19760 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 it is subsequent
19770 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a ly rolled back..
19780 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 **.** This funct
19790 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c ion is accessibl
197a0 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 e to SQL stateme
197b0 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b nts via the.** [
197c0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 last_insert_rowi
197d0 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e d() SQL function
197e0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 ]..**.** If a se
197f0 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 parate thread pe
19800 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e rforms a new [IN
19810 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d SERT] on the sam
19820 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f e.** database co
19830 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 nnection while t
19840 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 he [sqlite3_last
19850 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d _insert_rowid()]
19860 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 .** function is
19870 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 running and thus
19880 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 changes the las
19890 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d t insert [rowid]
198a0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 ,.** then the va
198b0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 lue returned by
198c0 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e [sqlite3_last_in
198d0 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 sert_rowid()] is
198e0 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c .** unpredictabl
198f0 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 e and might not
19900 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 equal either the
19910 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a old or the new.
19920 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b ** last insert [
19930 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 rowid]..*/.sqlit
19940 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 e3_int64 sqlite3
19950 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 _last_insert_row
19960 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f id(sqlite3*);../
19970 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
19980 65 74 20 74 68 65 20 4c 61 73 74 20 49 6e 73 65 et the Last Inse
19990 72 74 20 52 6f 77 69 64 20 76 61 6c 75 65 2e 0a rt Rowid value..
199a0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
199b0 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c e3.**.** The sql
199c0 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e ite3_set_last_in
199d0 73 65 72 74 5f 72 6f 77 69 64 28 44 2c 20 52 29 sert_rowid(D, R)
199e0 20 6d 65 74 68 6f 64 20 61 6c 6c 6f 77 73 20 74 method allows t
199f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 he application t
19a00 6f 0a 2a 2a 20 73 65 74 20 74 68 65 20 76 61 6c o.** set the val
19a10 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 63 ue returned by c
19a20 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6c alling sqlite3_l
19a30 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 ast_insert_rowid
19a40 28 44 29 20 74 6f 20 52 20 0a 2a 2a 20 77 69 74 (D) to R .** wit
19a50 68 6f 75 74 20 69 6e 73 65 72 74 69 6e 67 20 61 hout inserting a
19a60 20 72 6f 77 20 69 6e 74 6f 20 74 68 65 20 64 61 row into the da
19a70 74 61 62 61 73 65 2e 0a 2a 2f 0a 76 6f 69 64 20 tabase..*/.void
19a80 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 sqlite3_set_last
19a90 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 _insert_rowid(sq
19aa0 6c 69 74 65 33 2a 2c 73 71 6c 69 74 65 33 5f 69 lite3*,sqlite3_i
19ab0 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 nt64);../*.** CA
19ac0 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 PI3REF: Count Th
19ad0 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 e Number Of Rows
19ae0 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 Modified.** MET
19af0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
19b00 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f ** ^This functio
19b10 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 n returns the nu
19b20 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 mber of rows mod
19b30 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 ified, inserted
19b40 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 or.** deleted by
19b50 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
19b60 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 ly completed INS
19b70 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 ERT, UPDATE or D
19b80 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 ELETE.** stateme
19b90 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 nt on the databa
19ba0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 se connection sp
19bb0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f ecified by the o
19bc0 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a nly parameter..*
19bd0 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 * ^Executing any
19be0 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 other type of S
19bf0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 QL statement doe
19c00 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 s not modify the
19c10 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e value.** return
19c20 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 ed by this funct
19c30 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 ion..**.** ^Only
19c40 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 changes made di
19c50 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e rectly by the IN
19c60 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 SERT, UPDATE or
19c70 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 DELETE statement
19c80 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 are.** consider
19c90 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 ed - auxiliary c
19ca0 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 hanges caused by
19cb0 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 [CREATE TRIGGER
19cc0 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a | triggers], .*
19cd0 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 * [foreign key a
19ce0 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c ctions] or [REPL
19cf0 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 ACE] constraint
19d00 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e resolution are n
19d10 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a ot counted..** .
19d20 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 ** Changes to a
19d30 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e view that are in
19d40 74 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a tercepted by .**
19d50 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 [INSTEAD OF tri
19d60 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f gger | INSTEAD O
19d70 46 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 F triggers] are
19d80 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 not counted. ^Th
19d90 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 e value .** retu
19da0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
19db0 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 changes() immedi
19dc0 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 ately after an I
19dd0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 NSERT, UPDATE or
19de0 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 .** DELETE stat
19df0 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 ement run on a v
19e00 69 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 iew is always ze
19e10 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 ro. Only changes
19e20 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a made to real .*
19e30 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 * tables are cou
19e40 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e nted..**.** Thin
19e50 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 gs are more comp
19e60 6c 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73 licated if the s
19e70 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 qlite3_changes()
19e80 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 function is.**
19e90 65 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 executed while a
19ea0 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d trigger program
19eb0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 is running. Thi
19ec0 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 s may happen if
19ed0 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 the.** program u
19ee0 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 ses the [changes
19ef0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d () SQL function]
19f00 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 , or if some oth
19f10 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 er callback.** f
19f20 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 unction invokes
19f30 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
19f40 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 ) directly. Esse
19f50 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 ntially:.** .**
19f60 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e <ul>.** <li> ^
19f70 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 (Before entering
19f80 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 a trigger progr
19f90 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 am the value ret
19fa0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 urned by.**
19fb0 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 sqlite3_chang
19fc0 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 es() function is
19fd0 20 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 saved. After th
19fe0 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 e trigger progra
19ff0 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 m .** has
1a000 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f finished, the o
1a010 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 riginal value is
1a020 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 restored.)^.**
1a030 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 .** <li> ^(Wit
1a040 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 hin a trigger pr
1a050 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 ogram each INSER
1a060 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 T, UPDATE and DE
1a070 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 LETE .**
1a080 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 statement sets t
1a090 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
1a0a0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 d by sqlite3_cha
1a0b0 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 nges() .**
1a0c0 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f upon completio
1a0d0 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 n as normal. Of
1a0e0 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c course, this val
1a0f0 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c ue will not incl
1a100 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 ude .** a
1a110 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f ny changes perfo
1a120 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 rmed by sub-trig
1a130 67 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c gers, as the sql
1a140 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a ite3_changes() .
1a150 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 ** value
1a160 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e will be saved an
1a170 64 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 d restored after
1a180 20 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 each sub-trigge
1a190 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 r has run.)^.**
1a1a0 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 </ul>.** .** ^Th
1a1b0 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 is means that if
1a1c0 20 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 the changes() S
1a1d0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 QL function (or
1a1e0 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 similar) is used
1a1f0 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 .** by the first
1a200 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 INSERT, UPDATE
1a210 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d or DELETE statem
1a220 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 ent within a tri
1a230 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 gger, it .** ret
1a240 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 urns the value a
1a250 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 s set when the c
1a260 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 alling statement
1a270 20 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 began executing
1a280 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 ..** ^If it is u
1a290 73 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e sed by the secon
1a2a0 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 d or subsequent
1a2b0 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 such statement w
1a2c0 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 ithin a trigger
1a2d0 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 .** program, the
1a2e0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
1a2f0 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d reflects the num
1a300 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 ber of rows modi
1a310 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 fied by the .**
1a320 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c previous INSERT,
1a330 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 UPDATE or DELET
1a340 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 E statement with
1a350 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 in the same trig
1a360 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ger..**.** See a
1a370 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 lso the [sqlite3
1a380 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 _total_changes()
1a390 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 ] interface, the
1a3a0 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 .** [count_chang
1a3b0 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 es pragma], and
1a3c0 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 the [changes() S
1a3d0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a QL function]..**
1a3e0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 .** If a separat
1a3f0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 e thread makes c
1a400 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 hanges on the sa
1a410 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e me database conn
1a420 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 ection.** while
1a430 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 [sqlite3_changes
1a440 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 ()] is running t
1a450 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 hen the value re
1a460 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 turned.** is unp
1a470 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e redictable and n
1a480 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a ot meaningful..*
1a490 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 /.int sqlite3_ch
1a4a0 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b anges(sqlite3*);
1a4b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1a4c0 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f : Total Number O
1a4d0 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a f Rows Modified.
1a4e0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
1a4f0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 e3.**.** ^This f
1a500 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
1a510 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 the total number
1a520 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65 of rows inserte
1a530 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a d, modified or.*
1a540 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c * deleted by all
1a550 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 [INSERT], [UPDA
1a560 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 TE] or [DELETE]
1a570 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c statements compl
1a580 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 eted.** since th
1a590 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
1a5a0 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 ction was opened
1a5b0 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 , including thos
1a5c0 65 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a e executed as.**
1a5d0 20 70 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 part of trigger
1a5e0 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 programs. ^Exec
1a5f0 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 uting any other
1a600 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 type of SQL stat
1a610 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f ement.** does no
1a620 74 20 61 66 66 65 63 74 20 74 68 65 20 76 61 6c t affect the val
1a630 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ue returned by s
1a640 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 qlite3_total_cha
1a650 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e nges()..** .** ^
1a660 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20 Changes made as
1a670 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e part of [foreign
1a680 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 key actions] ar
1a690 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 e included in th
1a6a0 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 e.** count, but
1a6b0 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61 those made as pa
1a6c0 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f rt of REPLACE co
1a6d0 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 nstraint resolut
1a6e0 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 ion are.** not.
1a6f0 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 ^Changes to a vi
1a700 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 ew that are inte
1a710 72 63 65 70 74 65 64 20 62 79 20 49 4e 53 54 45 rcepted by INSTE
1a720 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a AD OF triggers .
1a730 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 ** are not count
1a740 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 ed..** .** See a
1a750 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 lso the [sqlite3
1a760 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 _changes()] inte
1a770 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 rface, the.** [c
1a780 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 ount_changes pra
1a790 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 gma], and the [t
1a7a0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 otal_changes() S
1a7b0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a QL function]..**
1a7c0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 .** If a separat
1a7d0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 e thread makes c
1a7e0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 hanges on the sa
1a7f0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e me database conn
1a800 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 ection.** while
1a810 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 [sqlite3_total_c
1a820 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e hanges()] is run
1a830 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 ning then the va
1a840 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 lue.** returned
1a850 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 is unpredictable
1a860 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 and not meaning
1a870 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ful..*/.int sqli
1a880 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
1a890 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a s(sqlite3*);../*
1a8a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e .** CAPI3REF: In
1a8b0 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 terrupt A Long-R
1a8c0 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 unning Query.**
1a8d0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
1a8e0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 **.** ^This func
1a8f0 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 tion causes any
1a900 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 pending database
1a910 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 operation to ab
1a920 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 ort and.** retur
1a930 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 n at its earlies
1a940 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 t opportunity. T
1a950 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 his routine is t
1a960 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c ypically.** call
1a970 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 ed in response t
1a980 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 o a user action
1a990 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 such as pressing
1a9a0 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 "Cancel".** or
1a9b0 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 Ctrl-C where the
1a9c0 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f user wants a lo
1a9d0 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 ng query operati
1a9e0 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d on to halt.** im
1a9f0 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a mediately..**.**
1aa00 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 ^It is safe to
1aa10 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e call this routin
1aa20 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 e from a thread
1aa30 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 different from t
1aa40 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 he.** thread tha
1aa50 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 t is currently r
1aa60 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 unning the datab
1aa70 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 ase operation.
1aa80 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 But it.** is not
1aa90 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 safe to call th
1aaa0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 is routine with
1aab0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a [database conn
1aac0 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 ection] that.**
1aad0 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 is closed or mig
1aae0 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 ht close before
1aaf0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
1ab00 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a t() returns..**.
1ab10 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 ** ^If an SQL op
1ab20 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 eration is very
1ab30 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 nearly finished
1ab40 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e at the time when
1ab50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 .** sqlite3_inte
1ab60 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 rrupt() is calle
1ab70 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 d, then it might
1ab80 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 not have an opp
1ab90 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 ortunity.** to b
1aba0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e e interrupted an
1abb0 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 d might continue
1abc0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a to completion..
1abd0 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 **.** ^An SQL op
1abe0 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 eration that is
1abf0 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c interrupted will
1ac00 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
1ac10 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e INTERRUPT]..** ^
1ac20 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 If the interrupt
1ac30 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e ed SQL operation
1ac40 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 is an INSERT, U
1ac50 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 PDATE, or DELETE
1ac60 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 .** that is insi
1ac70 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 de an explicit t
1ac80 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e ransaction, then
1ac90 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e the entire tran
1aca0 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 saction.** will
1acb0 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 be rolled back a
1acc0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a utomatically..**
1acd0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1ace0 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 _interrupt(D) ca
1acf0 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 ll is in effect
1ad00 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e until all curren
1ad10 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 tly running.** S
1ad20 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e QL statements on
1ad30 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
1ad40 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 ction] D complet
1ad50 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c e. ^Any new SQL
1ad60 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 statements.** t
1ad70 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 hat are started
1ad80 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 after the sqlite
1ad90 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 3_interrupt() ca
1ada0 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 ll and before th
1adb0 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 e .** running st
1adc0 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 atements reaches
1add0 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 zero are interr
1ade0 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79 upted as if they
1adf0 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e had been.** run
1ae00 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 ning prior to th
1ae10 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 e sqlite3_interr
1ae20 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 upt() call. ^Ne
1ae30 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 w SQL statements
1ae40 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 .** that are sta
1ae50 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72 rted after the r
1ae60 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 unning statement
1ae70 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a count reaches z
1ae80 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 ero are.** not e
1ae90 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73 ffected by the s
1aea0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
1aeb0 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 ()..** ^A call t
1aec0 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 o sqlite3_interr
1aed0 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 upt(D) that occu
1aee0 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 rs when there ar
1aef0 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 e no running.**
1af00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 SQL statements i
1af10 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 s a no-op and ha
1af20 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 s no effect on S
1af30 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a QL statements.**
1af40 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 that are starte
1af50 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 d after the sqli
1af60 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 te3_interrupt()
1af70 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a call returns..**
1af80 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 .** If the datab
1af90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 ase connection c
1afa0 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c loses while [sql
1afb0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
1afc0 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 ].** is running
1afd0 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 then bad things
1afe0 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 will likely happ
1aff0 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 en..*/.void sqli
1b000 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 te3_interrupt(sq
1b010 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
1b020 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d CAPI3REF: Determ
1b030 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 ine If An SQL St
1b040 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c atement Is Compl
1b050 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ete.**.** These
1b060 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 routines are use
1b070 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 ful during comma
1b080 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f nd-line input to
1b090 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 determine if th
1b0a0 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 e.** currently e
1b0b0 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d ntered text seem
1b0c0 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 s to form a comp
1b0d0 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 lete SQL stateme
1b0e0 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 nt or.** if addi
1b0f0 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 tional input is
1b100 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 needed before se
1b110 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 nding the text i
1b120 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f nto.** SQLite fo
1b130 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 r parsing. ^The
1b140 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 se routines retu
1b150 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 rn 1 if the inpu
1b160 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 t string.** appe
1b170 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 ars to be a comp
1b180 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 lete SQL stateme
1b190 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e nt. ^A statemen
1b1a0 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 t is judged to b
1b1b0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 e.** complete if
1b1c0 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 it ends with a
1b1d0 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 semicolon token
1b1e0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 and is not a pre
1b1f0 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c fix of a.** well
1b200 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 -formed CREATE T
1b210 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 RIGGER statement
1b220 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 . ^Semicolons t
1b230 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 hat are embedded
1b240 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e within.** strin
1b250 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 g literals or qu
1b260 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 oted identifier
1b270 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 names or comment
1b280 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 s are not.** ind
1b290 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 ependent tokens
1b2a0 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f (they are part o
1b2b0 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 f the token in w
1b2c0 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a hich they are.**
1b2d0 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 embedded) and t
1b2e0 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 hus do not count
1b2f0 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 as a statement
1b300 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 terminator. ^Wh
1b310 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 itespace.** and
1b320 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f comments that fo
1b330 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 llow the final s
1b340 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e emicolon are ign
1b350 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ored..**.** ^The
1b360 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 se routines retu
1b370 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 rn 0 if the stat
1b380 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c ement is incompl
1b390 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d ete. ^If a.** m
1b3a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
1b3b0 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c fails, then SQL
1b3c0 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 ITE_NOMEM is ret
1b3d0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 urned..**.** ^Th
1b3e0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 ese routines do
1b3f0 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 not parse the SQ
1b400 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 L statements thu
1b410 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 s.** will not de
1b420 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c tect syntactical
1b430 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c ly incorrect SQL
1b440 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c ..**.** ^(If SQL
1b450 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e ite has not been
1b460 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 initialized usi
1b470 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 ng [sqlite3_init
1b480 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 ialize()] prior
1b490 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 .** to invoking
1b4a0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 sqlite3_complete
1b4b0 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 16() then sqlite
1b4c0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 3_initialize() i
1b4d0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 s invoked.** aut
1b4e0 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 omatically by sq
1b4f0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 lite3_complete16
1b500 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 (). If that ini
1b510 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c tialization fail
1b520 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 s,.** then the r
1b530 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d eturn value from
1b540 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 sqlite3_complet
1b550 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f e16() will be no
1b560 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 n-zero.** regard
1b570 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 less of whether
1b580 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 or not the input
1b590 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 SQL is complete
1b5a0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e .)^.**.** The in
1b5b0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f put to [sqlite3_
1b5c0 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 complete()] must
1b5d0 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 be a zero-termi
1b5e0 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 nated.** UTF-8 s
1b5f0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tring..**.** The
1b600 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 input to [sqlit
1b610 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d e3_complete16()]
1b620 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d must be a zero-
1b630 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 terminated.** UT
1b640 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e F-16 string in n
1b650 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
1b660 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
1b670 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 _complete(const
1b680 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 char *sql);.int
1b690 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 sqlite3_complete
1b6a0 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 16(const void *s
1b6b0 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ql);../*.** CAPI
1b6c0 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 3REF: Register A
1b6d0 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e Callback To Han
1b6e0 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 dle SQLITE_BUSY
1b6f0 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 Errors.** KEYWOR
1b700 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 DS: {busy-handle
1b710 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 r callback} {bus
1b720 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 y handler}.** ME
1b730 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a THOD: sqlite3.**
1b740 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1b750 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c _busy_handler(D,
1b760 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74 X,P) routine set
1b770 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e s a callback fun
1b780 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 ction X.** that
1b790 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 might be invoked
1b7a0 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 with argument P
1b7b0 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 whenever.** an
1b7c0 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 attempt is made
1b7d0 74 6f 20 61 63 63 65 73 73 20 61 20 64 61 74 61 to access a data
1b7e0 62 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63 base table assoc
1b7f0 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 iated with.** [d
1b800 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1b810 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 on] D when anoth
1b820 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 er thread.** or
1b830 70 72 6f 63 65 73 73 20 68 61 73 20 74 68 65 20 process has the
1b840 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a table locked..**
1b850 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 The sqlite3_bus
1b860 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 y_handler() inte
1b870 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f rface is used to
1b880 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 implement.** [s
1b890 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 qlite3_busy_time
1b8a0 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 out()] and [PRAG
1b8b0 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d MA busy_timeout]
1b8c0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
1b8d0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 busy callback is
1b8e0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c NULL, then [SQL
1b8f0 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 ITE_BUSY].** is
1b900 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 returned immedia
1b910 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e tely upon encoun
1b920 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e tering the lock.
1b930 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 ^If the busy c
1b940 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f allback.** is no
1b950 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 t NULL, then the
1b960 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 callback might
1b970 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 be invoked with
1b980 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a two arguments..*
1b990 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 *.** ^The first
1b9a0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
1b9b0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 busy handler is
1b9c0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f a copy of the vo
1b9d0 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 id* pointer whic
1b9e0 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 h.** is the thir
1b9f0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 d argument to sq
1ba00 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
1ba10 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f er(). ^The seco
1ba20 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a nd argument to.*
1ba30 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c * the busy handl
1ba40 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 er callback is t
1ba50 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d he number of tim
1ba60 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 es that the busy
1ba70 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 handler has.**
1ba80 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 been invoked pre
1ba90 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20 viously for the
1baa0 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 same locking eve
1bab0 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 nt. ^If the.**
1bac0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 busy callback re
1bad0 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f turns 0, then no
1bae0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 additional atte
1baf0 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f mpts are made to
1bb00 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 .** access the d
1bb10 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c atabase and [SQL
1bb20 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74 ITE_BUSY] is ret
1bb30 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 urned.** to the
1bb40 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 application..**
1bb50 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b ^If the callback
1bb60 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 returns non-zer
1bb70 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 o, then another
1bb80 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 attempt.** is ma
1bb90 64 65 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 de to access the
1bba0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 68 database and th
1bbb0 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e e cycle repeats.
1bbc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 .**.** The prese
1bbd0 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 nce of a busy ha
1bbe0 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 ndler does not g
1bbf0 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 uarantee that it
1bc00 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 will be invoked
1bc10 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 .** when there i
1bc20 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f s lock contentio
1bc30 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 n. ^If SQLite de
1bc40 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e termines that in
1bc50 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a voking the busy.
1bc60 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 ** handler could
1bc70 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 result in a dea
1bc80 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 dlock, it will g
1bc90 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 o ahead and retu
1bca0 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d rn [SQLITE_BUSY]
1bcb0 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 .** to the appli
1bcc0 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f cation instead o
1bcd0 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a f invoking the .
1bce0 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e ** busy handler.
1bcf0 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 .** Consider a s
1bd00 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e cenario where on
1bd10 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c e process is hol
1bd20 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b ding a read lock
1bd30 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 that.** it is t
1bd40 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 rying to promote
1bd50 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c to a reserved l
1bd60 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 ock and.** a sec
1bd70 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 ond process is h
1bd80 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 olding a reserve
1bd90 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 d lock that it i
1bda0 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 s trying.** to p
1bdb0 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 romote to an exc
1bdc0 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 lusive lock. Th
1bdd0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 e first process
1bde0 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a cannot proceed.*
1bdf0 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 * because it is
1be00 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 blocked by the s
1be10 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 econd and the se
1be20 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e cond process can
1be30 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 not.** proceed b
1be40 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f ecause it is blo
1be50 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 cked by the firs
1be60 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 t. If both proc
1be70 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 esses.** invoke
1be80 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
1be90 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 s, neither will
1bea0 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 make any progres
1beb0 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a s. Therefore,.*
1bec0 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 * SQLite returns
1bed0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 [SQLITE_BUSY] f
1bee0 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f or the first pro
1bef0 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 cess, hoping tha
1bf00 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 t this.** will i
1bf10 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 nduce the first
1bf20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 process to relea
1bf30 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b se its read lock
1bf40 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 and allow.** th
1bf50 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 e second process
1bf60 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a to proceed..**.
1bf70 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 ** ^The default
1bf80 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 busy callback is
1bf90 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 NULL..**.** ^(T
1bfa0 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 here can only be
1bfb0 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 a single busy h
1bfc0 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 andler defined f
1bfd0 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 or each.** [data
1bfe0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
1bff0 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 . Setting a new
1c000 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c busy handler cl
1c010 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 ears any.** prev
1c020 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c iously set handl
1c030 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 er.)^ ^Note tha
1c040 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 t calling [sqlit
1c050 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 e3_busy_timeout(
1c060 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 )].** or evaluat
1c070 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79 ing [PRAGMA busy
1c080 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c _timeout=N] will
1c090 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 change the.** b
1c0a0 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 usy handler and
1c0b0 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70 thus clear any p
1c0c0 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75 reviously set bu
1c0d0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a sy handler..**.*
1c0e0 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 * The busy callb
1c0f0 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 ack should not t
1c100 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 ake any actions
1c110 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 which modify the
1c120 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
1c130 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 nection that inv
1c140 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 oked the busy ha
1c150 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 ndler. In other
1c160 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 words,.** the b
1c170 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e usy handler is n
1c180 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 ot reentrant. A
1c190 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a ny such actions.
1c1a0 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 ** result in und
1c1b0 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e efined behavior.
1c1c0 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 .** .** A busy h
1c1d0 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 andler must not
1c1e0 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 close the databa
1c1f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
1c200 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 or [prepared st
1c210 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e atement] that in
1c220 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 voked the busy h
1c230 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 andler..*/.int s
1c240 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
1c250 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 69 6e 74 ler(sqlite3*,int
1c260 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 76 (*)(void*,int),v
1c270 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 oid*);../*.** CA
1c280 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 PI3REF: Set A Bu
1c290 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 sy Timeout.** ME
1c2a0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a THOD: sqlite3.**
1c2b0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e .** ^This routin
1c2c0 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 e sets a [sqlite
1c2d0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 3_busy_handler |
1c2e0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 busy handler] t
1c2f0 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f hat sleeps.** fo
1c300 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d r a specified am
1c310 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 ount of time whe
1c320 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 n a table is loc
1c330 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c ked. ^The handl
1c340 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 er.** will sleep
1c350 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 multiple times
1c360 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 until at least "
1c370 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 ms" milliseconds
1c380 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 of sleeping.**
1c390 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 have accumulated
1c3a0 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 . ^After at lea
1c3b0 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 st "ms" millisec
1c3c0 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 onds of sleeping
1c3d0 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 ,.** the handler
1c3e0 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 returns 0 which
1c3f0 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 causes [sqlite3
1c400 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 _step()] to retu
1c410 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 rn.** [SQLITE_BU
1c420 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c SY]..**.** ^Call
1c430 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 ing this routine
1c440 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e with an argumen
1c450 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 t less than or e
1c460 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 qual to zero.**
1c470 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 turns off all bu
1c480 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a sy handlers..**.
1c490 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f ** ^(There can o
1c4a0 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 nly be a single
1c4b0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 busy handler for
1c4c0 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a a particular.**
1c4d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
1c4e0 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 ction] at any gi
1c4f0 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 ven moment. If
1c500 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e another busy han
1c510 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 dler.** was defi
1c520 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c ned (using [sql
1c530 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 ite3_busy_handle
1c540 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 r()]) prior to c
1c550 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 alling.** this r
1c560 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 outine, that oth
1c570 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 er busy handler
1c580 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a is cleared.)^.**
1c590 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b .** See also: [
1c5a0 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 PRAGMA busy_time
1c5b0 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 out].*/.int sqli
1c5c0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 te3_busy_timeout
1c5d0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d (sqlite3*, int m
1c5e0 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 s);../*.** CAPI3
1c5f0 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 REF: Convenience
1c600 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 Routines For Ru
1c610 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a nning Queries.**
1c620 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
1c630 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 .**.** This is a
1c640 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 legacy interfac
1c650 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 e that is preser
1c660 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 ved for backward
1c670 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e s compatibility.
1c680 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 .** Use of this
1c690 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 interface is not
1c6a0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a recommended..**
1c6b0 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 .** Definition:
1c6c0 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c A <b>result tabl
1c6d0 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 e</b> is memory
1c6e0 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 data structure c
1c6f0 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a reated by the.**
1c700 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 [sqlite3_get_ta
1c710 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ble()] interface
1c720 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c . A result tabl
1c730 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a e records the.**
1c740 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 complete query
1c750 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 results from one
1c760 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 or more queries
1c770 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c ..**.** The tabl
1c780 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 e conceptually h
1c790 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 as a number of r
1c7a0 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e ows and columns.
1c7b0 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e But.** these n
1c7c0 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 umbers are not p
1c7d0 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c art of the resul
1c7e0 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 t table itself.
1c7f0 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 These.** number
1c800 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 s are obtained s
1c810 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 eparately. Let
1c820 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 N be the number
1c830 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d of rows.** and M
1c840 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f be the number o
1c850 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a f columns..**.**
1c860 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 A result table
1c870 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 is an array of p
1c880 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d ointers to zero-
1c890 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 terminated UTF-8
1c8a0 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 strings..** The
1c8b0 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 re are (N+1)*M e
1c8c0 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 lements in the a
1c8d0 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 rray. The first
1c8e0 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e M pointers poin
1c8f0 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 t.** to zero-ter
1c900 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 minated strings
1c910 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 that contain th
1c920 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 e names of the c
1c930 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 olumns..** The r
1c940 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 emaining entries
1c950 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 all point to qu
1c960 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 ery results. NU
1c970 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 LL values result
1c980 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e .** in NULL poin
1c990 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 ters. All other
1c9a0 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 values are in t
1c9b0 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d heir UTF-8 zero-
1c9c0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 terminated.** st
1c9d0 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 ring representat
1c9e0 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 ion as returned
1c9f0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by [sqlite3_colu
1ca00 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a mn_text()]..**.*
1ca10 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 * A result table
1ca20 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f might consist o
1ca30 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 f one or more me
1ca40 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 mory allocations
1ca50 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 ..** It is not s
1ca60 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 afe to pass a re
1ca70 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 sult table direc
1ca80 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f tly to [sqlite3_
1ca90 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 free()]..** A re
1caa0 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c sult table shoul
1cab0 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 d be deallocated
1cac0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
1cad0 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a free_table()]..*
1cae0 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 *.** ^(As an exa
1caf0 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 mple of the resu
1cb00 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c lt table format,
1cb10 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 suppose a query
1cb20 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 result.** is as
1cb30 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 follows:.**.**
1cb40 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
1cb50 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 >.** Name
1cb60 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a | Age.**
1cb70 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d --------
1cb80 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a ---------------.
1cb90 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 ** Alice
1cba0 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 | 43.**
1cbb0 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 Bob
1cbc0 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 | 28.**
1cbd0 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 Cindy | 21
1cbe0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
1cbf0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 kquote>.**.** Th
1cc00 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 ere are two colu
1cc10 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 mn (M==2) and th
1cc20 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e ree rows (N==3).
1cc30 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 Thus the.** re
1cc40 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 sult table has 8
1cc50 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f entries. Suppo
1cc60 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 se the result ta
1cc70 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a ble is stored.**
1cc80 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d in an array nam
1cc90 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 es azResult. Th
1cca0 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 en azResult hold
1ccb0 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a s this content:.
1ccc0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
1ccd0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 e><pre>.**
1cce0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 azResult[0
1ccf0 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 ] = "Name";.**
1cd00 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
1cd10 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 91;1] = "Age";.*
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 32 5d 20 3d 20 22 41 6c 69 63 t[2] = "Alic
1cd40 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a e";.** az
1cd50 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 Result[3] =
1cd60 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 "43";.**
1cd70 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 azResult[4]
1cd80 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 = "Bob";.**
1cd90 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
1cda0 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 5] = "28";.**
1cdb0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
1cdc0 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 1;6] = "Cindy";.
1cdd0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
1cde0 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 lt[7] = "21"
1cdf0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f ;.** </pre></blo
1ce00 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a ckquote>)^.**.**
1ce10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 ^The sqlite3_ge
1ce20 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 t_table() functi
1ce30 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 on evaluates one
1ce40 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 or more.** semi
1ce50 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 colon-separated
1ce60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 SQL statements i
1ce70 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 n the zero-termi
1ce80 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 nated UTF-8.** s
1ce90 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 tring of its 2nd
1cea0 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 parameter and r
1ceb0 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 eturns a result
1cec0 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 table to the.**
1ced0 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e pointer given in
1cee0 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 its 3rd paramet
1cef0 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 er..**.** After
1cf00 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
1cf10 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 has finished wit
1cf20 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f h the result fro
1cf30 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 m sqlite3_get_ta
1cf40 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 ble(),.** it mus
1cf50 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c t pass the resul
1cf60 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 t table pointer
1cf70 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f to sqlite3_free_
1cf80 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 table() in order
1cf90 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 to.** release t
1cfa0 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 he memory that w
1cfb0 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 as malloced. Be
1cfc0 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 cause of the way
1cfd0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
1cfe0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 _malloc()] happe
1cff0 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 ns within sqlite
1d000 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 3_get_table(), t
1d010 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 he calling.** fu
1d020 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 nction must not
1d030 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c try to call [sql
1d040 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 ite3_free()] dir
1d050 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 ectly. Only.**
1d060 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 [sqlite3_free_ta
1d070 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 ble()] is able t
1d080 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 o release the me
1d090 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e mory properly an
1d0a0 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 d safely..**.**
1d0b0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f The sqlite3_get_
1d0c0 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 table() interfac
1d0d0 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 e is implemented
1d0e0 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 as a wrapper ar
1d0f0 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ound.** [sqlite3
1d100 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 _exec()]. The s
1d110 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
1d120 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 () routine does
1d130 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a not have access.
1d140 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e ** to any intern
1d150 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 al data structur
1d160 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 es of SQLite. I
1d170 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 t uses only the
1d180 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 public.** interf
1d190 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 ace defined here
1d1a0 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 . As a conseque
1d1b0 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 nce, errors that
1d1c0 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a occur in the.**
1d1d0 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f wrapper layer o
1d1e0 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e utside of the in
1d1f0 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f ternal [sqlite3_
1d200 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 exec()] call are
1d210 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 not.** reflecte
1d220 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 d in subsequent
1d230 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
1d240 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 3_errcode()] or.
1d250 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d ** [sqlite3_errm
1d260 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 sg()]..*/.int sq
1d270 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
1d280 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
1d290 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f /* An o
1d2a0 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a pen database */.
1d2b0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 const char *zS
1d2c0 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 ql, /* SQL t
1d2d0 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a o be evaluated *
1d2e0 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 /. char ***pazR
1d2f0 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 esult, /* Res
1d300 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 ults of the quer
1d310 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f y */. int *pnRo
1d320 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 w, /*
1d330 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 Number of result
1d340 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 rows written he
1d350 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 re */. int *pnC
1d360 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a olumn, /*
1d370 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c Number of resul
1d380 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 t columns writte
1d390 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 n here */. char
1d3a0 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 **pzErrmsg
1d3b0 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 /* Error msg w
1d3c0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 ritten here */.)
1d3d0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 ;.void sqlite3_f
1d3e0 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a ree_table(char *
1d3f0 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a *result);../*.**
1d400 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 CAPI3REF: Forma
1d410 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e tted String Prin
1d420 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a ting Functions.*
1d430 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
1d440 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 nes are work-ali
1d450 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e kes of the "prin
1d460 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 tf()" family of
1d470 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f functions.** fro
1d480 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 m the standard C
1d490 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 library..** The
1d4a0 73 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 se routines unde
1d4b0 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 rstand most of t
1d4c0 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f he common K&R fo
1d4d0 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 rmatting options
1d4e0 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 ,.** plus some a
1d4f0 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 dditional non-st
1d500 61 6e 64 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 andard formats,
1d510 64 65 74 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a detailed below..
1d520 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d ** Note that som
1d530 65 20 6f 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 e of the more ob
1d540 73 63 75 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 scure formatting
1d550 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 options from re
1d560 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 cent.** C-librar
1d570 79 20 73 74 61 6e 64 61 72 64 73 20 61 72 65 20 y standards are
1d580 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 69 omitted from thi
1d590 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e s implementation
1d5a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
1d5b0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 ite3_mprintf() a
1d5c0 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 nd sqlite3_vmpri
1d5d0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 ntf() routines w
1d5e0 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 rite their.** re
1d5f0 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 sults into memor
1d600 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
1d610 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
1d620 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e )]..** The strin
1d630 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 gs returned by t
1d640 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 hese two routine
1d650 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 s should be.** r
1d660 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 eleased by [sqli
1d670 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 te3_free()]. ^B
1d680 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 oth routines ret
1d690 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f urn a.** NULL po
1d6a0 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 inter if [sqlite
1d6b0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 3_malloc()] is u
1d6c0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 nable to allocat
1d6d0 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f e enough.** memo
1d6e0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 ry to hold the r
1d6f0 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e esulting string.
1d700 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c .**.** ^(The sql
1d710 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 ite3_snprintf()
1d720 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c routine is simil
1d730 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 ar to "snprintf(
1d740 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 )" from.** the s
1d750 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 tandard C librar
1d760 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 y. The result i
1d770 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 s written into t
1d780 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 he.** buffer sup
1d790 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 plied as the sec
1d7a0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 ond parameter wh
1d7b0 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 ose size is give
1d7c0 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 n by.** the firs
1d7d0 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 t parameter. Not
1d7e0 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 e that the order
1d7f0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 of the.** first
1d800 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 two parameters
1d810 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d is reversed from
1d820 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 snprintf().)^
1d830 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 This is an.** hi
1d840 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e storical acciden
1d850 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 t that cannot be
1d860 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 fixed without b
1d870 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 reaking.** backw
1d880 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 ards compatibili
1d890 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f ty. ^(Note also
1d8a0 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e that sqlite3_sn
1d8b0 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 printf().** retu
1d8c0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
1d8d0 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 its buffer inst
1d8e0 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 ead of the numbe
1d8f0 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 r of.** characte
1d900 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 rs actually writ
1d910 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 ten into the buf
1d920 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 fer.)^ We admit
1d930 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d that.** the num
1d940 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 ber of character
1d950 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 s written would
1d960 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c be a more useful
1d970 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 return.** value
1d980 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 but we cannot c
1d990 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d hange the implem
1d9a0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 entation of sqli
1d9b0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a te3_snprintf().*
1d9c0 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 * now without br
1d9d0 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 eaking compatibi
1d9e0 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 lity..**.** ^As
1d9f0 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 long as the buff
1da00 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 er size is great
1da10 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 er than zero, sq
1da20 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
1da30 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 .** guarantees t
1da40 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 hat the buffer i
1da50 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 s always zero-te
1da60 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 rminated. ^The
1da70 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 first.** paramet
1da80 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f er "n" is the to
1da90 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 tal size of the
1daa0 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e buffer, includin
1dab0 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 g space for.** t
1dac0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 he zero terminat
1dad0 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 or. So the long
1dae0 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 est string that
1daf0 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c can be completel
1db00 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c y.** written wil
1db10 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 l be n-1 charact
1db20 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ers..**.** ^The
1db30 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 sqlite3_vsnprint
1db40 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 f() routine is a
1db50 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e varargs version
1db60 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 of sqlite3_snpr
1db70 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 intf()..**.** Th
1db80 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c ese routines all
1db90 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 implement some
1dba0 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 additional forma
1dbb0 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 tting.** options
1dbc0 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c that are useful
1dbd0 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e for constructin
1dbe0 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 g SQL statements
1dbf0 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 ..** All of the
1dc00 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 usual printf() f
1dc10 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e ormatting option
1dc20 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 s apply. In add
1dc30 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 ition, there.**
1dc40 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 is are "%q", "%Q
1dc50 22 2c 20 22 25 77 22 20 61 6e 64 20 22 25 7a 22 ", "%w" and "%z"
1dc60 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 options..**.**
1dc70 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 ^(The %q option
1dc80 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e works like %s in
1dc90 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 that it substit
1dca0 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 utes a nul-termi
1dcb0 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 nated.** string
1dcc0 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e from the argumen
1dcd0 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 t list. But %q
1dce0 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 also doubles eve
1dcf0 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 ry '\'' characte
1dd00 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 r..** %q is desi
1dd10 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 gned for use ins
1dd20 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 ide a string lit
1dd30 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 eral.)^ By doub
1dd40 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a ling each '\''.*
1dd50 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 * character it e
1dd60 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 scapes that char
1dd70 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 acter and allows
1dd80 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 it to be insert
1dd90 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 ed into.** the s
1dda0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 tring..**.** For
1ddb0 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 example, assume
1ddc0 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 the string vari
1ddd0 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 able zText conta
1dde0 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c ins text as foll
1ddf0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 ows:.**.** <bloc
1de00 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 kquote><pre>.**
1de10 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 char *zText = "
1de20 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 It's a happy day
1de30 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 !";.** </pre></b
1de40 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
1de50 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 One can use thi
1de60 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c s text in an SQL
1de70 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f statement as fo
1de80 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c llows:.**.** <bl
1de90 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
1dea0 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 * char *zSQL =
1deb0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
1dec0 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 "INSERT INTO tab
1ded0 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 le VALUES('%q')"
1dee0 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 , zText);.** sq
1def0 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a lite3_exec(db, z
1df00 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a SQL, 0, 0, 0);.*
1df10 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 * sqlite3_free(
1df20 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e zSQL);.** </pre>
1df30 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
1df40 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 .** Because the
1df50 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 %q format string
1df60 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c is used, the '\
1df70 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 '' character in
1df80 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 zText.** is esca
1df90 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 ped and the SQL
1dfa0 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 generated is as
1dfb0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c follows:.**.** <
1dfc0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
1dfd0 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f .** INSERT INTO
1dfe0 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 table1 VALUES('
1dff0 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 It''s a happy da
1e000 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f y!').** </pre></
1e010 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
1e020 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 * This is correc
1e030 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 t. Had we used
1e040 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 %s instead of %q
1e050 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 , the generated
1e060 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 SQL.** would hav
1e070 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 e looked like th
1e080 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b is:.**.** <block
1e090 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
1e0a0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c INSERT INTO tabl
1e0b0 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 e1 VALUES('It's
1e0c0 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a a happy day!');.
1e0d0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
1e0e0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 quote>.**.** Thi
1e0f0 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 s second example
1e100 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 is an SQL synta
1e110 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 x error. As a g
1e120 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 eneral rule you
1e130 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 should.** always
1e140 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 use %q instead
1e150 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 of %s when inser
1e160 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 ting text into a
1e170 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e string literal.
1e180 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 .**.** ^(The %Q
1e190 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b option works lik
1e1a0 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 e %q except it a
1e1b0 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 lso adds single
1e1c0 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a quotes around.**
1e1d0 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 the outside of
1e1e0 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 the total string
1e1f0 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c . Additionally,
1e200 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 if the paramete
1e210 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 r in the.** argu
1e220 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e ment list is a N
1e230 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 ULL pointer, %Q
1e240 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 substitutes the
1e250 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 text "NULL" (wit
1e260 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 hout.** single q
1e270 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 uotes).)^ So, f
1e280 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 or example, one
1e290 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a could say:.**.**
1e2a0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
1e2b0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 e>.** char *zSQ
1e2c0 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 L = sqlite3_mpri
1e2d0 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f ntf("INSERT INTO
1e2e0 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 table VALUES(%Q
1e2f0 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 )", zText);.**
1e300 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c sqlite3_exec(db,
1e310 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b zSQL, 0, 0, 0);
1e320 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 .** sqlite3_fre
1e330 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 e(zSQL);.** </pr
1e340 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
1e350 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 **.** The code a
1e360 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 bove will render
1e370 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 a correct SQL s
1e380 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 tatement in the
1e390 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 zSQL.** variable
1e3a0 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 even if the zTe
1e3b0 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 xt variable is a
1e3c0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a NULL pointer..*
1e3d0 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 77 22 20 *.** ^(The "%w"
1e3e0 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f formatting optio
1e3f0 6e 20 69 73 20 6c 69 6b 65 20 22 25 71 22 20 65 n is like "%q" e
1e400 78 63 65 70 74 20 74 68 61 74 20 69 74 20 65 78 xcept that it ex
1e410 70 65 63 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 pects to.** be c
1e420 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 ontained within
1e430 64 6f 75 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e double-quotes in
1e440 73 74 65 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 stead of single
1e450 71 75 6f 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a quotes, and it.*
1e460 2a 20 65 73 63 61 70 65 73 20 74 68 65 20 64 6f * escapes the do
1e470 75 62 6c 65 2d 71 75 6f 74 65 20 63 68 61 72 61 uble-quote chara
1e480 63 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 cter instead of
1e490 74 68 65 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 the single-quote
1e4a0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 2e 29 5e .** character.)^
1e4b0 20 20 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 The "%w" forma
1e4c0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 tting option is
1e4d0 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 73 61 66 intended for saf
1e4e0 65 6c 79 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a ely inserting.**
1e4f0 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d table and colum
1e500 6e 20 6e 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 n names into a c
1e510 6f 6e 73 74 72 75 63 74 65 64 20 53 51 4c 20 73 onstructed SQL s
1e520 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 tatement..**.**
1e530 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 ^(The "%z" forma
1e540 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 tting option wor
1e550 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 ks like "%s" but
1e560 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 with the.** add
1e570 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 ition that after
1e580 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 the string has
1e590 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f been read and co
1e5a0 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 pied into.** the
1e5b0 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 result, [sqlite
1e5c0 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 3_free()] is cal
1e5d0 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 led on the input
1e5e0 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 string.)^.*/.ch
1e5f0 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 ar *sqlite3_mpri
1e600 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c ntf(const char*,
1e610 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 ...);.char *sqli
1e620 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e te3_vmprintf(con
1e630 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 st char*, va_lis
1e640 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 t);.char *sqlite
1e650 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 3_snprintf(int,c
1e660 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a har*,const char*
1e670 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 , ...);.char *sq
1e680 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 lite3_vsnprintf(
1e690 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 int,char*,const
1e6a0 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b char*, va_list);
1e6b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1e6c0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 : Memory Allocat
1e6d0 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a ion Subsystem.**
1e6e0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 .** The SQLite c
1e6f0 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 ore uses these t
1e700 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f hree routines fo
1e710 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e r all of its own
1e720 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d .** internal mem
1e730 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e ory allocation n
1e740 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 eeds. "Core" in
1e750 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e the previous sen
1e760 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f tence.** does no
1e770 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 t include operat
1e780 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 ing-system speci
1e790 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e fic VFS implemen
1e7a0 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 tation. The.**
1e7b0 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 Windows VFS uses
1e7c0 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 native malloc()
1e7d0 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 and free() for
1e7e0 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e some operations.
1e7f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
1e800 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 te3_malloc() rou
1e810 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 tine returns a p
1e820 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 ointer to a bloc
1e830 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 k.** of memory a
1e840 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 t least N bytes
1e850 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 in length, where
1e860 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 N is the parame
1e870 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 ter..** ^If sqli
1e880 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 te3_malloc() is
1e890 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e unable to obtain
1e8a0 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 sufficient free
1e8b0 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 .** memory, it r
1e8c0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f eturns a NULL po
1e8d0 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 inter. ^If the
1e8e0 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a parameter N to.*
1e8f0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 * sqlite3_malloc
1e900 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 () is zero or ne
1e910 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 gative then sqli
1e920 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 te3_malloc() ret
1e930 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 urns.** a NULL p
1e940 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ointer..**.** ^T
1e950 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f he sqlite3_mallo
1e960 63 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 c64(N) routine w
1e970 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a orks just like.*
1e980 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 * sqlite3_malloc
1e990 28 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 (N) except that
1e9a0 4e 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 N is an unsigned
1e9b0 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 64-bit integer
1e9c0 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 instead.** of a
1e9d0 73 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e signed 32-bit in
1e9e0 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 teger..**.** ^Ca
1e9f0 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 lling sqlite3_fr
1ea00 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e ee() with a poin
1ea10 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 ter previously r
1ea20 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 eturned.** by sq
1ea30 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f lite3_malloc() o
1ea40 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f r sqlite3_reallo
1ea50 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 c() releases tha
1ea60 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 t memory so.** t
1ea70 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 hat it might be
1ea80 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 reused. ^The sq
1ea90 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 lite3_free() rou
1eaa0 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d tine is.** a no-
1eab0 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 op if is called
1eac0 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e with a NULL poin
1ead0 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 ter. Passing a
1eae0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 NULL pointer.**
1eaf0 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 to sqlite3_free(
1eb00 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 ) is harmless.
1eb10 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 After being free
1eb20 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f d, memory.** sho
1eb30 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 uld neither be r
1eb40 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e ead nor written.
1eb50 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 Even reading p
1eb60 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a reviously freed.
1eb70 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 ** memory might
1eb80 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d result in a segm
1eb90 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f entation fault o
1eba0 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 r other severe e
1ebb0 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 rror..** Memory
1ebc0 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 corruption, a se
1ebd0 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 gmentation fault
1ebe0 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 , or other sever
1ebf0 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 e error.** might
1ec00 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 result if sqlit
1ec10 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c e3_free() is cal
1ec20 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e led with a non-N
1ec30 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 ULL pointer that
1ec40 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 .** was not obta
1ec50 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 ined from sqlite
1ec60 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 3_malloc() or sq
1ec70 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e lite3_realloc().
1ec80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
1ec90 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 te3_realloc(X,N)
1eca0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d interface attem
1ecb0 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a pts to resize a.
1ecc0 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 ** prior memory
1ecd0 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 allocation X to
1ece0 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 be at least N by
1ecf0 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 tes..** ^If the
1ed00 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 X parameter to s
1ed10 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 qlite3_realloc(X
1ed20 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c ,N).** is a NULL
1ed30 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 pointer then it
1ed40 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 s behavior is id
1ed50 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 entical to calli
1ed60 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 ng.** sqlite3_ma
1ed70 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 lloc(N)..** ^If
1ed80 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 the N parameter
1ed90 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c to sqlite3_reall
1eda0 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 oc(X,N) is zero
1edb0 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 or.** negative t
1edc0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
1edd0 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 is exactly the
1ede0 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a same as calling.
1edf0 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 ** sqlite3_free(
1ee00 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f X)..** ^sqlite3_
1ee10 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 realloc(X,N) ret
1ee20 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
1ee30 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 o a memory alloc
1ee40 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c ation.** of at l
1ee50 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 east N bytes in
1ee60 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 size or NULL if
1ee70 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d insufficient mem
1ee80 6f 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 ory is available
1ee90 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 ..** ^If M is th
1eea0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 e size of the pr
1eeb0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 ior allocation,
1eec0 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 then min(N,M) by
1eed0 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 tes.** of the pr
1eee0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 ior allocation a
1eef0 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 re copied into t
1ef00 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 he beginning of
1ef10 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a buffer returned.
1ef20 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 ** by sqlite3_re
1ef30 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 alloc(X,N) and t
1ef40 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 he prior allocat
1ef50 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a ion is freed..**
1ef60 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 ^If sqlite3_rea
1ef70 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e lloc(X,N) return
1ef80 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 s NULL and N is
1ef90 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 positive, then t
1efa0 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f he.** prior allo
1efb0 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 cation is not fr
1efc0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 eed..**.** ^The
1efd0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 sqlite3_realloc6
1efe0 34 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 4(X,N) interface
1eff0 73 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 s works the same
1f000 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 as.** sqlite3_r
1f010 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 ealloc(X,N) exce
1f020 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 pt that N is a 6
1f030 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 4-bit unsigned i
1f040 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a nteger instead.*
1f050 2a 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 * of a 32-bit si
1f060 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a gned integer..**
1f070 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d .** ^If X is a m
1f080 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
1f090 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 previously obta
1f0a0 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 ined from sqlite
1f0b0 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 3_malloc(),.** s
1f0c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 qlite3_malloc64(
1f0d0 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c ), sqlite3_reall
1f0e0 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 oc(), or sqlite3
1f0f0 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 _realloc64(), th
1f100 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 en.** sqlite3_ms
1f110 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 ize(X) returns t
1f120 68 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 he size of that
1f130 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
1f140 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e n in bytes..** ^
1f150 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e The value return
1f160 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 ed by sqlite3_ms
1f170 69 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 ize(X) might be
1f180 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 larger than the
1f190 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 number.** of byt
1f1a0 65 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65 es requested whe
1f1b0 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 n X was allocate
1f1c0 64 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e d. ^If X is a N
1f1d0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e ULL pointer then
1f1e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a .** sqlite3_msiz
1f1f0 65 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 e(X) returns zer
1f200 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 o. If X points
1f210 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 to something tha
1f220 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 t is not.** the
1f230 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d beginning of mem
1f240 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 ory allocation,
1f250 6f 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 or if it points
1f260 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a to a formerly.**
1f270 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c valid memory al
1f280 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 location that ha
1f290 73 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 s now been freed
1f2a0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 , then the behav
1f2b0 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 ior.** of sqlite
1f2c0 33 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 3_msize(X) is un
1f2d0 64 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 defined and poss
1f2e0 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a ibly harmful..**
1f2f0 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 .** ^The memory
1f300 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
1f310 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 te3_malloc(), sq
1f320 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c lite3_realloc(),
1f330 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c .** sqlite3_mall
1f340 6f 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 oc64(), and sqli
1f350 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a te3_realloc64().
1f360 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 ** is always ali
1f370 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 gned to at least
1f380 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 an 8 byte bound
1f390 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 ary, or to a.**
1f3a0 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 4 byte boundary
1f3b0 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 if the [SQLITE_4
1f3c0 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 _BYTE_ALIGNED_MA
1f3d0 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 LLOC] compile-ti
1f3e0 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 me.** option is
1f3f0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 used..**.** In S
1f400 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e QLite version 3.
1f410 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 5.0 and 3.5.1, i
1f420 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 t was possible t
1f430 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 o define.** the
1f440 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f SQLITE_OMIT_MEMO
1f450 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 RY_ALLOCATION wh
1f460 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 ich would cause
1f470 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 the built-in.**
1f480 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
1f490 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
1f4a0 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 to be omitted.
1f4b0 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 That capability
1f4c0 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 .** is no longer
1f4d0 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 provided. Only
1f4e0 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 built-in memory
1f4f0 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 allocators can
1f500 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 be used..**.** P
1f510 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 rior to SQLite v
1f520 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 ersion 3.7.10, t
1f530 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e he Windows OS in
1f540 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 terface layer ca
1f550 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 lled.** the syst
1f560 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 em malloc() and
1f570 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 free() directly
1f580 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a when converting.
1f590 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 ** filenames bet
1f5a0 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 ween the UTF-8 e
1f5b0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 ncoding used by
1f5c0 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 SQLite.** and wh
1f5d0 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 atever filename
1f5e0 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 encoding is used
1f5f0 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c by the particul
1f600 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e ar Windows.** in
1f610 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d stallation. Mem
1f620 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 ory allocation e
1f630 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 rrors were detec
1f640 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 ted, but.** they
1f650 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 were reported b
1f660 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 ack as [SQLITE_C
1f670 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b ANTOPEN] or.** [
1f680 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 SQLITE_IOERR] ra
1f690 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
1f6a0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 E_NOMEM]..**.**
1f6b0 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 The pointer argu
1f6c0 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 ments to [sqlite
1f6d0 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 3_free()] and [s
1f6e0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
1f6f0 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 ].** must be eit
1f700 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 her NULL or else
1f710 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e pointers obtain
1f720 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a ed from a prior.
1f730 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 ** invocation of
1f740 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
1f750 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
1f760 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 realloc()] that
1f770 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 have.** not yet
1f780 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a been released..*
1f790 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 *.** The applica
1f7a0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 tion must not re
1f7b0 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 ad or write any
1f7c0 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f part of.** a blo
1f7d0 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 ck of memory aft
1f7e0 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 er it has been r
1f7f0 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a eleased using.**
1f800 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
1f810 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ] or [sqlite3_re
1f820 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 alloc()]..*/.voi
1f830 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f d *sqlite3_mallo
1f840 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 c(int);.void *sq
1f850 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 lite3_malloc64(s
1f860 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a qlite3_uint64);.
1f870 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 void *sqlite3_re
1f880 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 alloc(void*, int
1f890 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 );.void *sqlite3
1f8a0 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a _realloc64(void*
1f8b0 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 , sqlite3_uint64
1f8c0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
1f8d0 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c free(void*);.sql
1f8e0 69 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 ite3_uint64 sqli
1f8f0 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 te3_msize(void*)
1f900 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1f910 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 F: Memory Alloca
1f920 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a tor Statistics.*
1f930 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 *.** SQLite prov
1f940 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 ides these two i
1f950 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 nterfaces for re
1f960 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 porting on the s
1f970 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 tatus.** of the
1f980 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
1f990 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 )], [sqlite3_fre
1f9a0 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 e()], and [sqlit
1f9b0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a e3_realloc()].**
1f9c0 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 routines, which
1f9d0 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d form the built-
1f9e0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 in memory alloca
1f9f0 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a tion subsystem..
1fa00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 **.** ^The [sqli
1fa10 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 te3_memory_used(
1fa20 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 )] routine retur
1fa30 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
1fa40 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d bytes.** of mem
1fa50 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 ory currently ou
1fa60 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f tstanding (mallo
1fa70 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 ced but not free
1fa80 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c d)..** ^The [sql
1fa90 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 ite3_memory_high
1faa0 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 water()] routine
1fab0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 returns the max
1fac0 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 imum.** value of
1fad0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
1fae0 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 _used()] since t
1faf0 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 he high-water ma
1fb00 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 rk.** was last r
1fb10 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 eset. ^The valu
1fb20 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b es returned by [
1fb30 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 sqlite3_memory_u
1fb40 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 sed()] and.** [s
1fb50 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
1fb60 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 ghwater()] inclu
1fb70 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a de any overhead.
1fb80 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 ** added by SQLi
1fb90 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d te in its implem
1fba0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c entation of [sql
1fbb0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a ite3_malloc()],.
1fbc0 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 ** but not overh
1fbd0 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 ead added by the
1fbe0 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 any underlying
1fbf0 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a system library.*
1fc00 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 * routines that
1fc10 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
1fc20 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a )] may call..**.
1fc30 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 ** ^The memory h
1fc40 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 igh-water mark i
1fc50 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 s reset to the c
1fc60 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a urrent value of.
1fc70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f ** [sqlite3_memo
1fc80 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e ry_used()] if an
1fc90 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 d only if the pa
1fca0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 rameter to.** [s
1fcb0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
1fcc0 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 ghwater()] is tr
1fcd0 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 ue. ^The value
1fce0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b returned.** by [
1fcf0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 sqlite3_memory_h
1fd00 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 ighwater(1)] is
1fd10 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d the high-water m
1fd20 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 ark.** prior to
1fd30 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 the reset..*/.sq
1fd40 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 lite3_int64 sqli
1fd50 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 te3_memory_used(
1fd60 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 void);.sqlite3_i
1fd70 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d nt64 sqlite3_mem
1fd80 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e ory_highwater(in
1fd90 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f t resetFlag);../
1fda0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 *.** CAPI3REF: P
1fdb0 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d seudo-Random Num
1fdc0 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a ber Generator.**
1fdd0 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 .** SQLite conta
1fde0 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 ins a high-quali
1fdf0 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d ty pseudo-random
1fe00 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f number generato
1fe10 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f r (PRNG) used to
1fe20 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f .** select rando
1fe30 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 m [ROWID | ROWID
1fe40 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e s] when insertin
1fe50 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e g new records in
1fe60 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a to a table that.
1fe70 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 ** already uses
1fe80 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 the largest poss
1fe90 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 ible [ROWID]. T
1fea0 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 he PRNG is also
1feb0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 used for.** the
1fec0 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 build-in random(
1fed0 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 ) and randomblob
1fee0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 () SQL functions
1fef0 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 . This interfac
1ff00 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c e allows.** appl
1ff10 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 ications to acce
1ff20 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 ss the same PRNG
1ff30 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f for other purpo
1ff40 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 ses..**.** ^A ca
1ff50 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 ll to this routi
1ff60 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 ne stores N byte
1ff70 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 s of randomness
1ff80 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a into buffer P..*
1ff90 2a 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 * ^The P paramet
1ffa0 65 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c er can be a NULL
1ffb0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 pointer..**.**
1ffc0 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 ^If this routine
1ffd0 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 has not been pr
1ffe0 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 eviously called
1fff0 6f 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f or if the previo
20000 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e us.** call had N
20010 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f less than one o
20020 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 r a NULL pointer
20030 20 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 for P, then the
20040 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 PRNG is.** seed
20050 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e ed using randomn
20060 65 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f ess obtained fro
20070 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 m the xRandomnes
20080 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 s method of.** t
20090 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 he default [sqli
200a0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e te3_vfs] object.
200b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 .** ^If the prev
200c0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 ious call to thi
200d0 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e s routine had an
200e0 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 N of 1 or more
200f0 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c and a.** non-NUL
20100 4c 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 L P then the pse
20110 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 udo-randomness i
20120 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 s generated.** i
20130 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 nternally and wi
20140 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 thout recourse t
20150 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 o the [sqlite3_v
20160 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a fs] xRandomness.
20170 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f ** method..*/.vo
20180 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f id sqlite3_rando
20190 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 mness(int N, voi
201a0 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 d *P);../*.** CA
201b0 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d PI3REF: Compile-
201c0 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 Time Authorizati
201d0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 on Callbacks.**
201e0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
201f0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 **.** ^This rout
20200 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e ine registers an
20210 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
20220 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 back with a part
20230 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 icular.** [datab
20240 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c ase connection],
20250 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 supplied in the
20260 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e first argument.
20270 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 .** ^The authori
20280 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 zer callback is
20290 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 invoked as SQL s
202a0 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 tatements are be
202b0 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 ing compiled.**
202c0 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 by [sqlite3_prep
202d0 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 are()] or its va
202e0 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f riants [sqlite3_
202f0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a prepare_v2()],.*
20300 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
20310 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c re16()] and [sql
20320 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
20330 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 2()]. ^At vario
20340 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 us.** points dur
20350 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 ing the compilat
20360 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 ion process, as
20370 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 logic is being c
20380 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 reated.** to per
20390 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 form various act
203a0 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 ions, the author
203b0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 izer callback is
203c0 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 invoked to.** s
203d0 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 ee if those acti
203e0 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e ons are allowed.
203f0 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 ^The authorize
20400 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c r callback shoul
20410 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c d.** return [SQL
20420 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 ITE_OK] to allow
20430 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 the action, [SQ
20440 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 LITE_IGNORE] to
20450 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 disallow the.**
20460 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 specific action
20470 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 but allow the SQ
20480 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 L statement to c
20490 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a ontinue to be.**
204a0 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 compiled, or [S
204b0 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 QLITE_DENY] to c
204c0 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 ause the entire
204d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f SQL statement to
204e0 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 be.** rejected
204f0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 with an error.
20500 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a ^If the authoriz
20510 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 er callback retu
20520 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 rns.** any value
20530 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c other than [SQL
20540 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 ITE_IGNORE], [SQ
20550 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 LITE_OK], or [SQ
20560 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 LITE_DENY].** th
20570 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f en the [sqlite3_
20580 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
20590 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c equivalent call
205a0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a that triggered.
205b0 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 ** the authorize
205c0 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 r will fail with
205d0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 an error messag
205e0 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 e..**.** When th
205f0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 e callback retur
20600 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 ns [SQLITE_OK],
20610 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f that means the o
20620 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 peration.** requ
20630 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 ested is ok. ^W
20640 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b hen the callback
20650 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
20660 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b _DENY], the.** [
20670 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
20680 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c v2()] or equival
20690 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 ent call that tr
206a0 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 iggered the.** a
206b0 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 uthorizer will f
206c0 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f ail with an erro
206d0 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 r message explai
206e0 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 ning that.** acc
206f0 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a ess is denied. .
20700 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 **.** ^The first
20710 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
20720 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
20730 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 lback is a copy
20740 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 of the third.**
20750 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
20760 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 sqlite3_set_aut
20770 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 horizer() interf
20780 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 ace. ^The second
20790 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f parameter.** to
207a0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 the callback is
207b0 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c an integer [SQL
207c0 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f ITE_COPY | actio
207d0 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 n code] that spe
207e0 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 cifies.** the pa
207f0 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 rticular action
20800 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 to be authorized
20810 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 . ^The third thr
20820 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d ough sixth param
20830 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 eters.** to the
20840 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 callback are zer
20850 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 o-terminated str
20860 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 ings that contai
20870 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 n additional.**
20880 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 details about th
20890 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 e action to be a
208a0 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a uthorized..**.**
208b0 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 ^If the action
208c0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f code is [SQLITE_
208d0 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 READ].** and the
208e0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
208f0 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 s [SQLITE_IGNORE
20900 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 ] then the.** [p
20910 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
20920 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 t] statement is
20930 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 constructed to s
20940 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e ubstitute.** a N
20950 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 ULL value in pla
20960 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 ce of the table
20970 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c column that woul
20980 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 d have.** been r
20990 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f ead if [SQLITE_O
209a0 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 K] had been retu
209b0 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 rned. The [SQLI
209c0 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 TE_IGNORE].** re
209d0 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 turn can be used
209e0 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 to deny an untr
209f0 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 usted user acces
20a00 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a s to individual.
20a10 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 ** columns of a
20a20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 table..** ^If th
20a30 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 e action code is
20a40 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d [SQLITE_DELETE]
20a50 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 and the callbac
20a60 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 k returns.** [SQ
20a70 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 LITE_IGNORE] the
20a80 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f n the [DELETE] o
20a90 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 peration proceed
20aa0 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 s but the.** [tr
20ab0 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 uncate optimizat
20ac0 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 ion] is disabled
20ad0 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 and all rows ar
20ae0 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 e deleted indivi
20af0 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e dually..**.** An
20b00 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 authorizer is u
20b10 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 sed when [sqlite
20b20 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 3_prepare | prep
20b30 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 aring].** SQL st
20b40 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e atements from an
20b50 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 untrusted sourc
20b60 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 e, to ensure tha
20b70 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d t the SQL statem
20b80 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 ents.** do not t
20b90 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 ry to access dat
20ba0 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 a they are not a
20bb0 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f llowed to see, o
20bc0 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e r that they do n
20bd0 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 ot.** try to exe
20be0 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 cute malicious s
20bf0 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 tatements that d
20c00 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 amage the databa
20c10 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d se. For.** exam
20c20 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 ple, an applicat
20c30 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 ion may allow a
20c40 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 user to enter ar
20c50 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 bitrary.** SQL q
20c60 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 ueries for evalu
20c70 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 ation by a datab
20c80 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 ase. But the ap
20c90 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a plication does.*
20ca0 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 * not want the u
20cb0 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 ser to be able t
20cc0 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 o make arbitrary
20cd0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a changes to the.
20ce0 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e ** database. An
20cf0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c authorizer coul
20d00 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e d then be put in
20d10 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 place while the
20d20 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 .** user-entered
20d30 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 SQL is being [s
20d40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c qlite3_prepare |
20d50 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a prepared] that.
20d60 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 ** disallows eve
20d70 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b rything except [
20d80 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
20d90 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 ts..**.** Applic
20da0 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 ations that need
20db0 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 to process SQL
20dc0 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 from untrusted s
20dd0 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 ources.** might
20de0 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f also consider lo
20df0 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 wering resource
20e00 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 limits using [sq
20e10 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a lite3_limit()].*
20e20 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 * and limiting d
20e30 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 atabase size usi
20e40 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 ng the [max_page
20e50 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d _count] [PRAGMA]
20e60 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 .** in addition
20e70 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 to using an auth
20e80 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 orizer..**.** ^(
20e90 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 Only a single au
20ea0 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 thorizer can be
20eb0 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 in place on a da
20ec0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
20ed0 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 n.** at a time.
20ee0 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 Each call to sq
20ef0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
20f00 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 izer overrides t
20f10 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 he.** previous c
20f20 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 all.)^ ^Disable
20f30 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
20f40 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 by installing a
20f50 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a NULL callback..*
20f60 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 * The authorizer
20f70 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 is disabled by
20f80 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 default..**.** T
20f90 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
20fa0 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 llback must not
20fb0 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 do anything that
20fc0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 will modify.**
20fd0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
20fe0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 nection that inv
20ff0 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 oked the authori
21000 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a zer callback..**
21010 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 Note that [sqli
21020 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
21030 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 ] and [sqlite3_s
21040 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 tep()] both modi
21050 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 fy their.** data
21060 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
21070 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 for the meaning
21080 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 of "modify" in
21090 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a this paragraph..
210a0 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c **.** ^When [sql
210b0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
210c0 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 )] is used to pr
210d0 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e epare a statemen
210e0 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d t, the.** statem
210f0 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d ent might be re-
21100 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 prepared during
21110 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
21120 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 due to a .** sc
21130 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 hema change. He
21140 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 nce, the applica
21150 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 tion should ensu
21160 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 re that the.** c
21170 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 orrect authorize
21180 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 r callback remai
21190 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 ns in place duri
211a0 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f ng the [sqlite3_
211b0 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e step()]..**.** ^
211c0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 Note that the au
211d0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
211e0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c k is invoked onl
211f0 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c y during.** [sql
21200 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
21210 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e or its variants.
21220 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 Authorization
21230 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 is not.** perfor
21240 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 med during state
21250 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 ment evaluation
21260 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 in [sqlite3_step
21270 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 ()], unless.** a
21280 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 s stated in the
21290 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 previous paragra
212a0 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 ph, sqlite3_step
212b0 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 () invokes.** sq
212c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
212d0 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 () to reprepare
212e0 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 a statement afte
212f0 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 r a schema chang
21300 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 e..*/.int sqlite
21310 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
21320 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 (. sqlite3*,.
21330 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 int (*xAuth)(voi
21340 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 d*,int,const cha
21350 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 r*,const char*,c
21360 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 onst char*,const
21370 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 char*),. void
21380 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f *pUserData.);../
21390 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 *.** CAPI3REF: A
213a0 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e uthorizer Return
213b0 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 Codes.**.** The
213c0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
213d0 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f thorizer | autho
213e0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 rizer callback f
213f0 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a unction] must.**
21400 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b return either [
21410 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e SQLITE_OK] or on
21420 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 e of these two c
21430 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 onstants in orde
21440 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 r.** to signal S
21450 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 QLite whether or
21460 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 not the action
21470 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 is permitted. S
21480 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ee the.** [sqlit
21490 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
214a0 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 r | authorizer d
214b0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f ocumentation] fo
214c0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 r additional.**
214d0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a information..**.
214e0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c ** Note that SQL
214f0 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c ITE_IGNORE is al
21500 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f so used as a [co
21510 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f nflict resolutio
21520 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 n mode].** retur
21530 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 ned from the [sq
21540 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f lite3_vtab_on_co
21550 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 nflict()] interf
21560 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ace..*/.#define
21570 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 SQLITE_DENY 1
21580 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 /* Abort the S
21590 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 QL statement wit
215a0 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 h an error */.#d
215b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e efine SQLITE_IGN
215c0 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 ORE 2 /* Don't
215d0 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 allow access, b
215e0 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 ut don't generat
215f0 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f e an error */../
21600 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 *.** CAPI3REF: A
21610 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e uthorizer Action
21620 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 Codes.**.** The
21630 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
21640 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 thorizer()] inte
21650 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 rface registers
21660 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 a callback funct
21670 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 ion.** that is i
21680 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 nvoked to author
21690 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 ize certain SQL
216a0 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e statement action
216b0 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e s. The.** secon
216c0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 d parameter to t
216d0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 he callback is a
216e0 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 n integer code t
216f0 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a hat specifies.**
21700 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 what action is
21710 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 being authorized
21720 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 . These are the
21730 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 integer action
21740 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 codes that.** th
21750 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
21760 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 lback may be pas
21770 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 sed..**.** These
21780 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c action code val
21790 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 ues signify what
217a0 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 kind of operati
217b0 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 on is to be.** a
217c0 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 uthorized. The
217d0 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 3rd and 4th para
217e0 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 meters to the au
217f0 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 thorization.** c
21800 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
21810 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 will be paramet
21820 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 ers or NULL depe
21830 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f nding on which o
21840 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 f these.** codes
21850 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 is used as the
21860 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
21870 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 . ^(The 5th par
21880 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a ameter to the.**
21890 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
218a0 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 back is the name
218b0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
218c0 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 ("main", "temp"
218d0 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 ,.** etc.) if ap
218e0 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 plicable.)^ ^Th
218f0 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 6th parameter
21900 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 to the authorize
21910 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 r callback.** is
21920 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
21930 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 inner-most trig
21940 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 ger or view that
21950 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 is responsible
21960 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 for.** the acces
21970 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c s attempt or NUL
21980 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 L if this access
21990 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 attempt is dire
219a0 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 ctly from.** top
219b0 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e -level SQL code.
219c0 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a .*/./***********
219d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
219e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
219f0 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 3rd ***********
21a00 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a * 4th **********
21a10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
21a20 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 E_CREATE_INDEX
21a30 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 1 /* I
21a40 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 ndex Name T
21a50 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
21a60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
21a70 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 _CREATE_TABLE
21a80 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 2 /* Ta
21a90 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
21aa0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
21ab0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
21ac0 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 CREATE_TEMP_INDE
21ad0 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 X 3 /* Ind
21ae0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 ex Name Tab
21af0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
21b00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
21b10 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 REATE_TEMP_TABLE
21b20 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 4 /* Tabl
21b30 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
21b40 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
21b50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
21b60 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 EATE_TEMP_TRIGGE
21b70 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 R 5 /* Trigg
21b80 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 er Name Table
21b90 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
21ba0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
21bb0 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 ATE_TEMP_VIEW
21bc0 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 6 /* View N
21bd0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 ame NULL
21be0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
21bf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
21c00 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 TE_TRIGGER
21c10 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 7 /* Trigger
21c20 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e Name Table N
21c30 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
21c40 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
21c50 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 E_VIEW
21c60 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 8 /* View Nam
21c70 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 e NULL
21c80 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
21c90 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 ne SQLITE_DELETE
21ca0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
21cb0 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 9 /* Table Nam
21cc0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
21cd0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
21ce0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e e SQLITE_DROP_IN
21cf0 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 DEX 10
21d00 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 /* Index Name
21d10 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 Table Name
21d20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
21d30 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 SQLITE_DROP_TAB
21d40 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 LE 11
21d50 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
21d60 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
21d70 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
21d80 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 SQLITE_DROP_TEMP
21d90 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 _INDEX 12
21da0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 /* Index Name
21db0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
21dc0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
21dd0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f QLITE_DROP_TEMP_
21de0 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 TABLE 13
21df0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
21e00 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
21e10 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
21e20 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 LITE_DROP_TEMP_T
21e30 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f RIGGER 14 /
21e40 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 * Trigger Name
21e50 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
21e60 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
21e70 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 ITE_DROP_TEMP_VI
21e80 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a EW 15 /*
21e90 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 View Name
21ea0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
21eb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
21ec0 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 TE_DROP_TRIGGER
21ed0 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 16 /*
21ee0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 Trigger Name
21ef0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
21f00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
21f10 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 E_DROP_VIEW
21f20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 17 /* V
21f30 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e iew Name N
21f40 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
21f50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
21f60 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 _INSERT
21f70 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 18 /* Ta
21f80 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
21f90 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
21fa0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
21fb0 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 PRAGMA
21fc0 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 19 /* Pra
21fd0 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 gma Name 1st
21fe0 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a arg or NULL */.
21ff0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
22000 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 EAD
22010 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 20 /* Tabl
22020 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 e Name Colu
22030 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 mn Name */.#
22040 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 define SQLITE_SE
22050 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 LECT
22060 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 21 /* NULL
22070 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 NULL
22080 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
22090 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 efine SQLITE_TRA
220a0 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 NSACTION
220b0 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 22 /* Operat
220c0 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 ion NULL
220d0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
220e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 fine SQLITE_UPDA
220f0 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TE
22100 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 23 /* Table N
22110 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 ame Column
22120 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 Name */.#def
22130 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 ine SQLITE_ATTAC
22140 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 H
22150 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 24 /* Filename
22160 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 NULL
22170 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
22180 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 ne SQLITE_DETACH
22190 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 2
221a0 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 5 /* Database
221b0 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 Name NULL
221c0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
221d0 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 e SQLITE_ALTER_T
221e0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 ABLE 26
221f0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e /* Database N
22200 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 ame Table Name
22210 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
22220 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 SQLITE_REINDEX
22230 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 27
22240 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 /* Index Name
22250 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
22260 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
22270 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 SQLITE_ANALYZE
22280 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 28
22290 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
222a0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
222b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
222c0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 QLITE_CREATE_VTA
222d0 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 BLE 29
222e0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
222f0 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 Module Name
22300 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
22310 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 LITE_DROP_VTABLE
22320 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 30 /
22330 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
22340 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 Module Name
22350 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
22360 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 ITE_FUNCTION
22370 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 31 /*
22380 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
22390 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 Function Name
223a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
223b0 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 TE_SAVEPOINT
223c0 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 32 /*
223d0 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 Operation
223e0 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 Savepoint Name
223f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
22400 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 E_COPY
22410 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 0 /* N
22420 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f o longer used */
22430 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
22440 52 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20 RECURSIVE
22450 20 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 33 /* NUL
22460 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c L NUL
22470 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
22480 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
22490 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f Tracing And Pro
224a0 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 filing Functions
224b0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
224c0 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 te3.**.** These
224d0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 70 routines are dep
224e0 72 65 63 61 74 65 64 2e 20 55 73 65 20 74 68 65 recated. Use the
224f0 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f [sqlite3_trace_
22500 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a v2()] interface.
22510 2a 2a 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 ** instead of th
22520 65 20 72 6f 75 74 69 6e 65 73 20 64 65 73 63 72 e routines descr
22530 69 62 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a ibed here..**.**
22540 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
22550 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 register callbac
22560 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 k functions that
22570 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 can be used for
22580 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 .** tracing and
22590 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 profiling the ex
225a0 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 ecution of SQL s
225b0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a tatements..**.**
225c0 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 ^The callback f
225d0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 unction register
225e0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 ed by sqlite3_tr
225f0 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 ace() is invoked
22600 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 at.** various t
22610 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c imes when an SQL
22620 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 statement is be
22630 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 ing run by [sqli
22640 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 te3_step()]..**
22650 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 ^The sqlite3_tra
22660 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 ce() callback is
22670 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 invoked with a
22680 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 UTF-8 rendering
22690 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 of the.** SQL st
226a0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 atement text as
226b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 the statement fi
226c0 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 rst begins execu
226d0 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 ting..** ^(Addit
226e0 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 ional sqlite3_tr
226f0 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 ace() callbacks
22700 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 might occur.** a
22710 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 s each triggered
22720 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 subprogram is e
22730 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c ntered. The cal
22740 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 lbacks for trigg
22750 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 ers.** contain a
22760 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 UTF-8 SQL comme
22770 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 nt that identifi
22780 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 es the trigger.)
22790 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c ^.**.** The [SQL
227a0 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c ITE_TRACE_SIZE_L
227b0 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 IMIT] compile-ti
227c0 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 me option can be
227d0 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a used to limit.*
227e0 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 * the length of
227f0 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 [bound parameter
22800 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 ] expansion in t
22810 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c he output of sql
22820 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a ite3_trace()..**
22830 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 .** ^The callbac
22840 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 k function regis
22850 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 tered by sqlite3
22860 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e _profile() is in
22870 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 voked.** as each
22880 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 SQL statement f
22890 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 inishes. ^The p
228a0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 rofile callback
228b0 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 contains.** the
228c0 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 original stateme
228d0 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 nt text and an e
228e0 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d stimate of wall-
228f0 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 clock time.** of
22900 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 how long that s
22910 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f tatement took to
22920 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 run. ^The prof
22930 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 ile callback.**
22940 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 time is in units
22950 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c of nanoseconds,
22960 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 however the cur
22970 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 rent implementat
22980 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 ion.** is only c
22990 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 apable of millis
229a0 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e econd resolution
229b0 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 so the six leas
229c0 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a t significant.**
229d0 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 digits in the t
229e0 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c ime are meaningl
229f0 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 ess. Future ver
22a00 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a sions of SQLite.
22a10 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 ** might provide
22a20 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 greater resolut
22a30 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 ion on the profi
22a40 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 ler callback. T
22a50 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 he.** sqlite3_pr
22a60 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e ofile() function
22a70 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 is considered e
22a80 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 xperimental and
22a90 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f is.** subject to
22aa0 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 change in futur
22ab0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
22ac0 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f Lite..*/.SQLITE_
22ad0 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 DEPRECATED void
22ae0 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 *sqlite3_trace(s
22af0 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 qlite3*,. void
22b00 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c (*xTrace)(void*,
22b10 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f const char*), vo
22b20 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 id*);.SQLITE_DEP
22b30 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71 RECATED void *sq
22b40 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 lite3_profile(sq
22b50 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 lite3*,. void(
22b60 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a *xProfile)(void*
22b70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c ,const char*,sql
22b80 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f ite3_uint64), vo
22b90 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 id*);../*.** CAP
22ba0 49 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 I3REF: SQL Trace
22bb0 20 45 76 65 6e 74 20 43 6f 64 65 73 0a 2a 2a 20 Event Codes.**
22bc0 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 KEYWORDS: SQLITE
22bd0 5f 54 52 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65 _TRACE.**.** The
22be0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 69 64 65 se constants ide
22bf0 6e 74 69 66 79 20 63 6c 61 73 73 65 73 20 6f 66 ntify classes of
22c00 20 65 76 65 6e 74 73 20 74 68 61 74 20 63 61 6e events that can
22c10 20 62 65 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a be monitored.**
22c20 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 using the [sqli
22c30 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 te3_trace_v2()]
22c40 74 72 61 63 69 6e 67 20 6c 6f 67 69 63 2e 20 20 tracing logic.
22c50 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 The third argume
22c60 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 nt.** to [sqlite
22c70 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 69 73 3_trace_v2()] is
22c80 20 61 6e 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e an OR-ed combin
22c90 61 74 69 6f 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 ation of one or
22ca0 6d 6f 72 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 more of.** the f
22cb0 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e ollowing constan
22cc0 74 73 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 ts. ^The first
22cd0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
22ce0 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a trace callback.*
22cf0 2a 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 * is one of the
22d00 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 following consta
22d10 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 nts..**.** New t
22d20 72 61 63 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 racing constants
22d30 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e may be added in
22d40 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
22d50 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 ..**.** ^A trace
22d60 20 63 61 6c 6c 62 61 63 6b 20 68 61 73 20 66 6f callback has fo
22d70 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 78 43 ur arguments: xC
22d80 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 allback(T,C,P,X)
22d90 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75 ..** ^The T argu
22da0 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 ment is one of t
22db0 68 65 20 69 6e 74 65 67 65 72 20 74 79 70 65 20 he integer type
22dc0 63 6f 64 65 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 codes above..**
22dd0 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 ^The C argument
22de0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 is a copy of the
22df0 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 context pointer
22e00 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 passed in as th
22e10 65 0a 2a 2a 20 66 6f 75 72 74 68 20 61 72 67 75 e.** fourth argu
22e20 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 ment to [sqlite3
22e30 5f 74 72 61 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a _trace_v2()]..**
22e40 20 54 68 65 20 50 20 61 6e 64 20 58 20 61 72 67 The P and X arg
22e50 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 uments are point
22e60 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e ers whose meanin
22e70 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a gs depend on T..
22e80 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b **.** <dl>.** [[
22e90 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d SQLITE_TRACE_STM
22ea0 54 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 T]] <dt>SQLITE_T
22eb0 52 41 43 45 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a RACE_STMT</dt>.*
22ec0 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 * <dd>^An SQLITE
22ed0 5f 54 52 41 43 45 5f 53 54 4d 54 20 63 61 6c 6c _TRACE_STMT call
22ee0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
22ef0 77 68 65 6e 20 61 20 70 72 65 70 61 72 65 64 20 when a prepared
22f00 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 statement.** fir
22f10 73 74 20 62 65 67 69 6e 73 20 72 75 6e 6e 69 6e st begins runnin
22f20 67 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 61 g and possibly a
22f30 74 20 6f 74 68 65 72 20 74 69 6d 65 73 20 64 75 t other times du
22f40 72 69 6e 67 20 74 68 65 0a 2a 2a 20 65 78 65 63 ring the.** exec
22f50 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 70 72 65 ution of the pre
22f60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c pared statement,
22f70 20 73 75 63 68 20 61 73 20 61 74 20 74 68 65 20 such as at the
22f80 73 74 61 72 74 20 6f 66 20 65 61 63 68 0a 2a 2a start of each.**
22f90 20 74 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 trigger subprog
22fa0 72 61 6d 2e 20 5e 54 68 65 20 50 20 61 72 67 75 ram. ^The P argu
22fb0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 ment is a pointe
22fc0 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 70 72 65 r to the.** [pre
22fd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
22fe0 2e 20 5e 54 68 65 20 58 20 61 72 67 75 6d 65 6e . ^The X argumen
22ff0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 t is a pointer t
23000 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 o a string which
23010 0a 2a 2a 20 69 73 20 74 68 65 20 75 6e 65 78 70 .** is the unexp
23020 61 6e 64 65 64 20 53 51 4c 20 74 65 78 74 20 6f anded SQL text o
23030 66 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 f the prepared s
23040 74 61 74 65 6d 65 6e 74 20 6f 72 20 61 6e 20 53 tatement or an S
23050 51 4c 20 63 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 QL comment .** t
23060 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 hat indicates th
23070 65 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 e invocation of
23080 61 20 74 72 69 67 67 65 72 2e 20 20 5e 54 68 65 a trigger. ^The
23090 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e 20 63 6f callback can co
230a0 6d 70 75 74 65 0a 2a 2a 20 74 68 65 20 73 61 6d mpute.** the sam
230b0 65 20 74 65 78 74 20 74 68 61 74 20 77 6f 75 6c e text that woul
230c0 64 20 68 61 76 65 20 62 65 65 6e 20 72 65 74 75 d have been retu
230d0 72 6e 65 64 20 62 79 20 74 68 65 20 6c 65 67 61 rned by the lega
230e0 63 79 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 cy [sqlite3_trac
230f0 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 e()].** interfac
23100 65 20 62 79 20 75 73 69 6e 67 20 74 68 65 20 58 e by using the X
23110 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 58 argument when X
23120 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 2d 2d begins with "--
23130 22 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a " and invoking.*
23140 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 70 61 6e * [sqlite3_expan
23150 64 65 64 5f 73 71 6c 28 50 29 5d 20 6f 74 68 65 ded_sql(P)] othe
23160 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 rwise..**.** [[S
23170 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 QLITE_TRACE_PROF
23180 49 4c 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 ILE]] <dt>SQLITE
23190 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 3c 2f _TRACE_PROFILE</
231a0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 dt>.** <dd>^An S
231b0 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 QLITE_TRACE_PROF
231c0 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 70 72 6f ILE callback pro
231d0 76 69 64 65 73 20 61 70 70 72 6f 78 69 6d 61 74 vides approximat
231e0 65 6c 79 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 ely the same.**
231f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 information as i
23200 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 s provided by th
23210 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 e [sqlite3_profi
23220 6c 65 28 29 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a le()] callback..
23230 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 ** ^The P argume
23240 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 nt is a pointer
23250 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 to the [prepared
23260 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 statement] and
23270 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e the.** X argumen
23280 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 36 34 t points to a 64
23290 2d 62 69 74 20 69 6e 74 65 67 65 72 20 77 68 69 -bit integer whi
232a0 63 68 20 69 73 20 74 68 65 20 65 73 74 69 6d 61 ch is the estima
232b0 74 65 64 20 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 ted of.** the nu
232c0 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f mber of nanoseco
232d0 6e 64 20 74 68 61 74 20 74 68 65 20 70 72 65 70 nd that the prep
232e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74 ared statement t
232f0 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e ook to run..** ^
23300 54 68 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 The SQLITE_TRACE
23310 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 _PROFILE callbac
23320 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 k is invoked whe
23330 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 n the statement
23340 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 finishes..**.**
23350 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 [[SQLITE_TRACE_R
23360 4f 57 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f OW]] <dt>SQLITE_
23370 54 52 41 43 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a TRACE_ROW</dt>.*
23380 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 * <dd>^An SQLITE
23390 5f 54 52 41 43 45 5f 52 4f 57 20 63 61 6c 6c 62 _TRACE_ROW callb
233a0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 ack is invoked w
233b0 68 65 6e 65 76 65 72 20 61 20 70 72 65 70 61 72 henever a prepar
233c0 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 ed.** statement
233d0 67 65 6e 65 72 61 74 65 73 20 61 20 73 69 6e 67 generates a sing
233e0 6c 65 20 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 le row of result
233f0 2e 20 20 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 . .** ^The P ar
23400 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e gument is a poin
23410 74 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70 ter to the [prep
23420 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
23430 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 and the.** X arg
23440 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e ument is unused.
23450 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
23460 54 52 41 43 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 TRACE_CLOSE]] <d
23470 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 t>SQLITE_TRACE_C
23480 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 LOSE</dt>.** <dd
23490 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 >^An SQLITE_TRAC
234a0 45 5f 43 4c 4f 53 45 20 63 61 6c 6c 62 61 63 6b E_CLOSE callback
234b0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e is invoked when
234c0 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 a database.** c
234d0 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 onnection closes
234e0 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 ..** ^The P argu
234f0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 ment is a pointe
23500 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 r to the [databa
23510 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f se connection] o
23520 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 74 68 65 bject.** and the
23530 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75 X argument is u
23540 6e 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a nused..** </dl>.
23550 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
23560 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 20 20 20 E_TRACE_STMT
23570 20 20 20 30 78 30 31 0a 23 64 65 66 69 6e 65 20 0x01.#define
23580 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f SQLITE_TRACE_PRO
23590 46 49 4c 45 20 20 20 20 30 78 30 32 0a 23 64 65 FILE 0x02.#de
235a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 fine SQLITE_TRAC
235b0 45 5f 52 4f 57 20 20 20 20 20 20 20 20 30 78 30 E_ROW 0x0
235c0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
235d0 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20 20 20 20 _TRACE_CLOSE
235e0 20 20 30 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 0x08../*.** CA
235f0 50 49 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63 PI3REF: SQL Trac
23600 65 20 48 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 e Hook.** METHOD
23610 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
23620 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 ^The sqlite3_tra
23630 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 20 69 ce_v2(D,M,X,P) i
23640 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 nterface registe
23650 72 73 20 61 20 74 72 61 63 65 20 63 61 6c 6c 62 rs a trace callb
23660 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ack.** function
23670 58 20 61 67 61 69 6e 73 74 20 5b 64 61 74 61 62 X against [datab
23680 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
23690 44 2c 20 75 73 69 6e 67 20 70 72 6f 70 65 72 74 D, using propert
236a0 79 20 6d 61 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 y mask M.** and
236b0 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 context pointer
236c0 50 2e 20 20 5e 49 66 20 74 68 65 20 58 20 63 61 P. ^If the X ca
236d0 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c llback is.** NUL
236e0 4c 20 6f 72 20 69 66 20 74 68 65 20 4d 20 6d 61 L or if the M ma
236f0 73 6b 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e sk is zero, then
23700 20 74 72 61 63 69 6e 67 20 69 73 20 64 69 73 61 tracing is disa
23710 62 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 bled. The.** M
23720 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 argument should
23730 62 65 20 74 68 65 20 62 69 74 77 69 73 65 20 4f be the bitwise O
23740 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e R-ed combination
23750 20 6f 66 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d of.** zero or m
23760 6f 72 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 ore [SQLITE_TRAC
23770 45 5d 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a E] constants..**
23780 0a 2a 2a 20 5e 45 61 63 68 20 63 61 6c 6c 20 74 .** ^Each call t
23790 6f 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 o either sqlite3
237a0 5f 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 _trace() or sqli
237b0 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20 6f te3_trace_v2() o
237c0 76 65 72 72 69 64 65 73 20 0a 2a 2a 20 28 63 61 verrides .** (ca
237d0 6e 63 65 6c 73 29 20 61 6e 79 20 70 72 69 6f 72 ncels) any prior
237e0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 calls to sqlite
237f0 33 5f 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c 3_trace() or sql
23800 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 2e ite3_trace_v2().
23810 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 58 20 63 61 .**.** ^The X ca
23820 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
23830 64 20 77 68 65 6e 65 76 65 72 20 61 6e 79 20 6f d whenever any o
23840 66 20 74 68 65 20 65 76 65 6e 74 73 20 69 64 65 f the events ide
23850 6e 74 69 66 69 65 64 20 62 79 20 0a 2a 2a 20 6d ntified by .** m
23860 61 73 6b 20 4d 20 6f 63 63 75 72 2e 20 20 5e 54 ask M occur. ^T
23870 68 65 20 69 6e 74 65 67 65 72 20 72 65 74 75 72 he integer retur
23880 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 n value from the
23890 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 75 72 callback is cur
238a0 72 65 6e 74 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 rently.** ignore
238b0 64 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 6d d, though this m
238c0 61 79 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 ay change in fut
238d0 75 72 65 20 72 65 6c 65 61 73 65 73 2e 20 20 43 ure releases. C
238e0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 allback.** imple
238f0 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c mentations shoul
23900 64 20 72 65 74 75 72 6e 20 7a 65 72 6f 20 74 6f d return zero to
23910 20 65 6e 73 75 72 65 20 66 75 74 75 72 65 20 63 ensure future c
23920 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a ompatibility..**
23930 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c .** ^A trace cal
23940 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
23950 20 77 69 74 68 20 66 6f 75 72 20 61 72 67 75 6d with four argum
23960 65 6e 74 73 3a 20 63 61 6c 6c 62 61 63 6b 28 54 ents: callback(T
23970 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 ,C,P,X)..** ^The
23980 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f T argument is o
23990 6e 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 ne of the [SQLIT
239a0 45 5f 54 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 E_TRACE].** cons
239b0 74 61 6e 74 73 20 74 6f 20 69 6e 64 69 63 61 74 tants to indicat
239c0 65 20 77 68 79 20 74 68 65 20 63 61 6c 6c 62 61 e why the callba
239d0 63 6b 20 77 61 73 20 69 6e 76 6f 6b 65 64 2e 0a ck was invoked..
239e0 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65 ** ^The C argume
239f0 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 nt is a copy of
23a00 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e the context poin
23a10 74 65 72 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e ter..** The P an
23a20 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72 d X arguments ar
23a30 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 e pointers whose
23a40 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 meanings depend
23a50 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 on T..**.** The
23a60 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 sqlite3_trace_v
23a70 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 2() interface is
23a80 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 72 65 70 intended to rep
23a90 6c 61 63 65 20 74 68 65 20 6c 65 67 61 63 79 0a lace the legacy.
23aa0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 ** interfaces [s
23ab0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 qlite3_trace()]
23ac0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f and [sqlite3_pro
23ad0 66 69 6c 65 28 29 5d 2c 20 62 6f 74 68 20 6f 66 file()], both of
23ae0 20 77 68 69 63 68 0a 2a 2a 20 61 72 65 20 64 65 which.** are de
23af0 70 72 65 63 61 74 65 64 2e 0a 2a 2f 0a 69 6e 74 precated..*/.int
23b00 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 sqlite3_trace_v
23b10 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 2(. sqlite3*,.
23b20 20 75 6e 73 69 67 6e 65 64 20 75 4d 61 73 6b 2c unsigned uMask,
23b30 0a 20 20 69 6e 74 28 2a 78 43 61 6c 6c 62 61 63 . int(*xCallbac
23b40 6b 29 28 75 6e 73 69 67 6e 65 64 2c 76 6f 69 64 k)(unsigned,void
23b50 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a *,void*,void*),.
23b60 20 20 76 6f 69 64 20 2a 70 43 74 78 0a 29 3b 0a void *pCtx.);.
23b70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
23b80 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 Query Progress
23b90 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 Callbacks.** MET
23ba0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
23bb0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
23bc0 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 progress_handler
23bd0 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 (D,N,X,P) interf
23be0 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63 ace causes the c
23bf0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 allback.** funct
23c00 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f ion X to be invo
23c10 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 ked periodically
23c20 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e during long run
23c30 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a ning calls to.**
23c40 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 [sqlite3_exec()
23c50 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ], [sqlite3_step
23c60 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
23c70 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f _get_table()] fo
23c80 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f r.** database co
23c90 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 nnection D. An
23ca0 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 example use for
23cb0 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 this.** interfac
23cc0 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 e is to keep a G
23cd0 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e UI updated durin
23ce0 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e g a large query.
23cf0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 .**.** ^The para
23d00 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65 meter P is passe
23d10 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 d through as the
23d20 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 only parameter
23d30 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 to the .** callb
23d40 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 ack function X.
23d50 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 ^The parameter
23d60 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 69 N is the approxi
23d70 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a mate number of .
23d80 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 ** [virtual mach
23d90 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 ine instructions
23da0 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 ] that are evalu
23db0 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 ated between suc
23dc0 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 cessive.** invoc
23dd0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 ations of the ca
23de0 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e llback X. ^If N
23df0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e is less than on
23e00 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 e then the progr
23e10 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 ess.** handler i
23e20 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a s disabled..**.*
23e30 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 * ^Only a single
23e40 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 progress handle
23e50 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 r may be defined
23e60 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 at one time per
23e70 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
23e80 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 nnection]; setti
23e90 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 ng a new progres
23ea0 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c s handler cancel
23eb0 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 s the.** old one
23ec0 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 . ^Setting para
23ed0 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 meter X to NULL
23ee0 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f disables the pro
23ef0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a gress handler..*
23f00 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 * ^The progress
23f10 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 handler is also
23f20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 disabled by sett
23f30 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 ing N to a value
23f40 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e less.** than 1.
23f50 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 .**.** ^If the p
23f60 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b rogress callback
23f70 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 returns non-zer
23f80 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e o, the operation
23f90 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 is.** interrupt
23fa0 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 ed. This featur
23fb0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f e can be used to
23fc0 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 implement a.**
23fd0 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 "Cancel" button
23fe0 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 on a GUI progres
23ff0 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a s dialog box..**
24000 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 .** The progress
24010 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 handler callbac
24020 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e k must not do an
24030 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c ything that will
24040 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 modify.** the d
24050 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
24060 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 on that invoked
24070 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e the progress han
24080 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 dler..** Note th
24090 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 at [sqlite3_prep
240a0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 are_v2()] and [s
240b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 qlite3_step()] b
240c0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 oth modify their
240d0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
240e0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 nections for the
240f0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 meaning of "mod
24100 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 ify" in this par
24110 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f agraph..**.*/.vo
24120 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 id sqlite3_progr
24130 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 ess_handler(sqli
24140 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a te3*, int, int(*
24150 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 )(void*), void*)
24160 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
24170 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 F: Opening A New
24180 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 Database Connec
24190 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 tion.** CONSTRUC
241a0 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a TOR: sqlite3.**.
241b0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
241c0 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 es open an SQLit
241d0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
241e0 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20 as specified by
241f0 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 the .** filename
24200 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 argument. ^The
24210 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e filename argumen
24220 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 t is interpreted
24230 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a as UTF-8 for.**
24240 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
24250 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e and sqlite3_open
24260 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 _v2() and as UTF
24270 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 -16 in the nativ
24280 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 e byte.** order
24290 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e for sqlite3_open
242a0 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 16(). ^(A [datab
242b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
242c0 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c handle is usuall
242d0 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e y.** returned in
242e0 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 *ppDb, even if
242f0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e an error occurs.
24300 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 The only excep
24310 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 tion is that.**
24320 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 if SQLite is una
24330 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 ble to allocate
24340 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 memory to hold t
24350 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a he [sqlite3] obj
24360 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 ect,.** a NULL w
24370 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 ill be written i
24380 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 nto *ppDb instea
24390 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 d of a pointer t
243a0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a o the [sqlite3].
243b0 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 ** object.)^ ^(I
243c0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 f the database i
243d0 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 s opened (and/or
243e0 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 created) succes
243f0 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 sfully, then.**
24400 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 [SQLITE_OK] is r
24410 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 eturned. Otherw
24420 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f ise an [error co
24430 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e de] is returned.
24440 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 )^ ^The.** [sqli
24450 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 te3_errmsg()] or
24460 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
24470 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 16()] routines c
24480 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 an be used to ob
24490 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 tain.** an Engli
244a0 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 sh language desc
244b0 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 ription of the e
244c0 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 rror following a
244d0 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a failure of any.
244e0 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 ** of the sqlite
244f0 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 3_open() routine
24500 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 s..**.** ^The de
24510 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 fault encoding w
24520 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72 ill be UTF-8 for
24530 20 64 61 74 61 62 61 73 65 73 20 63 72 65 61 74 databases creat
24540 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 ed using.** sqli
24550 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 te3_open() or sq
24560 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e lite3_open_v2().
24570 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 ^The default e
24580 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61 ncoding for data
24590 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 bases.** created
245a0 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f using sqlite3_o
245b0 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20 pen16() will be
245c0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 UTF-16 in the na
245d0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e tive byte order.
245e0 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f .**.** Whether o
245f0 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f r not an error o
24600 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 ccurs when it is
24610 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 opened, resourc
24620 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 es.** associated
24630 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 with the [datab
24640 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
24650 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 handle should be
24660 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 released by.**
24670 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 passing it to [s
24680 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 qlite3_close()]
24690 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f when it is no lo
246a0 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a nger required..*
246b0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
246c0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 _open_v2() inter
246d0 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 face works like
246e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a sqlite3_open().*
246f0 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 * except that it
24700 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 accepts two add
24710 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 itional paramete
24720 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 rs for additiona
24730 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 l control.** ove
24740 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 r the new databa
24750 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 se connection.
24760 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 ^(The flags para
24770 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 meter to.** sqli
24780 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 te3_open_v2() ca
24790 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a n take one of.**
247a0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 the following t
247b0 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 hree values, opt
247c0 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 ionally combined
247d0 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 with the .** [S
247e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 QLITE_OPEN_NOMUT
247f0 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 EX], [SQLITE_OPE
24800 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 N_FULLMUTEX], [S
24810 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 QLITE_OPEN_SHARE
24820 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c DCACHE],.** [SQL
24830 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 ITE_OPEN_PRIVATE
24840 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b CACHE], and/or [
24850 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d SQLITE_OPEN_URI]
24860 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 flags:)^.**.**
24870 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 <dl>.** ^(<dt>[S
24880 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
24890 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 NLY]</dt>.** <dd
248a0 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 >The database is
248b0 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d opened in read-
248c0 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 only mode. If t
248d0 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 he database does
248e0 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 not.** already
248f0 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 exist, an error
24900 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 is returned.</dd
24910 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e >)^.**.** ^(<dt>
24920 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 [SQLITE_OPEN_REA
24930 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 DWRITE]</dt>.**
24940 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 <dd>The database
24950 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 is opened for r
24960 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 eading and writi
24970 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 ng if possible,
24980 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e or reading.** on
24990 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 ly if the file i
249a0 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 s write protecte
249b0 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 d by the operati
249c0 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 ng system. In e
249d0 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 ither.** case th
249e0 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 e database must
249f0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f already exist, o
24a00 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f therwise an erro
24a10 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f r is returned.</
24a20 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 dd>)^.**.** ^(<d
24a30 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 t>[SQLITE_OPEN_R
24a40 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c EADWRITE] | [SQL
24a50 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d ITE_OPEN_CREATE]
24a60 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
24a70 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
24a80 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 ned for reading
24a90 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 and writing, and
24aa0 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a is created if.*
24ab0 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c * it does not al
24ac0 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 ready exist. Thi
24ad0 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f s is the behavio
24ae0 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 r that is always
24af0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c used for.** sql
24b00 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 ite3_open() and
24b10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
24b20 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c .</dd>)^.** </dl
24b30 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 >.**.** If the 3
24b40 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
24b50 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
24b60 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 ) is not one of
24b70 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 the.** combinati
24b80 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 ons shown above
24b90 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 optionally combi
24ba0 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a ned with other.*
24bb0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 * [SQLITE_OPEN_R
24bc0 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 EADONLY | SQLITE
24bd0 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a _OPEN_* bits].**
24be0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 then the behavi
24bf0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e or is undefined.
24c00 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b .**.** ^If the [
24c10 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 SQLITE_OPEN_NOMU
24c20 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 TEX] flag is set
24c30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 , then the datab
24c40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
24c50 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d * opens in the m
24c60 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 ulti-thread [thr
24c70 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 eading mode] as
24c80 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 long as the sing
24c90 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 le-thread.** mod
24ca0 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 e has not been s
24cb0 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 et at compile-ti
24cc0 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 me or start-time
24cd0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 . ^If the.** [S
24ce0 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d QLITE_OPEN_FULLM
24cf0 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 UTEX] flag is se
24d00 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 t then the datab
24d10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f ase connection o
24d20 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 pens.** in the s
24d30 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 erialized [threa
24d40 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 ding mode] unles
24d50 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 s single-thread
24d60 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c was.** previousl
24d70 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f y selected at co
24d80 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 mpile-time or st
24d90 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 art-time..** ^Th
24da0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 e [SQLITE_OPEN_S
24db0 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 HAREDCACHE] flag
24dc0 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 causes the data
24dd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
24de0 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c to be.** eligibl
24df0 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 e to use [shared
24e00 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 cache mode], re
24e10 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 gardless of whet
24e20 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 her or not share
24e30 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e d.** cache is en
24e40 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c abled using [sql
24e50 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 ite3_enable_shar
24e60 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 ed_cache()]. ^T
24e70 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 he.** [SQLITE_OP
24e80 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d EN_PRIVATECACHE]
24e90 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 flag causes the
24ea0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
24eb0 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 tion to not.** p
24ec0 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 articipate in [s
24ed0 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 hared cache mode
24ee0 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 ] even if it is
24ef0 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e enabled..**.** ^
24f00 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d The fourth param
24f10 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
24f20 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 open_v2() is the
24f30 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 name of the.**
24f40 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
24f50 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 ject that define
24f60 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 s the operating
24f70 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 system interface
24f80 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 that.** the new
24f90 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
24fa0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e tion should use.
24fb0 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 ^If the fourth
24fc0 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a parameter is.**
24fd0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
24fe0 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 then the default
24ff0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f [sqlite3_vfs] o
25000 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a bject is used..*
25010 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c *.** ^If the fil
25020 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 ename is ":memor
25030 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 y:", then a priv
25040 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 ate, temporary i
25050 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 n-memory databas
25060 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 e.** is created
25070 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 for the connecti
25080 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 on. ^This in-me
25090 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 mory database wi
250a0 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a ll vanish when.*
250b0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 * the database c
250c0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f onnection is clo
250d0 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 sed. Future ver
250e0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 sions of SQLite
250f0 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 might.** make us
25100 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 e of additional
25110 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 special filename
25120 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 s that begin wit
25130 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 h the ":" charac
25140 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 ter..** It is re
25150 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 commended that w
25160 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 hen a database f
25170 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 ilename actually
25180 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 does begin with
25190 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 .** a ":" charac
251a0 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 ter you should p
251b0 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 refix the filena
251c0 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 me with a pathna
251d0 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e me such as.** ".
251e0 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 /" to avoid ambi
251f0 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 guity..**.** ^If
25200 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 the filename is
25210 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
25220 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 , then a private
25230 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f , temporary.** o
25240 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 n-disk database
25250 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e will be created.
25260 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 ^This private
25270 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 database will be
25280 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c .** automaticall
25290 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f y deleted as soo
252a0 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 n as the databas
252b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
252c0 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b closed..**.** [[
252d0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e URI filenames in
252e0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d sqlite3_open()]
252f0 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 ] <h3>URI Filena
25300 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e mes</h3>.**.** ^
25310 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 If [URI filename
25320 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e ] interpretation
25330 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 is enabled, and
25340 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 the filename ar
25350 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 gument.** begins
25360 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 with "file:", t
25370 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 hen the filename
25380 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 is interpreted
25390 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a as a URI. ^URI.*
253a0 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 * filename inter
253b0 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 pretation is ena
253c0 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c bled if the [SQL
253d0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c ITE_OPEN_URI] fl
253e0 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 ag is.** set in
253f0 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d the fourth argum
25400 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f ent to sqlite3_o
25410 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 pen_v2(), or if
25420 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 it has.** been e
25430 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 nabled globally
25440 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 using the [SQLIT
25450 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 E_CONFIG_URI] op
25460 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a tion with the.**
25470 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
25480 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 ()] method or by
25490 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 the [SQLITE_USE
254a0 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 _URI] compile-ti
254b0 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 me option..** As
254c0 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 of SQLite versi
254d0 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 on 3.7.7, URI fi
254e0 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 lename interpret
254f0 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 ation is turned
25500 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c off.** by defaul
25510 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65 t, but future re
25520 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
25530 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 might enable UR
25540 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e I filename.** in
25550 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 terpretation by
25560 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b default. See "[
25570 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 URI filenames]"
25580 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a for additional.*
25590 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a * information..*
255a0 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d *.** URI filenam
255b0 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63 es are parsed ac
255c0 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 cording to RFC 3
255d0 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 986. ^If the URI
255e0 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 contains an.**
255f0 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 authority, then
25600 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 it must be eithe
25610 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e r an empty strin
25620 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 g or the string
25630 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e .** "localhost".
25640 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 ^If the authori
25650 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 ty is not an emp
25660 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f ty string or "lo
25670 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a calhost", an .**
25680 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e error is return
25690 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 ed to the caller
256a0 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 . ^The fragment
256b0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 component of a U
256c0 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 RI, if .** prese
256d0 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a nt, is ignored..
256e0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 **.** ^SQLite us
256f0 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 es the path comp
25700 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 onent of the URI
25710 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 as the name of
25720 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a the disk file.**
25730 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 which contains
25740 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 the database. ^I
25750 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e f the path begin
25760 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 s with a '/' cha
25770 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e racter, .** then
25780 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 it is interpret
25790 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 ed as an absolut
257a0 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 e path. ^If the
257b0 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 path does not be
257c0 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 gin .** with a '
257d0 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 /' (meaning that
257e0 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 the authority s
257f0 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 ection is omitte
25800 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a d from the URI).
25810 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 ** then the path
25820 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 is interpreted
25830 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 as a relative pa
25840 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e th. .** ^(On win
25850 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 dows, the first
25860 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 component of an
25870 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a absolute path .*
25880 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65 * is a drive spe
25890 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e cification (e.g.
258a0 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 "C:").)^.**.**
258b0 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 [[core URI query
258c0 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a parameters]].**
258d0 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f The query compo
258e0 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 nent of a URI ma
258f0 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 y contain parame
25900 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e ters that are in
25910 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 terpreted.** eit
25920 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 her by SQLite it
25930 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 self, or by a [V
25940 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 FS | custom VFS
25950 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e implementation].
25960 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69 .** SQLite and i
25970 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 ts built-in [VFS
25980 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68 es] interpret th
25990 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 e.** following q
259a0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a uery parameters:
259b0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 .**.** <ul>.**
259c0 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e <li> <b>vfs</b>
259d0 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 : ^The "vfs" par
259e0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 ameter may be us
259f0 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 ed to specify th
25a00 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 e name of.**
25a10 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 a VFS object th
25a20 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 at provides the
25a30 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d operating system
25a40 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 interface that
25a50 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 should.** be
25a60 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 used to access
25a70 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
25a80 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 e on disk. ^If t
25a90 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 his option is se
25aa0 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 t to.** an e
25ab0 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 mpty string the
25ac0 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 default VFS obje
25ad0 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 ct is used. ^Spe
25ae0 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f cifying an unkno
25af0 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 wn.** VFS is
25b00 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 an error. ^If s
25b10 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
25b20 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 is used and the
25b30 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a vfs option is.*
25b40 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 * present, t
25b50 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 hen the VFS spec
25b60 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 ified by the opt
25b70 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 ion takes preced
25b80 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 ence over.**
25b90 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 the value passe
25ba0 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 d as the fourth
25bb0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
25bc0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a ite3_open_v2()..
25bd0 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e **.** <li> <b>
25be0 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 mode</b>: ^(The
25bf0 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d mode parameter m
25c00 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 ay be set to eit
25c10 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a her "ro", "rw",.
25c20 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 ** "rwc", or
25c30 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d "memory". Attem
25c40 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 pting to set it
25c50 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c to any other val
25c60 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 ue is.** an
25c70 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 error)^. .**
25c80 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 ^If "ro" is spe
25c90 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 cified, then the
25ca0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
25cb0 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c ned for read-onl
25cc0 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 y .** access
25cd0 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 , just as if the
25ce0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 [SQLITE_OPEN_RE
25cf0 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 ADONLY] flag had
25d00 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 been set in the
25d10 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 .** third a
25d20 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
25d30 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 e3_open_v2(). ^I
25d40 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f f the mode optio
25d50 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 n is set to .**
25d60 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 "rw", then t
25d70 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
25d80 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 pened for read-w
25d90 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 rite (but not cr
25da0 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 eate) .** ac
25db0 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 cess, as if SQLI
25dc0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 TE_OPEN_READWRIT
25dd0 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 E (but not SQLIT
25de0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 E_OPEN_CREATE) h
25df0 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 ad .** been
25e00 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 set. ^Value "rwc
25e10 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 " is equivalent
25e20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 to setting both
25e30 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f .** SQLITE_O
25e40 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e PEN_READWRITE an
25e50 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 d SQLITE_OPEN_CR
25e60 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d EATE. ^If the m
25e70 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a ode option is.**
25e80 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d set to "mem
25e90 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 ory" then a pure
25ea0 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 [in-memory data
25eb0 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 base] that never
25ec0 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 reads.** or
25ed0 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 writes from dis
25ee0 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 k is used. ^It i
25ef0 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 s an error to sp
25f00 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f ecify a value fo
25f10 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 r.** the mod
25f20 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 e parameter that
25f30 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 is less restric
25f40 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 tive than that s
25f50 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 pecified by.**
25f60 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 the flags pas
25f70 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 sed in the third
25f80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
25f90 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e lite3_open_v2().
25fa0 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 .**.** <li> <b
25fb0 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 >cache</b>: ^The
25fc0 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 cache parameter
25fd0 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 may be set to e
25fe0 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f ither "shared" o
25ff0 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 r.** "privat
26000 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 e". ^Setting it
26010 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65 to "shared" is e
26020 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 quivalent to set
26030 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 ting the.**
26040 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 SQLITE_OPEN_SHAR
26050 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 EDCACHE bit in t
26060 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e he flags argumen
26070 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 t passed to.**
26080 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f sqlite3_open_
26090 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 v2(). ^Setting t
260a0 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 he cache paramet
260b0 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 er to "private"
260c0 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 is .** equiv
260d0 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 alent to setting
260e0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e the SQLITE_OPEN
260f0 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69 _PRIVATECACHE bi
26100 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 t..** ^If sq
26110 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
26120 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 is used and the
26130 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 "cache" paramete
26140 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a r is present in.
26150 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c ** a URI fil
26160 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 ename, its value
26170 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 overrides any b
26180 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 ehavior requeste
26190 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 d by setting.**
261a0 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f SQLITE_OPEN_
261b0 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 PRIVATECACHE or
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 66 6c 61 67 2e 0a 2a 2a EDCACHE flag..**
261e0 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f .** <li> <b>pso
261f0 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 w</b>: ^The psow
26200 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63 parameter indic
26210 61 74 65 73 20 77 68 65 74 68 65 72 20 6f 72 20 ates whether or
26220 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b not the.** [
26230 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 powersafe overwr
26240 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f ite] property do
26250 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 es or does not a
26260 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 pply to the.**
26270 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 storage media
26280 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 on which the da
26290 74 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 tabase file resi
262a0 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e des..**.** <li>
262b0 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 <b>nolock</b>:
262c0 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 ^The nolock para
262d0 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 meter is a boole
262e0 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 an query paramet
262f0 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20 er.** which
26300 69 66 20 73 65 74 20 64 69 73 61 62 6c 65 73 20 if set disables
26310 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 file locking in
26320 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c rollback journal
26330 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a modes. This.**
26340 20 20 20 20 20 69 73 20 75 73 65 66 75 6c 20 66 is useful f
26350 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61 20 64 or accessing a d
26360 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c atabase on a fil
26370 65 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 esystem that doe
26380 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 s not.** sup
26390 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 port locking. C
263a0 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 aution: Databas
263b0 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 e corruption mig
263c0 68 74 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f ht result if two
263d0 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 .** or more
263e0 70 72 6f 63 65 73 73 65 73 20 77 72 69 74 65 20 processes write
263f0 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 to the same data
26400 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 base and any one
26410 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 of those.**
26420 20 70 72 6f 63 65 73 73 65 73 20 75 73 65 73 20 processes uses
26430 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 nolock=1..**.**
26440 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 <li> <b>immutab
26450 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d le</b>: ^The imm
26460 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 utable parameter
26470 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 is a boolean qu
26480 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d ery.** param
26490 65 74 65 72 20 74 68 61 74 20 69 6e 64 69 63 61 eter that indica
264a0 74 65 73 20 74 68 61 74 20 74 68 65 20 64 61 74 tes that the dat
264b0 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 73 74 abase file is st
264c0 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 ored on.** r
264d0 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 ead-only media.
264e0 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 ^When immutable
264f0 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20 is set, SQLite
26500 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 assumes that the
26510 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 .** database
26520 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 file cannot be
26530 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 changed, even by
26540 20 61 20 70 72 6f 63 65 73 73 20 77 69 74 68 20 a process with
26550 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 higher.** pr
26560 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 ivilege, and so
26570 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 the database is
26580 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 opened read-only
26590 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 and all locking
265a0 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e .** and chan
265b0 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 ge detection is
265c0 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69 disabled. Cauti
265d0 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20 on: Setting the
265e0 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 immutable.**
265f0 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 property on a d
26600 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 atabase file tha
26610 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63 t does in fact c
26620 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74 hange can result
26630 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 .** in incor
26640 72 65 63 74 20 71 75 65 72 79 20 72 65 73 75 6c rect query resul
26650 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 ts and/or [SQLIT
26660 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 E_CORRUPT] error
26670 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c s..** See al
26680 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 so: [SQLITE_IOCA
26690 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a P_IMMUTABLE]..**
266a0 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e .** </ul>
266b0 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 .**.** ^Specifyi
266c0 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 ng an unknown pa
266d0 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 rameter in the q
266e0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f uery component o
266f0 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 f a URI is not a
26700 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 n.** error. Fut
26710 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 ure versions of
26720 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 SQLite might und
26730 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e erstand addition
26740 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 al query.** para
26750 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 meters. See "[q
26760 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 uery parameters
26770 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 with special mea
26780 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 ning to SQLite]"
26790 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e for.** addition
267a0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a al information..
267b0 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 **.** [[URI file
267c0 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 name examples]]
267d0 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 <h3>URI filename
267e0 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a examples</h3>.*
267f0 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 *.** <table bord
26800 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e er="1" align=cen
26810 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d ter cellpadding=
26820 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 5>.** <tr><th> U
26830 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 RI filenames <th
26840 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 > Results.** <tr
26850 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e ><td> file:data.
26860 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 db <td> .**
26870 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 Open the fi
26880 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 le "data.db" in
26890 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 the current dire
268a0 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 ctory..** <tr><t
268b0 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 d> file:/home/fr
268c0 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a ed/data.db<br>.*
268d0 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a * file:
268e0 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 ///home/fred/dat
268f0 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 a.db <br> .**
26900 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f file://lo
26910 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 calhost/home/fre
26920 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c d/data.db <br> <
26930 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 td> .**
26940 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 Open the databa
26950 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 se file "/home/f
26960 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a red/data.db"..**
26970 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f <tr><td> file:/
26980 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 /darkstar/home/f
26990 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e red/data.db <td>
269a0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e .** An
269b0 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 error. "darksta
269c0 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f r" is not a reco
269d0 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 gnized authority
269e0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 ..** <tr><td sty
269f0 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a le="white-space:
26a00 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 nowrap"> .**
26a10 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a file:///C:
26a20 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 /Documents%20and
26a30 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 %20Settings/fred
26a40 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 /Desktop/data.db
26a50 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e .** <td> Win
26a60 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 dows only: Open
26a70 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 the file "data.d
26a80 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 b" on fred's des
26a90 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a ktop on drive.**
26aa0 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f C:. No
26ab0 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20 te that the %20
26ac0 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 escaping in this
26ad0 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 example is not
26ae0 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 strictly .**
26af0 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 necessary
26b00 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65 - space characte
26b10 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c rs can be used l
26b20 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 iterally.**
26b30 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 in URI file
26b40 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 names..** <tr><t
26b50 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f d> file:data.db?
26b60 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 mode=ro&cache=pr
26b70 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 ivate <td> .**
26b80 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c Open fil
26b90 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 e "data.db" in t
26ba0 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 he current direc
26bb0 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e tory for read-on
26bc0 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 ly access..**
26bd0 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 Regardles
26be0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 s of whether or
26bf0 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 not shared-cache
26c00 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 mode is enabled
26c10 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 by.**
26c20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 default, use a p
26c30 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a rivate cache..**
26c40 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f <tr><td> file:/
26c50 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 home/fred/data.d
26c60 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 b?vfs=unix-dotfi
26c70 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 le <td>.**
26c80 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f Open file "/
26c90 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 home/fred/data.d
26ca0 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 b". Use the spec
26cb0 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f ial VFS "unix-do
26cc0 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 tfile".**
26cd0 20 20 20 74 68 61 74 20 75 73 65 73 20 64 6f 74 that uses dot
26ce0 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 -files in place
26cf0 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72 of posix advisor
26d00 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 y locking..** <t
26d10 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 r><td> file:data
26d20 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c .db?mode=readonl
26d30 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 y <td> .**
26d40 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 An error. "r
26d50 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 eadonly" is not
26d60 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 a valid option f
26d70 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 or the "mode" pa
26d80 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 rameter..** </ta
26d90 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 ble>.**.** ^URI
26da0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 hexadecimal esca
26db0 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 pe sequences (%H
26dc0 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 H) are supported
26dd0 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 within the path
26de0 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f and.** query co
26df0 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 mponents of a UR
26e00 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c I. A hexadecimal
26e10 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 escape sequence
26e20 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a consists of a.*
26e30 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d * percent sign -
26e40 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 "%" - followed
26e50 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 by exactly two h
26e60 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 exadecimal digit
26e70 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 s .** specifying
26e80 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e an octet value.
26e90 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 ^Before the pat
26ea0 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f h or query compo
26eb0 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 nents of a.** UR
26ec0 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 I filename are i
26ed0 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 nterpreted, they
26ee0 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 are encoded usi
26ef0 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c ng UTF-8 and all
26f00 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c .** hexadecimal
26f10 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 escape sequence
26f20 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 s replaced by a
26f30 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 single byte cont
26f40 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f aining the.** co
26f50 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 rresponding octe
26f60 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 t. If this proce
26f70 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 ss generates an
26f80 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e invalid UTF-8 en
26f90 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 coding,.** the r
26fa0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 esults are undef
26fb0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e ined..**.** <b>N
26fc0 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 ote to Windows u
26fd0 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 sers:</b> The e
26fe0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 ncoding used for
26ff0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 the filename ar
27000 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c gument.** of sql
27010 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 ite3_open() and
27020 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
27030 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c ) must be UTF-8,
27040 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a not whatever.**
27050 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 codepage is cur
27060 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 rently defined.
27070 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 Filenames conta
27080 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f ining internatio
27090 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 nal.** character
270a0 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 s must be conver
270b0 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 ted to UTF-8 pri
270c0 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 or to passing th
270d0 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 em into.** sqlit
270e0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c e3_open() or sql
270f0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a ite3_open_v2()..
27100 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f **.** <b>Note to
27110 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 Windows Runtime
27120 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 users:</b> The
27130 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 temporary direc
27140 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 tory must be set
27150 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c .** prior to cal
27160 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 ling sqlite3_ope
27170 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f n() or sqlite3_o
27180 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 pen_v2(). Other
27190 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a wise, various.**
271a0 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72 features that r
271b0 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f equire the use o
271c0 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 f temporary file
271d0 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a s may fail..**.*
271e0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
271f0 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 ite3_temp_direct
27200 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ory].*/.int sqli
27210 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 te3_open(. cons
27220 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 t char *filename
27230 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 , /* Database
27240 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 filename (UTF-8)
27250 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a */. sqlite3 **
27260 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a ppDb /*
27270 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 OUT: SQLite db
27280 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 handle */.);.int
27290 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 sqlite3_open16(
272a0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 . const void *f
272b0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 ilename, /* Da
272c0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 tabase filename
272d0 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 (UTF-16) */. sq
272e0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 lite3 **ppDb
272f0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 /* OUT: SQ
27300 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a Lite db handle *
27310 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 /.);.int sqlite3
27320 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 _open_v2(. cons
27330 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 t char *filename
27340 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 , /* Database
27350 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 filename (UTF-8)
27360 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a */. sqlite3 **
27370 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a ppDb, /*
27380 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 OUT: SQLite db
27390 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 handle */. int
273a0 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 flags,
273b0 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a /* Flags */.
273c0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 const char *zV
273d0 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d fs /* Nam
273e0 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 e of VFS module
273f0 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a to use */.);../*
27400 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 .** CAPI3REF: Ob
27410 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 tain Values For
27420 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a URI Parameters.*
27430 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 *.** These are u
27440 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c tility routines,
27450 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 useful to VFS i
27460 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 mplementations,
27470 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f that check.** to
27480 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61 see if a databa
27490 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 se file was a UR
274a0 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 I that contained
274b0 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72 a specific quer
274c0 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c y .** parameter,
274d0 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 and if so obtai
274e0 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 ns the value of
274f0 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d that query param
27500 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 eter..**.** If F
27510 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 is the database
27520 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 filename pointe
27530 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 r passed into th
27540 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 e xOpen() method
27550 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d of .** a VFS im
27560 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 plementation whe
27570 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 n the flags para
27580 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 meter to xOpen()
27590 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 has one or .**
275a0 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c more of the [SQL
275b0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 ITE_OPEN_URI] or
275c0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 [SQLITE_OPEN_MA
275d0 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 IN_DB] bits set
275e0 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 and.** P is the
275f0 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 name of the quer
27600 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 y parameter, the
27610 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 n.** sqlite3_uri
27620 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 _parameter(F,P)
27630 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 returns the valu
27640 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 e of the P.** pa
27650 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 rameter if it ex
27660 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 ists or a NULL p
27670 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 ointer if P does
27680 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 not appear as a
27690 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d .** query param
276a0 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 eter on F. If P
276b0 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61 is a query para
276c0 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 meter of F.** ha
276d0 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 s no explicit va
276e0 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 lue, then sqlite
276f0 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 3_uri_parameter(
27700 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 F,P) returns.**
27710 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
27720 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a empty string..**
27730 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
27740 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c uri_boolean(F,P,
27750 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d B) routine assum
27760 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62 es that P is a b
27770 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 oolean.** parame
27780 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 ter and returns
27790 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 true (1) or fals
277a0 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 e (0) according
277b0 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 to the value.**
277c0 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 of P. The sqlit
277d0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 e3_uri_boolean(F
277e0 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 ,P,B) routine re
277f0 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 turns true (1) i
27800 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f f the.** value o
27810 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 f query paramete
27820 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 r P is one of "y
27830 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 es", "true", or
27840 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 "on" in any.** c
27850 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 ase or if the va
27860 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 lue begins with
27870 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 a non-zero numbe
27880 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 r. The .** sqli
27890 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 te3_uri_boolean(
278a0 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 F,P,B) routines
278b0 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 returns false (0
278c0 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f ) if the value o
278d0 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d f.** query param
278e0 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 eter P is one of
278f0 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 "no", "false",
27900 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 or "off" in any
27910 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 case or.** if th
27920 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 e value begins w
27930 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 ith a numeric ze
27940 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 ro. If P is not
27950 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 a query.** para
27960 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 meter on F or if
27970 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 the value of P
27980 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 is does not matc
27990 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 h any of the.**
279a0 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 above, then sqli
279b0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 te3_uri_boolean(
279c0 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 F,P,B) returns (
279d0 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 B!=0)..**.** The
279e0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 sqlite3_uri_int
279f0 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 64(F,P,D) routin
27a00 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 e converts the v
27a10 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 alue of P into a
27a20 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 .** 64-bit signe
27a30 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 d integer and re
27a40 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 turns that integ
27a50 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f er, or D if P do
27a60 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e es not.** exist.
27a70 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f If the value o
27a80 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 f P is something
27a90 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 other than an i
27aa0 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 nteger, then.**
27ab0 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 zero is returned
27ac0 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 ..** .** If F is
27ad0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
27ae0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 then sqlite3_ur
27af0 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 i_parameter(F,P)
27b00 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e returns NULL an
27b10 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 d.** sqlite3_uri
27b20 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 _boolean(F,P,B)
27b30 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 returns B. If F
27b40 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 is not a NULL p
27b50 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 ointer and.** is
27b60 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 not a database
27b70 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f file pathname po
27b80 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 inter that SQLit
27b90 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 e passed into th
27ba0 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d e xOpen.** VFS m
27bb0 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 ethod, then the
27bc0 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 behavior of this
27bd0 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 routine is unde
27be0 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 fined and probab
27bf0 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c ly.** undesirabl
27c00 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 e..*/.const char
27c10 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 *sqlite3_uri_pa
27c20 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 rameter(const ch
27c30 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 ar *zFilename, c
27c40 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 onst char *zPara
27c50 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f m);.int sqlite3_
27c60 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 uri_boolean(cons
27c70 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 t char *zFile, c
27c80 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 onst char *zPara
27c90 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 m, int bDefault)
27ca0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 ;.sqlite3_int64
27cb0 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 sqlite3_uri_int6
27cc0 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 4(const char*, c
27cd0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 onst char*, sqli
27ce0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a te3_int64);.../*
27cf0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 .** CAPI3REF: Er
27d00 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 ror Codes And Me
27d10 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 ssages.** METHOD
27d20 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
27d30 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 ^If the most rec
27d40 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 ent sqlite3_* AP
27d50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 I call associate
27d60 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 d with .** [data
27d70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
27d80 20 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 D failed, then
27d90 74 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 the sqlite3_errc
27da0 6f 64 65 28 44 29 20 69 6e 74 65 72 66 61 63 65 ode(D) interface
27db0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 .** returns the
27dc0 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 numeric [result
27dd0 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 code] or [extend
27de0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 ed result code]
27df0 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 for that.** API
27e00 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20 call..** If the
27e10 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 most recent API
27e20 63 61 6c 6c 20 77 61 73 20 73 75 63 63 65 73 73 call was success
27e30 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ful,.** then the
27e40 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 return value fr
27e50 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f om sqlite3_errco
27e60 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 de() is undefine
27e70 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 d..** ^The sqlit
27e80 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 e3_extended_errc
27e90 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 ode().** interfa
27ea0 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 ce is the same e
27eb0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c xcept that it al
27ec0 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 ways returns the
27ed0 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 .** [extended r
27ee0 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e esult code] even
27ef0 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 when extended r
27f00 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a esult codes are.
27f10 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a ** disabled..**.
27f20 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
27f30 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c errmsg() and sql
27f40 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 ite3_errmsg16()
27f50 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c return English-l
27f60 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 anguage.** text
27f70 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 that describes t
27f80 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 he error, as eit
27f90 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 her UTF-8 or UTF
27fa0 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 -16 respectively
27fb0 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f ..** ^(Memory to
27fc0 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 hold the error
27fd0 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 message string i
27fe0 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e s managed intern
27ff0 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 ally..** The app
28000 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f lication does no
28010 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 t need to worry
28020 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 about freeing th
28030 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 e result..** How
28040 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 ever, the error
28050 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 string might be
28060 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 overwritten or d
28070 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a eallocated by.**
28080 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
28090 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 s to other SQLit
280a0 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 e interface func
280b0 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e tions.)^.**.** ^
280c0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 The sqlite3_errs
280d0 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 tr() interface r
280e0 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 eturns the Engli
280f0 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 sh-language text
28100 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 .** that describ
28110 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 es the [result c
28120 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a ode], as UTF-8..
28130 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 ** ^(Memory to h
28140 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 old the error me
28150 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 ssage string is
28160 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c managed internal
28170 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e ly.** and must n
28180 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74 ot be freed by t
28190 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e he application)^
281a0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 ..**.** When the
281b0 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 serialized [thr
281c0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 eading mode] is
281d0 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 in use, it might
281e0 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 be the.** case
281f0 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 that a second er
28200 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 ror occurs on a
28210 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 separate thread
28220 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 in between.** th
28230 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 e time of the fi
28240 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 rst error and th
28250 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 e call to these
28260 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 interfaces..** W
28270 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 hen that happens
28280 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 , the second err
28290 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 or will be repor
282a0 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a ted since these.
282b0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c ** interfaces al
282c0 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 ways report the
282d0 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 most recent resu
282e0 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a lt. To avoid.**
282f0 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 this, each thre
28300 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 ad can obtain ex
28310 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 clusive use of t
28320 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
28330 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 nection] D.** by
28340 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 invoking [sqlit
28350 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 e3_mutex_enter](
28360 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 [sqlite3_db_mute
28370 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 x](D)) before be
28380 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 ginning.** to us
28390 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 e D and invoking
283a0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
283b0 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f leave]([sqlite3_
283c0 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 db_mutex](D)) af
283d0 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 ter.** all calls
283e0 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 to the interfac
283f0 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 es listed here a
28400 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a re completed..**
28410 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 .** If an interf
28420 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 ace fails with S
28430 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 QLITE_MISUSE, th
28440 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 at means the int
28450 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e erface.** was in
28460 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c voked incorrectl
28470 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 y by the applica
28480 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 tion. In that c
28490 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f ase, the.** erro
284a0 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 r code and messa
284b0 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f ge may or may no
284c0 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 t be set..*/.int
284d0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 sqlite3_errcode
284e0 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 (sqlite3 *db);.i
284f0 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e nt sqlite3_exten
28500 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 ded_errcode(sqli
28510 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 te3 *db);.const
28520 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 char *sqlite3_er
28530 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a rmsg(sqlite3*);.
28540 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
28550 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c te3_errmsg16(sql
28560 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 ite3*);.const ch
28570 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 ar *sqlite3_errs
28580 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 tr(int);../*.**
28590 43 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 CAPI3REF: Prepar
285a0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a ed Statement Obj
285b0 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ect.** KEYWORDS:
285c0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 {prepared state
285d0 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 ment} {prepared
285e0 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a statements}.**.*
285f0 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 * An instance of
28600 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 this object rep
28610 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 resents a single
28620 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
28630 68 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 hat.** has been
28640 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62 69 compiled into bi
28650 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 69 73 nary form and is
28660 20 72 65 61 64 79 20 74 6f 20 62 65 20 65 76 61 ready to be eva
28670 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 luated..**.** Th
28680 69 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 4c 20 ink of each SQL
28690 73 74 61 74 65 6d 65 6e 74 20 61 73 20 61 20 73 statement as a s
286a0 65 70 61 72 61 74 65 20 63 6f 6d 70 75 74 65 72 eparate computer
286b0 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a program. The.*
286c0 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 * original SQL t
286d0 65 78 74 20 69 73 20 73 6f 75 72 63 65 20 63 6f ext is source co
286e0 64 65 2e 20 20 41 20 70 72 65 70 61 72 65 64 20 de. A prepared
286f0 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 statement object
28700 20 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d 70 .** is the comp
28710 69 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f 64 65 iled object code
28720 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20 . All SQL must
28730 62 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 be converted int
28740 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 o a.** prepared
28750 73 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72 65 statement before
28760 20 69 74 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a it can be run..
28770 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63 **.** The life-c
28780 79 63 6c 65 20 6f 66 20 61 20 70 72 65 70 61 72 ycle of a prepar
28790 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a ed statement obj
287a0 65 63 74 20 75 73 75 61 6c 6c 79 20 67 6f 65 73 ect usually goes
287b0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a like this:.**.*
287c0 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 * <ol>.** <li> C
287d0 72 65 61 74 65 20 74 68 65 20 70 72 65 70 61 72 reate the prepar
287e0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a ed statement obj
287f0 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ect using [sqlit
28800 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
28810 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 ..** <li> Bind v
28820 61 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 6d 65 alues to [parame
28830 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 ters] using the
28840 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 sqlite3_bind_*()
28850 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 .** interfa
28860 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e ces..** <li> Run
28870 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c the SQL by call
28880 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 ing [sqlite3_ste
28890 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 p()] one or more
288a0 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 times..** <li>
288b0 52 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 Reset the prepar
288c0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 ed statement usi
288d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ng [sqlite3_rese
288e0 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 t()] then go bac
288f0 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 k.** to ste
28900 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 p 2. Do this ze
28910 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 ro or more times
28920 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f ..** <li> Destro
28930 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 y the object usi
28940 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ng [sqlite3_fina
28950 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c lize()]..** </ol
28960 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 >.*/.typedef str
28970 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 uct sqlite3_stmt
28980 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a sqlite3_stmt;..
28990 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
289a0 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a Run-time Limits.
289b0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
289c0 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 e3.**.** ^(This
289d0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 interface allows
289e0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 the size of var
289f0 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 ious constructs
28a00 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a to be limited.**
28a10 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e on a connection
28a20 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 by connection b
28a30 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 asis. The first
28a40 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
28a50 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 e.** [database c
28a60 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 onnection] whose
28a70 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 limit is to be
28a80 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 set or queried.
28a90 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 The.** second p
28aa0 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 arameter is one
28ab0 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 of the [limit ca
28ac0 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 tegories] that d
28ad0 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 efine a.** class
28ae0 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 of constructs t
28af0 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 o be size limite
28b00 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 d. The third pa
28b10 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a rameter is the.*
28b20 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 * new limit for
28b30 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 that construct.)
28b40 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ^.**.** ^If the
28b50 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e new limit is a n
28b60 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 egative number,
28b70 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 the limit is unc
28b80 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 hanged..** ^(For
28b90 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 each limit cate
28ba0 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 gory SQLITE_LIMI
28bb0 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 T_<i>NAME</i> th
28bc0 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 ere is a .** [li
28bd0 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 mits | hard uppe
28be0 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 r bound].** set
28bf0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 at compile-time
28c00 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 by a C preproces
28c10 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 sor macro called
28c20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 .** [limits | SQ
28c30 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 LITE_MAX_<i>NAME
28c40 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 </i>]..** (The "
28c50 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 _LIMIT_" in the
28c60 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 name is changed
28c70 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a to "_MAX_".))^.*
28c80 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 * ^Attempts to i
28c90 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 ncrease a limit
28ca0 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 above its hard u
28cb0 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a pper bound are.*
28cc0 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 * silently trunc
28cd0 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 ated to the hard
28ce0 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a upper bound..**
28cf0 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 .** ^Regardless
28d00 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f of whether or no
28d10 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 t the limit was
28d20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a changed, the .**
28d30 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 [sqlite3_limit(
28d40 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 )] interface ret
28d50 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 urns the prior v
28d60 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 alue of the limi
28d70 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f t..** ^Hence, to
28d80 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e find the curren
28d90 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d t value of a lim
28da0 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 it without chang
28db0 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c ing it,.** simpl
28dc0 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e y invoke this in
28dd0 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65 terface with the
28de0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
28df0 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a set to -1..**.*
28e00 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 * Run-time limit
28e10 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 s are intended f
28e20 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 or use in applic
28e30 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 ations that mana
28e40 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 ge.** both their
28e50 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 own internal da
28e60 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 tabase and also
28e70 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 databases that a
28e80 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a re controlled.**
28e90 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 by untrusted ex
28ea0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 ternal sources.
28eb0 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c An example appl
28ec0 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 ication might be
28ed0 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 a.** web browse
28ee0 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f r that has its o
28ef0 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 wn databases for
28f00 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 storing history
28f10 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 and.** separate
28f20 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 databases contr
28f30 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 olled by JavaScr
28f40 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 ipt applications
28f50 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f downloaded.** o
28f60 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e ff the Internet.
28f70 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 The internal d
28f80 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 atabases can be
28f90 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 given the.** lar
28fa0 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 ge, default limi
28fb0 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d ts. Databases m
28fc0 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e anaged by extern
28fd0 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a al sources can.*
28fe0 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 * be given much
28ff0 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 smaller limits d
29000 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 esigned to preve
29010 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 nt a denial of s
29020 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b ervice.** attack
29030 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 . Developers mi
29040 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f ght also want to
29050 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 use the [sqlite
29060 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
29070 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 ()].** interface
29080 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 to further cont
29090 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 rol untrusted SQ
290a0 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 L. The size of
290b0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 the database.**
290c0 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e created by an un
290d0 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 trusted script c
290e0 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 an be contained
290f0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 using the.** [ma
29100 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 x_page_count] [P
29110 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 RAGMA]..**.** Ne
29120 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 w run-time limit
29130 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 categories may
29140 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 be added in futu
29150 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a re releases..*/.
29160 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 int sqlite3_limi
29170 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 t(sqlite3*, int
29180 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b id, int newVal);
29190 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
291a0 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 : Run-Time Limit
291b0 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b Categories.** K
291c0 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 EYWORDS: {limit
291d0 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 category} {*limi
291e0 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a t categories}.**
291f0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
29200 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f nts define vario
29210 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c us performance l
29220 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 imits.** that ca
29230 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 n be lowered at
29240 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b run-time using [
29250 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d sqlite3_limit()]
29260 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 ..** The synopsi
29270 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 s of the meaning
29280 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 s of the various
29290 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e limits is shown
292a0 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 below..** Addit
292b0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f ional informatio
292c0 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 n is available a
292d0 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 t [limits | Limi
292e0 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a ts in SQLite]..*
292f0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 *.** <dl>.** [[S
29300 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 QLITE_LIMIT_LENG
29310 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 TH]] ^(<dt>SQLIT
29320 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f E_LIMIT_LENGTH</
29330 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
29340 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 aximum size of a
29350 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f ny string or BLO
29360 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 B or table row,
29370 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a in bytes.<dd>)^.
29380 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
29390 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d IMIT_SQL_LENGTH]
293a0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
293b0 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c IMIT_SQL_LENGTH<
293c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
293d0 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f maximum length o
293e0 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 f an SQL stateme
293f0 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 nt, in bytes.</d
29400 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d>)^.**.** [[SQL
29410 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e ITE_LIMIT_COLUMN
29420 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ]] ^(<dt>SQLITE_
29430 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 LIMIT_COLUMN</dt
29440 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
29450 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 imum number of c
29460 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c olumns in a tabl
29470 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 e definition or
29480 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 in the.** result
29490 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 set of a [SELEC
294a0 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 T] or the maximu
294b0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 m number of colu
294c0 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a mns in an index.
294d0 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 ** or in an ORDE
294e0 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 R BY or GROUP BY
294f0 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a clause.</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 45 58 50 52 5f 44 45 50 54 48 5d IMIT_EXPR_DEPTH]
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 45 58 50 52 5f 44 45 50 54 48 3c IMIT_EXPR_DEPTH<
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 64 65 70 74 68 20 6f 66 maximum depth of
29560 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 the parse tree
29570 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f on any expressio
29580 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 n.</dd>)^.**.**
29590 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 [[SQLITE_LIMIT_C
295a0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d OMPOUND_SELECT]]
295b0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
295c0 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c MIT_COMPOUND_SEL
295d0 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ECT</dt>.** <dd>
295e0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
295f0 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 er of terms in a
29600 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 compound SELECT
29610 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e statement.</dd>
29620 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
29630 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d E_LIMIT_VDBE_OP]
29640 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
29650 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 IMIT_VDBE_OP</dt
29660 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
29670 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 imum number of i
29680 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 nstructions in a
29690 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 virtual machine
296a0 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 program.** used
296b0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e to implement an
296c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 SQL statement.
296d0 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 If [sqlite3_pre
296e0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a pare_v2()] or.**
296f0 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 the equivalent
29700 74 72 69 65 73 20 74 6f 20 61 6c 6c 6f 63 61 74 tries to allocat
29710 65 20 73 70 61 63 65 20 66 6f 72 20 6d 6f 72 65 e space for more
29720 20 74 68 61 6e 20 74 68 69 73 20 6d 61 6e 79 20 than this many
29730 6f 70 63 6f 64 65 73 0a 2a 2a 20 69 6e 20 61 20 opcodes.** in a
29740 73 69 6e 67 6c 65 20 70 72 65 70 61 72 65 64 20 single prepared
29750 73 74 61 74 65 6d 65 6e 74 2c 20 61 6e 20 53 51 statement, an SQ
29760 4c 49 54 45 5f 4e 4f 4d 45 4d 20 65 72 72 6f 72 LITE_NOMEM error
29770 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
29780 20 41 20 76 61 6c 75 65 20 6f 66 20 30 20 6d 65 A value of 0 me
29790 61 6e 73 20 22 75 6e 6c 69 6d 69 74 65 64 22 2e ans "unlimited".
297a0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b </dd>)^.**.** [[
297b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e SQLITE_LIMIT_FUN
297c0 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 CTION_ARG]] ^(<d
297d0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 t>SQLITE_LIMIT_F
297e0 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e UNCTION_ARG</dt>
297f0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
29800 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 mum number of ar
29810 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e guments on a fun
29820 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a ction.</dd>)^.**
29830 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d .** [[SQLITE_LIM
29840 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 IT_ATTACHED]] ^(
29850 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
29860 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a _ATTACHED</dt>.*
29870 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
29880 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 m number of [ATT
29890 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 ACH | attached d
298a0 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 atabases].)^</dd
298b0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
298c0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 _LIMIT_LIKE_PATT
298d0 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 ERN_LENGTH]].**
298e0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
298f0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f IT_LIKE_PATTERN_
29900 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c LENGTH</dt>.** <
29910 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c dd>The maximum l
29920 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 ength of the pat
29930 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f tern argument to
29940 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a the [LIKE] or.*
29950 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f * [GLOB] operato
29960 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a rs.</dd>)^.**.**
29970 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
29980 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d VARIABLE_NUMBER]
29990 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 ].** ^(<dt>SQLIT
299a0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 E_LIMIT_VARIABLE
299b0 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 _NUMBER</dt>.**
299c0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
299d0 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 index number of
299e0 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 any [parameter]
299f0 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d in an SQL statem
29a00 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 ent.)^.**.** [[S
29a10 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 QLITE_LIMIT_TRIG
29a20 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 GER_DEPTH]] ^(<d
29a30 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 t>SQLITE_LIMIT_T
29a40 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 RIGGER_DEPTH</dt
29a50 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
29a60 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 imum depth of re
29a70 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 cursion for trig
29a80 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a gers.</dd>)^.**.
29a90 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
29aa0 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 T_WORKER_THREADS
29ab0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ]] ^(<dt>SQLITE_
29ac0 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 LIMIT_WORKER_THR
29ad0 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 EADS</dt>.** <dd
29ae0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d >The maximum num
29af0 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79 ber of auxiliary
29b00 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20 worker threads
29b10 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a that a single.**
29b20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
29b30 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e ment] may start.
29b40 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e </dd>)^.** </dl>
29b50 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
29b60 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 TE_LIMIT_LENGTH
29b70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
29b80 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0.#define SQL
29b90 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 ITE_LIMIT_SQL_LE
29ba0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 NGTH
29bb0 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 1.#define SQ
29bc0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d LITE_LIMIT_COLUM
29bd0 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 N
29be0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 2.#define S
29bf0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 QLITE_LIMIT_EXPR
29c00 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 _DEPTH
29c10 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 3.#define
29c20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d SQLITE_LIMIT_COM
29c30 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 POUND_SELECT
29c40 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 4.#define
29c50 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 SQLITE_LIMIT_VD
29c60 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 BE_OP
29c70 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 5.#defin
29c80 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 e SQLITE_LIMIT_F
29c90 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 UNCTION_ARG
29ca0 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6.#defi
29cb0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
29cc0 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 ATTACHED
29cd0 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 7.#def
29ce0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
29cf0 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 _LIKE_PATTERN_LE
29d00 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 NGTH 8.#de
29d10 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
29d20 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 T_VARIABLE_NUMBE
29d30 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 R 9.#d
29d40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
29d50 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 IT_TRIGGER_DEPTH
29d60 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 10.#
29d70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
29d80 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 MIT_WORKER_THREA
29d90 44 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a DS 11.
29da0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
29db0 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 : Compiling An S
29dc0 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 QL Statement.**
29dd0 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 KEYWORDS: {SQL s
29de0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 tatement compile
29df0 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 r}.** METHOD: sq
29e00 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 lite3.** CONSTRU
29e10 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 CTOR: sqlite3_st
29e20 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 mt.**.** To exec
29e30 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 ute an SQL query
29e40 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 , it must first
29e50 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f be compiled into
29e60 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 a byte-code.**
29e70 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e program using on
29e80 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 e of these routi
29e90 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 nes..**.** The f
29ea0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 irst argument, "
29eb0 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 db", is a [datab
29ec0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
29ed0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a obtained from a.
29ee0 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 ** prior success
29ef0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ful call to [sql
29f00 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 ite3_open()], [s
29f10 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
29f20 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ] or.** [sqlite3
29f30 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 _open16()]. The
29f40 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
29f50 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 tion must not ha
29f60 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a ve been closed..
29f70 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 **.** The second
29f80 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c argument, "zSql
29f90 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d ", is the statem
29fa0 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c ent to be compil
29fb0 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 ed, encoded.** a
29fc0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f s either UTF-8 o
29fd0 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 r UTF-16. The s
29fe0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
29ff0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 and sqlite3_pre
2a000 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 pare_v2().** int
2a010 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d erfaces use UTF-
2a020 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 8, and sqlite3_p
2a030 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 repare16() and s
2a040 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
2a050 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 _v2().** use UTF
2a060 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 -16..**.** ^If t
2a070 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e he nByte argumen
2a080 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 t is negative, t
2a090 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 hen zSql is read
2a0a0 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 up to the.** fi
2a0b0 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 rst zero termina
2a0c0 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 tor. ^If nByte i
2a0d0 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e s positive, then
2a0e0 20 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 it is the.** nu
2a0f0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 72 65 mber of bytes re
2a100 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e ad from zSql. ^
2a110 49 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f If nByte is zero
2a120 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 , then no prepar
2a130 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 ed.** statement
2a140 69 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a is generated..**
2a150 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b If the caller k
2a160 6e 6f 77 73 20 74 68 61 74 20 74 68 65 20 73 75 nows that the su
2a170 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 pplied string is
2a180 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c nul-terminated,
2a190 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 then.** there i
2a1a0 73 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 s a small perfor
2a1b0 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 mance advantage
2a1c0 74 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 to passing an nB
2a1d0 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 yte parameter th
2a1e0 61 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d at.** is the num
2a1f0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 ber of bytes in
2a200 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 the input string
2a210 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 <i>including</i
2a220 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 >.** the nul-ter
2a230 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e minator..**.** ^
2a240 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 If pzTail is not
2a250 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 NULL then *pzTa
2a260 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f il is made to po
2a270 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 int to the first
2a280 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 byte.** past th
2a290 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 e end of the fir
2a2a0 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 st SQL statement
2a2b0 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 in zSql. These
2a2c0 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a routines only.*
2a2d0 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 * compile the fi
2a2e0 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e rst statement in
2a2f0 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 zSql, so *pzTai
2a300 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 l is left pointi
2a310 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 ng to.** what re
2a320 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 mains uncompiled
2a330 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 ..**.** ^*ppStmt
2a340 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e is left pointin
2a350 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 g to a compiled
2a360 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2a370 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 ent] that can be
2a380 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 .** executed usi
2a390 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ng [sqlite3_step
2a3a0 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 ()]. ^If there
2a3b0 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 is an error, *pp
2a3c0 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 Stmt is set.** t
2a3d0 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 o NULL. ^If the
2a3e0 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 input text cont
2a3f0 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 ains no SQL (if
2a400 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 the input is an
2a410 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 empty.** string
2a420 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 or a comment) th
2a430 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 en *ppStmt is se
2a440 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 t to NULL..** Th
2a450 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 e calling proced
2a460 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 ure is responsib
2a470 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 le for deleting
2a480 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 the compiled.**
2a490 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 SQL statement us
2a4a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e ing [sqlite3_fin
2a4b0 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 alize()] after i
2a4c0 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 t has finished w
2a4d0 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d ith it..** ppStm
2a4e0 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c t may not be NUL
2a4f0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 L..**.** ^On suc
2a500 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 cess, the sqlite
2a510 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 3_prepare() fami
2a520 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 ly of routines r
2a530 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b eturn [SQLITE_OK
2a540 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 ];.** otherwise
2a550 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 an [error code]
2a560 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
2a570 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 ** The sqlite3_p
2a580 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 repare_v2() and
2a590 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
2a5a0 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 6_v2() interface
2a5b0 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 s are.** recomme
2a5c0 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 nded for all new
2a5d0 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 programs. The t
2a5e0 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 wo older interfa
2a5f0 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 ces are retained
2a600 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 .** for backward
2a610 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c s compatibility,
2a620 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 but their use i
2a630 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a s discouraged..*
2a640 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 * ^In the "v2" i
2a650 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 nterfaces, the p
2a660 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2a670 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 t.** that is ret
2a680 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 urned (the [sqli
2a690 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 te3_stmt] object
2a6a0 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 ) contains a cop
2a6b0 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 y of the.** orig
2a6c0 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 inal SQL text. T
2a6d0 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b his causes the [
2a6e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
2a6f0 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 interface to.**
2a700 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 behave different
2a710 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 ly in three ways
2a720 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 :.**.** <ol>.**
2a730 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 <li>.** ^If the
2a740 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 database schema
2a750 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 changes, instead
2a760 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 of returning [S
2a770 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 QLITE_SCHEMA] as
2a780 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 it.** always us
2a790 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 ed to do, [sqlit
2a7a0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 e3_step()] will
2a7b0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 automatically re
2a7c0 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a compile the SQL.
2a7d0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 ** statement and
2a7e0 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 try to run it a
2a7f0 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 gain. As many as
2a800 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 [SQLITE_MAX_SCH
2a810 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 EMA_RETRY].** re
2a820 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 tries will occur
2a830 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f before sqlite3_
2a840 73 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20 step() gives up
2a850 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 and returns an e
2a860 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a rror..** </li>.*
2a870 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 *.** <li>.** ^Wh
2a880 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 en an error occu
2a890 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 rs, [sqlite3_ste
2a8a0 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e p()] will return
2a8b0 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 one of the deta
2a8c0 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 iled.** [error c
2a8d0 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 odes] or [extend
2a8e0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e ed error codes].
2a8f0 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 ^The legacy be
2a900 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a havior was that.
2a910 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ** [sqlite3_step
2a920 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 ()] would only r
2a930 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 eturn a generic
2a940 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 [SQLITE_ERROR] r
2a950 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e esult code.** an
2a960 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f d the applicatio
2a970 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 n would have to
2a980 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 make a second ca
2a990 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 ll to [sqlite3_r
2a9a0 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 eset()].** in or
2a9b0 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 der to find the
2a9c0 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 underlying cause
2a9d0 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e of the problem.
2a9e0 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 With the "v2" p
2a9f0 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 repare.** interf
2aa00 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c aces, the underl
2aa10 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 ying reason for
2aa20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 the error is ret
2aa30 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c urned immediatel
2aa40 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a y..** </li>.**.*
2aa50 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 * <li>.** ^If th
2aa60 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 e specific value
2aa70 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d bound to [param
2aa80 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 eter | host para
2aa90 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a meter] in the .*
2aaa0 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d * WHERE clause m
2aab0 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 ight influence t
2aac0 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 he choice of que
2aad0 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 ry plan for a st
2aae0 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e atement,.** then
2aaf0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 the statement w
2ab00 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 ill be automatic
2ab10 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c ally recompiled,
2ab20 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64 as if there had
2ab30 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 been .** a sche
2ab40 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 ma change, on th
2ab50 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 e first [sqlite
2ab60 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 3_step()] call f
2ab70 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 ollowing any cha
2ab80 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 nge.** to the [s
2ab90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
2aba0 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 | bindings] of
2abb0 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d that [parameter]
2abc0 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 . .** ^The speci
2abd0 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 fic value of WHE
2abe0 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d RE-clause [param
2abf0 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c eter] might infl
2ac00 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 uence the .** ch
2ac10 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c oice of query pl
2ac20 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 an if the parame
2ac30 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d ter is the left-
2ac40 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b hand side of a [
2ac50 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f LIKE].** or [GLO
2ac60 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 B] operator or i
2ac70 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 f the parameter
2ac80 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 is compared to a
2ac90 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e n indexed column
2aca0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c .** and the [SQL
2acb0 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 ITE_ENABLE_STAT3
2acc0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
2acd0 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 ption is enabled
2ace0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f ..** </li>.** </
2acf0 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ol>.*/.int sqlit
2ad00 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 e3_prepare(. sq
2ad10 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
2ad20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 /* Databas
2ad30 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f e handle */. co
2ad40 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 nst char *zSql,
2ad50 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 /* SQL sta
2ad60 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e tement, UTF-8 en
2ad70 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e coded */. int n
2ad80 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 Byte,
2ad90 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 /* Maximum le
2ada0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 ngth of zSql in
2adb0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 bytes. */. sqli
2adc0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d te3_stmt **ppStm
2add0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 t, /* OUT: Stat
2ade0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a ement handle */.
2adf0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 const char **p
2ae00 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 zTail /* OUT
2ae10 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 : Pointer to unu
2ae20 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a sed portion of z
2ae30 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 Sql */.);.int sq
2ae40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
2ae50 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
2ae60 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 /* D
2ae70 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a atabase handle *
2ae80 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
2ae90 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 zSql, /* S
2aea0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 QL statement, UT
2aeb0 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 F-8 encoded */.
2aec0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 int nByte,
2aed0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 /* Maxi
2aee0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 mum length of zS
2aef0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a ql in bytes. */.
2af00 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a sqlite3_stmt *
2af10 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 *ppStmt, /* OUT
2af20 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 : Statement hand
2af30 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 le */. const ch
2af40 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 ar **pzTail
2af50 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 /* OUT: Pointer
2af60 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f to unused portio
2af70 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a n of zSql */.);.
2af80 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 int sqlite3_prep
2af90 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 are16(. sqlite3
2afa0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
2afb0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e /* Database han
2afc0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 dle */. const v
2afd0 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 oid *zSql,
2afe0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e /* SQL statemen
2aff0 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 t, UTF-16 encode
2b000 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 d */. int nByte
2b010 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
2b020 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 * Maximum length
2b030 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 of zSql in byte
2b040 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f s. */. sqlite3_
2b050 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 stmt **ppStmt,
2b060 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e /* OUT: Statemen
2b070 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f t handle */. co
2b080 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 nst void **pzTai
2b090 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f l /* OUT: Po
2b0a0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 inter to unused
2b0b0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 portion of zSql
2b0c0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 */.);.int sqlite
2b0d0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 3_prepare16_v2(.
2b0e0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
2b0f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
2b100 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a abase handle */.
2b110 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 const void *zS
2b120 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c ql, /* SQL
2b130 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d statement, UTF-
2b140 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 16 encoded */.
2b150 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 int nByte,
2b160 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d /* Maxim
2b170 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 um length of zSq
2b180 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 l in bytes. */.
2b190 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a sqlite3_stmt **
2b1a0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a ppStmt, /* OUT:
2b1b0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c Statement handl
2b1c0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 e */. const voi
2b1d0 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f d **pzTail /
2b1e0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 * OUT: Pointer t
2b1f0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e o unused portion
2b200 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a of zSql */.);..
2b210 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2b220 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 Retrieving State
2b230 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 ment SQL.** METH
2b240 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 OD: sqlite3_stmt
2b250 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2b260 74 65 33 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 te3_sql(P) inter
2b270 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 face returns a p
2b280 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 70 79 ointer to a copy
2b290 20 6f 66 20 74 68 65 20 55 54 46 2d 38 0a 2a 2a of the UTF-8.**
2b2a0 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 SQL text used t
2b2b0 6f 20 63 72 65 61 74 65 20 5b 70 72 65 70 61 72 o create [prepar
2b2c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 20 ed statement] P
2b2d0 69 66 20 50 20 77 61 73 0a 2a 2a 20 63 72 65 61 if P was.** crea
2b2e0 74 65 64 20 62 79 20 65 69 74 68 65 72 20 5b 73 ted by either [s
2b2f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
2b300 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 2()] or [sqlite3
2b310 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
2b320 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 ..** ^The sqlite
2b330 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 3_expanded_sql(P
2b340 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
2b350 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
2b360 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 a UTF-8.** stri
2b370 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 ng containing th
2b380 65 20 53 51 4c 20 74 65 78 74 20 6f 66 20 70 72 e SQL text of pr
2b390 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2b3a0 20 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e P with.** [boun
2b3b0 64 20 70 61 72 61 6d 65 74 65 72 73 5d 20 65 78 d parameters] ex
2b3c0 70 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 panded..**.** ^(
2b3d0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 For example, if
2b3e0 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 a prepared state
2b3f0 6d 65 6e 74 20 69 73 20 63 72 65 61 74 65 64 20 ment is created
2b400 75 73 69 6e 67 20 74 68 65 20 53 51 4c 0a 2a 2a using the SQL.**
2b410 20 74 65 78 74 20 22 53 45 4c 45 43 54 20 24 61 text "SELECT $a
2b420 62 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69 66 20 bc,:xyz" and if
2b430 70 61 72 61 6d 65 74 65 72 20 24 61 62 63 20 69 parameter $abc i
2b440 73 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74 65 67 s bound to integ
2b450 65 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64 20 70 er 2345.** and p
2b460 61 72 61 6d 65 74 65 72 20 3a 78 79 7a 20 69 73 arameter :xyz is
2b470 20 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e 20 73 unbound, then s
2b480 71 6c 69 74 65 33 5f 73 71 6c 28 29 20 77 69 6c qlite3_sql() wil
2b490 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 l return.** the
2b4a0 6f 72 69 67 69 6e 61 6c 20 73 74 72 69 6e 67 2c original string,
2b4b0 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 "SELECT $abc,:x
2b4c0 79 7a 22 20 62 75 74 20 73 71 6c 69 74 65 33 5f yz" but sqlite3_
2b4d0 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 0a 2a expanded_sql().*
2b4e0 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 22 53 * will return "S
2b4f0 45 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c 4c 22 ELECT 2345,NULL"
2b500 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 .)^.**.** ^The s
2b510 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f qlite3_expanded_
2b520 73 71 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 sql() interface
2b530 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 returns NULL if
2b540 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d insufficient mem
2b550 6f 72 79 0a 2a 2a 20 69 73 20 61 76 61 69 6c 61 ory.** is availa
2b560 62 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 ble to hold the
2b570 72 65 73 75 6c 74 2c 20 6f 72 20 69 66 20 74 68 result, or if th
2b580 65 20 72 65 73 75 6c 74 20 77 6f 75 6c 64 20 65 e result would e
2b590 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 74 68 65 xceed the.** the
2b5a0 20 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e 67 20 maximum string
2b5b0 6c 65 6e 67 74 68 20 64 65 74 65 72 6d 69 6e 65 length determine
2b5c0 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 d by the [SQLITE
2b5d0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a _LIMIT_LENGTH]..
2b5e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 **.** ^The [SQLI
2b5f0 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 TE_TRACE_SIZE_LI
2b600 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d MIT] compile-tim
2b610 65 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74 73 20 e option limits
2b620 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 62 the size of.** b
2b630 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 20 65 ound parameter e
2b640 78 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54 68 65 xpansions. ^The
2b650 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 [SQLITE_OMIT_TR
2b660 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d ACE] compile-tim
2b670 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61 75 73 e.** option caus
2b680 65 73 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e es sqlite3_expan
2b690 64 65 64 5f 73 71 6c 28 29 20 74 6f 20 61 6c 77 ded_sql() to alw
2b6a0 61 79 73 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e ays return NULL.
2b6b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 .**.** ^The stri
2b6c0 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ng returned by s
2b6d0 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 73 qlite3_sql(P) is
2b6e0 20 6d 61 6e 61 67 65 64 20 62 79 20 53 51 4c 69 managed by SQLi
2b6f0 74 65 20 61 6e 64 20 69 73 0a 2a 2a 20 61 75 74 te and is.** aut
2b700 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 64 omatically freed
2b710 20 77 68 65 6e 20 74 68 65 20 70 72 65 70 61 72 when the prepar
2b720 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 ed statement is
2b730 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54 finalized..** ^T
2b740 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e he string return
2b750 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 65 78 ed by sqlite3_ex
2b760 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20 6f panded_sql(P), o
2b770 6e 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e 64 n the other hand
2b780 2c 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65 64 ,.** is obtained
2b790 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
2b7a0 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75 73 alloc()] and mus
2b7b0 74 20 62 65 20 66 72 65 65 20 62 79 20 74 68 65 t be free by the
2b7c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 application.**
2b7d0 62 79 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f by passing it to
2b7e0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
2b7f0 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 ]..*/.const char
2b800 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 *sqlite3_sql(sq
2b810 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d lite3_stmt *pStm
2b820 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 t);.char *sqlite
2b830 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 73 3_expanded_sql(s
2b840 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
2b850 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
2b860 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 3REF: Determine
2b870 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d If An SQL Statem
2b880 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44 ent Writes The D
2b890 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f atabase.** METHO
2b8a0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a D: sqlite3_stmt.
2b8b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2b8c0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 e3_stmt_readonly
2b8d0 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 (X) interface re
2b8e0 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d turns true (non-
2b8f0 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 zero) if.** and
2b900 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 only if the [pre
2b910 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2b920 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 X makes no dire
2b930 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a ct changes to.**
2b940 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
2b950 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
2b960 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 e..**.** Note th
2b970 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d at [application-
2b980 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
2b990 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 tions] or.** [vi
2b9a0 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 rtual tables] mi
2b9b0 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 ght change the d
2b9c0 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 atabase indirect
2b9d0 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66 ly as a side eff
2b9e0 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 ect. .** ^(For
2b9f0 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 example, if an a
2ba00 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e pplication defin
2ba10 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 es a function "e
2ba20 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 val()" that .**
2ba30 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 calls [sqlite3_e
2ba40 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 xec()], then the
2ba50 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 following SQL s
2ba60 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a tatement would.*
2ba70 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 * change the dat
2ba80 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 abase file throu
2ba90 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a gh side-effects:
2baa0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
2bab0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 te><pre>.** S
2bac0 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 ELECT eval('DELE
2bad0 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f TE FROM t1') FRO
2bae0 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c M t2;.** </pre><
2baf0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
2bb00 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74 ** But because t
2bb10 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 he [SELECT] stat
2bb20 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 ement does not c
2bb30 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 hange the databa
2bb40 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 se file.** direc
2bb50 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d tly, sqlite3_stm
2bb60 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 t_readonly() wou
2bb70 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 ld still return
2bb80 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 true.)^.**.** ^T
2bb90 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 ransaction contr
2bba0 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 ol statements su
2bbb0 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b ch as [BEGIN], [
2bbc0 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 COMMIT], [ROLLBA
2bbd0 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 CK],.** [SAVEPOI
2bbe0 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 NT], and [RELEAS
2bbf0 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 E] cause sqlite3
2bc00 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 _stmt_readonly()
2bc10 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c to return true,
2bc20 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 .** since the st
2bc30 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c atements themsel
2bc40 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 ves do not actua
2bc50 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 lly modify the d
2bc60 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 atabase but.** r
2bc70 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 ather they contr
2bc80 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 ol the timing of
2bc90 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 when other stat
2bca0 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 ements modify th
2bcb0 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 e .** database.
2bcc0 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 ^The [ATTACH] a
2bcd0 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 nd [DETACH] stat
2bce0 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 ements also caus
2bcf0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d e.** sqlite3_stm
2bd00 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 t_readonly() to
2bd10 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 return true sinc
2bd20 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 e, while those s
2bd30 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 tatements.** cha
2bd40 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 nge the configur
2bd50 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 ation of a datab
2bd60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 ase connection,
2bd70 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 they do not make
2bd80 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 .** changes to
2bd90 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 the content of t
2bda0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
2bdb0 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e 54 s on disk..** ^T
2bdc0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f he sqlite3_stmt_
2bdd0 72 65 61 64 6f 6e 6c 79 28 29 20 69 6e 74 65 72 readonly() inter
2bde0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 face returns tru
2bdf0 65 20 66 6f 72 20 5b 42 45 47 49 4e 5d 20 73 69 e for [BEGIN] si
2be00 6e 63 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20 6d nce.** [BEGIN] m
2be10 65 72 65 6c 79 20 73 65 74 73 20 69 6e 74 65 72 erely sets inter
2be20 6e 61 6c 20 66 6c 61 67 73 2c 20 62 75 74 20 74 nal flags, but t
2be30 68 65 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 he [BEGIN|BEGIN
2be40 49 4d 4d 45 44 49 41 54 45 5d 20 61 6e 64 0a 2a IMMEDIATE] and.*
2be50 2a 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 45 * [BEGIN|BEGIN E
2be60 58 43 4c 55 53 49 56 45 5d 20 63 6f 6d 6d 61 6e XCLUSIVE] comman
2be70 64 73 20 64 6f 20 74 6f 75 63 68 20 74 68 65 20 ds do touch the
2be80 64 61 74 61 62 61 73 65 20 61 6e 64 20 73 6f 0a database and so.
2be90 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f ** sqlite3_stmt_
2bea0 72 65 61 64 6f 6e 6c 79 28 29 20 72 65 74 75 72 readonly() retur
2beb0 6e 73 20 66 61 6c 73 65 20 66 6f 72 20 74 68 6f ns false for tho
2bec0 73 65 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a se commands..*/.
2bed0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 int sqlite3_stmt
2bee0 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 _readonly(sqlite
2bef0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
2bf00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2bf10 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 Determine If A
2bf20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 Prepared Stateme
2bf30 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 nt Has Been Rese
2bf40 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c t.** METHOD: sql
2bf50 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
2bf60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d ^The sqlite3_stm
2bf70 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 t_busy(S) interf
2bf80 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 ace returns true
2bf90 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 (non-zero) if t
2bfa0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 he.** [prepared
2bfb0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 statement] S has
2bfc0 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 been stepped at
2bfd0 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e least once usin
2bfe0 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 g .** [sqlite3_s
2bff0 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 tep(S)] but has
2c000 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20 63 neither run to c
2c010 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75 72 ompletion (retur
2c020 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 ned.** [SQLITE_D
2c030 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74 ONE] from [sqlit
2c040 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f 72 e3_step(S)]) nor
2c050 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 .** been reset u
2c060 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 sing [sqlite3_re
2c070 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 set(S)]. ^The s
2c080 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 qlite3_stmt_busy
2c090 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 (S).** interface
2c0a0 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 returns false i
2c0b0 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f f S is a NULL po
2c0c0 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 inter. If S is
2c0d0 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 not a .** NULL p
2c0e0 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f ointer and is no
2c0f0 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 t a pointer to a
2c100 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 valid [prepared
2c110 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f statement].** o
2c120 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 bject, then the
2c130 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 behavior is unde
2c140 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 fined and probab
2c150 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a ly undesirable..
2c160 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 **.** This inter
2c170 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 face can be used
2c180 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 in combination
2c190 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 [sqlite3_next_st
2c1a0 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 mt()].** to loca
2c1b0 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 te all prepared
2c1c0 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 statements assoc
2c1d0 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74 iated with a dat
2c1e0 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 abase .** connec
2c1f0 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e tion that are in
2c200 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 need of being r
2c210 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 eset. This can
2c220 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 be used,.** for
2c230 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 example, in diag
2c240 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 nostic routines
2c250 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 to search for pr
2c260 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 epared .** state
2c270 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 ments that are h
2c280 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 olding a transac
2c290 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e tion open..*/.in
2c2a0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 t sqlite3_stmt_b
2c2b0 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 usy(sqlite3_stmt
2c2c0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
2c2d0 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 REF: Dynamically
2c2e0 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a Typed Value Obj
2c2f0 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ect.** KEYWORDS:
2c300 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 {protected sqli
2c310 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 te3_value} {unpr
2c320 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
2c330 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c value}.**.** SQL
2c340 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c ite uses the sql
2c350 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
2c360 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 t to represent a
2c370 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 ll values.** tha
2c380 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 t can be stored
2c390 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 in a database ta
2c3a0 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 ble. SQLite uses
2c3b0 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a dynamic typing.
2c3c0 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 ** for the value
2c3d0 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 s it stores. ^V
2c3e0 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 alues stored in
2c3f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
2c400 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 jects.** can be
2c410 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 integers, floati
2c420 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c ng point values,
2c430 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c strings, BLOBs,
2c440 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 or NULL..**.**
2c450 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 An sqlite3_value
2c460 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 object may be e
2c470 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 ither "protected
2c480 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 " or "unprotecte
2c490 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 d"..** Some inte
2c4a0 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 rfaces require a
2c4b0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 protected sqlit
2c4c0 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 e3_value. Other
2c4d0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 interfaces.** w
2c4e0 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 ill accept eithe
2c4f0 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 r a protected or
2c500 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 an unprotected
2c510 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a sqlite3_value..*
2c520 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 * Every interfac
2c530 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 e that accepts s
2c540 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 qlite3_value arg
2c550 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 uments specifies
2c560 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e .** whether or n
2c570 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 ot it requires a
2c580 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 protected sqlit
2c590 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a e3_value. The.*
2c5a0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 * [sqlite3_value
2c5b0 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63 _dup()] interfac
2c5c0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f e can be used to
2c5d0 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 construct a new
2c5e0 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73 .** protected s
2c5f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f qlite3_value fro
2c600 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 m an unprotected
2c610 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a sqlite3_value..
2c620 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 **.** The terms
2c630 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 "protected" and
2c640 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 "unprotected" re
2c650 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f fer to whether o
2c660 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 r not.** a mutex
2c670 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e is held. An in
2c680 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 ternal mutex is
2c690 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 held for a prote
2c6a0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f cted.** sqlite3_
2c6b0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 value object but
2c6c0 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c no mutex is hel
2c6d0 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 d for an unprote
2c6e0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f cted.** sqlite3_
2c6f0 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 value object. I
2c700 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 f SQLite is comp
2c710 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c iled to be singl
2c720 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 e-threaded.** (w
2c730 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 ith [SQLITE_THRE
2c740 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 ADSAFE=0] and wi
2c750 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 th [sqlite3_thre
2c760 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e adsafe()] return
2c770 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 ing 0).** or if
2c780 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e SQLite is run in
2c790 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 one of reduced
2c7a0 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 mutex modes .**
2c7b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
2c7c0 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 INGLETHREAD] or
2c7d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
2c7e0 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 ULTITHREAD].** t
2c7f0 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 hen there is no
2c800 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 distinction betw
2c810 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e een protected an
2c820 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a d unprotected.**
2c830 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
2c840 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 bjects and they
2c850 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 can be used inte
2c860 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f rchangeably. Ho
2c870 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 wever,.** for ma
2c880 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 ximum code porta
2c890 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 bility it is rec
2c8a0 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 ommended that ap
2c8b0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 plications.** st
2c8c0 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 ill make the dis
2c8d0 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e tinction between
2c8e0 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 protected and u
2c8f0 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 nprotected.** sq
2c900 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
2c910 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f cts even when no
2c920 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 t strictly requi
2c930 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 red..**.** ^The
2c940 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
2c950 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 jects that are p
2c960 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 assed as paramet
2c970 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 ers into the.**
2c980 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
2c990 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 f [application-d
2c9a0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
2c9b0 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 ions] are protec
2c9c0 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ted..** ^The sql
2c9d0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
2c9e0 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a t returned by.**
2c9f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
2ca00 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 _value()] is unp
2ca10 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 rotected..** Unp
2ca20 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
2ca30 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d _value objects m
2ca40 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 ay only be used
2ca50 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 with.** [sqlite3
2ca60 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d _result_value()]
2ca70 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 and [sqlite3_bi
2ca80 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 nd_value()]..**
2ca90 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c The [sqlite3_val
2caa0 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 ue_blob | sqlite
2cab0 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 3_value_type()]
2cac0 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 family of.** int
2cad0 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 erfaces require
2cae0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
2caf0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 3_value objects.
2cb00 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
2cb10 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 ct Mem sqlite3_v
2cb20 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 alue;../*.** CAP
2cb30 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 I3REF: SQL Funct
2cb40 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 ion Context Obje
2cb50 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e ct.**.** The con
2cb60 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e text in which an
2cb70 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 SQL function ex
2cb80 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 ecutes is stored
2cb90 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 in an.** sqlite
2cba0 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 3_context object
2cbb0 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f . ^A pointer to
2cbc0 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 an sqlite3_cont
2cbd0 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 ext object.** is
2cbe0 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 always first pa
2cbf0 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c rameter to [appl
2cc00 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
2cc10 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a SQL functions]..
2cc20 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
2cc30 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
2cc40 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e unction implemen
2cc50 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 tation will pass
2cc60 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 this.** pointer
2cc70 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 through into ca
2cc80 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
2cc90 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c result_int | sql
2cca0 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a ite3_result()],.
2ccb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 ** [sqlite3_aggr
2ccc0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d egate_context()]
2ccd0 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f , [sqlite3_user_
2cce0 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c data()],.** [sql
2ccf0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f ite3_context_db_
2cd00 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 handle()], [sqli
2cd10 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 te3_get_auxdata(
2cd20 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 )],.** and/or [s
2cd30 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 qlite3_set_auxda
2cd40 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 ta()]..*/.typede
2cd50 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
2cd60 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 _context sqlite3
2cd70 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a _context;../*.**
2cd80 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 CAPI3REF: Bindi
2cd90 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 ng Values To Pre
2cda0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 pared Statements
2cdb0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 .** KEYWORDS: {h
2cdc0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b ost parameter} {
2cdd0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d host parameters}
2cde0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 {host parameter
2cdf0 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 name}.** KEYWOR
2ce00 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 DS: {SQL paramet
2ce10 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 er} {SQL paramet
2ce20 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 ers} {parameter
2ce30 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 binding}.** METH
2ce40 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 OD: sqlite3_stmt
2ce50 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 .**.** ^(In the
2ce60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 SQL statement te
2ce70 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c xt input to [sql
2ce80 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
2ce90 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 )] and its varia
2cea0 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 nts,.** literals
2ceb0 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 may be replaced
2cec0 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 by a [parameter
2ced0 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f ] that matches o
2cee0 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a ne of following.
2cef0 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a ** templates:.**
2cf00 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
2cf10 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e ?.** <li> ?NN
2cf20 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a N.** <li> :VVV.
2cf30 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a ** <li> @VVV.**
2cf40 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c <li> $VVV.** <
2cf50 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 /ul>.**.** In th
2cf60 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 e templates abov
2cf70 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 e, NNN represent
2cf80 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 s an integer lit
2cf90 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 eral,.** and VVV
2cfa0 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 represents an a
2cfb0 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e lphanumeric iden
2cfc0 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 tifier.)^ ^The
2cfd0 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a values of these.
2cfe0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 ** parameters (a
2cff0 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 lso called "host
2d000 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 parameter names
2d010 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 " or "SQL parame
2d020 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 ters").** can be
2d030 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 set using the s
2d040 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 qlite3_bind_*()
2d050 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 routines defined
2d060 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 here..**.** ^Th
2d070 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
2d080 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
2d090 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 bind_*() routine
2d0a0 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 s is always.** a
2d0b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
2d0c0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f [sqlite3_stmt] o
2d0d0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 bject returned f
2d0e0 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f rom.** [sqlite3_
2d0f0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
2d100 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a its variants..*
2d110 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 *.** ^The second
2d120 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
2d130 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 index of the SQ
2d140 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 L parameter to b
2d150 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c e set..** ^The l
2d160 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 eftmost SQL para
2d170 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 meter has an ind
2d180 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 ex of 1. ^When
2d190 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a the same named.*
2d1a0 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 * SQL parameter
2d1b0 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 is used more tha
2d1c0 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 n once, second a
2d1d0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a nd subsequent.**
2d1e0 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 occurrences hav
2d1f0 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 e the same index
2d200 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 as the first oc
2d210 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 currence..** ^Th
2d220 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 e index for name
2d230 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e d parameters can
2d240 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 be looked up us
2d250 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 ing the.** [sqli
2d260 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
2d270 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 er_index()] API
2d280 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 if desired. ^Th
2d290 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 e index.** for "
2d2a0 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 ?NNN" parameters
2d2b0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 is the value of
2d2c0 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e NNN..** ^The NN
2d2d0 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 N value must be
2d2e0 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 between 1 and th
2d2f0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 e [sqlite3_limit
2d300 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ()].** parameter
2d310 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 [SQLITE_LIMIT_V
2d320 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 ARIABLE_NUMBER]
2d330 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 (default value:
2d340 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 999)..**.** ^The
2d350 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 third argument
2d360 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 is the value to
2d370 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 bind to the para
2d380 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 meter..** ^If th
2d390 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
2d3a0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e r to sqlite3_bin
2d3b0 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 d_text() or sqli
2d3c0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 te3_bind_text16(
2d3d0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f ).** or sqlite3_
2d3e0 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 bind_blob() is a
2d3f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 NULL pointer th
2d400 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 en the fourth pa
2d410 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 rameter.** is ig
2d420 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e nored and the en
2d430 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 d result is the
2d440 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f same as sqlite3_
2d450 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a bind_null()..**.
2d460 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f ** ^(In those ro
2d470 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 utines that have
2d480 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 a fourth argume
2d490 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 nt, its value is
2d4a0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f the.** number o
2d4b0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 f bytes in the p
2d4c0 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 arameter. To be
2d4d0 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 clear: the valu
2d4e0 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 e is the.** numb
2d4f0 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f er of <u>bytes</
2d500 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c u> in the value,
2d510 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 not the number
2d520 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e of characters.)^
2d530 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 .** ^If the four
2d540 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
2d550 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
2d560 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 t() or sqlite3_b
2d570 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 ind_text16().**
2d580 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 is negative, the
2d590 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 n the length of
2d5a0 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a the string is.**
2d5b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
2d5c0 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 ytes up to the f
2d5d0 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e irst zero termin
2d5e0 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 ator..** If the
2d5f0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
2d600 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
2d610 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 _blob() is negat
2d620 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 ive, then.** the
2d630 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 behavior is und
2d640 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 efined..** If a
2d650 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 non-negative fou
2d660 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 rth parameter is
2d670 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c provided to sql
2d680 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 ite3_bind_text()
2d690 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 .** or sqlite3_b
2d6a0 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20 ind_text16() or
2d6b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
2d6c0 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 t64() then.** th
2d6d0 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 at parameter mus
2d6e0 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 t be the byte of
2d6f0 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 fset.** where th
2d700 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 e NUL terminator
2d710 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 would occur ass
2d720 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 uming the string
2d730 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 were NUL.** ter
2d740 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 minated. If any
2d750 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 NUL characters
2d760 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 occur at byte of
2d770 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 fsets less than
2d780 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 .** the value of
2d790 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
2d7a0 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 meter then the r
2d7b0 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 esulting string
2d7c0 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f value will.** co
2d7d0 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e ntain embedded N
2d7e0 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 ULs. The result
2d7f0 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 of expressions
2d800 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 involving string
2d810 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 s.** with embedd
2d820 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 ed NULs is undef
2d830 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ined..**.** ^The
2d840 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 fifth argument
2d850 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 to the BLOB and
2d860 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 string binding i
2d870 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 nterfaces.** is
2d880 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 a destructor use
2d890 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 d to dispose of
2d8a0 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 the BLOB or.** s
2d8b0 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 tring after SQLi
2d8c0 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 te has finished
2d8d0 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 with it. ^The d
2d8e0 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c estructor is cal
2d8f0 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 led.** to dispos
2d900 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 e of the BLOB or
2d910 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 string even if
2d920 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 the call to bind
2d930 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e API fails..** ^
2d940 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 If the fifth arg
2d950 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 ument is.** the
2d960 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 special value [S
2d970 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 QLITE_STATIC], t
2d980 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d hen SQLite assum
2d990 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 es that the.** i
2d9a0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e nformation is in
2d9b0 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 static, unmanag
2d9c0 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 ed space and doe
2d9d0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 s not need to be
2d9e0 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 freed..** ^If t
2d9f0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e he fifth argumen
2da00 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 t has the value
2da10 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e [SQLITE_TRANSIEN
2da20 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 T], then.** SQLi
2da30 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e te makes its own
2da40 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 private copy of
2da50 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 the data immedi
2da60 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a ately, before.**
2da70 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e the sqlite3_bin
2da80 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 d_*() routine re
2da90 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 turns..**.** ^Th
2daa0 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 e sixth argument
2dab0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
2dac0 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74 20 62 _text64() must b
2dad0 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c e one of.** [SQL
2dae0 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 ITE_UTF8], [SQLI
2daf0 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 TE_UTF16], [SQLI
2db00 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 TE_UTF16BE], or
2db10 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d [SQLITE_UTF16LE]
2db20 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74 .** to specify t
2db30 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 he encoding of t
2db40 68 65 20 74 65 78 74 20 69 6e 20 74 68 65 20 74 he text in the t
2db50 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 hird parameter.
2db60 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 If.** the sixth
2db70 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
2db80 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 ite3_bind_text64
2db90 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 () is not one of
2dba0 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 the.** allowed
2dbb0 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f values shown abo
2dbc0 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65 ve, or if the te
2dbd0 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 xt encoding is d
2dbe0 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d ifferent.** from
2dbf0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 the encoding sp
2dc00 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 73 ecified by the s
2dc10 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 ixth parameter,
2dc20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f then the behavio
2dc30 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 r.** is undefine
2dc40 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 d..**.** ^The sq
2dc50 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 lite3_bind_zerob
2dc60 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 lob() routine bi
2dc70 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 nds a BLOB of le
2dc80 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 ngth N that.** i
2dc90 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 s filled with ze
2dca0 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c roes. ^A zerobl
2dcb0 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 ob uses a fixed
2dcc0 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 amount of memory
2dcd0 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 .** (just an int
2dce0 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 eger to hold its
2dcf0 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 size) while it
2dd00 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 is being process
2dd10 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 ed..** Zeroblobs
2dd20 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f are intended to
2dd30 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 serve as placeh
2dd40 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 olders for BLOBs
2dd50 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e whose.** conten
2dd60 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 t is later writt
2dd70 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c en using.** [sql
2dd80 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c ite3_blob_open |
2dd90 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f incremental BLO
2dda0 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e B I/O] routines.
2ddb0 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 .** ^A negative
2ddc0 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 value for the ze
2ddd0 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 roblob results i
2dde0 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 n a zero-length
2ddf0 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 BLOB..**.** ^If
2de00 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 any of the sqlit
2de10 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 e3_bind_*() rout
2de20 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 ines are called
2de30 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e with a NULL poin
2de40 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b ter.** for the [
2de50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2de60 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 nt] or with a pr
2de70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2de80 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 for which.** [s
2de90 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 qlite3_step()] h
2dea0 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d as been called m
2deb0 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 ore recently tha
2dec0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 n [sqlite3_reset
2ded0 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ()],.** then the
2dee0 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 call will retur
2def0 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 n [SQLITE_MISUSE
2df00 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 ]. If any sqlit
2df10 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f e3_bind_().** ro
2df20 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 utine is passed
2df30 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
2df40 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 ement] that has
2df50 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 been finalized,
2df60 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 the.** result is
2df70 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 undefined and p
2df80 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e robably harmful.
2df90 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 .**.** ^Bindings
2dfa0 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 are not cleared
2dfb0 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 by the [sqlite3
2dfc0 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e _reset()] routin
2dfd0 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 e..** ^Unbound p
2dfe0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e arameters are in
2dff0 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c terpreted as NUL
2e000 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 L..**.** ^The sq
2e010 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 lite3_bind_* rou
2e020 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 tines return [SQ
2e030 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 LITE_OK] on succ
2e040 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 ess or an.** [er
2e050 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 ror code] if any
2e060 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 thing goes wrong
2e070 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f ..** ^[SQLITE_TO
2e080 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 OBIG] might be r
2e090 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 eturned if the s
2e0a0 69 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 ize of a string
2e0b0 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 or BLOB.** excee
2e0c0 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 ds limits impose
2e0d0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 d by [sqlite3_li
2e0e0 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d mit]([SQLITE_LIM
2e0f0 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a IT_LENGTH]) or.*
2e100 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 * [SQLITE_MAX_LE
2e110 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 NGTH]..** ^[SQLI
2e120 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 TE_RANGE] is ret
2e130 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 urned if the par
2e140 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 ameter.** index
2e150 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e is out of range.
2e160 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d ^[SQLITE_NOMEM
2e170 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 ] is returned if
2e180 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e malloc() fails.
2e190 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
2e1a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
2e1b0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 arameter_count()
2e1c0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 ],.** [sqlite3_b
2e1d0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 ind_parameter_na
2e1e0 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 me()], and [sqli
2e1f0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
2e200 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a er_index()]..*/.
2e210 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
2e220 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 _blob(sqlite3_st
2e230 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 mt*, int, const
2e240 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f void*, int n, vo
2e250 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 id(*)(void*));.i
2e260 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
2e270 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 blob64(sqlite3_s
2e280 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
2e290 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f void*, sqlite3_
2e2a0 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 uint64,.
2e2b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2e2c0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
2e2d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
2e2e0 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 d_double(sqlite3
2e2f0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 _stmt*, int, dou
2e300 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 ble);.int sqlite
2e310 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 3_bind_int(sqlit
2e320 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 e3_stmt*, int, i
2e330 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 nt);.int sqlite3
2e340 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 _bind_int64(sqli
2e350 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
2e360 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a sqlite3_int64);.
2e370 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
2e380 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 _null(sqlite3_st
2e390 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 mt*, int);.int s
2e3a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
2e3b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
2e3c0 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 nt,const char*,i
2e3d0 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a nt,void(*)(void*
2e3e0 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f ));.int sqlite3_
2e3f0 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 bind_text16(sqli
2e400 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
2e410 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
2e420 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 , void(*)(void*)
2e430 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 );.int sqlite3_b
2e440 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74 ind_text64(sqlit
2e450 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 e3_stmt*, int, c
2e460 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 onst char*, sqli
2e470 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 te3_uint64,.
2e480 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2e490 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 void(*)(voi
2e4a0 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 d*), unsigned ch
2e4b0 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e ar encoding);.in
2e4c0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 t sqlite3_bind_v
2e4d0 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d alue(sqlite3_stm
2e4e0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 t*, int, const s
2e4f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
2e500 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
2e510 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 _zeroblob(sqlite
2e520 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 3_stmt*, int, in
2e530 74 20 6e 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 t n);.int sqlite
2e540 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 3_bind_zeroblob6
2e550 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 4(sqlite3_stmt*,
2e560 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 69 int, sqlite3_ui
2e570 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 nt64);../*.** CA
2e580 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f PI3REF: Number O
2e590 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 f SQL Parameters
2e5a0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
2e5b0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e te3_stmt.**.** ^
2e5c0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e This routine can
2e5d0 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 be used to find
2e5e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b the number of [
2e5f0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a SQL parameters].
2e600 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 ** in a [prepare
2e610 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 d statement]. S
2e620 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 QL parameters ar
2e630 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a e tokens of the.
2e640 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e ** form "?", "?N
2e650 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 NN", ":AAA", "$A
2e660 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 AA", or "@AAA" t
2e670 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 hat serve as.**
2e680 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 placeholders for
2e690 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 values that are
2e6a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
2e6b0 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 lob | bound].**
2e6c0 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 to the parameter
2e6d0 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d s at a later tim
2e6e0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 e..**.** ^(This
2e6f0 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 routine actually
2e700 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 returns the ind
2e710 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 ex of the larges
2e720 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a t (rightmost).**
2e730 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 parameter. For
2e740 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 all forms except
2e750 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c ?NNN, this will
2e760 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 correspond to t
2e770 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 he.** number of
2e780 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 unique parameter
2e790 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 s. If parameter
2e7a0 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f s of the ?NNN fo
2e7b0 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 rm are used,.**
2e7c0 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 there may be gap
2e7d0 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e s in the list.)^
2e7e0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
2e7f0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
2e800 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 lob|sqlite3_bind
2e810 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
2e820 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
2e830 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 name()], and.**
2e840 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
2e850 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d rameter_index()]
2e860 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
2e870 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
2e880 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 count(sqlite3_st
2e890 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 mt*);../*.** CAP
2e8a0 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 I3REF: Name Of A
2e8b0 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a Host Parameter.
2e8c0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
2e8d0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 e3_stmt.**.** ^T
2e8e0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
2e8f0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 parameter_name(P
2e900 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 ,N) interface re
2e910 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d turns.** the nam
2e920 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 e of the N-th [S
2e930 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e QL parameter] in
2e940 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
2e950 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 tatement] P..**
2e960 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 ^(SQL parameters
2e970 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e of the form "?N
2e980 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 NN" or ":AAA" or
2e990 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 "@AAA" or "$AAA
2e9a0 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 ".** have a name
2e9b0 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 which is the st
2e9c0 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 ring "?NNN" or "
2e9d0 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 :AAA" or "@AAA"
2e9e0 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 or "$AAA".** res
2e9f0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e pectively..** In
2ea00 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 other words, th
2ea10 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 e initial ":" or
2ea20 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 "$" or "@" or "
2ea30 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 ?".** is include
2ea40 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 d as part of the
2ea50 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 name.)^.** ^Par
2ea60 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 ameters of the f
2ea70 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 orm "?" without
2ea80 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 a following inte
2ea90 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 ger have no name
2eaa0 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 .** and are refe
2eab0 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 rred to as "name
2eac0 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d less" or "anonym
2ead0 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e ous parameters".
2eae0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 .**.** ^The firs
2eaf0 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 t host parameter
2eb00 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 has an index of
2eb10 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 1, not 0..**.**
2eb20 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e ^If the value N
2eb30 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 is out of range
2eb40 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 or if the N-th
2eb50 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 parameter is.**
2eb60 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e nameless, then N
2eb70 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e ULL is returned.
2eb80 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 ^The returned
2eb90 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 string is.** alw
2eba0 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 ays in UTF-8 enc
2ebb0 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 oding even if th
2ebc0 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 e named paramete
2ebd0 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 r was.** origina
2ebe0 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73 lly specified as
2ebf0 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 UTF-16 in [sqli
2ec00 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d te3_prepare16()]
2ec10 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
2ec20 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e prepare16_v2()].
2ec30 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
2ec40 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
2ec50 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 lob|sqlite3_bind
2ec60 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
2ec70 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
2ec80 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a count()], and.**
2ec90 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
2eca0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 arameter_index()
2ecb0 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 ]..*/.const char
2ecc0 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 *sqlite3_bind_p
2ecd0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 arameter_name(sq
2ece0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2ecf0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2ed00 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 EF: Index Of A P
2ed10 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 arameter With A
2ed20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 Given Name.** ME
2ed30 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 THOD: sqlite3_st
2ed40 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e mt.**.** ^Return
2ed50 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e the index of an
2ed60 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 SQL parameter g
2ed70 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 iven its name.
2ed80 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 ^The.** index va
2ed90 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 lue returned is
2eda0 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 suitable for use
2edb0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a as the second.*
2edc0 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b * parameter to [
2edd0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
2ede0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 b|sqlite3_bind()
2edf0 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 ]. ^A zero.** i
2ee00 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f s returned if no
2ee10 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 matching parame
2ee20 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e ter is found. ^
2ee30 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a The parameter.**
2ee40 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 name must be gi
2ee50 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 ven in UTF-8 eve
2ee60 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 n if the origina
2ee70 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 l statement.** w
2ee80 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d as prepared from
2ee90 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 UTF-16 text usi
2eea0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ng [sqlite3_prep
2eeb0 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a are16_v2()]..**.
2eec0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
2eed0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c lite3_bind_blob|
2eee0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c sqlite3_bind()],
2eef0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
2ef00 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e d_parameter_coun
2ef10 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 t()], and.** [sq
2ef20 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
2ef30 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f eter_name()]..*/
2ef40 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
2ef50 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 d_parameter_inde
2ef60 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c x(sqlite3_stmt*,
2ef70 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
2ef80 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 me);../*.** CAPI
2ef90 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 3REF: Reset All
2efa0 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 Bindings On A Pr
2efb0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
2efc0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
2efd0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e te3_stmt.**.** ^
2efe0 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 Contrary to the
2eff0 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e intuition of man
2f000 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 y, [sqlite3_rese
2f010 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 t()] does not re
2f020 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 set.** the [sqli
2f030 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 te3_bind_blob |
2f040 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b bindings] on a [
2f050 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2f060 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 nt]..** ^Use thi
2f070 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 s routine to res
2f080 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 et all host para
2f090 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a meters to NULL..
2f0a0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 */.int sqlite3_c
2f0b0 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 lear_bindings(sq
2f0c0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f lite3_stmt*);../
2f0d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e *.** CAPI3REF: N
2f0e0 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 umber Of Columns
2f0f0 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 In A Result Set
2f100 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
2f110 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e te3_stmt.**.** ^
2f120 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 Return the numbe
2f130 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 r of columns in
2f140 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 the result set r
2f150 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a eturned by the.*
2f160 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 * [prepared stat
2f170 65 6d 65 6e 74 5d 2e 20 5e 49 66 20 74 68 69 73 ement]. ^If this
2f180 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
2f190 20 30 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 0, that means t
2f1a0 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 he .** [prepared
2f1b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 72 65 74 75 statement] retu
2f1c0 72 6e 73 20 6e 6f 20 64 61 74 61 20 28 66 6f 72 rns no data (for
2f1d0 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 example an [UPD
2f1e0 41 54 45 5d 29 2e 0a 2a 2a 20 5e 48 6f 77 65 76 ATE])..** ^Howev
2f1f0 65 72 2c 20 6a 75 73 74 20 62 65 63 61 75 73 65 er, just because
2f200 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 this routine re
2f210 74 75 72 6e 73 20 61 20 70 6f 73 69 74 69 76 65 turns a positive
2f220 20 6e 75 6d 62 65 72 20 64 6f 65 73 20 6e 6f 74 number does not
2f230 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 6f 6e .** mean that on
2f240 65 20 6f 72 20 6d 6f 72 65 20 72 6f 77 73 20 6f e or more rows o
2f250 66 20 64 61 74 61 20 77 69 6c 6c 20 62 65 20 72 f data will be r
2f260 65 74 75 72 6e 65 64 2e 20 20 5e 41 20 53 45 4c eturned. ^A SEL
2f270 45 43 54 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a ECT statement.**
2f280 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 68 61 76 will always hav
2f290 65 20 61 20 70 6f 73 69 74 69 76 65 20 73 71 6c e a positive sql
2f2a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e ite3_column_coun
2f2b0 74 28 29 20 62 75 74 20 64 65 70 65 6e 64 69 6e t() but dependin
2f2c0 67 20 6f 6e 20 74 68 65 0a 2a 2a 20 57 48 45 52 g on the.** WHER
2f2d0 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 E clause constra
2f2e0 69 6e 74 73 20 61 6e 64 20 74 68 65 20 74 61 62 ints and the tab
2f2f0 6c 65 20 63 6f 6e 74 65 6e 74 2c 20 69 74 20 6d le content, it m
2f300 69 67 68 74 20 72 65 74 75 72 6e 20 6e 6f 20 72 ight return no r
2f310 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ows..**.** See a
2f320 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 lso: [sqlite3_da
2f330 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 ta_count()].*/.i
2f340 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nt sqlite3_colum
2f350 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f n_count(sqlite3_
2f360 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f stmt *pStmt);../
2f370 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
2f380 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 olumn Names In A
2f390 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d Result Set.** M
2f3a0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 ETHOD: sqlite3_s
2f3b0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 tmt.**.** ^These
2f3c0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
2f3d0 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e the name assign
2f3e0 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c ed to a particul
2f3f0 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 ar column.** in
2f400 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f the result set o
2f410 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 f a [SELECT] sta
2f420 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 tement. ^The sq
2f430 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
2f440 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 e().** interface
2f450 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
2f460 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 er to a zero-ter
2f470 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 minated UTF-8 st
2f480 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 ring.** and sqli
2f490 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 te3_column_name1
2f4a0 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 6() returns a po
2f4b0 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d inter to a zero-
2f4c0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 terminated.** UT
2f4d0 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 F-16 string. ^T
2f4e0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
2f4f0 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 er is the [prepa
2f500 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a red statement].*
2f510 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 * that implement
2f520 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 s the [SELECT] s
2f530 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 tatement. ^The s
2f540 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
2f550 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e is the.** column
2f560 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c number. ^The l
2f570 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 eftmost column i
2f580 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a s number 0..**.*
2f590 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 * ^The returned
2f5a0 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 string pointer i
2f5b0 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 s valid until ei
2f5c0 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 ther the [prepar
2f5d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a ed statement].**
2f5e0 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 is destroyed by
2f5f0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
2f600 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 ze()] or until t
2f610 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 he statement is
2f620 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a automatically.**
2f630 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 reprepared by t
2f640 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f he first call to
2f650 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
2f660 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c ] for a particul
2f670 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 ar run.** or unt
2f680 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c il the next call
2f690 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 to.** sqlite3_c
2f6a0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 olumn_name() or
2f6b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e sqlite3_column_n
2f6c0 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 ame16() on the s
2f6d0 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a ame column..**.*
2f6e0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 * ^If sqlite3_ma
2f6f0 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 lloc() fails dur
2f700 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 ing the processi
2f710 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 ng of either rou
2f720 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 tine.** (for exa
2f730 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f mple during a co
2f740 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 nversion from UT
2f750 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 F-8 to UTF-16) t
2f760 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f hen a.** NULL po
2f770 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 inter is returne
2f780 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 d..**.** ^The na
2f790 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 me of a result c
2f7a0 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c olumn is the val
2f7b0 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 ue of the "AS" c
2f7c0 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 lause for.** tha
2f7d0 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 t column, if the
2f7e0 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 re is an AS clau
2f7f0 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 se. If there is
2f800 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a no AS clause.**
2f810 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f then the name o
2f820 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 f the column is
2f830 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 unspecified and
2f840 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a may change from.
2f850 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f ** one release o
2f860 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 f SQLite to the
2f870 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 next..*/.const c
2f880 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c har *sqlite3_col
2f890 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 umn_name(sqlite3
2f8a0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a _stmt*, int N);.
2f8b0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
2f8c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 te3_column_name1
2f8d0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
2f8e0 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 int N);../*.**
2f8f0 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 CAPI3REF: Source
2f900 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 Of Data In A Qu
2f910 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 ery Result.** ME
2f920 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 THOD: sqlite3_st
2f930 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 mt.**.** ^These
2f940 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 routines provide
2f950 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 a means to dete
2f960 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 rmine the databa
2f970 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a se, table, and.*
2f980 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 * table column t
2f990 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 hat is the origi
2f9a0 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 n of a particula
2f9b0 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 r result column
2f9c0 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 in.** [SELECT] s
2f9d0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 tatement..** ^Th
2f9e0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 e name of the da
2f9f0 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 tabase or table
2fa00 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 or column can be
2fa10 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 returned as.**
2fa20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f either a UTF-8 o
2fa30 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e r UTF-16 string.
2fa40 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 ^The _database
2fa50 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 _ routines retur
2fa60 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 n.** the databas
2fa70 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 e name, the _tab
2fa80 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 le_ routines ret
2fa90 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 urn the table na
2faa0 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f me, and.** the o
2fab0 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 rigin_ routines
2fac0 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d return the colum
2fad0 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 n name..** ^The
2fae0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 returned string
2faf0 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 is valid until t
2fb00 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
2fb10 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 tement] is destr
2fb20 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 oyed.** using [s
2fb30 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2fb40 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 )] or until the
2fb50 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 statement is aut
2fb60 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 omatically.** re
2fb70 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 prepared by the
2fb80 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 first call to [s
2fb90 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 qlite3_step()] f
2fba0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 or a particular
2fbb0 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 run.** or until
2fbc0 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 the same informa
2fbd0 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 tion is requeste
2fbe0 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 d.** again in a
2fbf0 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 different encodi
2fc00 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e ng..**.** ^The n
2fc10 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 ames returned ar
2fc20 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 e the original u
2fc30 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 n-aliased names
2fc40 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 of the.** databa
2fc50 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 se, table, and c
2fc60 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 olumn..**.** ^Th
2fc70 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
2fc80 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 to these interf
2fc90 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 aces is a [prepa
2fca0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a red statement]..
2fcb0 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 ** ^These functi
2fcc0 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 ons return infor
2fcd0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 mation about the
2fce0 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 Nth result colu
2fcf0 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a mn returned by.*
2fd00 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c * the statement,
2fd10 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 where N is the
2fd20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 second function
2fd30 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 argument..** ^Th
2fd40 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 e left-most colu
2fd50 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 mn is column 0 f
2fd60 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 or these routine
2fd70 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 s..**.** ^If the
2fd80 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 Nth column retu
2fd90 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 rned by the stat
2fda0 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 ement is an expr
2fdb0 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 ession or.** sub
2fdc0 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 query and is not
2fdd0 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c a column value,
2fde0 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 then all of the
2fdf0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 se functions ret
2fe00 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 urn.** NULL. ^T
2fe10 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 hese routine mig
2fe20 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e ht also return N
2fe30 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 ULL if a memory
2fe40 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 allocation error
2fe50 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 .** occurs. ^Ot
2fe60 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 herwise, they re
2fe70 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 turn the name of
2fe80 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 the attached da
2fe90 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a tabase, table,.*
2fea0 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 * or column that
2feb0 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f query result co
2fec0 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 lumn was extract
2fed0 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e ed from..**.** ^
2fee0 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 As with all othe
2fef0 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 r SQLite APIs, t
2ff00 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 hose whose names
2ff10 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 end with "16" r
2ff20 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 eturn.** UTF-16
2ff30 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 encoded strings
2ff40 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 and the other fu
2ff50 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 nctions return U
2ff60 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 TF-8..**.** ^The
2ff70 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 se APIs are only
2ff80 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 available if th
2ff90 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f e library was co
2ffa0 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a mpiled with the.
2ffb0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c ** [SQLITE_ENABL
2ffc0 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 E_COLUMN_METADAT
2ffd0 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f A] C-preprocesso
2ffe0 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 r symbol..**.**
2fff0 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 If two or more t
30000 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 hreads call one
30010 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 or more of these
30020 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 routines agains
30030 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 t the same.** pr
30040 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
30050 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 and column at t
30060 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 he same time the
30070 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 n the results ar
30080 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a e.** undefined..
30090 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 **.** If two or
300a0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c more threads cal
300b0 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a l one or more.**
300c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
300d0 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c _database_name |
300e0 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 column metadata
300f0 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 interfaces].**
30100 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 for the same [pr
30110 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
30120 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c ] and result col
30130 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 umn.** at the sa
30140 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 me time then the
30150 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 results are und
30160 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 efined..*/.const
30170 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 char *sqlite3_c
30180 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e olumn_database_n
30190 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ame(sqlite3_stmt
301a0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f *,int);.const vo
301b0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 id *sqlite3_colu
301c0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 mn_database_name
301d0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
301e0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 ,int);.const cha
301f0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d r *sqlite3_colum
30200 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c n_table_name(sql
30210 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
30220 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
30230 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c ite3_column_tabl
30240 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 e_name16(sqlite3
30250 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e _stmt*,int);.con
30260 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
30270 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e _column_origin_n
30280 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ame(sqlite3_stmt
30290 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f *,int);.const vo
302a0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 id *sqlite3_colu
302b0 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 mn_origin_name16
302c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
302d0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 nt);../*.** CAPI
302e0 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 3REF: Declared D
302f0 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 atatype Of A Que
30300 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 ry Result.** MET
30310 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d HOD: sqlite3_stm
30320 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 t.**.** ^(The fi
30330 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 rst parameter is
30340 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
30350 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 tement]..** If t
30360 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 his statement is
30370 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 a [SELECT] stat
30380 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 ement and the Nt
30390 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a h column of the.
303a0 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 ** returned resu
303b0 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b lt set of that [
303c0 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 SELECT] is a tab
303d0 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 le column (not a
303e0 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 n.** expression
303f0 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65 or subquery) the
30400 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 n the declared t
30410 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 ype of the table
30420 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 .** column is re
30430 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 turned.)^ ^If t
30440 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 he Nth column of
30450 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 the result set
30460 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 is an.** express
30470 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c ion or subquery,
30480 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 then a NULL poi
30490 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 nter is returned
304a0 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e ..** ^The return
304b0 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 ed string is alw
304c0 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 ays UTF-8 encode
304d0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 d..**.** ^(For e
304e0 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 xample, given th
304f0 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d e database schem
30500 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 a:.**.** CREATE
30510 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 TABLE t1(c1 VARI
30520 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 ANT);.**.** and
30530 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 the following st
30540 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f atement to be co
30550 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 mpiled:.**.** SE
30560 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 LECT c1 + 1, c1
30570 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 FROM t1;.**.** t
30580 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c his routine woul
30590 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 d return the str
305a0 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f ing "VARIANT" fo
305b0 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 r the second res
305c0 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 ult.** column (i
305d0 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c ==1), and a NULL
305e0 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 pointer for the
305f0 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f first result co
30600 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a lumn (i==0).)^.*
30610 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 *.** ^SQLite use
30620 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 s dynamic run-ti
30630 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 me typing. ^So
30640 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63 just because a c
30650 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c olumn.** is decl
30660 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 ared to contain
30670 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 a particular typ
30680 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 e does not mean
30690 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 that the.** data
306a0 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 stored in that
306b0 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 column is of the
306c0 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 declared type.
306d0 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 SQLite is.** st
306e0 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 rongly typed, bu
306f0 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 t the typing is
30700 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 dynamic not stat
30710 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 ic. ^Type.** is
30720 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
30730 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 individual valu
30740 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 es, not with the
30750 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 containers.** u
30760 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 sed to hold thos
30770 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e e values..*/.con
30780 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
30790 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 _column_decltype
307a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
307b0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 nt);.const void
307c0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
307d0 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 decltype16(sqlit
307e0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a e3_stmt*,int);..
307f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
30800 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 Evaluate An SQL
30810 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 Statement.** MET
30820 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d HOD: sqlite3_stm
30830 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 t.**.** After a
30840 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
30850 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 ent] has been pr
30860 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 epared using eit
30870 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f her.** [sqlite3_
30880 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
30890 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
308a0 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 e16_v2()] or one
308b0 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a of the legacy.*
308c0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 * interfaces [sq
308d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d lite3_prepare()]
308e0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 or [sqlite3_pre
308f0 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 pare16()], this
30900 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 function.** must
30910 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f be called one o
30920 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 r more times to
30930 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 evaluate the sta
30940 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 tement..**.** Th
30950 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 e details of the
30960 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 behavior of the
30970 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
30980 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 interface depend
30990 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 .** on whether t
309a0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 he statement was
309b0 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 prepared using
309c0 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 the newer "v2" i
309d0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c nterface.** [sql
309e0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
309f0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
30a00 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 prepare16_v2()]
30a10 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 or the older leg
30a20 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 acy.** interface
30a30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
30a40 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 e()] and [sqlite
30a50 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 3_prepare16()].
30a60 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a The use of the.
30a70 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 ** new "v2" inte
30a80 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 rface is recomme
30a90 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 nded for new app
30aa0 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 lications but th
30ab0 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 e legacy.** inte
30ac0 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 rface will conti
30ad0 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 nue to be suppor
30ae0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 ted..**.** ^In t
30af0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 he legacy interf
30b00 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 ace, the return
30b10 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 value will be ei
30b20 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 ther [SQLITE_BUS
30b30 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 Y],.** [SQLITE_D
30b40 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f ONE], [SQLITE_RO
30b50 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f W], [SQLITE_ERRO
30b60 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d R], or [SQLITE_M
30b70 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 ISUSE]..** ^With
30b80 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 the "v2" interf
30b90 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 ace, any of the
30ba0 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f other [result co
30bb0 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 des] or.** [exte
30bc0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
30bd0 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 s] might be retu
30be0 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a rned as well..**
30bf0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 .** ^[SQLITE_BUS
30c00 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 Y] means that th
30c10 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e e database engin
30c20 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 e was unable to
30c30 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 acquire the.** d
30c40 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 atabase locks it
30c50 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 needs to do its
30c60 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 job. ^If the s
30c70 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 tatement is a [C
30c80 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 OMMIT].** or occ
30c90 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 urs outside of a
30ca0 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 n explicit trans
30cb0 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 action, then you
30cc0 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a can retry the.*
30cd0 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 * statement. If
30ce0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
30cf0 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d s not a [COMMIT]
30d00 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 and occurs with
30d10 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 in an.** explici
30d20 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 t transaction th
30d30 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f en you should ro
30d40 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 llback the trans
30d50 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a action before.**
30d60 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a continuing..**.
30d70 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 ** ^[SQLITE_DONE
30d80 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 ] means that the
30d90 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 statement has f
30da0 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e inished executin
30db0 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c g.** successfull
30dc0 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 y. sqlite3_step
30dd0 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 () should not be
30de0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e called again on
30df0 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a this virtual.**
30e00 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 machine without
30e10 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b first calling [
30e20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
30e30 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 to reset the vi
30e40 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 rtual.** machine
30e50 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 back to its ini
30e60 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a tial state..**.*
30e70 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 * ^If the SQL st
30e80 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 atement being ex
30e90 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 ecuted returns a
30ea0 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 ny data, then [S
30eb0 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 QLITE_ROW].** is
30ec0 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 returned each t
30ed0 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 ime a new row of
30ee0 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 data is ready f
30ef0 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 or processing by
30f00 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 the.** caller.
30f10 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 The values may b
30f20 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 e accessed using
30f30 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 the [column acc
30f40 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a ess functions]..
30f50 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 ** sqlite3_step(
30f60 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 ) is called agai
30f70 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 n to retrieve th
30f80 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 e next row of da
30f90 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 ta..**.** ^[SQLI
30fa0 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 TE_ERROR] means
30fb0 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 that a run-time
30fc0 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 error (such as a
30fd0 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 constraint.** v
30fe0 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 iolation) has oc
30ff0 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 curred. sqlite3
31000 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e _step() should n
31010 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 ot be called aga
31020 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e in on.** the VM.
31030 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f More informatio
31040 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 n may be found b
31050 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 y calling [sqlit
31060 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a e3_errmsg()]..**
31070 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 ^With the legac
31080 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d y interface, a m
31090 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 ore specific err
310a0 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 or code (for exa
310b0 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 mple,.** [SQLITE
310c0 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 _INTERRUPT], [SQ
310d0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 LITE_SCHEMA], [S
310e0 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 QLITE_CORRUPT],
310f0 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a and so forth).**
31100 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 can be obtained
31110 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c by calling [sql
31120 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e ite3_reset()] on
31130 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
31140 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e d statement]. ^
31150 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 In the "v2" inte
31160 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f rface,.** the mo
31170 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f re specific erro
31180 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e r code is return
31190 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 ed directly by s
311a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a qlite3_step()..*
311b0 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 *.** [SQLITE_MIS
311c0 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 USE] means that
311d0 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 the this routine
311e0 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 was called inap
311f0 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 propriately..**
31200 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 Perhaps it was c
31210 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 alled on a [prep
31220 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
31230 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 that has.** alre
31240 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 ady been [sqlite
31250 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 3_finalize | fin
31260 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e alized] or on on
31270 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 e that had.** pr
31280 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 eviously returne
31290 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d d [SQLITE_ERROR]
312a0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 or [SQLITE_DONE
312b0 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a ]. Or it could.
312c0 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 ** be the case t
312d0 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 hat the same dat
312e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
312f0 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 is being used b
31300 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 y two or.** more
31310 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 threads at the
31320 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 same moment in t
31330 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 ime..**.** For a
31340 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 ll versions of S
31350 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 QLite up to and
31360 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 including 3.6.23
31370 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a .1, a call to.**
31380 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
31390 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 )] was required
313a0 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 after sqlite3_st
313b0 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e ep() returned an
313c0 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 ything.** other
313d0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 than [SQLITE_ROW
313e0 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 ] before any sub
313f0 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 sequent invocati
31400 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 on of.** sqlite3
31410 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 _step(). Failur
31420 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 e to reset the p
31430 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
31440 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c t using .** [sql
31450 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f ite3_reset()] wo
31460 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e uld result in an
31470 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
31480 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 return from.**
31490 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 sqlite3_step().
314a0 20 42 75 74 20 61 66 74 65 72 20 5b 76 65 72 73 But after [vers
314b0 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 5d 20 28 5b ion 3.6.23.1] ([
314c0 64 61 74 65 6f 66 3a 33 2e 36 2e 32 33 2e 31 5d dateof:3.6.23.1]
314d0 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 ,.** sqlite3_ste
314e0 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c p() began.** cal
314f0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 ling [sqlite3_re
31500 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 set()] automatic
31510 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 ally in this cir
31520 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 cumstance rather
31530 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 .** than returni
31540 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 ng [SQLITE_MISUS
31550 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 E]. This is not
31560 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f considered a co
31570 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 mpatibility.** b
31580 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 reak because any
31590 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 application tha
315a0 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73 20 t ever receives
315b0 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 an SQLITE_MISUSE
315c0 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f error.** is bro
315d0 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f ken by definitio
315e0 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f n. The [SQLITE_
315f0 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 OMIT_AUTORESET]
31600 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
31610 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 ion.** can be us
31620 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 ed to restore th
31630 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f e legacy behavio
31640 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 r..**.** <b>Goof
31650 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 y Interface Aler
31660 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 t:</b> In the le
31670 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 gacy interface,
31680 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 the sqlite3_step
31690 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 ().** API always
316a0 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 returns a gener
316b0 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b ic error code, [
316c0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 SQLITE_ERROR], f
316d0 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 ollowing any.**
316e0 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e error other than
316f0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 [SQLITE_BUSY] a
31700 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 nd [SQLITE_MISUS
31710 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 E]. You must ca
31720 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 ll.** [sqlite3_r
31730 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 eset()] or [sqli
31740 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
31750 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 in order to find
31760 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 one of the.** s
31770 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 pecific [error c
31780 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 odes] that bette
31790 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 r describes the
317a0 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d error..** We adm
317b0 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20 it that this is
317c0 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 a goofy design.
317d0 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 The problem has
317e0 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 been fixed.** w
317f0 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 ith the "v2" int
31800 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 erface. If you
31810 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 prepare all of y
31820 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e our SQL statemen
31830 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 ts.** using eith
31840 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 er [sqlite3_prep
31850 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 are_v2()] or [sq
31860 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
31870 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a v2()] instead.**
31880 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b of the legacy [
31890 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
318a0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
318b0 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 prepare16()] int
318c0 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e erfaces,.** then
318d0 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 the more specif
318e0 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d ic [error codes]
318f0 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 are returned di
31900 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c rectly.** by sql
31910 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 ite3_step(). Th
31920 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 e use of the "v2
31930 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 " interface is r
31940 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 ecommended..*/.i
31950 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 nt sqlite3_step(
31960 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a sqlite3_stmt*);.
31970 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
31980 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d Number of colum
31990 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 ns in a result s
319a0 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 et.** METHOD: sq
319b0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a lite3_stmt.**.**
319c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 ^The sqlite3_da
319d0 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 ta_count(P) inte
319e0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 rface returns th
319f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 e number of colu
31a00 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 mns in the.** cu
31a10 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 rrent row of the
31a20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b result set of [
31a30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
31a40 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 nt] P..** ^If pr
31a50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
31a60 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 P does not have
31a70 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 results ready t
31a80 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 o return.** (via
31a90 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 calls to the [s
31aa0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e qlite3_column_in
31ab0 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 t | sqlite3_colu
31ac0 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e mn_*()] of.** in
31ad0 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 terfaces) then s
31ae0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
31af0 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a t(P) returns 0..
31b00 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
31b10 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f data_count(P) ro
31b20 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 utine also retur
31b30 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e ns 0 if P is a N
31b40 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 ULL pointer..**
31b50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 ^The sqlite3_dat
31b60 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 a_count(P) routi
31b70 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 ne returns 0 if
31b80 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c the previous cal
31b90 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 l to.** [sqlite3
31ba0 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e _step](P) return
31bb0 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d ed [SQLITE_DONE]
31bc0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f . ^The sqlite3_
31bd0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a data_count(P).**
31be0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e will return non
31bf0 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 -zero if previou
31c00 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 s call to [sqlit
31c10 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 e3_step](P) retu
31c20 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f rned.** [SQLITE_
31c30 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 ROW], except in
31c40 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 the case of the
31c50 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e [PRAGMA incremen
31c60 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 tal_vacuum].** w
31c70 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 here it always r
31c80 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 eturns zero sinc
31c90 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 e each step of t
31ca0 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a hat multi-step.*
31cb0 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 * pragma returns
31cc0 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 0 columns of da
31cd0 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c ta..**.** See al
31ce0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c so: [sqlite3_col
31cf0 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a umn_count()].*/.
31d00 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 int sqlite3_data
31d10 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 _count(sqlite3_s
31d20 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
31d30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 .** CAPI3REF: Fu
31d40 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 ndamental Dataty
31d50 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a pes.** KEYWORDS:
31d60 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a SQLITE_TEXT.**.
31d70 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 ** ^(Every value
31d80 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f in SQLite has o
31d90 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 ne of five funda
31da0 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 mental datatypes
31db0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
31dc0 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e <li> 64-bit sign
31dd0 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c ed integer.** <l
31de0 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 i> 64-bit IEEE f
31df0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 loating point nu
31e00 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 mber.** <li> str
31e10 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 ing.** <li> BLOB
31e20 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a .** <li> NULL.**
31e30 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 </ul>)^.**.** T
31e40 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 hese constants a
31e50 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 re codes for eac
31e60 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 h of those types
31e70 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ..**.** Note tha
31e80 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 t the SQLITE_TEX
31e90 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 T constant was a
31ea0 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 lso used in SQLi
31eb0 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 te version 2.**
31ec0 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 for a completely
31ed0 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 different meani
31ee0 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 ng. Software th
31ef0 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 at links against
31f00 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 both.** SQLite
31f10 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 version 2 and SQ
31f20 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 Lite version 3 s
31f30 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 hould use SQLITE
31f40 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 3_TEXT, not.** S
31f50 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 QLITE_TEXT..*/.#
31f60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
31f70 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 TEGER 1.#define
31f80 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 SQLITE_FLOAT
31f90 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
31fa0 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 E_BLOB 4.#de
31fb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c fine SQLITE_NULL
31fc0 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 5.#ifdef SQ
31fd0 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 LITE_TEXT.# unde
31fe0 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 f SQLITE_TEXT.#e
31ff0 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c lse.# define SQL
32000 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 ITE_TEXT 3.#
32010 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 endif.#define SQ
32020 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 LITE3_TEXT 3
32030 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
32040 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 : Result Values
32050 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 From A Query.**
32060 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d KEYWORDS: {colum
32070 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f n access functio
32080 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ns}.** METHOD: s
32090 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a qlite3_stmt.**.*
320a0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 * ^These routine
320b0 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 s return informa
320c0 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e tion about a sin
320d0 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 gle column of th
320e0 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 e current.** res
320f0 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 ult row of a que
32100 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 ry. ^In every c
32110 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 ase the first ar
32120 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e gument is a poin
32130 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 ter.** to the [p
32140 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
32150 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 t] that is being
32160 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 evaluated (the
32170 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a [sqlite3_stmt*].
32180 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 ** that was retu
32190 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 rned from [sqlit
321a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
321b0 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 or one of its v
321c0 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 ariants).** and
321d0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d the second argum
321e0 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 ent is the index
321f0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 of the column f
32200 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 or which informa
32210 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 tion.** should b
32220 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 e returned. ^The
32230 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e leftmost column
32240 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 of the result s
32250 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 et has the index
32260 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 0..** ^The numb
32270 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
32280 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 the result can
32290 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 be determined us
322a0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
322b0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e column_count()].
322c0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 .**.** If the SQ
322d0 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 L statement does
322e0 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 not currently p
322f0 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 oint to a valid
32300 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a row, or if the.*
32310 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 * column index i
32320 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 s out of range,
32330 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e the result is un
32340 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 defined..** Thes
32350 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f e routines may o
32360 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 nly be called wh
32370 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 en the most rece
32380 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 nt call to.** [s
32390 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 qlite3_step()] h
323a0 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c as returned [SQL
323b0 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 ITE_ROW] and nei
323c0 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ther.** [sqlite3
323d0 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 _reset()] nor [s
323e0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
323f0 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c )] have been cal
32400 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 led subsequently
32410 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 ..** If any of t
32420 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
32430 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b e called after [
32440 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
32450 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
32460 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 finalize()] or a
32470 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 fter [sqlite3_st
32480 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e ep()] has return
32490 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 ed.** something
324a0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 other than [SQLI
324b0 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 TE_ROW], the res
324c0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e ults are undefin
324d0 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 ed..** If [sqlit
324e0 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 e3_step()] or [s
324f0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
32500 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 or [sqlite3_fina
32510 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 lize()].** are c
32520 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 alled from a dif
32530 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 ferent thread wh
32540 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 ile any of these
32550 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 routines.** are
32560 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 pending, then t
32570 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 he results are u
32580 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
32590 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c ^The sqlite3_col
325a0 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 umn_type() routi
325b0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a ne returns the.*
325c0 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 * [SQLITE_INTEGE
325d0 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 R | datatype cod
325e0 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 e] for the initi
325f0 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 al data type.**
32600 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f of the result co
32610 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 lumn. ^The retu
32620 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e rned value is on
32630 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 e of [SQLITE_INT
32640 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 EGER],.** [SQLIT
32650 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 E_FLOAT], [SQLIT
32660 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 E_TEXT], [SQLITE
32670 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 _BLOB], or [SQLI
32680 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 TE_NULL]. The v
32690 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 alue.** returned
326a0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by sqlite3_colu
326b0 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c mn_type() is onl
326c0 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 y meaningful if
326d0 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 no type.** conve
326e0 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 rsions have occu
326f0 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65 rred as describe
32700 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 d below. After
32710 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f a type conversio
32720 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 n,.** the value
32730 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
32740 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
32750 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 ) is undefined.
32760 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 Future.** versi
32770 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 ons of SQLite ma
32780 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 y change the beh
32790 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 avior of sqlite3
327a0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a _column_type().*
327b0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 * following a ty
327c0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a pe conversion..*
327d0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 *.** ^If the res
327e0 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 ult is a BLOB or
327f0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 UTF-8 string th
32800 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 en the sqlite3_c
32810 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a olumn_bytes().**
32820 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
32830 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
32840 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f ytes in that BLO
32850 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 B or string..**
32860 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
32870 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e s a UTF-16 strin
32880 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f g, then sqlite3_
32890 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 column_bytes() c
328a0 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 onverts.** the s
328b0 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 tring to UTF-8 a
328c0 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 nd then returns
328d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
328e0 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 tes..** ^If the
328f0 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 result is a nume
32900 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 ric value then s
32910 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
32920 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 tes() uses.** [s
32930 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
32940 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 )] to convert th
32950 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 at value to a UT
32960 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 F-8 string and r
32970 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 eturns.** the nu
32980 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e mber of bytes in
32990 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a that string..**
329a0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 ^If the result
329b0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 is NULL, then sq
329c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
329d0 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 es() returns zer
329e0 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 o..**.** ^If the
329f0 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f result is a BLO
32a00 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 B or UTF-16 stri
32a10 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 ng then the sqli
32a20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
32a30 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 16().** routine
32a40 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
32a50 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
32a60 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 hat BLOB or stri
32a70 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 ng..** ^If the r
32a80 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 esult is a UTF-8
32a90 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 string, then sq
32aa0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
32ab0 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a es16() converts.
32ac0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f ** the string to
32ad0 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e UTF-16 and then
32ae0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
32af0 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a ber of bytes..**
32b00 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 ^If the result
32b10 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c is a numeric val
32b20 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f ue then sqlite3_
32b30 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
32b40 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 uses.** [sqlite
32b50 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 3_snprintf()] to
32b60 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 convert that va
32b70 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 lue to a UTF-16
32b80 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 string and retur
32b90 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 ns.** the number
32ba0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 of bytes in tha
32bb0 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 t string..** ^If
32bc0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e the result is N
32bd0 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 ULL, then sqlite
32be0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
32bf0 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e () returns zero.
32c00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 .**.** ^The valu
32c10 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b es returned by [
32c20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
32c30 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 ytes()] and .**
32c40 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
32c50 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f bytes16()] do no
32c60 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 t include the ze
32c70 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 ro terminators a
32c80 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 t the end.** of
32c90 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f the string. ^Fo
32ca0 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 r clarity: the v
32cb0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 alues returned b
32cc0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f y.** [sqlite3_co
32cd0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e lumn_bytes()] an
32ce0 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d [sqlite3_colum
32cf0 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 n_bytes16()] are
32d00 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a the number of.*
32d10 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 * bytes in the s
32d20 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e tring, not the n
32d30 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 umber of charact
32d40 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 ers..**.** ^Stri
32d50 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 ngs returned by
32d60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
32d70 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 ext() and sqlite
32d80 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
32d90 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 ),.** even empty
32da0 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c strings, are al
32db0 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e ways zero-termin
32dc0 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 ated. ^The retu
32dd0 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d rn.** value from
32de0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
32df0 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 blob() for a zer
32e00 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 o-length BLOB is
32e10 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
32e20 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e .**.** <b>Warnin
32e30 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62 6a 65 g:</b> ^The obje
32e40 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b ct returned by [
32e50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 sqlite3_column_v
32e60 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a alue()] is an.**
32e70 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 [unprotected sq
32e80 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
32e90 65 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c 74 69 ect. In a multi
32ea0 74 68 72 65 61 64 65 64 20 65 6e 76 69 72 6f 6e threaded environ
32eb0 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72 ment,.** an unpr
32ec0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
32ed0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 value object may
32ee0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 73 61 only be used sa
32ef0 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b 73 71 fely with.** [sq
32f00 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 lite3_bind_value
32f10 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
32f20 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d _result_value()]
32f30 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 ..** If the [unp
32f40 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
32f50 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 _value] object r
32f60 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 eturned by.** [s
32f70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 qlite3_column_va
32f80 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 lue()] is used i
32f90 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c n any other way,
32fa0 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 including calls
32fb0 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 .** to routines
32fc0 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 like [sqlite3_va
32fd0 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c lue_int()], [sql
32fe0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 ite3_value_text(
32ff0 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 )],.** or [sqlit
33000 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 e3_value_bytes()
33010 5d 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 ], the behavior
33020 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 is not threadsaf
33030 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 e..**.** These r
33040 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 outines attempt
33050 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 to convert the v
33060 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f alue where appro
33070 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a priate. ^For.**
33080 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 example, if the
33090 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 internal repres
330a0 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 entation is FLOA
330b0 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 T and a text res
330c0 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 ult.** is reques
330d0 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e ted, [sqlite3_sn
330e0 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 printf()] is use
330f0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 d internally to
33100 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 perform the.** c
33110 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 onversion automa
33120 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 tically. ^(The
33130 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 following table
33140 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 details the conv
33150 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 ersions.** that
33160 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a are applied:.**.
33170 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a ** <blockquote>.
33180 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 ** <table border
33190 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 ="1">.** <tr><th
331a0 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 > Internal<br>Ty
331b0 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 pe <th> Requeste
331c0 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 d<br>Type <th>
331d0 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a Conversion.**.**
331e0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 <tr><td> NULL
331f0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 <td> INTEGER
33200 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 <td> Result is
33210 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 0.** <tr><td>
33220 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c NULL <td> FL
33230 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 OAT <td> Resu
33240 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 lt is 0.0.** <tr
33250 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c ><td> NULL <
33260 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 td> TEXT <t
33270 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e d> Result is a N
33280 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c ULL pointer.** <
33290 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 tr><td> NULL
332a0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 <td> BLOB
332b0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 <td> Result is a
332c0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a NULL pointer.**
332d0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 <tr><td> INTEGE
332e0 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 R <td> FLOAT
332f0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 <td> Convert f
33300 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 rom integer to f
33310 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e loat.** <tr><td>
33320 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 INTEGER <td>
33330 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 TEXT <td> AS
33340 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 CII rendering of
33350 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 the integer.**
33360 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 <tr><td> INTEGER
33370 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 <td> BLOB
33380 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e <td> Same as IN
33390 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c TEGER->TEXT.** <
333a0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 tr><td> FLOAT
333b0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 <td> INTEGER
333c0 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 <td> [CAST] to I
333d0 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 NTEGER.** <tr><t
333e0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e d> FLOAT <td>
333f0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 TEXT <td>
33400 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 ASCII rendering
33410 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 of the float.**
33420 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <tr><td> FLOAT
33430 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 <td> BLOB
33440 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 <td> [CAST] to
33450 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e BLOB.** <tr><td>
33460 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 TEXT <td> I
33470 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 NTEGER <td> [C
33480 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a AST] to INTEGER.
33490 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 ** <tr><td> TEX
334a0 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 T <td> FLOAT
334b0 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 <td> [CAST]
334c0 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c to REAL.** <tr><
334d0 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 td> TEXT <td
334e0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e > BLOB <td>
334f0 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 No change.** <t
33500 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 r><td> BLOB
33510 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c <td> INTEGER <
33520 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e td> [CAST] to IN
33530 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 TEGER.** <tr><td
33540 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 > BLOB <td>
33550 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b FLOAT <td> [
33560 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a CAST] to REAL.**
33570 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 <tr><td> BLOB
33580 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 <td> TEXT
33590 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 <td> Add a zer
335a0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 o terminator if
335b0 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c needed.** </tabl
335c0 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f e>.** </blockquo
335d0 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 te>)^.**.** Note
335e0 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 that when type
335f0 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 conversions occu
33600 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 r, pointers retu
33610 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a rned by prior.**
33620 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 calls to sqlite
33630 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 3_column_blob(),
33640 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
33650 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a text(), and/or.*
33660 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e * sqlite3_column
33670 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 _text16() may be
33680 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a invalidated..**
33690 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e Type conversion
336a0 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e s and pointer in
336b0 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 validations migh
336c0 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 t occur.** in th
336d0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 e following case
336e0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a s:.**.** <ul>.**
336f0 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 <li> The initia
33700 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 l content is a B
33710 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f LOB and sqlite3_
33720 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 column_text() or
33730 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 .** sqlite3
33740 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
33750 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a is called. A z
33760 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d ero-terminator m
33770 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 ight.** nee
33780 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f d to be added to
33790 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 the string.</li
337a0 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e >.** <li> The in
337b0 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 itial content is
337c0 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 UTF-8 text and
337d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
337e0 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 ytes16() or.**
337f0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 sqlite3_colu
33800 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 mn_text16() is c
33810 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 alled. The cont
33820 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 ent must be conv
33830 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f erted.** to
33840 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a UTF-16.</li>.**
33850 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 <li> The initia
33860 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 l content is UTF
33870 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c -16 text and sql
33880 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
33890 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 s() or.** s
338a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
338b0 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 xt() is called.
338c0 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 The content mus
338d0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a t be converted.*
338e0 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e * to UTF-8.
338f0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a </li>.** </ul>.*
33900 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e *.** ^Conversion
33910 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 s between UTF-16
33920 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 be and UTF-16le
33930 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 are always done
33940 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a in place and do.
33950 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 ** not invalidat
33960 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 e a prior pointe
33970 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 r, though of cou
33980 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 rse the content
33990 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a of the buffer.**
339a0 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 that the prior
339b0 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 pointer referenc
339c0 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 es will have bee
339d0 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 n modified. Oth
339e0 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 er kinds.** of c
339f0 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f onversion are do
33a00 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e ne in place when
33a10 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c it is possible,
33a20 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 but sometimes t
33a30 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 hey.** are not p
33a40 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 ossible and in t
33a50 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 hose cases prior
33a60 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e pointers are in
33a70 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a validated..**.**
33a80 20 54 68 65 20 73 61 66 65 73 74 20 70 6f 6c 69 The safest poli
33a90 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 cy is to invoke
33aa0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a these routines.*
33ab0 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 * in one of the
33ac0 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a following ways:.
33ad0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c **.** <ul>.** <
33ae0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d li>sqlite3_colum
33af0 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 n_text() followe
33b00 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c d by sqlite3_col
33b10 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e umn_bytes()</li>
33b20 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 .** <li>sqlite3
33b30 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 _column_blob() f
33b40 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 ollowed by sqlit
33b50 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
33b60 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 )</li>.** <li>s
33b70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
33b80 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 xt16() followed
33b90 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d by sqlite3_colum
33ba0 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e n_bytes16()</li>
33bb0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
33bc0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 In other words,
33bd0 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 you should call
33be0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
33bf0 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 ext(),.** sqlite
33c00 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 3_column_blob(),
33c10 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 or sqlite3_colu
33c20 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 mn_text16() firs
33c30 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 t to force the r
33c40 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 esult.** into th
33c50 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 e desired format
33c60 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 , then invoke sq
33c70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
33c80 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 es() or.** sqlit
33c90 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
33ca0 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6() to find the
33cb0 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 size of the resu
33cc0 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 lt. Do not mix
33cd0 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 calls.** to sqli
33ce0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
33cf0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c ) or sqlite3_col
33d00 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 umn_blob() with
33d10 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 calls to.** sqli
33d20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
33d30 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 16(), and do not
33d40 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 mix calls to sq
33d50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
33d60 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 t16().** with ca
33d70 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 lls to sqlite3_c
33d80 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a olumn_bytes()..*
33d90 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 *.** ^The pointe
33da0 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 rs returned are
33db0 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 valid until a ty
33dc0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 pe conversion oc
33dd0 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 curs as.** descr
33de0 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 ibed above, or u
33df0 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 ntil [sqlite3_st
33e00 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 ep()] or [sqlite
33e10 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 3_reset()] or.**
33e20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
33e30 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e ze()] is called.
33e40 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 ^The memory sp
33e50 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 ace used to hold
33e60 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 strings.** and
33e70 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 BLOBs is freed a
33e80 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 utomatically. D
33e90 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 70 o <em>not</em> p
33ea0 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 ass the pointers
33eb0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f returned.** fro
33ec0 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d m [sqlite3_colum
33ed0 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 n_blob()], [sqli
33ee0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
33ef0 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a )], etc. into.**
33f00 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
33f10 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 ]..**.** ^(If a
33f20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
33f30 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 n error occurs d
33f40 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 uring the evalua
33f50 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f tion of any.** o
33f60 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
33f70 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 , a default valu
33f80 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 e is returned.
33f90 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 The default valu
33fa0 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 e.** is either t
33fb0 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 he integer 0, th
33fc0 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 e floating point
33fd0 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 number 0.0, or
33fe0 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 a NULL.** pointe
33ff0 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 r. Subsequent c
34000 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
34010 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c _errcode()] will
34020 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 return.** [SQLI
34030 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a TE_NOMEM].)^.*/.
34040 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
34050 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
34060 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
34070 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 nt iCol);.int sq
34080 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
34090 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a es(sqlite3_stmt*
340a0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 , int iCol);.int
340b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
340c0 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f bytes16(sqlite3_
340d0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
340e0 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 ;.double sqlite3
340f0 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 _column_double(s
34100 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
34110 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c t iCol);.int sql
34120 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 ite3_column_int(
34130 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
34140 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 nt iCol);.sqlite
34150 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 3_int64 sqlite3_
34160 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c column_int64(sql
34170 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
34180 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 iCol);.const uns
34190 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 igned char *sqli
341a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
341b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
341c0 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 nt iCol);.const
341d0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
341e0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 lumn_text16(sqli
341f0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
34200 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 Col);.int sqlite
34210 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 3_column_type(sq
34220 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
34230 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f iCol);.sqlite3_
34240 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 value *sqlite3_c
34250 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 olumn_value(sqli
34260 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
34270 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 Col);../*.** CAP
34280 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 I3REF: Destroy A
34290 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d Prepared Statem
342a0 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 ent Object.** DE
342b0 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 STRUCTOR: sqlite
342c0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 3_stmt.**.** ^Th
342d0 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 e sqlite3_finali
342e0 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 ze() function is
342f0 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 called to delet
34300 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 e a [prepared st
34310 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 atement]..** ^If
34320 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
34330 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 evaluation of t
34340 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 he statement enc
34350 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f ountered no erro
34360 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 rs.** or if the
34370 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 statement is nev
34380 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 er been evaluate
34390 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f d, then sqlite3_
343a0 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 finalize() retur
343b0 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e ns.** SQLITE_OK.
343c0 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 ^If the most r
343d0 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e ecent evaluation
343e0 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 of statement S
343f0 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 failed, then.**
34400 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
34410 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 (S) returns the
34420 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 appropriate [err
34430 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b or code] or.** [
34440 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 extended error c
34450 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ode]..**.** ^The
34460 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a sqlite3_finaliz
34470 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e e(S) routine can
34480 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e be called at an
34490 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a y point during.*
344a0 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 * the life cycle
344b0 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 of [prepared st
344c0 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 atement] S:.** b
344d0 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 efore statement
344e0 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 S is ever evalua
344f0 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e ted, after.** on
34500 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 e or more calls
34510 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 to [sqlite3_rese
34520 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 t()], or after a
34530 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 ny call.** to [s
34540 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 qlite3_step()] r
34550 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 egardless of whe
34560 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 ther or not the
34570 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a statement has.**
34580 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 completed execu
34590 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 tion..**.** ^Inv
345a0 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 oking sqlite3_fi
345b0 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 nalize() on a NU
345c0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 LL pointer is a
345d0 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a harmless no-op..
345e0 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 **.** The applic
345f0 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c ation must final
34600 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 ize every [prepa
34610 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 red statement] i
34620 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 n order to avoid
34630 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 .** resource lea
34640 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 ks. It is a gri
34650 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 evous error for
34660 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
34670 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a to try to use.**
34680 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 a prepared stat
34690 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 ement after it h
346a0 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 as been finalize
346b0 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 d. Any use of a
346c0 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 prepared.** sta
346d0 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 tement after it
346e0 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a has been finaliz
346f0 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e ed can result in
34700 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a undefined and.*
34710 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 * undesirable be
34720 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 havior such as s
34730 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 egfaults and hea
34740 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f p corruption..*/
34750 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e .int sqlite3_fin
34760 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 alize(sqlite3_st
34770 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a mt *pStmt);../*.
34780 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 ** CAPI3REF: Res
34790 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 et A Prepared St
347a0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a atement Object.*
347b0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
347c0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65 3_stmt.**.** The
347d0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 sqlite3_reset()
347e0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c function is cal
347f0 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b led to reset a [
34800 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
34810 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 nt].** object ba
34820 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 ck to its initia
34830 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 l state, ready t
34840 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 o be re-executed
34850 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 ..** ^Any SQL st
34860 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 atement variable
34870 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 s that had value
34880 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 s bound to them
34890 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 using.** the [sq
348a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 lite3_bind_blob
348b0 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a | sqlite3_bind_*
348c0 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 () API] retain t
348d0 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 heir values..**
348e0 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 Use [sqlite3_cle
348f0 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 ar_bindings()] t
34900 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 o reset the bind
34910 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ings..**.** ^The
34920 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
34930 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 S)] interface re
34940 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 sets the [prepar
34950 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a ed statement] S.
34960 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 ** back to the b
34970 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 eginning of its
34980 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e program..**.** ^
34990 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 If the most rece
349a0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 nt call to [sqli
349b0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 te3_step(S)] for
349c0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
349d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 d statement] S r
349e0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f eturned [SQLITE_
349f0 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f ROW] or [SQLITE_
34a00 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 DONE],.** or if
34a10 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
34a20 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f ] has never befo
34a30 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f re been called o
34a40 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 n S,.** then [sq
34a50 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 lite3_reset(S)]
34a60 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
34a70 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 OK]..**.** ^If t
34a80 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 he most recent c
34a90 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
34aa0 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 step(S)] for the
34ab0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 .** [prepared st
34ac0 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 atement] S indic
34ad0 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 ated an error, t
34ae0 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f hen.** [sqlite3_
34af0 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e reset(S)] return
34b00 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 s an appropriate
34b10 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a [error code]..*
34b20 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 *.** ^The [sqlit
34b30 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 e3_reset(S)] int
34b40 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 erface does not
34b50 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 change the value
34b60 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c s.** of any [sql
34b70 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 ite3_bind_blob|b
34b80 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 indings] on the
34b90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
34ba0 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 ent] S..*/.int s
34bb0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c qlite3_reset(sql
34bc0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
34bd0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
34be0 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 EF: Create Or Re
34bf0 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 define SQL Funct
34c00 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ions.** KEYWORDS
34c10 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 : {function crea
34c20 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a tion routines}.*
34c30 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 * KEYWORDS: {app
34c40 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
34c50 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a SQL function}.*
34c60 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 * KEYWORDS: {app
34c70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
34c80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a SQL functions}.
34c90 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
34ca0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 e3.**.** ^These
34cb0 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 functions (colle
34cc0 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 ctively known as
34cd0 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 "function creat
34ce0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a ion routines").*
34cf0 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 * are used to ad
34d00 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 d SQL functions
34d10 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 or aggregates or
34d20 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 to redefine the
34d30 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 behavior.** of
34d40 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e existing SQL fun
34d50 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 ctions or aggreg
34d60 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 ates. The only
34d70 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 differences betw
34d80 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 een.** these rou
34d90 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 tines are the te
34da0 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 xt encoding expe
34db0 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 cted for.** the
34dc0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
34dd0 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 (the name of th
34de0 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 e function being
34df0 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 created).** and
34e00 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 the presence or
34e10 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 absence of a de
34e20 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 structor callbac
34e30 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 k for.** the app
34e40 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f lication data po
34e50 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 inter..**.** ^Th
34e60 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
34e70 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 r is the [databa
34e80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 se connection] t
34e90 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a o which the SQL.
34ea0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 ** function is t
34eb0 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 o be added. ^If
34ec0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 an application
34ed0 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f uses more than o
34ee0 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 ne database.** c
34ef0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 onnection then a
34f00 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
34f10 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 ed SQL functions
34f20 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a must be added.*
34f30 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 * to each databa
34f40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 se connection se
34f50 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 parately..**.**
34f60 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 ^The second para
34f70 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d meter is the nam
34f80 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e e of the SQL fun
34f90 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 ction to be crea
34fa0 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 ted or.** redefi
34fb0 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 ned. ^The lengt
34fc0 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 h of the name is
34fd0 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 limited to 255
34fe0 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 bytes in a UTF-8
34ff0 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 .** representati
35000 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 on, exclusive of
35010 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e the zero-termin
35020 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 ator. ^Note tha
35030 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 t the name.** le
35040 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e ngth limit is in
35050 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f UTF-8 bytes, no
35060 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 t characters nor
35070 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 UTF-16 bytes.
35080 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 .** ^Any attempt
35090 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e to create a fun
350a0 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e ction with a lon
350b0 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c ger name.** will
350c0 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 result in [SQLI
350d0 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 TE_MISUSE] being
350e0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
350f0 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 ^The third para
35100 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 meter (nArg).**
35110 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 is the number of
35120 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 arguments that
35130 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
35140 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 or.** aggregate
35150 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 takes. ^If this
35160 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 parameter is -1
35170 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 , then the SQL f
35180 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 unction or.** ag
35190 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 gregate may take
351a0 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 any number of a
351b0 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e rguments between
351c0 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0 and the limit
351d0 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 .** set by [sqli
351e0 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 te3_limit]([SQLI
351f0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f TE_LIMIT_FUNCTIO
35200 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 N_ARG]). If the
35210 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 third.** parame
35220 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e ter is less than
35230 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 -1 or greater t
35240 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 han 127 then the
35250 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 behavior is.**
35260 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
35270 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 ^The fourth par
35280 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 ameter, eTextRep
35290 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 , specifies what
352a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 .** [SQLITE_UTF8
352b0 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 | text encoding
352c0 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 ] this SQL funct
352d0 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a ion prefers for.
352e0 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 ** its parameter
352f0 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 s. The applicat
35300 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74 ion should set t
35310 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f his parameter to
35320 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 .** [SQLITE_UTF1
35330 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63 6LE] if the func
35340 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 tion implementat
35350 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 ion invokes .**
35360 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 [sqlite3_value_t
35370 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e ext16le()] on an
35380 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 input, or [SQLI
35390 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74 TE_UTF16BE] if t
353a0 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 he.** implementa
353b0 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 tion invokes [sq
353c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
353d0 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 16be()] on an in
353e0 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 put, or.** [SQLI
353f0 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71 TE_UTF16] if [sq
35400 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
35410 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 16()] is used, o
35420 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a r [SQLITE_UTF8].
35430 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e ** otherwise. ^
35440 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e The same SQL fun
35450 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 ction may be reg
35460 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 istered multiple
35470 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 times using.**
35480 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 65 72 different prefer
35490 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e red text encodin
354a0 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 72 65 gs, with differe
354b0 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f nt implementatio
354c0 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 ns for.** each e
354d0 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 ncoding..** ^Whe
354e0 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 n multiple imple
354f0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 mentations of th
35500 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 e same function
35510 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 are available, S
35520 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 QLite.** will pi
35530 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 ck the one that
35540 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 involves the lea
35550 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 st amount of dat
35560 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a a conversion..**
35570 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 .** ^The fourth
35580 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 parameter may op
35590 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 tionally be ORed
355a0 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 with [SQLITE_DE
355b0 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 TERMINISTIC].**
355c0 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74 to signal that t
355d0 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c he function will
355e0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 always return t
355f0 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67 he same result g
35600 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 iven.** the same
35610 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61 inputs within a
35620 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 single SQL stat
35630 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c ement. Most SQL
35640 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a functions are.*
35650 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e * deterministic.
35660 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b The built-in [
35670 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 random()] SQL fu
35680 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 nction is an exa
35690 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e mple of a.** fun
356a0 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f ction that is no
356b0 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e t deterministic.
356c0 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75 65 The SQLite que
356d0 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 ry planner is ab
356e0 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d le to.** perform
356f0 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 additional opti
35700 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 mizations on det
35710 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74 erministic funct
35720 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 ions, so use.**
35730 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 of the [SQLITE_D
35740 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c ETERMINISTIC] fl
35750 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 ag is recommende
35760 64 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65 d where possible
35770 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 ..**.** ^(The fi
35780 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 fth parameter is
35790 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f an arbitrary po
357a0 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c inter. The impl
357b0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 ementation of th
357c0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 e.** function ca
357d0 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f n gain access to
357e0 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 this pointer us
357f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 ing [sqlite3_use
35800 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a r_data()].)^.**.
35810 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 ** ^The sixth, s
35820 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 eventh and eight
35830 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 h parameters, xF
35840 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 unc, xStep and x
35850 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f Final, are.** po
35860 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 inters to C-lang
35870 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 uage functions t
35880 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 hat implement th
35890 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f e SQL function o
358a0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 r.** aggregate.
358b0 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 ^A scalar SQL fu
358c0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 nction requires
358d0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f an implementatio
358e0 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a n of the xFunc.*
358f0 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b * callback only;
35900 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d NULL pointers m
35910 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 ust be passed as
35920 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 the xStep and x
35930 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 Final.** paramet
35940 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 ers. ^An aggrega
35950 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 te SQL function
35960 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c requires an impl
35970 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 ementation of xS
35980 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 tep.** and xFina
35990 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 l and NULL point
359a0 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 er must be passe
359b0 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f d for xFunc. ^To
359c0 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 delete an exist
359d0 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 ing.** SQL funct
359e0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 ion or aggregate
359f0 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e , pass NULL poin
35a00 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 ters for all thr
35a10 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 ee function.** c
35a20 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 allbacks..**.**
35a30 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 ^(If the ninth p
35a40 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
35a50 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
35a60 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 ion_v2() is not
35a70 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 NULL,.** then it
35a80 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 is destructor f
35a90 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 or the applicati
35aa0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e on data pointer.
35ab0 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 .** The destruc
35ac0 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 tor is invoked w
35ad0 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e hen the function
35ae0 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 is deleted, eit
35af0 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 her by being.**
35b00 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 overloaded or wh
35b10 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
35b20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 connection close
35b30 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 s.)^.** ^The des
35b40 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 tructor is also
35b50 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 invoked if the c
35b60 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 all to.** sqlite
35b70 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
35b80 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a n_v2() fails..**
35b90 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 ^When the destr
35ba0 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f uctor callback o
35bb0 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 f the tenth para
35bc0 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 meter is invoked
35bd0 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 , it.** is passe
35be0 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d d a single argum
35bf0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63 ent which is a c
35c00 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 opy of the appli
35c10 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 cation data .**
35c20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 pointer which wa
35c30 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61 s the fifth para
35c40 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
35c50 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
35c60 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 _v2()..**.** ^It
35c70 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f is permitted to
35c80 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 register multip
35c90 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
35ca0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a ns of the same.*
35cb0 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 * functions with
35cc0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 the same name b
35cd0 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 ut with either d
35ce0 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 iffering numbers
35cf0 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 of.** arguments
35d00 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 or differing pr
35d10 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 eferred text enc
35d20 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 odings. ^SQLite
35d30 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 will use.** the
35d40 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
35d50 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c that most closel
35d60 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 y matches the wa
35d70 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a y in which the.*
35d80 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 * SQL function i
35d90 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 s used. ^A func
35da0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 tion implementat
35db0 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e ion with a non-n
35dc0 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 egative.** nArg
35dd0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 parameter is a b
35de0 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e etter match than
35df0 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c a function impl
35e00 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a ementation with.
35e10 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 ** a negative nA
35e20 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e rg. ^A function
35e30 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65 where the prefe
35e40 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 rred text encodi
35e50 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 ng.** matches th
35e60 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 e database encod
35e70 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a ing is a better.
35e80 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 ** match than a
35e90 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 function where t
35ea0 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 he encoding is d
35eb0 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e ifferent. .** ^
35ec0 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 A function where
35ed0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 the encoding di
35ee0 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 fference is betw
35ef0 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 een UTF16le and
35f00 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 UTF16be.** is a
35f10 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 closer match tha
35f20 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 n a function whe
35f30 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 re the encoding
35f40 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a difference is.**
35f50 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e between UTF8 an
35f60 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e d UTF16..**.** ^
35f70 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f Built-in functio
35f80 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f ns may be overlo
35f90 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c aded by new appl
35fa0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
35fb0 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a functions..**.**
35fc0 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e ^An application
35fd0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
35fe0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 n is permitted t
35ff0 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 o call other.**
36000 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
36010 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 s. However, suc
36020 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 h calls must not
36030 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 .** close the da
36040 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
36050 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f n nor finalize o
36060 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 r reset the prep
36070 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e ared.** statemen
36080 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 t in which the f
36090 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 unction is runni
360a0 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ng..*/.int sqlit
360b0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
360c0 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 on(. sqlite3 *d
360d0 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 b,. const char
360e0 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a *zFunctionName,.
360f0 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e int nArg,. in
36100 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f t eTextRep,. vo
36110 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 id *pApp,. void
36120 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 (*xFunc)(sqlite
36130 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 3_context*,int,s
36140 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c qlite3_value**),
36150 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 . void (*xStep)
36160 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
36170 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
36180 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
36190 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 *xFinal)(sqlite3
361a0 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e _context*).);.in
361b0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
361c0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 _function16(. s
361d0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f qlite3 *db,. co
361e0 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 nst void *zFunct
361f0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e ionName,. int n
36200 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 Arg,. int eText
36210 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 Rep,. void *pAp
36220 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e p,. void (*xFun
36230 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 c)(sqlite3_conte
36240 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f xt*,int,sqlite3_
36250 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 value**),. void
36260 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 (*xStep)(sqlite
36270 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 3_context*,int,s
36280 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c qlite3_value**),
36290 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c . void (*xFinal
362a0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 )(sqlite3_contex
362b0 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 t*).);.int sqlit
362c0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
362d0 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 on_v2(. sqlite3
362e0 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 *db,. const ch
362f0 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d ar *zFunctionNam
36300 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 e,. int nArg,.
36310 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 int eTextRep,.
36320 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 void *pApp,. v
36330 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c oid (*xFunc)(sql
36340 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e ite3_context*,in
36350 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t,sqlite3_value*
36360 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 *),. void (*xSt
36370 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ep)(sqlite3_cont
36380 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
36390 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
363a0 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 d (*xFinal)(sqli
363b0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 te3_context*),.
363c0 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 void(*xDestroy)
363d0 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a (void*).);../*.*
363e0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 * CAPI3REF: Text
363f0 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a Encodings.**.**
36400 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 These constant
36410 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 define integer c
36420 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73 odes that repres
36430 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a ent the various.
36440 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 ** text encoding
36450 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 s supported by S
36460 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e QLite..*/.#defin
36470 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 e SQLITE_UTF8
36480 20 20 20 20 20 20 20 20 31 20 20 20 20 2f 2a 20 1 /*
36490 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d 33 35 35 IMP: R-37514-355
364a0 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 66 */.#define SQ
364b0 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 LITE_UTF16LE
364c0 20 20 20 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a 2 /* IMP:
364d0 20 52 2d 30 33 33 37 31 2d 33 37 36 33 37 20 2a R-03371-37637 *
364e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
364f0 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20 _UTF16BE
36500 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35 3 /* IMP: R-5
36510 31 39 37 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64 1971-34154 */.#d
36520 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 efine SQLITE_UTF
36530 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 16 4
36540 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 /* Use native b
36550 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 yte order */.#de
36560 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 fine SQLITE_ANY
36570 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 5
36580 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f /* Deprecated */
36590 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
365a0 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 UTF16_ALIGNED 8
365b0 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 /* sqlite3_c
365c0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 reate_collation
365d0 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 only */../*.** C
365e0 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f API3REF: Functio
365f0 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 n Flags.**.** Th
36600 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 ese constants ma
36610 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68 y be ORed togeth
36620 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 er with the .**
36630 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 [SQLITE_UTF8 | p
36640 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e referred text en
36650 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66 coding] as the f
36660 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a ourth argument.*
36670 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 * to [sqlite3_cr
36680 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d eate_function()]
36690 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 , [sqlite3_creat
366a0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c e_function16()],
366b0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
366c0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f create_function_
366d0 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e v2()]..*/.#defin
366e0 65 20 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 e SQLITE_DETERMI
366f0 4e 49 53 54 49 43 20 20 20 20 30 78 38 30 30 0a NISTIC 0x800.
36700 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
36710 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 Deprecated Func
36720 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 tions.** DEPRECA
36730 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 TED.**.** These
36740 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 functions are [d
36750 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 eprecated]. In
36760 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 order to maintai
36770 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 n.** backwards c
36780 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 ompatibility wit
36790 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 h older code, th
367a0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f ese functions co
367b0 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 ntinue .** to be
367c0 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 supported. How
367d0 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 ever, new applic
367e0 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 ations should av
367f0 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f oid.** the use o
36800 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e f these function
36810 73 2e 20 20 54 6f 20 65 6e 63 6f 75 72 61 67 65 s. To encourage
36820 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 74 6f 20 programmers to
36830 61 76 6f 69 64 0a 2a 2a 20 74 68 65 73 65 20 66 avoid.** these f
36840 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 77 69 6c unctions, we wil
36850 6c 20 6e 6f 74 20 65 78 70 6c 61 69 6e 20 77 68 l not explain wh
36860 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 at they do..*/.#
36870 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d ifndef SQLITE_OM
36880 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 IT_DEPRECATED.SQ
36890 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
368a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 int sqlite3_aggr
368b0 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 egate_count(sqli
368c0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 te3_context*);.S
368d0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 QLITE_DEPRECATED
368e0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 int sqlite3_exp
368f0 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d ired(sqlite3_stm
36900 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 t*);.SQLITE_DEPR
36910 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 ECATED int sqlit
36920 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 e3_transfer_bind
36930 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d ings(sqlite3_stm
36940 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 t*, sqlite3_stmt
36950 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 *);.SQLITE_DEPRE
36960 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 CATED int sqlite
36970 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 3_global_recover
36980 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 (void);.SQLITE_D
36990 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 EPRECATED void s
369a0 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c qlite3_thread_cl
369b0 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c eanup(void);.SQL
369c0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 ITE_DEPRECATED i
369d0 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 nt sqlite3_memor
369e0 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 y_alarm(void(*)(
369f0 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e void*,sqlite3_in
36a00 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 t64,int),.
36a10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
36a20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e void*,sqlite3_in
36a30 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a t64);.#endif../*
36a40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 .** CAPI3REF: Ob
36a50 74 61 69 6e 69 6e 67 20 53 51 4c 20 56 61 6c 75 taining SQL Valu
36a60 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 es.** METHOD: sq
36a70 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a lite3_value.**.*
36a80 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 * The C-language
36a90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
36aa0 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 of SQL functions
36ab0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 and aggregates
36ac0 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 uses.** this set
36ad0 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f of interface ro
36ae0 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 utines to access
36af0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 the parameter v
36b00 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 alues on.** the
36b10 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 function or aggr
36b20 65 67 61 74 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 egate. .**.** T
36b30 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 he xFunc (for sc
36b40 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 alar functions)
36b50 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 or xStep (for ag
36b60 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 gregates) parame
36b70 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 ters.** to [sqli
36b80 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
36b90 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 ion()] and [sqli
36ba0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
36bb0 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 ion16()].** defi
36bc0 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 ne callbacks tha
36bd0 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 t implement the
36be0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e SQL functions an
36bf0 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a d aggregates..**
36c00 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 The 3rd paramet
36c10 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c er to these call
36c20 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 backs is an arra
36c30 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f y of pointers to
36c40 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 .** [protected s
36c50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
36c60 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 jects. There is
36c70 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 one [sqlite3_va
36c80 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a lue] object for.
36c90 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 ** each paramete
36ca0 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e r to the SQL fun
36cb0 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f ction. These ro
36cc0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 utines are used
36cd0 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 to.** extract va
36ce0 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 lues from the [s
36cf0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
36d00 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 jects..**.** The
36d10 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b se routines work
36d20 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 only with [prot
36d30 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
36d40 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a lue] objects..**
36d50 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 Any attempt to
36d60 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e use these routin
36d70 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 es on an [unprot
36d80 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
36d90 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 lue].** object r
36da0 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 esults in undefi
36db0 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a ned behavior..**
36dc0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 .** ^These routi
36dd0 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 nes work just li
36de0 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e ke the correspon
36df0 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 ding [column acc
36e00 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a ess functions].*
36e10 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 * except that th
36e20 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b ese routines tak
36e30 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 e a single [prot
36e40 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
36e50 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 lue] object.** p
36e60 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f ointer instead o
36e70 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d f a [sqlite3_stm
36e80 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 t*] pointer and
36e90 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d an integer colum
36ea0 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 n number..**.**
36eb0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c ^The sqlite3_val
36ec0 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 ue_text16() inte
36ed0 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61 rface extracts a
36ee0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a UTF-16 string.*
36ef0 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 * in the native
36f00 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 byte-order of th
36f10 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 e host machine.
36f20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 ^The.** sqlite3
36f30 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 _value_text16be(
36f40 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 ) and sqlite3_va
36f50 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 lue_text16le() i
36f60 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 nterfaces.** ext
36f70 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 ract UTF-16 stri
36f80 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 ngs as big-endia
36f90 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 n and little-end
36fa0 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 ian respectively
36fb0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 ..**.** ^(The sq
36fc0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 lite3_value_nume
36fd0 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 ric_type() inter
36fe0 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f face attempts to
36ff0 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 apply.** numeri
37000 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 c affinity to th
37010 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d e value. This m
37020 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 eans that an att
37030 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 empt is.** made
37040 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 to convert the v
37050 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 alue to an integ
37060 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 er or floating p
37070 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 oint. If.** suc
37080 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 h a conversion i
37090 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f s possible witho
370a0 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 ut loss of infor
370b0 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 mation (in other
370c0 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 .** words, if th
370d0 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 e value is a str
370e0 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c ing that looks l
370f0 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a ike a number).**
37100 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 then the conver
37110 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 sion is performe
37120 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f d. Otherwise no
37130 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 conversion occu
37140 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 rs..** The [SQLI
37150 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 TE_INTEGER | dat
37160 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e atype] after con
37170 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 version is retur
37180 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 ned.)^.**.** Ple
37190 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c ase pay particul
371a0 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 ar attention to
371b0 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 the fact that th
371c0 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e e pointer return
371d0 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 ed.** from [sqli
371e0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 te3_value_blob()
371f0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ], [sqlite3_valu
37200 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a e_text()], or.**
37210 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
37220 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 text16()] can be
37230 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 invalidated by
37240 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c a subsequent cal
37250 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 l to.** [sqlite3
37260 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c _value_bytes()],
37270 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
37280 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c bytes16()], [sql
37290 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 ite3_value_text(
372a0 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 )],.** or [sqlit
372b0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 e3_value_text16(
372c0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 )]..**.** These
372d0 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 routines must be
372e0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 called from the
372f0 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a same thread as.
37300 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 ** the SQL funct
37310 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 ion that supplie
37320 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 d the [sqlite3_v
37330 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 alue*] parameter
37340 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 s..*/.const void
37350 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f *sqlite3_value_
37360 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c blob(sqlite3_val
37370 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 ue*);.int sqlite
37380 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 3_value_bytes(sq
37390 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 lite3_value*);.i
373a0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt sqlite3_value
373b0 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 _bytes16(sqlite3
373c0 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 _value*);.double
373d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 sqlite3_value_d
373e0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 ouble(sqlite3_va
373f0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 lue*);.int sqlit
37400 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c e3_value_int(sql
37410 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 ite3_value*);.sq
37420 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 lite3_int64 sqli
37430 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 te3_value_int64(
37440 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
37450 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 .const unsigned
37460 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 char *sqlite3_va
37470 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 lue_text(sqlite3
37480 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 _value*);.const
37490 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 void *sqlite3_va
374a0 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 lue_text16(sqlit
374b0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 e3_value*);.cons
374c0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
374d0 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 value_text16le(s
374e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
374f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
37500 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
37510 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 be(sqlite3_value
37520 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f *);.int sqlite3_
37530 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 value_type(sqlit
37540 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 e3_value*);.int
37550 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 sqlite3_value_nu
37560 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 meric_type(sqlit
37570 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a e3_value*);../*.
37580 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e ** CAPI3REF: Fin
37590 64 69 6e 67 20 54 68 65 20 53 75 62 74 79 70 65 ding The Subtype
375a0 20 4f 66 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a Of SQL Values.*
375b0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
375c0 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 3_value.**.** Th
375d0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f e sqlite3_value_
375e0 73 75 62 74 79 70 65 28 56 29 20 66 75 6e 63 74 subtype(V) funct
375f0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 ion returns the
37600 73 75 62 74 79 70 65 20 66 6f 72 0a 2a 2a 20 61 subtype for.** a
37610 6e 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 n [application-d
37620 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
37630 69 6f 6e 5d 20 61 72 67 75 6d 65 6e 74 20 56 2e ion] argument V.
37640 20 20 54 68 65 20 73 75 62 74 79 70 65 0a 2a 2a The subtype.**
37650 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 63 61 6e information can
37660 20 62 65 20 75 73 65 64 20 74 6f 20 70 61 73 73 be used to pass
37670 20 61 20 6c 69 6d 69 74 65 64 20 61 6d 6f 75 6e a limited amoun
37680 74 20 6f 66 20 63 6f 6e 74 65 78 74 20 66 72 6f t of context fro
37690 6d 0a 2a 2a 20 6f 6e 65 20 53 51 4c 20 66 75 6e m.** one SQL fun
376a0 63 74 69 6f 6e 20 74 6f 20 61 6e 6f 74 68 65 72 ction to another
376b0 2e 20 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 . Use the [sqli
376c0 74 65 33 5f 72 65 73 75 6c 74 5f 73 75 62 74 79 te3_result_subty
376d0 70 65 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 pe()].** routine
376e0 20 74 6f 20 73 65 74 20 74 68 65 20 73 75 62 74 to set the subt
376f0 79 70 65 20 66 6f 72 20 74 68 65 20 72 65 74 75 ype for the retu
37700 72 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 53 rn value of an S
37710 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a QL function..**.
37720 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 ** SQLite makes
37730 6e 6f 20 75 73 65 20 6f 66 20 73 75 62 74 79 70 no use of subtyp
37740 65 20 69 74 73 65 6c 66 2e 20 20 49 74 20 6d 65 e itself. It me
37750 72 65 6c 79 20 70 61 73 73 65 73 20 74 68 65 20 rely passes the
37760 73 75 62 74 79 70 65 0a 2a 2a 20 66 72 6f 6d 20 subtype.** from
37770 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 6f 6e the result of on
37780 65 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 e [application-d
37790 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
377a0 69 6f 6e 5d 20 69 6e 74 6f 20 74 68 65 0a 2a 2a ion] into the.**
377b0 20 69 6e 70 75 74 20 6f 66 20 61 6e 6f 74 68 65 input of anothe
377c0 72 2e 0a 2a 2f 0a 75 6e 73 69 67 6e 65 64 20 69 r..*/.unsigned i
377d0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt sqlite3_value
377e0 5f 73 75 62 74 79 70 65 28 73 71 6c 69 74 65 33 _subtype(sqlite3
377f0 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a _value*);../*.**
37800 20 43 41 50 49 33 52 45 46 3a 20 43 6f 70 79 20 CAPI3REF: Copy
37810 41 6e 64 20 46 72 65 65 20 53 51 4c 20 56 61 6c And Free SQL Val
37820 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ues.** METHOD: s
37830 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a qlite3_value.**.
37840 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
37850 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69 6e 74 value_dup(V) int
37860 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 erface makes a c
37870 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 opy of the [sqli
37880 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 te3_value].** ob
37890 6a 65 63 74 20 44 20 61 6e 64 20 72 65 74 75 72 ject D and retur
378a0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
378b0 74 68 61 74 20 63 6f 70 79 2e 20 20 5e 54 68 65 that copy. ^The
378c0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d [sqlite3_value]
378d0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 returned.** is
378e0 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c a [protected sql
378f0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
37900 63 74 20 65 76 65 6e 20 69 66 20 74 68 65 20 69 ct even if the i
37910 6e 70 75 74 20 69 73 20 6e 6f 74 2e 0a 2a 2a 20 nput is not..**
37920 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c ^The sqlite3_val
37930 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66 ue_dup(V) interf
37940 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c ace returns NULL
37950 20 69 66 20 56 20 69 73 20 4e 55 4c 4c 20 6f 72 if V is NULL or
37960 20 69 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 if a.** memory
37970 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 allocation fails
37980 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
37990 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 ite3_value_free(
379a0 56 29 20 69 6e 74 65 72 66 61 63 65 20 66 72 65 V) interface fre
379b0 65 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 es an [sqlite3_v
379c0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 alue] object.**
379d0 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 previously obtai
379e0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ned from [sqlite
379f0 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e 20 3_value_dup()].
37a00 20 5e 49 66 20 56 20 69 73 20 61 20 4e 55 4c 4c ^If V is a NULL
37a10 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6e pointer.** then
37a20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 sqlite3_value_f
37a30 72 65 65 28 56 29 20 69 73 20 61 20 68 61 72 6d ree(V) is a harm
37a40 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 73 less no-op..*/.s
37a50 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 qlite3_value *sq
37a60 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 lite3_value_dup(
37a70 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 const sqlite3_va
37a80 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 lue*);.void sqli
37a90 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 73 te3_value_free(s
37aa0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
37ab0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
37ac0 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 Obtain Aggregat
37ad0 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 e Function Conte
37ae0 78 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 xt.** METHOD: sq
37af0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a lite3_context.**
37b00 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 .** Implementati
37b10 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 ons of aggregate
37b20 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 SQL functions u
37b30 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 se this.** routi
37b40 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d ne to allocate m
37b50 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e emory for storin
37b60 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a g their state..*
37b70 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 *.** ^The first
37b80 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 time the sqlite3
37b90 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
37ba0 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 xt(C,N) routine
37bb0 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f is called .** fo
37bc0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 r a particular a
37bd0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f ggregate functio
37be0 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c n, SQLite.** all
37bf0 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f ocates N of memo
37c00 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 ry, zeroes out t
37c10 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 hat memory, and
37c20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
37c30 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 r.** to the new
37c40 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f memory. ^On seco
37c50 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e nd and subsequen
37c60 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 t calls to.** sq
37c70 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
37c80 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 context() for th
37c90 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 e same aggregate
37ca0 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e function instan
37cb0 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 ce,.** the same
37cc0 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e buffer is return
37cd0 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 ed. Sqlite3_agg
37ce0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 regate_context()
37cf0 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 is normally.**
37d00 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 called once for
37d10 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 each invocation
37d20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c of the xStep cal
37d30 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f lback and then o
37d40 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 ne.** last time
37d50 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 when the xFinal
37d60 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
37d70 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 ked. ^(When no
37d80 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e rows match.** an
37d90 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 aggregate query
37da0 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61 , the xStep() ca
37db0 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67 llback of the ag
37dc0 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e gregate function
37dd0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
37de0 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c on is never call
37df0 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 ed and xFinal()
37e00 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c is called exactl
37e10 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 y once..** In th
37e20 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74 ose cases, sqlit
37e30 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
37e40 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20 text() might be
37e50 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a called for the.*
37e60 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f * first time fro
37e70 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 m within xFinal(
37e80 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ).)^.**.** ^The
37e90 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
37ea0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 e_context(C,N) r
37eb0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 outine returns a
37ec0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a NULL pointer .*
37ed0 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c * when first cal
37ee0 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73 led if N is less
37ef0 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 than or equal t
37f00 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d o zero or if a m
37f10 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 emory.** allocat
37f20 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a e error occurs..
37f30 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 **.** ^(The amou
37f40 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f nt of space allo
37f50 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 cated by sqlite3
37f60 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
37f70 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 xt(C,N) is.** de
37f80 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 termined by the
37f90 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 N parameter on f
37fa0 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 irst successful
37fb0 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 call. Changing
37fc0 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 the.** value of
37fd0 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 N in subsequent
37fe0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
37ff0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
38000 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 t() within.** th
38010 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 e same aggregate
38020 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e function instan
38030 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 ce will not resi
38040 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a ze the memory.**
38050 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 allocation.)^
38060 57 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61 Within the xFina
38070 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69 l callback, it i
38080 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73 s customary to s
38090 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c et.** N=0 in cal
380a0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 ls to sqlite3_ag
380b0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
380c0 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20 C,N) so that no
380d0 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65 .** pointless me
380e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 mory allocations
380f0 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 occur..**.** ^S
38100 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 QLite automatica
38110 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 lly frees the me
38120 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 mory allocated b
38130 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 y .** sqlite3_ag
38140 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
38150 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 ) when the aggre
38160 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c gate query concl
38170 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 udes..**.** The
38180 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
38190 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f must be a copy o
381a0 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 f the.** [sqlite
381b0 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 3_context | SQL
381c0 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 function context
381d0 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69 ] that is the fi
381e0 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a rst parameter.**
381f0 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 to the xStep or
38200 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b xFinal callback
38210 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d routine that im
38220 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 plements the agg
38230 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 regate.** functi
38240 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 on..**.** This r
38250 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 outine must be c
38260 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 alled from the s
38270 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 ame thread in wh
38280 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 ich.** the aggre
38290 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f gate SQL functio
382a0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f n is running..*/
382b0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 .void *sqlite3_a
382c0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
382d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
382e0 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a *, int nBytes);.
382f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
38300 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 User Data For F
38310 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 unctions.** METH
38320 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 OD: sqlite3_cont
38330 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ext.**.** ^The s
38340 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 qlite3_user_data
38350 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 () interface ret
38360 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a urns a copy of.*
38370 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 * the pointer th
38380 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72 at was the pUser
38390 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 Data parameter (
383a0 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 the 5th paramete
383b0 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 r).** of the [sq
383c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
383d0 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 ction()].** and
383e0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
383f0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f function16()] ro
38400 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 utines that orig
38410 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 inally.** regist
38420 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 ered the applica
38430 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e tion defined fun
38440 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 ction..**.** Thi
38450 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 s routine must b
38460 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 e called from th
38470 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e e same thread in
38480 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 which.** the ap
38490 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
384a0 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 d function is ru
384b0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a nning..*/.void *
384c0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 sqlite3_user_dat
384d0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 a(sqlite3_contex
384e0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
384f0 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 3REF: Database C
38500 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 onnection For Fu
38510 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f nctions.** METHO
38520 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 D: sqlite3_conte
38530 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 xt.**.** ^The sq
38540 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 lite3_context_db
38550 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 _handle() interf
38560 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f ace returns a co
38570 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 py of.** the poi
38580 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 nter to the [dat
38590 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
385a0 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d ] (the 1st param
385b0 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 eter).** of the
385c0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
385d0 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 function()].** a
385e0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 nd [sqlite3_crea
385f0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d te_function16()]
38600 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f routines that o
38610 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 riginally.** reg
38620 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c istered the appl
38630 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 ication defined
38640 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c function..*/.sql
38650 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f ite3 *sqlite3_co
38660 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 ntext_db_handle(
38670 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
38680 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
38690 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 EF: Function Aux
386a0 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 20 4d iliary Data.** M
386b0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 ETHOD: sqlite3_c
386c0 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65 ontext.**.** The
386d0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 se functions may
386e0 20 62 65 20 75 73 65 64 20 62 79 20 28 6e 6f 6e be used by (non
386f0 2d 61 67 67 72 65 67 61 74 65 29 20 53 51 4c 20 -aggregate) SQL
38700 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 functions to.**
38710 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 associate metada
38720 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 ta with argument
38730 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 values. If the
38740 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 same value is pa
38750 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 ssed to.** multi
38760 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 ple invocations
38770 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 of the same SQL
38780 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 function during
38790 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c query execution,
387a0 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 under.** some c
387b0 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 ircumstances the
387c0 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 associated meta
387d0 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 data may be pres
387e0 65 72 76 65 64 2e 20 20 41 6e 20 65 78 61 6d 70 erved. An examp
387f0 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20 74 le.** of where t
38800 68 69 73 20 6d 69 67 68 74 20 62 65 20 75 73 65